@oxy-hq/sdk 0.1.5 → 0.2.0

package/README.md

@@ -28,264 +28,397 @@ npm install @duckdb/duckdb-wasm
 
 ## Quick Start
 
-### Option 1: Client-Side Usage (Iframe with PostMessage)
+### Basic Usage
 
-Perfect for embedding dashboards in iframes (e.g., v0.dev, sandboxed environments):
+```typescript
+import { OxySDK } from "@oxy/sdk";
+
+// Create SDK instance
+const sdk = new OxySDK({
+  apiKey: "your-api-key",
+  projectId: "your-project-id",
+  baseUrl: "https://api.oxy.tech"
+});
+
+// Load parquet files and query them
+await sdk.loadFile('data/sales.parquet', 'sales');
+await sdk.loadFile('data/customers.parquet', 'customers');
+
+// Query with SQL - supports joins across multiple tables
+const result = await sdk.query(`
+  SELECT s.product, s.amount, c.name as customer_name
+  FROM sales s
+  JOIN customers c ON s.customer_id = c.id
+  WHERE s.amount > 1000
+  ORDER BY s.amount DESC
+`);
+
+console.log(result.rows);
+await sdk.close();
+```
+
+### Load App Data Automatically
 
 ```typescript
-import { OxyClient } from '@oxy/sdk';
+import { OxySDK, createConfig } from "@oxy/sdk";
+
+const sdk = new OxySDK(createConfig());
+
+// Loads all data from the app and registers tables
+await sdk.loadAppData('dashboard.app.yml');
+
+// Query the loaded tables
+const result = await sdk.query('SELECT * FROM my_table LIMIT 10');
+```
+
+### Iframe Usage (PostMessage Authentication)
+
+For embedding in iframes (e.g., v0.dev, sandboxed environments):
+
+```typescript
+import { OxySDK } 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'
+const sdk = await OxySDK.create({
+  parentOrigin: "https://app.example.com",
+  projectId: "your-project-uuid"
 });
 
-// Use the client
-const apps = await client.listApps();
-console.log('Available apps:', apps);
+await sdk.loadAppData('dashboard.app.yml');
+const result = await sdk.query('SELECT * FROM my_table LIMIT 10');
 ```
 
-**Parent window setup** (one-time):
-```typescript
-// In parent window that hosts the iframe
-window.addEventListener('message', (event) => {
-  if (event.data.type !== 'OXY_AUTH_REQUEST') return;
+**Parent window setup:**
 
-  // Validate iframe origin
-  if (event.origin !== 'https://your-iframe-app.com') return;
+```typescript
+window.addEventListener("message", (event) => {
+  if (event.data.type !== "OXY_AUTH_REQUEST") return;
+  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',
+    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'
+    apiKey: getUserApiKey(),
+    projectId: "your-project-uuid",
+    baseUrl: "https://api.oxy.tech"
   }, event.origin);
 });
 ```
 
-### Option 2: Traditional Usage (Environment Variables)
-
-Set up environment variables:
+### Environment Variables
 
 ```bash
-export OXY_URL="https://api.oxy.tech"  # or your self-hosted URL
+export OXY_URL="https://api.oxy.tech"
 export OXY_API_KEY="your-api-key"
 export OXY_PROJECT_ID="your-project-uuid"
 export OXY_BRANCH="main"  # optional
 ```
 
-Basic usage:
+Use `createConfig()` to load from environment:
 
 ```typescript
-import { OxyClient, createConfig } from '@oxy/sdk';
-
-// Create configuration from environment variables
-const config = createConfig();
-
-// Initialize the client
-const client = new OxyClient(config);
+import { OxySDK, createConfig } from "@oxy/sdk";
 
-// 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
-
-```typescript
-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();
+const sdk = new OxySDK(createConfig());
 ```
 
 ## React Integration
 
-### Displaying App Data
+### Using React Context (Recommended)
 
