@oxy-hq/sdk 1.0.0 → 2.0.0

package/README.md

@@ -1,482 +1,103 @@
-# Oxy TypeScript SDK
+# @oxy-hq/sdk
 
-Official TypeScript/JavaScript SDK for interacting with the Oxy data platform.
+React SDK for building **customer-app bundles** on the [Oxy](https://oxy.tech)
+platform. A bundle is a normal Vite + React app that reads from its linked oxy
+project — raw SQL, the semantic layer, agents, and procedures — through a
+small set of hooks, plus a couple of drop-in components.
 
-## Features
+> **v2 is a complete rewrite.** The v1 stack (`OxyClient` / `OxySDK`, the
+> Parquet/DuckDB-WASM reader, postMessage auth) is gone. Bundles now talk to
+> `/api/projects/:id/*` exclusively. See `CHANGELOG.md`.
 
-- 🚀 **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
-
-```bash
-npm install @oxy/sdk
-# or
-yarn add @oxy/sdk
-# or
-pnpm add @oxy/sdk
-```
-
-For Parquet file support, also install DuckDB-WASM:
-
-```bash
-npm install @duckdb/duckdb-wasm
-```
-
-## Quick Start
-
-### Basic Usage
-
-```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 { 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 sdk = await OxySDK.create({
-  parentOrigin: "https://app.example.com",
-  projectId: "your-project-uuid",
-});
-
-await sdk.loadAppData("dashboard.app.yml");
-const result = await sdk.query("SELECT * FROM my_table LIMIT 10");
-```
-
-**Parent window setup:**
-
-```typescript
-window.addEventListener("message", (event) => {
-  if (event.data.type !== "OXY_AUTH_REQUEST") return;
-  if (event.origin !== "https://your-iframe-app.com") return;
-
-  event.source.postMessage(
-    {
-      type: "OXY_AUTH_RESPONSE",
-      version: "1.0",
-      requestId: event.data.requestId,
-      apiKey: getUserApiKey(),
-      projectId: "your-project-uuid",
-      baseUrl: "https://api.oxy.tech",
-    },
-    event.origin,
-  );
-});
-```
-
-### Environment Variables
+## Install
 
 ```bash
-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
+pnpm add @oxy-hq/sdk @oxy-hq/vite-plugin
 ```
 
-Use `createConfig()` to load from environment:
+`react` (^19) is a peer dependency. `@oxy-hq/vite-plugin` wires the served
+base path, copies `oxy-app.json` into the build, and injects the dev identity
+shim — drop it into `vite.config.ts`:
 
-```typescript
-import { OxySDK, createConfig } from "@oxy/sdk";
+```ts
+import oxyApp from "@oxy-hq/vite-plugin";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
 
-const sdk = new OxySDK(createConfig());
+export default defineConfig({ plugins: [react(), oxyApp()] });
 ```
 
-## React Integration
+## Quick start
 
-### Using React Context (Recommended)
-
-The SDK provides `OxyProvider` and `useOxy` hooks for easy integration:
+Wrap your tree in `<OxyAppProvider>` (it resolves the app's identity), then
+read data with hooks:
 
 ```tsx
-import { OxyProvider, useOxy, createConfig } from "@oxy/sdk";
-import { useEffect, useState } from "react";
-
-// Wrap your app with OxyProvider
-function App() {
-  return (
-    <OxyProvider config={createConfig()}>
-      <Dashboard />
-    </OxyProvider>
-  );
-}
+import { OxyAppProvider, useQuery, OxyChat } from "@oxy-hq/sdk";
 
-// Access SDK in child components
 function Dashboard() {
-  const { sdk, isLoading, error } = useOxy();
-  const [data, setData] = useState(null);
-
-  useEffect(() => {
-    if (sdk) {
-      sdk
-        .loadAppData("dashboard.app.yml")
-        .then(() => sdk.query("SELECT * FROM my_table LIMIT 100"))
-        .then(setData);
-    }
-  }, [sdk]);
-
-  if (isLoading) return <div>Initializing SDK...</div>;
-  if (error) return <div>Error: {error.message}</div>;
-  if (!data) return <div>Loading data...</div>;
-
+  const { rows, isLoading, error } = useQuery({
+    sql: "SELECT Store, SUM(Weekly_Sales) AS sales FROM oxymart GROUP BY 1 ORDER BY 2 DESC LIMIT 5"
+  });
+  if (isLoading) return <p>Loading…</p>;
+  if (error) return <p>{error.message}</p>;
   return (
-    <div>
-      <h1>Dashboard</h1>
-      <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>
+    <>
+      <table>{rows.map((r) => <tr key={r.Store}><td>{r.Store}</td><td>{r.sales}</td></tr>)}</table>
+      <OxyChat agentId="analytics" />
+    </>
   );
 }
-```
-
-### Iframe with PostMessage Auth
 
-```tsx
-import { OxyProvider, useOxySDK } from "@oxy/sdk";
-
-function App() {
+export function App() {
   return (
-    <OxyProvider useAsync config={{ parentOrigin: "https://app.example.com" }}>
+    <OxyAppProvider fallback={<p>Loading…</p>}>
       <Dashboard />
-    </OxyProvider>
+    </OxyAppProvider>
   );
 }
-
-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 { OxySDK, createConfig } from '@oxy/sdk';
-import { useEffect, useState } from 'react';
-
-const sdk = new OxySDK(createConfig());
-
-function Dashboard() {
-  const [data, setData] = useState(null);
-
-  useEffect(() => {
-    sdk.loadAppData('dashboard.app.yml')
-      .then(() => sdk.query('SELECT * FROM my_table LIMIT 100'))
-      .then(setData);
-  }, []);
-
-  return <div>{/* render data */}</div>;
-}
-```
-
-## Use with v0 and Sandbox Services
-
-**For AI Assistants (v0.dev, Cursor, etc.):** See [.v0/rules.md](.v0/rules.md) and [.cursorrules](.cursorrules) for integration guidelines.
-
-```typescript
-import { OxySDK, createConfig } from "@oxy/sdk";
-
-const sdk = new OxySDK(createConfig());
-
-export async function getDashboardData() {
-  await sdk.loadAppData("dashboard.app.yml");
-
-  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 getChartUrl() {
-  return sdk.getClient().getFileUrl("charts/sales-overview.png");
-}
-```
-
-## API Reference
-
-### OxySDK (Unified Interface)
-
-The `OxySDK` class combines `OxyClient` and `ParquetReader` into a single, easy-to-use interface.
-
-#### `constructor(config: OxyConfig)`
-
-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.
-
-```typescript
-const result = await sdk.query("SELECT * FROM sales WHERE amount > 1000");
-```
-
-#### `async getAll(tableName: string, limit?: number): Promise<QueryResult>`
-
-Gets all data from a loaded table.
-
-```typescript
-const data = await sdk.getAll("sales", 100);
-```
-
-#### `async getSchema(tableName: string): Promise<QueryResult>`
-
-Gets schema information for a loaded table.
-
-#### `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();
-```
-
-#### `getReader(): ParquetReader`
-
-Returns the underlying `ParquetReader` for advanced operations.
-
-#### `async close(): Promise<void>`
-
-Closes and cleans up all resources.
-
-### React Hooks
-
-#### `OxyProvider`
-
-Provider component that initializes and provides OxySDK to child components.
-
-**Props:**
-
-- `config?: Partial<OxyConfig>` - SDK configuration
-- `useAsync?: boolean` - If true, uses async initialization (supports postMessage auth)
-- `appPath?: string` - Optional app path to load initial app data upon initialization
-- `files?: Record<string, string>` - Optional initial files to preload as a mapping of table name to file path
-- `onReady?: (sdk: OxySDK) => void` - Called when SDK is initialized
-- `onError?: (error: Error) => void` - Called on initialization error
-- `loadingFallback?: ReactNode` - Rendered while the SDK is initializing (replaces `children` during load)
-- `errorFallback?: ReactNode | ((error: Error) => ReactNode)` - Rendered when initialization fails; can be a node or a render function that receives the error
-
-```tsx
-<OxyProvider
-  config={createConfig()}
-  loadingFallback={<div>Loading SDK...</div>}
-  errorFallback={(error) => <div>Failed to initialize: {error.message}</div>}
->
-  <YourApp />
-</OxyProvider>
-```
-
-#### `useOxy()`
-
-Hook to access SDK, loading state, and errors.
-
-```tsx
-const { sdk, isLoading, error } = useOxy();
-```
-
-Returns:
-
-- `sdk: OxySDK | null` - The SDK instance (null if not ready)
-- `isLoading: boolean` - True while initializing
-- `error: Error | null` - Initialization error if any
-
-#### `useOxySDK()`
-
-Hook that returns SDK directly or throws if not ready. Useful when you know SDK should be initialized.
-
-```tsx
-const sdk = useOxySDK(); // Throws if not ready
-```
-
-### Advanced: OxyClient
-
-For advanced use cases, access the underlying client via `sdk.getClient()`:
-
-```typescript
-const client = sdk.getClient();
-await client.listApps();
-await client.getDisplays("my-app.app.yml");
-const blob = await client.getFile("path/to/file.parquet");
-```
-
-### Advanced: ParquetReader
-
-For advanced use cases, access the underlying reader via `sdk.getReader()`:
-
-```typescript
-const reader = sdk.getReader();
-await reader.registerParquet(customBlob, "custom_table");
 ```
 
-Or use standalone:
-
-```typescript
-import { ParquetReader } from "@oxy/sdk";
+## Identity (`oxy-app.json`)
 
-const reader = new ParquetReader();
-await reader.registerParquet(blob1, "table1");
-await reader.registerParquet(blob2, "table2");
+Every bundle ships an identity-only manifest at its project root (next to
+`vite.config.ts`, **not** under `public/`):
 
-const result = await reader.query("SELECT * FROM table1 JOIN table2 ON ...");
-await reader.close();
+```json
+{ "schemaVersion": 2, "slug": "store-pulse", "orgSlug": "acme", "name": "Store Pulse" }
 ```
 
-## Environment Variables
+When oxy serves the bundle it injects the authoritative identity as
+`window.__OXY_APP__`; `OxyAppProvider` reads injection first and the manifest
+second. There is **no API key in the bundle** — requests are authorized by the
+viewer's oxy session (same-origin cookie) or, in cross-origin local dev, a
+bearer token the dev proxy attaches. A bundle can't read data its viewer
+couldn't already read.
 
-- `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)
+## API
 
-## Examples
+| Export | What it does |
+| --- | --- |
+| `OxyAppProvider` | Resolves identity, provides it via context. `fallback` renders while loading; `errorFallback` gets a structured error report. |
+| `useQuery({ sql })` | Inline SQL → rows. `SELECT`/`WITH` only, 10k-row cap. |
+| `useSemanticQuery({ topic, dimensions, measures, … })` | Semantic-layer query compiled by airlayer. |
+| `useAgentRun({ agentId })` | `.ask(question)` starts an analytics agent run; streams events over SSE; `.cancel()`. |
+| `useProcedureRun({ procedureId })` | Start a long-running procedure, poll, cancel (beta). |
+| `<OxyChat agentId="…" />` | Drop-in chat UI over `useAgentRun`. |
+| `<OxyAnswer … />` | Renders markdown + SQL artifacts + thread link. URL schemes are allowlisted (rejects `javascript:` etc.). |
+| `OxyApiError` | Structured `{ message, code? }` server-error envelope. |
 
-See the [examples](./examples) directory for more detailed examples:
+Hooks fail loudly if called outside `<OxyAppProvider>`. The default fetcher
+sends `credentials: "include"` so same-origin (served-by-oxy) calls carry the
+session cookie automatically.
 
-## Building and Publishing
-
-```bash
-# Install dependencies
-npm install
+## Docs
 
-# 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
-```
+- Hands-on dev + deploy guide: `docs/local-development.md` in the
+  [`oxy-hq/customer-apps`](https://github.com/oxy-hq/customer-apps) repo.
+- SDK flow reference: `docs/sdk-flow.md` in that repo.
+- Platform internals: `internal-docs/customer-apps.md` in oxygen-internal.
 
 ## License
 
 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)