@oxy-hq/sdk 0.1.6 → 0.2.1

package/dist/index.cjs

@@ -29,9 +29,22 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 const require_postMessage = require('./postMessage-B1J0jDRN.cjs');
 let _duckdb_duckdb_wasm = require("@duckdb/duckdb-wasm");
 _duckdb_duckdb_wasm = __toESM(_duckdb_duckdb_wasm);
+let react = require("react");
+react = __toESM(react);
 
 //#region src/config.ts
 /**
+* Safely get environment variable in both Node.js and browser environments
+*/
+function getEnvVar(name) {
+	if (typeof process !== "undefined" && process.env) return process.env[name];
+	if (typeof {} !== "undefined" && {}.env) {
+		const viteValue = {}.env[`VITE_${name}`];
+		if (viteValue !== void 0) return viteValue;
+		return {}.env[name];
+	}
+}
+/**
 * Creates an Oxy configuration from environment variables
 *
 * Environment variables:
@@ -45,16 +58,16 @@ _duckdb_duckdb_wasm = __toESM(_duckdb_duckdb_wasm);
 * @throws Error if required environment variables are missing
 */
 function createConfig(overrides) {
-	const baseUrl = overrides?.baseUrl || process.env.OXY_URL;
-	const apiKey = overrides?.apiKey || process.env.OXY_API_KEY;
-	const projectId = overrides?.projectId || process.env.OXY_PROJECT_ID;
+	const baseUrl = overrides?.baseUrl || getEnvVar("OXY_URL");
+	const apiKey = overrides?.apiKey || getEnvVar("OXY_API_KEY");
+	const projectId = overrides?.projectId || getEnvVar("OXY_PROJECT_ID");
 	if (!baseUrl) throw new Error("OXY_URL environment variable or baseUrl config is required");
 	if (!projectId) throw new Error("OXY_PROJECT_ID environment variable or projectId config is required");
 	return {
 		baseUrl: baseUrl.replace(/\/$/, ""),
 		apiKey,
 		projectId,
-		branch: overrides?.branch || process.env.OXY_BRANCH,
+		branch: overrides?.branch || getEnvVar("OXY_BRANCH"),
 		timeout: overrides?.timeout || 3e4,
 		parentOrigin: overrides?.parentOrigin,
 		disableAutoAuth: overrides?.disableAutoAuth
@@ -95,9 +108,9 @@ function createConfig(overrides) {
 */
 async function createConfigAsync(overrides) {
 	const { isInIframe: isInIframe$1 } = await Promise.resolve().then(() => require("./postMessage-BSNS3ccd.cjs"));
-	let baseUrl = overrides?.baseUrl || process.env.OXY_URL;
-	let apiKey = overrides?.apiKey || process.env.OXY_API_KEY;
-	let projectId = overrides?.projectId || process.env.OXY_PROJECT_ID;
+	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;
 	if (!disableAutoAuth && isInIframe$1() && !apiKey) if (!parentOrigin) logWarningAboutMissingParentOrigin();
@@ -134,7 +147,7 @@ function createFinalConfig(baseUrl, apiKey, projectId, overrides) {
 		baseUrl: baseUrl.replace(/\/$/, ""),
 		apiKey,
 		projectId,
-		branch: overrides?.branch || process.env.OXY_BRANCH,
+		branch: overrides?.branch || getEnvVar("OXY_BRANCH"),
 		timeout: overrides?.timeout || 3e4,
 		parentOrigin: overrides?.parentOrigin,
 		disableAutoAuth: overrides?.disableAutoAuth
@@ -178,41 +191,76 @@ async function getConnection() {
 	return connection;
 }
 /**
-* ParquetReader provides methods to read and query Parquet files
+* ParquetReader provides methods to read and query Parquet files.
+* Supports registering multiple Parquet files with different table names.
 */
 var ParquetReader = class {
-	constructor(tableName = "data") {
-		this.registered = false;
-		this.tableName = tableName;
-		this.internalTableName = `${tableName}_${`${Date.now()}_${Math.random().toString(36).substring(2, 9)}`}`;
+	constructor() {
+		this.tableMap = /* @__PURE__ */ new Map();
+	}
+	/**
+	* Generate a unique internal table name to prevent conflicts
+	*/
+	generateInternalTableName(tableName) {
+		return `${tableName}_${`${Date.now()}_${Math.random().toString(36).substring(2, 9)}`}`;
 	}
 	/**
-	* Register a Parquet file from a Blob
+	* Register a Parquet file from a Blob with a specific table name
 	*
 	* @param blob - Parquet file as Blob
+	* @param tableName - Name to use for the table in queries (required)
 	*
 	* @example
 	* ```typescript
 	* const blob = await client.getFile('data/sales.parquet');
-	* const reader = new ParquetReader('sales');
-	* await reader.registerParquet(blob);
+	* const reader = new ParquetReader();
+	* await reader.registerParquet(blob, 'sales');
+	* ```
+	*
+	* @example
+	* ```typescript
+	* // Register multiple files
+	* const reader = new ParquetReader();
+	* await reader.registerParquet(salesBlob, 'sales');
+	* await reader.registerParquet(customersBlob, 'customers');
+	* const result = await reader.query('SELECT * FROM sales JOIN customers ON sales.customer_id = customers.id');
 	* ```
 	*/
-	async registerParquet(blob) {
+	async registerParquet(blob, tableName) {
+		const internalTableName = this.generateInternalTableName(tableName);
 		await enqueueOperation(async () => {
 			const conn = await getConnection();
 			const db = await initializeDuckDB();
 			const arrayBuffer = await blob.arrayBuffer();
 			const uint8Array = new Uint8Array(arrayBuffer);
-			await db.registerFileBuffer(`${this.internalTableName}.parquet`, uint8Array);
+			await db.registerFileBuffer(`${internalTableName}.parquet`, uint8Array);
 			try {
-				await conn.query(`DROP TABLE IF EXISTS ${this.internalTableName}`);
+				await conn.query(`DROP TABLE IF EXISTS ${internalTableName}`);
 			} catch {}
-			await conn.query(`CREATE TABLE ${this.internalTableName} AS SELECT * FROM '${this.internalTableName}.parquet'`);
-			this.registered = true;
+			await conn.query(`CREATE TABLE ${internalTableName} AS SELECT * FROM '${internalTableName}.parquet'`);
+			this.tableMap.set(tableName, internalTableName);
 		});
 	}
 	/**
+	* Register multiple Parquet files at once
+	*
+	* @param files - Array of objects containing blob and tableName
+	*
+	* @example
+	* ```typescript
+	* const reader = new ParquetReader();
+	* await reader.registerMultipleParquet([
+	*   { blob: salesBlob, tableName: 'sales' },
+	*   { blob: customersBlob, tableName: 'customers' },
+	*   { blob: productsBlob, tableName: 'products' }
+	* ]);
+	* const result = await reader.query('SELECT * FROM sales JOIN customers ON sales.customer_id = customers.id');
+	* ```
+	*/
+	async registerMultipleParquet(files) {
+		for (const file of files) await this.registerParquet(file.blob, file.tableName);
+	}
+	/**
 	* Execute a SQL query against the registered Parquet data
 	*
 	* @param sql - SQL query string
@@ -224,12 +272,25 @@ var ParquetReader = class {
 	* console.log(result.columns);
 	* console.log(result.rows);
 	* ```
+	*
+	* @example
+	* ```typescript
+	* // Query multiple tables
+	* await reader.registerParquet(salesBlob, 'sales');
+	* await reader.registerParquet(customersBlob, 'customers');
+	* const result = await reader.query(`
+	*   SELECT s.*, c.name
+	*   FROM sales s
+	*   JOIN customers c ON s.customer_id = c.id
+	* `);
+	* ```
 	*/
 	async query(sql) {
-		if (!this.registered) throw new Error("Parquet file not registered. Call registerParquet() first.");
+		if (this.tableMap.size === 0) throw new Error("No Parquet files registered. Call registerParquet() first.");
 		return enqueueOperation(async () => {
 			const conn = await getConnection();
-			const rewrittenSql = sql.replace(new RegExp(`\\b${this.tableName}\\b`, "g"), this.internalTableName);
+			let rewrittenSql = sql;
+			for (const [userTableName, internalTableName] of this.tableMap.entries()) rewrittenSql = rewrittenSql.replace(new RegExp(`\\b${userTableName}\\b`, "g"), internalTableName);
 			const result = await conn.query(rewrittenSql);
 			const columns = result.schema.fields.map((field) => field.name);
 			const rows = [];
@@ -249,64 +310,69 @@ var ParquetReader = class {
 		});
 	}
 	/**
-	* Get all data from the registered table
+	* Get all data from a registered table
 	*
+	* @param tableName - Name of the table to query
 	* @param limit - Maximum number of rows to return (default: all)
 	* @returns Query result
 	*
 	* @example
 	* ```typescript
-	* const allData = await reader.getAll();
-	* const first100 = await reader.getAll(100);
+	* const allData = await reader.getAll('sales');
+	* const first100 = await reader.getAll('sales', 100);
 	* ```
 	*/
-	async getAll(limit) {
+	async getAll(tableName, limit) {
 		const limitClause = limit ? ` LIMIT ${limit}` : "";
-		return this.query(`SELECT * FROM ${this.tableName}${limitClause}`);
+		return this.query(`SELECT * FROM ${tableName}${limitClause}`);
 	}
 	/**
 	* Get table schema information
 	*
+	* @param tableName - Name of the table to describe
 	* @returns Schema information
 	*
 	* @example
 	* ```typescript
-	* const schema = await reader.getSchema();
+	* const schema = await reader.getSchema('sales');
 	* console.log(schema.columns); // ['id', 'name', 'sales']
 	* console.log(schema.rows);    // [['id', 'INTEGER'], ['name', 'VARCHAR'], ...]
 	* ```
 	*/
-	async getSchema() {
-		return this.query(`DESCRIBE ${this.tableName}`);
+	async getSchema(tableName) {
+		return this.query(`DESCRIBE ${tableName}`);
 	}
 	/**
-	* Get row count
+	* Get row count for a table
 	*
+	* @param tableName - Name of the table to count
 	* @returns Number of rows in the table
 	*
 	* @example
 	* ```typescript
-	* const count = await reader.count();
+	* const count = await reader.count('sales');
 	* console.log(`Total rows: ${count}`);
 	* ```
 	*/
-	async count() {
-		return (await this.query(`SELECT COUNT(*) as count FROM ${this.tableName}`)).rows[0][0];
+	async count(tableName) {
+		return (await this.query(`SELECT COUNT(*) as count FROM ${tableName}`)).rows[0][0];
 	}
 	/**
-	* Close and cleanup resources
+	* Close and cleanup all registered resources
 	*/
 	async close() {
-		if (this.registered) await enqueueOperation(async () => {
+		if (this.tableMap.size > 0) await enqueueOperation(async () => {
 			const conn = await getConnection();
 			const db = await initializeDuckDB();
-			try {
-				await conn.query(`DROP TABLE IF EXISTS ${this.internalTableName}`);
-			} catch {}
-			try {
-				await db.dropFile(`${this.internalTableName}.parquet`);
-			} catch {}
-			this.registered = false;
+			for (const [, internalTableName] of this.tableMap.entries()) {
+				try {
+					await conn.query(`DROP TABLE IF EXISTS ${internalTableName}`);
+				} catch {}
+				try {
+					await db.dropFile(`${internalTableName}.parquet`);
+				} catch {}
+			}
+			this.tableMap.clear();
 		});
 	}
 };
@@ -314,21 +380,21 @@ var ParquetReader = class {
 * Helper function to quickly read a Parquet blob and execute a query
 *
 * @param blob - Parquet file as Blob
-* @param sql - SQL query to execute (optional, defaults to SELECT *)
+* @param tableName - Name to use for the table in queries (default: 'data')
+* @param sql - SQL query to execute (optional, defaults to SELECT * FROM tableName)
 * @returns Query result
 *
 * @example
 * ```typescript
 * const blob = await client.getFile('data/sales.parquet');
-* const result = await queryParquet(blob, 'SELECT product, SUM(amount) as total FROM data GROUP BY product');
+* const result = await queryParquet(blob, 'sales', 'SELECT product, SUM(amount) as total FROM sales GROUP BY product');
 * console.log(result);
 * ```
 */
-async function queryParquet(blob, sql) {
-	const uniqueId = `temp_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
-	const reader = new ParquetReader(uniqueId);
-	await reader.registerParquet(blob);
-	const query = sql || `SELECT * FROM ${uniqueId}`;
+async function queryParquet(blob, tableName = "data", sql) {
+	const reader = new ParquetReader();
+	await reader.registerParquet(blob, tableName);
+	const query = sql || `SELECT * FROM ${tableName}`;
 	const result = await reader.query(query);
 	await reader.close();
 	return result;
@@ -337,20 +403,21 @@ async function queryParquet(blob, sql) {
 * Helper function to read Parquet file and get all data
 *
 * @param blob - Parquet file as Blob
+* @param tableName - Name to use for the table (default: 'data')
 * @param limit - Maximum number of rows (optional)
 * @returns Query result
 *
 * @example
 * ```typescript
 * const blob = await client.getFile('data/sales.parquet');
-* const data = await readParquet(blob, 1000);
+* const data = await readParquet(blob, 'sales', 1000);
 * console.log(`Loaded ${data.rowCount} rows`);
 * ```
 */
-async function readParquet(blob, limit) {
-	const reader = new ParquetReader(`temp_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`);
-	await reader.registerParquet(blob);
-	const result = await reader.getAll(limit);
+async function readParquet(blob, tableName = "data", limit) {
+	const reader = new ParquetReader();
+	await reader.registerParquet(blob, tableName);
+	const result = await reader.getAll(tableName, limit);
 	await reader.close();
 	return result;
 }
@@ -590,7 +657,7 @@ var OxyClient = class OxyClient {
 	* ```
 	*/
 	async getTableData(filePath, limit = 100) {
-		const result = await readParquet(await this.getFile(filePath), limit);
+		const result = await readParquet(await this.getFile(filePath), "data", limit);
 		return {
 			columns: result.columns,
 			rows: result.rows,
@@ -599,8 +666,405 @@ var OxyClient = class OxyClient {
 	}
 };
 
+//#endregion
+//#region src/sdk.ts
+/**
+* OxySDK provides a unified interface for fetching data from Oxy and querying it with SQL.
+* It combines OxyClient (for API calls) and ParquetReader (for SQL queries) into a single,
+* easy-to-use interface.
+*
+* @example
+* ```typescript
+* // Create SDK instance
+* const sdk = new OxySDK({ apiKey: 'your-key', projectId: 'your-project' });
+*
+* // Load a parquet file and query it
+* await sdk.loadFile('data/sales.parquet', 'sales');
+* const result = await sdk.query('SELECT * FROM sales WHERE amount > 1000');
+* console.log(result.rows);
+*
+* // Clean up when done
+* await sdk.close();
+* ```
+*/
+var OxySDK = class OxySDK {
+	constructor(config) {
+		this.client = new OxyClient(config);
+		this.reader = new ParquetReader();
+	}
+	/**
+	* Creates an OxySDK instance asynchronously with support for postMessage authentication
+	*
+	* @param config - Optional configuration overrides
+	* @returns Promise resolving to OxySDK instance
+	*
+	* @example
+	* ```typescript
+	* // In an iframe - automatic postMessage auth
+	* const sdk = await OxySDK.create({
+	*   parentOrigin: 'https://app.example.com',
+	*   projectId: 'my-project-id'
+	* });
+	* ```
+	*/
+	static async create(config) {
+		return new OxySDK(await createConfigAsync(config));
+	}
+	/**
+	* Load a Parquet file from Oxy and register it for SQL queries
+	*
+	* @param filePath - Path to the parquet file in the app state directory
+	* @param tableName - Name to use for the table in SQL queries
+	*
+	* @example
+	* ```typescript
+	* await sdk.loadFile('data/sales.parquet', 'sales');
+	* await sdk.loadFile('data/customers.parquet', 'customers');
+	*
+	* const result = await sdk.query(`
+	*   SELECT s.*, c.name
+	*   FROM sales s
+	*   JOIN customers c ON s.customer_id = c.id
+	* `);
+	* ```
+	*/
+	async loadFile(filePath, tableName) {
+		const blob = await this.client.getFile(filePath);
+		await this.reader.registerParquet(blob, tableName);
+	}
+	/**
+	* Load multiple Parquet files at once
+	*
+	* @param files - Array of file paths and table names
+	*
+	* @example
+	* ```typescript
+	* await sdk.loadFiles([
+	*   { filePath: 'data/sales.parquet', tableName: 'sales' },
+	*   { filePath: 'data/customers.parquet', tableName: 'customers' },
+	*   { filePath: 'data/products.parquet', tableName: 'products' }
+	* ]);
+	*
+	* const result = await sdk.query('SELECT * FROM sales');
+	* ```
+	*/
+	async loadFiles(files) {
+		for (const file of files) await this.loadFile(file.filePath, file.tableName);
+	}
+	/**
+	* Load all data from an app's data container
+	*
+	* This fetches the app's data and registers all parquet files using their container keys as table names.
+	*
+	* @param appPath - Path to the app file
+	* @returns DataContainer with file references
+	*
+	* @example
+	* ```typescript
+	* // If app has data: { sales: { file_path: 'data/sales.parquet' } }
+	* const data = await sdk.loadAppData('dashboard.app.yml');
+	* // Now you can query the 'sales' table
+	* const result = await sdk.query('SELECT * FROM sales LIMIT 10');
+	* ```
+	*/
+	async loadAppData(appPath) {
+		const appDataResponse = await this.client.getAppData(appPath);
+		if (appDataResponse.error) throw new Error(`Failed to load app data: ${appDataResponse.error}`);
+		if (!appDataResponse.data) return null;
+		const loadPromises = Object.entries(appDataResponse.data).map(async ([tableName, fileRef]) => {
+			await this.loadFile(fileRef.file_path, tableName);
+		});
+		await Promise.all(loadPromises);
+		return appDataResponse.data;
+	}
+	/**
+	* Execute a SQL query against loaded data
+	*
+	* @param sql - SQL query to execute
+	* @returns Query result with columns and rows
+	*
+	* @example
+	* ```typescript
+	* await sdk.loadFile('data/sales.parquet', 'sales');
+	*
+	* const result = await sdk.query('SELECT product, SUM(amount) as total FROM sales GROUP BY product');
+	* console.log(result.columns); // ['product', 'total']
+	* console.log(result.rows);    // [['Product A', 1000], ['Product B', 2000]]
+	* console.log(result.rowCount); // 2
+	* ```
+	*/
+	async query(sql) {
+		return this.reader.query(sql);
+	}
+	/**
+	* Get all data from a loaded table
+	*
+	* @param tableName - Name of the table
+	* @param limit - Maximum number of rows (optional)
+	* @returns Query result
+	*
+	* @example
+	* ```typescript
+	* await sdk.loadFile('data/sales.parquet', 'sales');
+	* const allData = await sdk.getAll('sales');
+	* const first100 = await sdk.getAll('sales', 100);
+	* ```
+	*/
+	async getAll(tableName, limit) {
+		return this.reader.getAll(tableName, limit);
+	}
+	/**
+	* Get schema information for a loaded table
+	*
+	* @param tableName - Name of the table
+	* @returns Schema information
+	*
+	* @example
+	* ```typescript
+	* await sdk.loadFile('data/sales.parquet', 'sales');
+	* const schema = await sdk.getSchema('sales');
+	* console.log(schema.columns); // ['column_name', 'column_type', ...]
+	* console.log(schema.rows);    // [['id', 'INTEGER'], ['name', 'VARCHAR'], ...]
+	* ```
+	*/
+	async getSchema(tableName) {
+		return this.reader.getSchema(tableName);
+	}
+	/**
+	* Get row count for a loaded table
+	*
+	* @param tableName - Name of the table
+	* @returns Number of rows
+	*
+	* @example
+	* ```typescript
+	* await sdk.loadFile('data/sales.parquet', 'sales');
+	* const count = await sdk.count('sales');
+	* console.log(`Total rows: ${count}`);
+	* ```
+	*/
+	async count(tableName) {
+		return this.reader.count(tableName);
+	}
+	/**
+	* Get direct access to the underlying OxyClient
+	*
+	* Useful for advanced operations like listing apps, getting displays, etc.
+	*
+	* @returns The OxyClient instance
+	*
+	* @example
+	* ```typescript
+	* const apps = await sdk.getClient().listApps();
+	* const displays = await sdk.getClient().getDisplays('my-app.app.yml');
+	* ```
+	*/
+	getClient() {
+		return this.client;
+	}
+	/**
+	* Get direct access to the underlying ParquetReader
+	*
+	* Useful for advanced operations like registering blobs directly.
+	*
+	* @returns The ParquetReader instance
+	*
+	* @example
+	* ```typescript
+	* const myBlob = new Blob([parquetData]);
+	* await sdk.getReader().registerParquet(myBlob, 'mydata');
+	* ```
+	*/
+	getReader() {
+		return this.reader;
+	}
+	/**
+	* Close and cleanup all resources
+	*
+	* This clears all loaded data and releases resources. Call this when you're done with the SDK.
+	*
+	* @example
+	* ```typescript
+	* const sdk = new OxySDK({ apiKey: 'key', projectId: 'project' });
+	* await sdk.loadFile('data/sales.parquet', 'sales');
+	* const result = await sdk.query('SELECT * FROM sales');
+	* await sdk.close(); // Clean up
+	* ```
+	*/
+	async close() {
+		await this.reader.close();
+	}
+};
+
+//#endregion
+//#region src/react.tsx
+/**
+* React context for OxySDK
+*/
+const OxyContext = (0, react.createContext)(void 0);
+/**
+* Provider component that initializes and provides OxySDK to child components
+*
+* @example
+* ```tsx
+* // Synchronous initialization with config
+* function App() {
+*   return (
+*     <OxyProvider config={{
+*       apiKey: 'your-key',
+*       projectId: 'your-project',
+*       baseUrl: 'https://api.oxy.tech'
+*     }}>
+*       <Dashboard />
+*     </OxyProvider>
+*   );
+* }
+* ```
+*
+* @example
+* ```tsx
+* // Async initialization (for iframe/postMessage auth)
+* function App() {
+*   return (
+*     <OxyProvider
+*       useAsync
+*       config={{ parentOrigin: 'https://app.example.com' }}
+*     >
+*       <Dashboard />
+*     </OxyProvider>
+*   );
+* }
+* ```
+*
+* @example
+* ```tsx
+* // With environment variables
+* import { createConfig } from '@oxy/sdk';
+*
+* function App() {
+*   return (
+*     <OxyProvider config={createConfig()}>
+*       <Dashboard />
+*     </OxyProvider>
+*   );
+* }
+* ```
+*/
+function OxyProvider({ children, config, useAsync = false, onReady, onError }) {
+	const [sdk, setSdk] = (0, react.useState)(null);
+	const [isLoading, setIsLoading] = (0, react.useState)(true);
+	const [error, setError] = (0, react.useState)(null);
+	(0, react.useEffect)(() => {
+		let mounted = true;
+		let sdkInstance = null;
+		async function initializeSDK() {
+			try {
+				setIsLoading(true);
+				setError(null);
+				if (useAsync) sdkInstance = await OxySDK.create(config);
+				else {
+					if (!config) throw new Error("Config is required when useAsync is false. Either provide config or set useAsync=true.");
+					sdkInstance = new OxySDK(config);
+				}
+				if (mounted) {
+					setSdk(sdkInstance);
+					setIsLoading(false);
+					onReady?.(sdkInstance);
+				}
+			} catch (err) {
+				const error$1 = err instanceof Error ? err : /* @__PURE__ */ new Error("Failed to initialize SDK");
+				if (mounted) {
+					setError(error$1);
+					setIsLoading(false);
+					onError?.(error$1);
+				}
+			}
+		}
+		initializeSDK();
+		return () => {
+			mounted = false;
+			if (sdkInstance) sdkInstance.close().catch(console.error);
+		};
+	}, [
+		config,
+		useAsync,
+		onReady,
+		onError
+	]);
+	return /* @__PURE__ */ react.default.createElement(OxyContext.Provider, { value: {
+		sdk,
+		isLoading,
+		error
+	} }, children);
+}
+/**
+* Hook to access OxySDK from child components
+*
+* @throws {Error} If used outside of OxyProvider
+* @returns {OxyContextValue} The SDK instance, loading state, and error
+*
+* @example
+* ```tsx
+* function Dashboard() {
+*   const { sdk, isLoading, error } = useOxy();
+*
+*   useEffect(() => {
+*     if (sdk) {
+*       sdk.loadAppData('dashboard.app.yml')
+*         .then(() => sdk.query('SELECT * FROM my_table'))
+*         .then(result => console.log(result));
+*     }
+*   }, [sdk]);
+*
+*   if (isLoading) return <div>Loading SDK...</div>;
+*   if (error) return <div>Error: {error.message}</div>;
+*   if (!sdk) return null;
+*
+*   return <div>Dashboard</div>;
+* }
+* ```
+*/
+function useOxy() {
+	const context = (0, react.useContext)(OxyContext);
+	if (context === void 0) throw new Error("useOxy must be used within an OxyProvider");
+	return context;
+}
+/**
+* Hook to access OxySDK that throws if not ready
+*
+* This is a convenience hook that returns the SDK directly or throws an error if not initialized.
+* Use this when you know the SDK should be ready.
+*
+* @throws {Error} If used outside of OxyProvider or if SDK is not initialized
+* @returns {OxySDK} The SDK instance
+*
+* @example
+* ```tsx
+* function DataTable() {
+*   const sdk = useOxySDK();
+*   const [data, setData] = useState(null);
+*
+*   useEffect(() => {
+*     sdk.loadFile('data.parquet', 'data')
+*       .then(() => sdk.query('SELECT * FROM data LIMIT 100'))
+*       .then(setData);
+*   }, [sdk]);
+*
+*   return <table>...</table>;
+* }
+* ```
+*/
+function useOxySDK() {
+	const { sdk, isLoading, error } = useOxy();
+	if (error) throw error;
+	if (isLoading || !sdk) throw new Error("OxySDK is not yet initialized");
+	return sdk;
+}
+
 //#endregion
 exports.OxyClient = OxyClient;
+exports.OxyProvider = OxyProvider;
+exports.OxySDK = OxySDK;
 exports.ParquetReader = ParquetReader;
 exports.PostMessageAuthInvalidOriginError = require_postMessage.PostMessageAuthInvalidOriginError;
 exports.PostMessageAuthInvalidResponseError = require_postMessage.PostMessageAuthInvalidResponseError;
@@ -613,4 +1077,6 @@ exports.isInIframe = require_postMessage.isInIframe;
 exports.queryParquet = queryParquet;
 exports.readParquet = readParquet;
 exports.requestAuthFromParent = require_postMessage.requestAuthFromParent;
+exports.useOxy = useOxy;
+exports.useOxySDK = useOxySDK;
 //# sourceMappingURL=index.cjs.map