-```typescript
-import { OxyClient, createConfig } from '@oxy/sdk';
+The SDK provides `OxyProvider` and `useOxy` hooks for easy integration:
+
+```tsx
+import { OxyProvider, useOxy, createConfig } from '@oxy/sdk';
 import { useEffect, useState } from 'react';
 
-const client = new OxyClient(createConfig());
+// Wrap your app with OxyProvider
+function App() {
+  return (
+    <OxyProvider config={createConfig()}>
+      <Dashboard />
+    </OxyProvider>
+  );
+}
 
+// Access SDK in child components
 function Dashboard() {
+  const { sdk, isLoading, error } = useOxy();
   const [data, setData] = useState(null);
 
   useEffect(() => {
-    client.getAppData('dashboard.app.yml')
-      .then(result => setData(result.data))
-      .catch(console.error);
-  }, []);
+    if (sdk) {
+      sdk.loadAppData('dashboard.app.yml')
+        .then(() => sdk.query('SELECT * FROM my_table LIMIT 100'))
+        .then(setData);
+    }
+  }, [sdk]);
 
-  if (!data) return <div>Loading...</div>;
+  if (isLoading) return <div>Initializing SDK...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  if (!data) return <div>Loading data...</div>;
 
   return (
     <div>
       <h1>Dashboard</h1>
-      {/* Render your data */}
+      <table>
+        <thead>
+          <tr>
+            {data.columns.map(col => <th key={col}>{col}</th>)}
+          </tr>
+        </thead>
+        <tbody>
+          {data.rows.map((row, i) => (
+            <tr key={i}>
+              {row.map((cell, j) => <td key={j}>{String(cell)}</td>)}
+            </tr>
+          ))}
+        </tbody>
+      </table>
     </div>
   );
 }
 ```
 
-### Displaying Parquet Data
+### Iframe with PostMessage Auth
+
+```tsx
+import { OxyProvider, useOxySDK } from '@oxy/sdk';
+
+function App() {
+  return (
+    <OxyProvider
+      useAsync
+      config={{ parentOrigin: 'https://app.example.com' }}
+    >
+      <Dashboard />
+    </OxyProvider>
+  );
+}
+
+function Dashboard() {
+  const sdk = useOxySDK(); // Throws if not ready
+  const [data, setData] = useState(null);
+
+  useEffect(() => {
+    sdk.loadFile('data/sales.parquet', 'sales')
+      .then(() => sdk.query('SELECT * FROM sales LIMIT 100'))
+      .then(setData);
+  }, [sdk]);
+
+  return <div>{/* render data */}</div>;
+}
+```
+
+### Without Context (Alternative)
 
 ```typescript
-import { ParquetReader } from '@oxy/sdk';
+import { OxySDK, createConfig } from '@oxy/sdk';
+import { useEffect, useState } from 'react';
 
-function DataTable({ filePath }: { filePath: string }) {
+const sdk = new OxySDK(createConfig());
+
+function Dashboard() {
   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]);
+    sdk.loadAppData('dashboard.app.yml')
+      .then(() => sdk.query('SELECT * FROM my_table LIMIT 100'))
+      .then(setData);
+  }, []);
 
-  // Render table...
+  return <div>{/* render data */}</div>;
 }
 ```
 
-## Use with v0 and Other Sandbox Services
+## Use with v0 and 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](.v0/rules.md) and [.cursorrules](.cursorrules) for integration guidelines.
 
 ```typescript
-// In your v0 app
-import { OxyClient, createConfig, readParquet } from '@oxy/sdk';
+import { OxySDK, createConfig } from "@oxy/sdk";
 
-// Configure with environment variables set in v0 project settings
-const client = new OxyClient(createConfig());
+const sdk = new OxySDK(createConfig());
 
