@oxy-hq/sdk 0.2.5 → 1.0.0

package/README.md

@@ -37,12 +37,12 @@ import { OxySDK } from "@oxy/sdk";
 const sdk = new OxySDK({
   apiKey: "your-api-key",
   projectId: "your-project-id",
-  baseUrl: "https://api.oxy.tech"
+  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');
+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(`
@@ -65,10 +65,10 @@ 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');
+await sdk.loadAppData("dashboard.app.yml");
 
 // Query the loaded tables
-const result = await sdk.query('SELECT * FROM my_table LIMIT 10');
+const result = await sdk.query("SELECT * FROM my_table LIMIT 10");
 ```
 
 ### Iframe Usage (PostMessage Authentication)
@@ -81,11 +81,11 @@ 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"
+  projectId: "your-project-uuid",
 });
 
-await sdk.loadAppData('dashboard.app.yml');
-const result = await sdk.query('SELECT * FROM my_table LIMIT 10');
+await sdk.loadAppData("dashboard.app.yml");
+const result = await sdk.query("SELECT * FROM my_table LIMIT 10");
 ```
 
 **Parent window setup:**
@@ -95,14 +95,17 @@ 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);
+  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,
+  );
 });
 ```
 
@@ -130,8 +133,8 @@ const sdk = new OxySDK(createConfig());
 The SDK provides `OxyProvider` and `useOxy` hooks for easy integration:
 
 ```tsx
-import { OxyProvider, useOxy, createConfig } from '@oxy/sdk';
-import { useEffect, useState } from 'react';
+import { OxyProvider, useOxy, createConfig } from "@oxy/sdk";
+import { useEffect, useState } from "react";
 
 // Wrap your app with OxyProvider
 function App() {
@@ -149,8 +152,9 @@ function Dashboard() {
 
   useEffect(() => {
     if (sdk) {
-      sdk.loadAppData('dashboard.app.yml')
-        .then(() => sdk.query('SELECT * FROM my_table LIMIT 100'))
+      sdk
+        .loadAppData("dashboard.app.yml")
+        .then(() => sdk.query("SELECT * FROM my_table LIMIT 100"))
         .then(setData);
     }
   }, [sdk]);
@@ -165,13 +169,17 @@ function Dashboard() {
       <table>
         <thead>
           <tr>
-            {data.columns.map(col => <th key={col}>{col}</th>)}
+            {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>)}
+              {row.map((cell, j) => (
+                <td key={j}>{String(cell)}</td>
+              ))}
             </tr>
           ))}
         </tbody>
@@ -184,14 +192,11 @@ function Dashboard() {
 ### Iframe with PostMessage Auth
 
 ```tsx
-import { OxyProvider, useOxySDK } from '@oxy/sdk';
+import { OxyProvider, useOxySDK } from "@oxy/sdk";
 
 function App() {
   return (
-    <OxyProvider
-      useAsync
-      config={{ parentOrigin: 'https://app.example.com' }}
-    >
+    <OxyProvider useAsync config={{ parentOrigin: "https://app.example.com" }}>
       <Dashboard />
     </OxyProvider>
   );
@@ -202,8 +207,9 @@ function Dashboard() {
   const [data, setData] = useState(null);
 
   useEffect(() => {
-    sdk.loadFile('data/sales.parquet', 'sales')
-      .then(() => sdk.query('SELECT * FROM sales LIMIT 100'))
+    sdk
+      .loadFile("data/sales.parquet", "sales")
+      .then(() => sdk.query("SELECT * FROM sales LIMIT 100"))
       .then(setData);
   }, [sdk]);
 
@@ -274,8 +280,8 @@ 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'
+  parentOrigin: "https://app.example.com",
+  projectId: "your-project-id",
 });
 ```
 
@@ -284,7 +290,7 @@ const sdk = await OxySDK.create({
 Loads a Parquet file from Oxy and registers it for SQL queries.
 
 ```typescript
-await sdk.loadFile('data/sales.parquet', 'sales');
+await sdk.loadFile("data/sales.parquet", "sales");
 ```
 
 #### `async loadFiles(files: Array<{filePath: string, tableName: string}>): Promise<void>`
@@ -293,8 +299,8 @@ Loads multiple Parquet files at once.
 
 ```typescript
 await sdk.loadFiles([
-  { filePath: 'data/sales.parquet', tableName: 'sales' },
-  { filePath: 'data/customers.parquet', tableName: 'customers' }
+  { filePath: "data/sales.parquet", tableName: "sales" },
+  { filePath: "data/customers.parquet", tableName: "customers" },
 ]);
 ```
 
@@ -303,9 +309,9 @@ await sdk.loadFiles([
 Loads all data from an app's data container. Uses container keys as table names.
 
 ```typescript
-const data = await sdk.loadAppData('dashboard.app.yml');
+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');
+const result = await sdk.query("SELECT * FROM my_table");
 ```
 
 #### `async query(sql: string): Promise<QueryResult>`
@@ -313,7 +319,7 @@ const result = await sdk.query('SELECT * FROM my_table');
 Executes a SQL query against loaded data.
 
 ```typescript
-const result = await sdk.query('SELECT * FROM sales WHERE amount > 1000');
+const result = await sdk.query("SELECT * FROM sales WHERE amount > 1000");
 ```
 
 #### `async getAll(tableName: string, limit?: number): Promise<QueryResult>`
@@ -321,7 +327,7 @@ const result = await sdk.query('SELECT * FROM sales WHERE amount > 1000');
 Gets all data from a loaded table.
 
 ```typescript
-const data = await sdk.getAll('sales', 100);
+const data = await sdk.getAll("sales", 100);
 ```
 
 #### `async getSchema(tableName: string): Promise<QueryResult>`
@@ -355,13 +361,22 @@ Closes and cleans up all resources.
 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()}>
+<OxyProvider
+  config={createConfig()}
+  loadingFallback={<div>Loading SDK...</div>}
+  errorFallback={(error) => <div>Failed to initialize: {error.message}</div>}
+>
   <YourApp />
 </OxyProvider>
 ```
@@ -375,6 +390,7 @@ 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
@@ -394,8 +410,8 @@ 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');
+await client.getDisplays("my-app.app.yml");
+const blob = await client.getFile("path/to/file.parquet");
 ```
 
 ### Advanced: ParquetReader
@@ -404,7 +420,7 @@ For advanced use cases, access the underlying reader via `sdk.getReader()`:
 
 ```typescript
 const reader = sdk.getReader();
-await reader.registerParquet(customBlob, 'custom_table');
+await reader.registerParquet(customBlob, "custom_table");
 ```
 
 Or use standalone:
@@ -413,10 +429,10 @@ Or use standalone:
 import { ParquetReader } from "@oxy/sdk";
 
 const reader = new ParquetReader();
-await reader.registerParquet(blob1, 'table1');
-await reader.registerParquet(blob2, 'table2');
+await reader.registerParquet(blob1, "table1");
+await reader.registerParquet(blob2, "table2");
 
-const result = await reader.query('SELECT * FROM table1 JOIN table2 ON ...');
+const result = await reader.query("SELECT * FROM table1 JOIN table2 ON ...");
 await reader.close();
 ```
 

package/dist/index.cjs

@@ -1,11 +1,25 @@
 // @oxy/sdk - TypeScript SDK for Oxy data platform
-//#region rolldown:runtime
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+//#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (!no_symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
 var __copyProps = (to, from, except, desc) => {
 	if (from && typeof from === "object" || typeof from === "function") {
 		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
@@ -26,7 +40,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
-const require_postMessage = require('./postMessage-B1J0jDRN.cjs');
+const require_postMessage = require('./postMessage-Cb5PCtcE.cjs');
 let _duckdb_duckdb_wasm = require("@duckdb/duckdb-wasm");
 _duckdb_duckdb_wasm = __toESM(_duckdb_duckdb_wasm);
 let react = require("react");
@@ -107,13 +121,13 @@ function createConfig(overrides) {
 * ```
 */
 async function createConfigAsync(overrides) {
-	const { isInIframe: isInIframe$1 } = await Promise.resolve().then(() => require("./postMessage-BSNS3ccd.cjs"));
+	const { isInIframe } = await Promise.resolve().then(() => require("./postMessage-Cb5PCtcE.cjs")).then((n) => n.postMessage_exports);
 	let baseUrl = overrides?.baseUrl || getEnvVar("OXY_URL");
 	let apiKey = overrides?.apiKey || getEnvVar("OXY_API_KEY");
 	let projectId = overrides?.projectId || getEnvVar("OXY_PROJECT_ID");
 	const disableAutoAuth = overrides?.disableAutoAuth ?? false;
 	const parentOrigin = overrides?.parentOrigin || (window?.location.ancestorOrigins?.[0] ? window.location.ancestorOrigins[0] : "https://app.oxy.tech");
-	if (!disableAutoAuth && isInIframe$1() && !apiKey) if (!parentOrigin) logWarningAboutMissingParentOrigin();
+	if (!disableAutoAuth && isInIframe() && !apiKey) if (!parentOrigin) logWarningAboutMissingParentOrigin();
 	else apiKey = await attemptPostMessageAuth(parentOrigin, overrides?.timeout || 5e3, apiKey, projectId, baseUrl).then((result) => {
 		if (result.projectId) projectId = result.projectId;
 		if (result.baseUrl) baseUrl = result.baseUrl;
@@ -128,8 +142,8 @@ function logWarningAboutMissingParentOrigin() {
 	console.warn("[Oxy SDK] Running in iframe without API key and no parentOrigin specified. PostMessage authentication will be skipped. Provide parentOrigin config to enable automatic authentication.");
 }
 async function attemptPostMessageAuth(parentOrigin, timeout, currentApiKey, currentProjectId, currentBaseUrl) {
-	const { requestAuthFromParent: requestAuthFromParent$1 } = await Promise.resolve().then(() => require("./postMessage-BSNS3ccd.cjs"));
-	const authResult = await requestAuthFromParent$1({
+	const { requestAuthFromParent } = await Promise.resolve().then(() => require("./postMessage-Cb5PCtcE.cjs")).then((n) => n.postMessage_exports);
+	const authResult = await requestAuthFromParent({
 		parentOrigin,
 		timeout
 	});
@@ -459,11 +473,12 @@ var OxyClient = class OxyClient {
 		return new OxyClient(await createConfigAsync(config));
 	}
 	/**
-	* Encodes a file path to base64 for use in API URLs
+	* Encodes a file path to base64 for use in API URLs.
+	* Handles Unicode characters (e.g., emojis) properly in both Node.js and browser.
 	*/
 	encodePathBase64(path) {
 		if (typeof Buffer !== "undefined") return Buffer.from(path).toString("base64");
-		else return btoa(path);
+		else return btoa(encodeURIComponent(path).replace(/%([0-9A-F]{2})/g, (_, p1) => String.fromCharCode(parseInt(p1, 16))));
 	}
 	/**
 	* Makes an authenticated HTTP request to the Oxy API
@@ -474,7 +489,7 @@ var OxyClient = class OxyClient {
 			"Content-Type": "application/json",
 			...options.headers || {}
 		};
-		if (this.config.apiKey) headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+		if (this.config.apiKey) headers.Authorization = `Bearer ${this.config.apiKey}`;
 		const controller = new AbortController();
 		const timeoutId = setTimeout(() => controller.abort(), this.config.timeout || 3e4);
 		try {
@@ -492,7 +507,7 @@ var OxyClient = class OxyClient {
 					details: errorText
 				};
 			}
-			if ((typeof options.headers === "object" && options.headers !== null ? options.headers["Accept"] : void 0) === "application/octet-stream") return response.blob();
+			if ((typeof options.headers === "object" && options.headers !== null ? options.headers.Accept : void 0) === "application/octet-stream") return response.blob();
 			return response.json();
 		} catch (error) {
 			clearTimeout(timeoutId);
@@ -522,7 +537,7 @@ var OxyClient = class OxyClient {
 	*/
 	async listApps() {
 		const query = this.buildQueryParams();
-		return this.request(`/${this.config.projectId}/app${query}`);
+		return this.request(`/${this.config.projectId}/apps${query}`);
 	}
 	/**
 	* Gets data for a specific app
@@ -543,7 +558,7 @@ var OxyClient = class OxyClient {
 	async getAppData(appPath) {
 		const pathb64 = this.encodePathBase64(appPath);
 		const query = this.buildQueryParams();
-		return this.request(`/${this.config.projectId}/app/${pathb64}${query}`);
+		return this.request(`/${this.config.projectId}/apps/${pathb64}${query}`);
 	}
 	/**
 	* Runs an app and returns fresh data (bypasses cache)
@@ -560,7 +575,7 @@ var OxyClient = class OxyClient {
 	async runApp(appPath) {
 		const pathb64 = this.encodePathBase64(appPath);
 		const query = this.buildQueryParams();
-		return this.request(`/${this.config.projectId}/app/${pathb64}/run${query}`, { method: "POST" });
+		return this.request(`/${this.config.projectId}/apps/${pathb64}/run${query}`, { method: "POST" });
 	}
 	/**
 	* Gets display configurations for an app
@@ -583,7 +598,7 @@ var OxyClient = class OxyClient {
 	async getDisplays(appPath) {
 		const pathb64 = this.encodePathBase64(appPath);
 		const query = this.buildQueryParams();
-		return this.request(`/${this.config.projectId}/app/${pathb64}/displays${query}`);
+		return this.request(`/${this.config.projectId}/apps/${pathb64}/displays${query}`);
 	}
 	/**
 	* Gets a file from the app state directory (e.g., generated charts, images)
@@ -617,7 +632,7 @@ var OxyClient = class OxyClient {
 	async getFile(filePath) {
 		const pathb64 = this.encodePathBase64(filePath);
 		const query = this.buildQueryParams();
-		return this.request(`/${this.config.projectId}/app/file/${pathb64}${query}`, { headers: { Accept: "application/octet-stream" } });
+		return this.request(`/${this.config.projectId}/apps/file/${pathb64}${query}`, { headers: { Accept: "application/octet-stream" } });
 	}
 	/**
 	* Gets a file URL for direct browser access
@@ -639,7 +654,7 @@ var OxyClient = class OxyClient {
 	getFileUrl(filePath) {
 		const pathb64 = this.encodePathBase64(filePath);
 		const query = this.buildQueryParams();
-		return `${this.config.baseUrl}/${this.config.projectId}/app/file/${pathb64}${query}`;
+		return `${this.config.baseUrl}/${this.config.projectId}/apps/file/${pathb64}${query}`;
 	}
 	/**
 	* Fetches a parquet file and parses it into table data
@@ -949,8 +964,24 @@ const OxyContext = (0, react.createContext)(void 0);
 *   );
 * }
 * ```
+*
+* @example
+* ```tsx
+* // With loading and error slots
+* function App() {
+*   return (
+*     <OxyProvider
+*       config={createConfig()}
+*       loadingFallback={<div>Loading SDK...</div>}
+*       errorFallback={(error) => <div>Error: {error.message}</div>}
+*     >
+*       <Dashboard />
+*     </OxyProvider>
+*   );
+* }
+* ```
 */
-function OxyProvider({ children, config, useAsync = false, appPath, files, onReady, onError }) {
+function OxyProvider({ children, config, useAsync = false, appPath, files, onReady, onError, loadingFallback, errorFallback }) {
 	const [sdk, setSdk] = (0, react.useState)(null);
 	const [isLoading, setIsLoading] = (0, react.useState)(true);
 	const [error, setError] = (0, react.useState)(null);
@@ -981,11 +1012,11 @@ function OxyProvider({ children, config, useAsync = false, appPath, files, onRea
 					onReady?.(sdkInstance);
 				}
 			} catch (err) {
-				const error$1 = err instanceof Error ? err : /* @__PURE__ */ new Error("Failed to initialize SDK");
+				const error = err instanceof Error ? err : /* @__PURE__ */ new Error("Failed to initialize SDK");
 				if (mounted) {
-					setError(error$1);
+					setError(error);
 					setIsLoading(false);
-					onError?.(error$1);
+					onError?.(error);
 				}
 			}
 		}
@@ -1000,11 +1031,16 @@ function OxyProvider({ children, config, useAsync = false, appPath, files, onRea
 		onReady,
 		onError
 	]);
+	const content = (() => {
+		if (isLoading && loadingFallback !== void 0) return loadingFallback;
+		if (error && errorFallback !== void 0) return typeof errorFallback === "function" ? errorFallback(error) : errorFallback;
+		return children;
+	})();
 	return /* @__PURE__ */ react.default.createElement(OxyContext.Provider, { value: {
 		sdk,
 		isLoading,
 		error
-	} }, children);
+	} }, content);
 }
 /**
 * Hook to access OxySDK from child components
@@ -1079,6 +1115,7 @@ exports.PostMessageAuthInvalidOriginError = require_postMessage.PostMessageAuthI
 exports.PostMessageAuthInvalidResponseError = require_postMessage.PostMessageAuthInvalidResponseError;
 exports.PostMessageAuthNotInIframeError = require_postMessage.PostMessageAuthNotInIframeError;
 exports.PostMessageAuthTimeoutError = require_postMessage.PostMessageAuthTimeoutError;
+exports.__exportAll = __exportAll;
 exports.createConfig = createConfig;
 exports.createConfigAsync = createConfigAsync;
 exports.initializeDuckDB = initializeDuckDB;