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.

For AI Assistants (v0.dev, Cursor, etc.): See .v0/rules.md and .cursorrules for comprehensive integration guidelines.

// 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");
}

v0 Environment Setup

In your v0 project settings, configure these environment variables:

OXY_URL=https://api.oxy.tech
OXY_API_KEY=your-api-key-here
OXY_PROJECT_ID=your-project-uuid-here
OXY_BRANCH=main

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.

Local development with v0 or cloud service

Disable the local network access check [flag](chrome ://flags/#local-network-access-check)

@oxy-hq/sdk