Package Exports

@oxy-hq/sdk

Readme

Oxy TypeScript SDK

Official TypeScript/JavaScript SDK for interacting with the Oxy data platform.

Features

🚀 Simple API - Easy-to-use client for fetching app data
📊 Parquet Support - Read and query Parquet files using DuckDB-WASM
🔒 Type-Safe - Full TypeScript support with comprehensive type definitions
🌐 Universal - Works in both Node.js and browser environments
⚡ Fast - Optimized for performance with efficient data handling

Installation

npm install @oxy/sdk
# or
yarn add @oxy/sdk
# or
pnpm add @oxy/sdk

For Parquet file support, also install DuckDB-WASM:

npm install @duckdb/duckdb-wasm

Quick Start

Option 1: Client-Side Usage (Iframe with PostMessage)

Perfect for embedding dashboards in iframes (e.g., v0.dev, sandboxed environments):

import { OxyClient } from '@oxy/sdk';

// SDK automatically requests API key from parent window
const client = await OxyClient.create({
  parentOrigin: 'https://app.example.com',  // Parent window origin
  projectId: 'your-project-uuid',
  baseUrl: 'https://api.oxy.tech'
});

// Use the client
const apps = await client.listApps();
console.log('Available apps:', apps);

Parent window setup (one-time):

// In parent window that hosts the iframe
window.addEventListener('message', (event) => {
  if (event.data.type !== 'OXY_AUTH_REQUEST') return;

  // Validate iframe origin
  if (event.origin !== 'https://your-iframe-app.com') return;

  // Send user's API key to iframe
  event.source.postMessage({
    type: 'OXY_AUTH_RESPONSE',
    version: '1.0',
    requestId: event.data.requestId,
    apiKey: getUserApiKey(),  // Your auth logic
    projectId: 'your-project-uuid',
    baseUrl: 'https://api.oxy.tech'
  }, event.origin);
});

Option 2: Traditional Usage (Environment Variables)

Set up environment variables:

export OXY_URL="https://api.oxy.tech"  # or your self-hosted URL
export OXY_API_KEY="your-api-key"
export OXY_PROJECT_ID="your-project-uuid"
export OXY_BRANCH="main"  # optional

Basic usage:

import { OxyClient, createConfig } from '@oxy/sdk';

// Create configuration from environment variables
const config = createConfig();

// Initialize the client
const client = new OxyClient(config);

// List all apps
const apps = await client.listApps();
console.log('Available apps:', apps);

// Get app data
const data = await client.getAppData('dashboard.app.yml');
if (!data.error) {
  console.log('App data:', data.data);
}

// Fetch a file (e.g., chart image)
const blob = await client.getFile('charts/sales-chart.png');
const url = URL.createObjectURL(blob);
// Use the URL in an <img> tag

Reading Parquet Files

import { OxyClient, createConfig, readParquet, ParquetReader } from '@oxy/sdk';

const config = createConfig();
const client = new OxyClient(config);

// Quick read - get all data
const blob = await client.getFile('data/sales.parquet');
const data = await readParquet(blob, 1000); // Read first 1000 rows
console.log(data.columns);
console.log(data.rows);

// Advanced - query with SQL
const reader = new ParquetReader('sales');
await reader.registerParquet(blob);

const result = await reader.query(`
  SELECT product, SUM(amount) as total_sales
  FROM sales
  GROUP BY product
  ORDER BY total_sales DESC
  LIMIT 10
`);

console.log('Top 10 products:', result.rows);
await reader.close();

React Integration

Displaying App Data

import { OxyClient, createConfig } from '@oxy/sdk';
import { useEffect, useState } from 'react';

const client = new OxyClient(createConfig());

function Dashboard() {
  const [data, setData] = useState(null);

  useEffect(() => {
    client.getAppData('dashboard.app.yml')
      .then(result => setData(result.data))
      .catch(console.error);
  }, []);

  if (!data) return <div>Loading...</div>;

  return (
    <div>
      <h1>Dashboard</h1>
      {/* Render your data */}
    </div>
  );
}

Displaying Parquet Data

import { ParquetReader } from '@oxy/sdk';

function DataTable({ filePath }: { filePath: string }) {
  const [data, setData] = useState(null);

  useEffect(() => {
    async function loadData() {
      const blob = await client.getFile(filePath);
      const reader = new ParquetReader();
      await reader.registerParquet(blob);
      const result = await reader.getAll(100);
      setData(result);
      await reader.close();
    }
    loadData();
  }, [filePath]);

  // Render table...
}

Use with v0 and Other Sandbox Services

Perfect for integrating Oxy data into v0-generated apps or other sandbox environments:

// In your v0 app
import { OxyClient, createConfig, readParquet } from '@oxy/sdk';

// Configure with environment variables set in v0 project settings
const client = new OxyClient(createConfig());

export async function fetchDashboardData() {
  const [sales, customers] = await Promise.all([
    client.getAppData('apps/sales.app.yml'),
    client.getAppData('apps/customers.app.yml'),
  ]);

  return { sales: sales.data, customers: customers.data };
}

export function getSalesChartUrl() {
  return client.getFileUrl('charts/sales-overview.png');
}

API Reference

OxyClient

`constructor(config: OxyConfig)`

Creates a new Oxy client instance.

`listApps(): Promise<AppItem[]>`

Lists all apps in the project.

`getAppData(appPath: string): Promise<AppDataResponse>`

Gets data for a specific app (with caching).

`runApp(appPath: string): Promise<AppDataResponse>`

Runs an app and returns fresh data (bypasses cache).

`getDisplays(appPath: string): Promise<GetDisplaysResponse>`

Gets display configurations for an app.

`getFile(filePath: string): Promise<Blob>`

Fetches a file from the app state directory.

`getFileUrl(filePath: string): string`

Returns a URL for direct file access.

ParquetReader

`registerParquet(blob: Blob): Promise<void>`

Registers a Parquet file for querying.

`query(sql: string): Promise<QueryResult>`

Executes a SQL query against the Parquet data.

`getAll(limit?: number): Promise<QueryResult>`

Gets all data from the Parquet file.

`getSchema(): Promise<QueryResult>`

Gets schema information for the Parquet file.

`count(): Promise<number>`

Returns the row count.

`close(): Promise<void>`

Closes the reader and cleans up resources.

Helper Functions

`createConfig(overrides?: Partial<OxyConfig>): OxyConfig`

Creates configuration from environment variables with optional overrides.

`queryParquet(blob: Blob, sql?: string): Promise<QueryResult>`

Quick helper to query a Parquet blob.

`readParquet(blob: Blob, limit?: number): Promise<QueryResult>`

Quick helper to read all data from a Parquet blob.

Environment Variables

OXY_URL - Base URL of the Oxy API (required)
OXY_API_KEY - API key for authentication (required)
OXY_PROJECT_ID - Project UUID (required)
OXY_BRANCH - Branch name (optional)

Examples

See the examples directory for more detailed examples:

basic-usage.ts - Basic SDK usage
parquet-usage.ts - Parquet file reading
react-example.tsx - React integration
react-parquet.tsx - React with Parquet
v0-integration.ts - v0 sandbox integration

Building and Publishing

# Install dependencies
npm install

# Build the SDK
npm run build

# Type check
npm run typecheck

# Lint
npm run lint

# Publish to npm (beta)
npm run publish:beta

# Publish to npm (latest)
npm run publish:latest

License

MIT

Support

For issues and questions, please visit GitHub Issues.

@oxy-hq/sdk