-export async function fetchDashboardData() {
-  const [sales, customers] = await Promise.all([
-    client.getAppData('apps/sales.app.yml'),
-    client.getAppData('apps/customers.app.yml'),
-  ]);
+export async function getDashboardData() {
+  await sdk.loadAppData("dashboard.app.yml");
 
-  return { sales: sales.data, customers: customers.data };
+  return await sdk.query(`
+    SELECT s.*, c.name as customer_name
+    FROM sales s
+    LEFT JOIN customers c ON s.customer_id = c.id
+    ORDER BY s.date DESC
+    LIMIT 100
+  `);
 }
 
-export function getSalesChartUrl() {
-  return client.getFileUrl('charts/sales-overview.png');
+export function getChartUrl() {
+  return sdk.getClient().getFileUrl("charts/sales-overview.png");
 }
 ```
 
 ## API Reference
 
-### OxyClient
+### OxySDK (Unified Interface)
+
+The `OxySDK` class combines `OxyClient` and `ParquetReader` into a single, easy-to-use interface.
 
 #### `constructor(config: OxyConfig)`
 
-Creates a new Oxy client instance.
+Creates a new SDK instance.
+
+#### `static async create(config?: Partial<OxyConfig>): Promise<OxySDK>`
+
+Creates an SDK instance with async configuration (supports postMessage auth).
+
+```typescript
+const sdk = await OxySDK.create({
+  parentOrigin: 'https://app.example.com',
+  projectId: 'your-project-id'
+});
+```
+
+#### `async loadFile(filePath: string, tableName: string): Promise<void>`
+
+Loads a Parquet file from Oxy and registers it for SQL queries.
+
+```typescript
+await sdk.loadFile('data/sales.parquet', 'sales');
+```
+
+#### `async loadFiles(files: Array<{filePath: string, tableName: string}>): Promise<void>`
+
+Loads multiple Parquet files at once.
+
+```typescript
+await sdk.loadFiles([
+  { filePath: 'data/sales.parquet', tableName: 'sales' },
+  { filePath: 'data/customers.parquet', tableName: 'customers' }
+]);
+```
+
+#### `async loadAppData(appPath: string): Promise<DataContainer | null>`
+
+Loads all data from an app's data container. Uses container keys as table names.
+
+```typescript
+const data = await sdk.loadAppData('dashboard.app.yml');
+// Now query the tables using their container keys
+const result = await sdk.query('SELECT * FROM my_table');
+```
+
+#### `async query(sql: string): Promise<QueryResult>`
+
+Executes a SQL query against loaded data.
 
-#### `listApps(): Promise<AppItem[]>`
+```typescript
+const result = await sdk.query('SELECT * FROM sales WHERE amount > 1000');
+```
 
-Lists all apps in the project.
+#### `async getAll(tableName: string, limit?: number): Promise<QueryResult>`
 
-#### `getAppData(appPath: string): Promise<AppDataResponse>`
+Gets all data from a loaded table.
+
+```typescript
+const data = await sdk.getAll('sales', 100);
+```
 
-Gets data for a specific app (with caching).
+#### `async getSchema(tableName: string): Promise<QueryResult>`
 
-#### `runApp(appPath: string): Promise<AppDataResponse>`
+Gets schema information for a loaded table.
 
-Runs an app and returns fresh data (bypasses cache).
+#### `async count(tableName: string): Promise<number>`
+
+Gets row count for a loaded table.
+
+#### `getClient(): OxyClient`
+
+Returns the underlying `OxyClient` for advanced operations.
+
+```typescript
+const apps = await sdk.getClient().listApps();
+```
 
-#### `getDisplays(appPath: string): Promise<GetDisplaysResponse>`
+#### `getReader(): ParquetReader`
 
-Gets display configurations for an app.
+Returns the underlying `ParquetReader` for advanced operations.
 
-#### `getFile(filePath: string): Promise<Blob>`
+#### `async close(): Promise<void>`
 
-Fetches a file from the app state directory.
+Closes and cleans up all resources.
 
-#### `getFileUrl(filePath: string): string`
+### React Hooks
 
-Returns a URL for direct file access.
+#### `OxyProvider`
 
-### ParquetReader
+Provider component that initializes and provides OxySDK to child components.
 
-#### `registerParquet(blob: Blob): Promise<void>`
+**Props:**
+- `config?: Partial<OxyConfig>` - SDK configuration
+- `useAsync?: boolean` - If true, uses async initialization (supports postMessage auth)
+- `onReady?: (sdk: OxySDK) => void` - Called when SDK is initialized
+- `onError?: (error: Error) => void` - Called on initialization error
 
-Registers a Parquet file for querying.
+```tsx
+<OxyProvider config={createConfig()}>
+  <YourApp />
+</OxyProvider>
+```
 
-#### `query(sql: string): Promise<QueryResult>`
+#### `useOxy()`
 
-Executes a SQL query against the Parquet data.
+Hook to access SDK, loading state, and errors.
 
-#### `getAll(limit?: number): Promise<QueryResult>`
+```tsx
+const { sdk, isLoading, error } = useOxy();
+```
 
-Gets all data from the Parquet file.
+Returns:
+- `sdk: OxySDK | null` - The SDK instance (null if not ready)
+- `isLoading: boolean` - True while initializing
+- `error: Error | null` - Initialization error if any
 
-#### `getSchema(): Promise<QueryResult>`
+#### `useOxySDK()`
 
-Gets schema information for the Parquet file.
+Hook that returns SDK directly or throws if not ready. Useful when you know SDK should be initialized.
 
-#### `count(): Promise<number>`
+```tsx
+const sdk = useOxySDK(); // Throws if not ready
+```
 
-Returns the row count.
+### Advanced: OxyClient
 
-#### `close(): Promise<void>`
+For advanced use cases, access the underlying client via `sdk.getClient()`:
 
-Closes the reader and cleans up resources.
+```typescript
+const client = sdk.getClient();
+await client.listApps();
+await client.getDisplays('my-app.app.yml');
+const blob = await client.getFile('path/to/file.parquet');
+```
 
-### Helper Functions
+### Advanced: ParquetReader
 
-#### `createConfig(overrides?: Partial<OxyConfig>): OxyConfig`
+For advanced use cases, access the underlying reader via `sdk.getReader()`:
 
-Creates configuration from environment variables with optional overrides.
+```typescript
+const reader = sdk.getReader();
+await reader.registerParquet(customBlob, 'custom_table');
+```
 
-#### `queryParquet(blob: Blob, sql?: string): Promise<QueryResult>`
+Or use standalone:
 
-Quick helper to query a Parquet blob.
+```typescript
+import { ParquetReader } from "@oxy/sdk";
 
-#### `readParquet(blob: Blob, limit?: number): Promise<QueryResult>`
+const reader = new ParquetReader();
+await reader.registerParquet(blob1, 'table1');
+await reader.registerParquet(blob2, 'table2');
 
-Quick helper to read all data from a Parquet blob.
+const result = await reader.query('SELECT * FROM table1 JOIN table2 ON ...');
+await reader.close();
+```
 
 ## Environment Variables
 
@@ -298,12 +431,6 @@ Quick helper to read all data from a Parquet blob.
 
 See the [examples](./examples) directory for more detailed examples:
 
-- [basic-usage.ts](./examples/basic-usage.ts) - Basic SDK usage
-- [parquet-usage.ts](./examples/parquet-usage.ts) - Parquet file reading
-- [react-example.tsx](./examples/react-example.tsx) - React integration
-- [react-parquet.tsx](./examples/react-parquet.tsx) - React with Parquet
-- [v0-integration.ts](./examples/v0-integration.ts) - v0 sandbox integration
-
 ## Building and Publishing
 
 ```bash
@@ -333,3 +460,7 @@ MIT
 ## Support
 
 For issues and questions, please visit [GitHub Issues](https://github.com/dataframehq/oxy-internal/issues).
+
+### Local development with v0 or cloud service
+
+- Disable the local network access check [flag](chrome ://flags/#local-network-access-check)