@oxy-hq/sdk 0.1.0

package/dist/index.mjs

@@ -0,0 +1,450 @@
+// @oxy/sdk - TypeScript SDK for Oxy data platform
+import * as duckdb from "@duckdb/duckdb-wasm";
+
+//#region src/parquet.ts
+let dbInstance = null;
+let connection = null;
+/**
+* Initialize DuckDB-WASM instance
+*/
+async function initializeDuckDB() {
+	if (dbInstance) return dbInstance;
+	const JSDELIVR_BUNDLES = duckdb.getJsDelivrBundles();
+	const bundle = await duckdb.selectBundle(JSDELIVR_BUNDLES);
+	const worker_url = URL.createObjectURL(new Blob([`importScripts("${bundle.mainWorker}");`], { type: "text/javascript" }));
+	const worker = new Worker(worker_url);
+	const logger = new duckdb.ConsoleLogger();
+	dbInstance = new duckdb.AsyncDuckDB(logger, worker);
+	await dbInstance.instantiate(bundle.mainModule, bundle.pthreadWorker);
+	URL.revokeObjectURL(worker_url);
+	return dbInstance;
+}
+/**
+* Get or create a DuckDB connection
+*/
+async function getConnection() {
+	if (connection) return connection;
+	connection = await (await initializeDuckDB()).connect();
+	return connection;
+}
+/**
+* ParquetReader provides methods to read and query Parquet files
+*/
+var ParquetReader = class {
+	constructor(tableName = "data") {
+		this.registered = false;
+		this.tableName = tableName;
+	}
+	/**
+	* Register a Parquet file from a Blob
+	*
+	* @param blob - Parquet file as Blob
+	*
+	* @example
+	* ```typescript
+	* const blob = await client.getFile('data/sales.parquet');
+	* const reader = new ParquetReader('sales');
+	* await reader.registerParquet(blob);
+	* ```
+	*/
+	async registerParquet(blob) {
+		const conn = await getConnection();
+		const db = await initializeDuckDB();
+		const arrayBuffer = await blob.arrayBuffer();
+		const uint8Array = new Uint8Array(arrayBuffer);
+		await db.registerFileBuffer(`${this.tableName}.parquet`, uint8Array);
+		try {
+			await conn.query(`DROP TABLE IF EXISTS ${this.tableName}`);
+		} catch (e) {}
+		await conn.query(`CREATE TABLE ${this.tableName} AS SELECT * FROM '${this.tableName}.parquet'`);
+		this.registered = true;
+	}
+	/**
+	* Execute a SQL query against the registered Parquet data
+	*
+	* @param sql - SQL query string
+	* @returns Query result with columns and rows
+	*
+	* @example
+	* ```typescript
+	* const result = await reader.query('SELECT * FROM sales LIMIT 10');
+	* console.log(result.columns);
+	* console.log(result.rows);
+	* ```
+	*/
+	async query(sql) {
+		if (!this.registered) throw new Error("Parquet file not registered. Call registerParquet() first.");
+		const result = await (await getConnection()).query(sql);
+		const columns = result.schema.fields.map((field) => field.name);
+		const rows = [];
+		for (let i = 0; i < result.numRows; i++) {
+			const row = [];
+			for (let j = 0; j < result.numCols; j++) {
+				const col = result.getChildAt(j);
+				row.push(col?.get(i));
+			}
+			rows.push(row);
+		}
+		return {
+			columns,
+			rows,
+			rowCount: result.numRows
+		};
+	}
+	/**
+	* Get all data from the registered table
+	*
+	* @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);
+	* ```
+	*/
+	async getAll(limit) {
+		const limitClause = limit ? ` LIMIT ${limit}` : "";
+		return this.query(`SELECT * FROM ${this.tableName}${limitClause}`);
+	}
+	/**
+	* Get table schema information
+	*
+	* @returns Schema information
+	*
+	* @example
+	* ```typescript
+	* const schema = await reader.getSchema();
+	* console.log(schema.columns); // ['id', 'name', 'sales']
+	* console.log(schema.rows);    // [['id', 'INTEGER'], ['name', 'VARCHAR'], ...]
+	* ```
+	*/
+	async getSchema() {
+		return this.query(`DESCRIBE ${this.tableName}`);
+	}
+	/**
+	* Get row count
+	*
+	* @returns Number of rows in the table
+	*
+	* @example
+	* ```typescript
+	* const count = await reader.count();
+	* console.log(`Total rows: ${count}`);
+	* ```
+	*/
+	async count() {
+		return (await this.query(`SELECT COUNT(*) as count FROM ${this.tableName}`)).rows[0][0];
+	}
+	/**
+	* Close and cleanup resources
+	*/
+	async close() {
+		if (this.registered) {
+			const conn = await getConnection();
+			const db = await initializeDuckDB();
+			try {
+				await conn.query(`DROP TABLE IF EXISTS ${this.tableName}`);
+			} catch (e) {}
+			try {
+				await db.dropFile(`${this.tableName}.parquet`);
+			} catch (e) {}
+			this.registered = false;
+		}
+	}
+};
+/**
+* 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 *)
+* @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');
+* 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}`;
+	const result = await reader.query(query);
+	await reader.close();
+	return result;
+}
+/**
+* Helper function to read Parquet file and get all data
+*
+* @param blob - Parquet file as Blob
+* @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);
+* 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);
+	await reader.close();
+	return result;
+}
+
+//#endregion
+//#region src/client.ts
+/**
+* Oxy API Client for interacting with Oxy data
+*/
+var OxyClient = class {
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* Encodes a file path to base64 for use in API URLs
+	*/
+	encodePathBase64(path) {
+		if (typeof Buffer !== "undefined") return Buffer.from(path).toString("base64");
+		else return btoa(path);
+	}
+	/**
+	* Makes an authenticated HTTP request to the Oxy API
+	*/
+	async request(endpoint, options = {}) {
+		const url = `${this.config.baseUrl}${endpoint}`;
+		const headers = {
+			"Content-Type": "application/json",
+			...options.headers || {}
+		};
+		if (this.config.apiKey) headers["X-API-Key"] = `${this.config.apiKey}`;
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), this.config.timeout || 3e4);
+		try {
+			const response = await fetch(url, {
+				...options,
+				headers,
+				signal: controller.signal
+			});
+			clearTimeout(timeoutId);
+			if (!response.ok) {
+				const errorText = await response.text().catch(() => "Unknown error");
+				throw {
+					message: `API request failed: ${response.statusText}`,
+					status: response.status,
+					details: errorText
+				};
+			}
+			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);
+			if (error.name === "AbortError") throw new Error(`Request timeout after ${this.config.timeout || 3e4}ms`);
+			throw error;
+		}
+	}
+	/**
+	* Builds query parameters including optional branch
+	*/
+	buildQueryParams(additionalParams = {}) {
+		const params = { ...additionalParams };
+		if (this.config.branch) params.branch = this.config.branch;
+		const queryString = new URLSearchParams(params).toString();
+		return queryString ? `?${queryString}` : "";
+	}
+	/**
+	* Lists all apps in the project
+	*
+	* @returns Array of app items
+	*
+	* @example
+	* ```typescript
+	* const apps = await client.listApps();
+	* console.log('Available apps:', apps);
+	* ```
+	*/
+	async listApps() {
+		const query = this.buildQueryParams();
+		return this.request(`/${this.config.projectId}/app${query}`);
+	}
+	/**
+	* Gets data for a specific app
+	*
+	* @param appPath - Relative path to the app file (e.g., 'my-app.app.yml')
+	* @returns App data response
+	*
+	* @example
+	* ```typescript
+	* const data = await client.getAppData('dashboard.app.yml');
+	* if (data.error) {
+	*   console.error('Error:', data.error);
+	* } else {
+	*   console.log('App data:', data.data);
+	* }
+	* ```
+	*/
+	async getAppData(appPath) {
+		const pathb64 = this.encodePathBase64(appPath);
+		const query = this.buildQueryParams();
+		return this.request(`/${this.config.projectId}/app/${pathb64}${query}`);
+	}
+	/**
+	* Runs an app and returns fresh data (bypasses cache)
+	*
+	* @param appPath - Relative path to the app file
+	* @returns App data response
+	*
+	* @example
+	* ```typescript
+	* const data = await client.runApp('dashboard.app.yml');
+	* console.log('Fresh app data:', data.data);
+	* ```
+	*/
+	async runApp(appPath) {
+		const pathb64 = this.encodePathBase64(appPath);
+		const query = this.buildQueryParams();
+		return this.request(`/${this.config.projectId}/app/${pathb64}/run${query}`, { method: "POST" });
+	}
+	/**
+	* Gets display configurations for an app
+	*
+	* @param appPath - Relative path to the app file
+	* @returns Display configurations with potential errors
+	*
+	* @example
+	* ```typescript
+	* const displays = await client.getDisplays('dashboard.app.yml');
+	* displays.displays.forEach(d => {
+	*   if (d.error) {
+	*     console.error('Display error:', d.error);
+	*   } else {
+	*     console.log('Display:', d.display);
+	*   }
+	* });
+	* ```
+	*/
+	async getDisplays(appPath) {
+		const pathb64 = this.encodePathBase64(appPath);
+		const query = this.buildQueryParams();
+		return this.request(`/${this.config.projectId}/app/${pathb64}/displays${query}`);
+	}
+	/**
+	* Gets a file from the app state directory (e.g., generated charts, images)
+	*
+	* This is useful for retrieving generated assets like charts, images, or other
+	* files produced by app workflows and stored in the state directory.
+	*
+	* @param filePath - Relative path to the file in state directory
+	* @returns Blob containing the file data
+	*
+	* @example
+	* ```typescript
+	* // Get a generated chart image
+	* const blob = await client.getFile('charts/sales-chart.png');
+	* const imageUrl = URL.createObjectURL(blob);
+	*
+	* // Use in an img tag
+	* document.querySelector('img').src = imageUrl;
+	* ```
+	*
+	* @example
+	* ```typescript
+	* // Download a file
+	* const blob = await client.getFile('exports/data.csv');
+	* const a = document.createElement('a');
+	* a.href = URL.createObjectURL(blob);
+	* a.download = 'data.csv';
+	* a.click();
+	* ```
+	*/
+	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" } });
+	}
+	/**
+	* Gets a file URL for direct browser access
+	*
+	* This returns a URL that can be used directly in img tags, fetch calls, etc.
+	* The URL includes authentication via query parameters.
+	*
+	* @param filePath - Relative path to the file in state directory
+	* @returns Full URL to the file
+	*
+	* @example
+	* ```typescript
+	* const imageUrl = client.getFileUrl('charts/sales-chart.png');
+	*
+	* // Use directly in img tag (in environments where query-based auth is supported)
+	* document.querySelector('img').src = imageUrl;
+	* ```
+	*/
+	getFileUrl(filePath) {
+		const pathb64 = this.encodePathBase64(filePath);
+		const query = this.buildQueryParams();
+		return `${this.config.baseUrl}/${this.config.projectId}/app/file/${pathb64}${query}`;
+	}
+	/**
+	* Fetches a parquet file and parses it into table data
+	*
+	* @param filePath - Relative path to the parquet file
+	* @param limit - Maximum number of rows to return (default: 100)
+	* @returns TableData with columns and rows
+	*
+	* @example
+	* ```typescript
+	* const tableData = await client.getTableData('data/sales.parquet', 50);
+	* console.log(tableData.columns);
+	* console.log(tableData.rows);
+	* console.log(`Total rows: ${tableData.total_rows}`);
+	* ```
+	*/
+	async getTableData(filePath, limit = 100) {
+		const result = await readParquet(await this.getFile(filePath), limit);
+		return {
+			columns: result.columns,
+			rows: result.rows,
+			total_rows: result.rowCount
+		};
+	}
+};
+
+//#endregion
+//#region src/config.ts
+/**
+* Creates an Oxy configuration from environment variables
+*
+* Environment variables:
+* - OXY_URL: Base URL of the Oxy API
+* - OXY_API_KEY: API key for authentication
+* - OXY_PROJECT_ID: Project ID (UUID)
+* - OXY_BRANCH: (Optional) Branch name
+*
+* @param overrides - Optional configuration overrides
+* @returns OxyConfig object
+* @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;
+	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,
+		timeout: overrides?.timeout || 3e4
+	};
+}
+
+//#endregion
+export { OxyClient, ParquetReader, createConfig, queryParquet, readParquet };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/parquet.ts","../src/client.ts","../src/config.ts"],"sourcesContent":["import * as duckdb from '@duckdb/duckdb-wasm';\n\nlet dbInstance: duckdb.AsyncDuckDB | null = null;\nlet connection: duckdb.AsyncDuckDBConnection | null = null;\n\n/**\n * Initialize DuckDB-WASM instance\n */\nasync function initializeDuckDB(): Promise<duckdb.AsyncDuckDB> {\n  if (dbInstance) {\n    return dbInstance;\n  }\n\n  const JSDELIVR_BUNDLES = duckdb.getJsDelivrBundles();\n\n  // Select a bundle based on browser features\n  const bundle = await duckdb.selectBundle(JSDELIVR_BUNDLES);\n\n  const worker_url = URL.createObjectURL(\n    new Blob([`importScripts(\"${bundle.mainWorker}\");`], {\n      type: 'text/javascript',\n    })\n  );\n\n  const worker = new Worker(worker_url);\n  const logger = new duckdb.ConsoleLogger();\n\n  dbInstance = new duckdb.AsyncDuckDB(logger, worker);\n  await dbInstance.instantiate(bundle.mainModule, bundle.pthreadWorker);\n  URL.revokeObjectURL(worker_url);\n\n  return dbInstance;\n}\n\n/**\n * Get or create a DuckDB connection\n */\nasync function getConnection(): Promise<duckdb.AsyncDuckDBConnection> {\n  if (connection) {\n    return connection;\n  }\n\n  const db = await initializeDuckDB();\n  connection = await db.connect();\n  return connection;\n}\n\n/**\n * Query result interface\n */\nexport interface QueryResult {\n  columns: string[];\n  rows: any[][];\n  rowCount: number;\n}\n\n/**\n * ParquetReader provides methods to read and query Parquet files\n */\nexport class ParquetReader {\n  private tableName: string;\n  private registered: boolean = false;\n\n  constructor(tableName: string = 'data') {\n    this.tableName = tableName;\n  }\n\n  /**\n   * Register a Parquet file from a Blob\n   *\n   * @param blob - Parquet file as Blob\n   *\n   * @example\n   * ```typescript\n   * const blob = await client.getFile('data/sales.parquet');\n   * const reader = new ParquetReader('sales');\n   * await reader.registerParquet(blob);\n   * ```\n   */\n  async registerParquet(blob: Blob): Promise<void> {\n    const conn = await getConnection();\n    const db = await initializeDuckDB();\n\n    // Convert blob to Uint8Array\n    const arrayBuffer = await blob.arrayBuffer();\n    const uint8Array = new Uint8Array(arrayBuffer);\n\n    // Register the file with DuckDB\n    await db.registerFileBuffer(\n      `${this.tableName}.parquet`,\n      uint8Array\n    );\n\n    // Drop table if it exists\n    try {\n      await conn.query(`DROP TABLE IF EXISTS ${this.tableName}`);\n    } catch (e) {\n      // Ignore error if table doesn't exist\n    }\n\n    // Create table from parquet\n    await conn.query(\n      `CREATE TABLE ${this.tableName} AS SELECT * FROM '${this.tableName}.parquet'`\n    );\n\n    this.registered = true;\n  }\n\n  /**\n   * Execute a SQL query against the registered Parquet data\n   *\n   * @param sql - SQL query string\n   * @returns Query result with columns and rows\n   *\n   * @example\n   * ```typescript\n   * const result = await reader.query('SELECT * FROM sales LIMIT 10');\n   * console.log(result.columns);\n   * console.log(result.rows);\n   * ```\n   */\n  async query(sql: string): Promise<QueryResult> {\n    if (!this.registered) {\n      throw new Error('Parquet file not registered. Call registerParquet() first.');\n    }\n\n    const conn = await getConnection();\n    const result = await conn.query(sql);\n\n    const columns = result.schema.fields.map((field) => field.name);\n    const rows: any[][] = [];\n\n    // Convert Arrow table to rows\n    for (let i = 0; i < result.numRows; i++) {\n      const row: any[] = [];\n      for (let j = 0; j < result.numCols; j++) {\n        const col = result.getChildAt(j);\n        row.push(col?.get(i));\n      }\n      rows.push(row);\n    }\n\n    return {\n      columns,\n      rows,\n      rowCount: result.numRows,\n    };\n  }\n\n  /**\n   * Get all data from the registered table\n   *\n   * @param limit - Maximum number of rows to return (default: all)\n   * @returns Query result\n   *\n   * @example\n   * ```typescript\n   * const allData = await reader.getAll();\n   * const first100 = await reader.getAll(100);\n   * ```\n   */\n  async getAll(limit?: number): Promise<QueryResult> {\n    const limitClause = limit ? ` LIMIT ${limit}` : '';\n    return this.query(`SELECT * FROM ${this.tableName}${limitClause}`);\n  }\n\n  /**\n   * Get table schema information\n   *\n   * @returns Schema information\n   *\n   * @example\n   * ```typescript\n   * const schema = await reader.getSchema();\n   * console.log(schema.columns); // ['id', 'name', 'sales']\n   * console.log(schema.rows);    // [['id', 'INTEGER'], ['name', 'VARCHAR'], ...]\n   * ```\n   */\n  async getSchema(): Promise<QueryResult> {\n    return this.query(`DESCRIBE ${this.tableName}`);\n  }\n\n  /**\n   * Get row count\n   *\n   * @returns Number of rows in the table\n   *\n   * @example\n   * ```typescript\n   * const count = await reader.count();\n   * console.log(`Total rows: ${count}`);\n   * ```\n   */\n  async count(): Promise<number> {\n    const result = await this.query(`SELECT COUNT(*) as count FROM ${this.tableName}`);\n    return result.rows[0][0];\n  }\n\n  /**\n   * Close and cleanup resources\n   */\n  async close(): Promise<void> {\n    if (this.registered) {\n      const conn = await getConnection();\n      const db = await initializeDuckDB();\n\n      // Drop the table\n      try {\n        await conn.query(`DROP TABLE IF EXISTS ${this.tableName}`);\n      } catch (e) {\n        // Ignore error\n      }\n\n      // Drop the registered file buffer\n      try {\n        await db.dropFile(`${this.tableName}.parquet`);\n      } catch (e) {\n        // Ignore error if file doesn't exist\n      }\n\n      this.registered = false;\n    }\n  }\n}\n\n/**\n * Helper function to quickly read a Parquet blob and execute a query\n *\n * @param blob - Parquet file as Blob\n * @param sql - SQL query to execute (optional, defaults to SELECT *)\n * @returns Query result\n *\n * @example\n * ```typescript\n * const blob = await client.getFile('data/sales.parquet');\n * const result = await queryParquet(blob, 'SELECT product, SUM(amount) as total FROM data GROUP BY product');\n * console.log(result);\n * ```\n */\nexport async function queryParquet(\n  blob: Blob,\n  sql?: string\n): Promise<QueryResult> {\n  // Generate unique table name to avoid conflicts\n  const uniqueId = `temp_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;\n  const reader = new ParquetReader(uniqueId);\n\n  await reader.registerParquet(blob);\n\n  const query = sql || `SELECT * FROM ${uniqueId}`;\n  const result = await reader.query(query);\n\n  await reader.close();\n  return result;\n}\n\n/**\n * Helper function to read Parquet file and get all data\n *\n * @param blob - Parquet file as Blob\n * @param limit - Maximum number of rows (optional)\n * @returns Query result\n *\n * @example\n * ```typescript\n * const blob = await client.getFile('data/sales.parquet');\n * const data = await readParquet(blob, 1000);\n * console.log(`Loaded ${data.rowCount} rows`);\n * ```\n */\nexport async function readParquet(\n  blob: Blob,\n  limit?: number\n): Promise<QueryResult> {\n  // Generate unique table name to avoid conflicts\n  const uniqueId = `temp_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;\n  const reader = new ParquetReader(uniqueId);\n\n  await reader.registerParquet(blob);\n\n  const result = await reader.getAll(limit);\n\n  await reader.close();\n  return result;\n}\n","import { OxyConfig } from './config';\nimport {\n  AppItem,\n  AppDataResponse,\n  GetDisplaysResponse,\n  ApiError,\n  TableData,\n} from './types';\nimport { readParquet } from './parquet';\n\n/**\n * Oxy API Client for interacting with Oxy data\n */\nexport class OxyClient {\n  private config: OxyConfig;\n\n  constructor(config: OxyConfig) {\n    this.config = config;\n  }\n\n  /**\n   * Encodes a file path to base64 for use in API URLs\n   */\n  private encodePathBase64(path: string): string {\n    if (typeof Buffer !== 'undefined') {\n      // Node.js environment\n      return Buffer.from(path).toString('base64');\n    } else {\n      // Browser environment\n      return btoa(path);\n    }\n  }\n\n  /**\n   * Makes an authenticated HTTP request to the Oxy API\n   */\n  private async request<T>(\n    endpoint: string,\n    options: RequestInit = {}\n  ): Promise<T> {\n    const url = `${this.config.baseUrl}${endpoint}`;\n\n    const headers: Record<string, string> = {\n      'Content-Type': 'application/json',\n      ...((options.headers as Record<string, string>) || {}),\n    };\n\n    // Only add Authorization header if API key is provided (optional for local dev)\n    if (this.config.apiKey) {\n      headers['X-API-Key'] = `${this.config.apiKey}`;\n    }\n\n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout || 30000);\n\n    try {\n      const response = await fetch(url, {\n        ...options,\n        headers,\n        signal: controller.signal,\n      });\n\n      clearTimeout(timeoutId);\n\n      if (!response.ok) {\n        const errorText = await response.text().catch(() => 'Unknown error');\n        const error: ApiError = {\n          message: `API request failed: ${response.statusText}`,\n          status: response.status,\n          details: errorText,\n        };\n        throw error;\n      }\n\n      // Handle binary responses\n      const acceptHeader =\n        typeof options.headers === 'object' && options.headers !== null\n          ? (options.headers as Record<string, string>)['Accept']\n          : undefined;\n      if (acceptHeader === 'application/octet-stream') {\n        return response.blob() as Promise<T>;\n      }\n\n      return response.json();\n    } catch (error: any) {\n      clearTimeout(timeoutId);\n\n      if (error.name === 'AbortError') {\n        throw new Error(`Request timeout after ${this.config.timeout || 30000}ms`);\n      }\n\n      throw error;\n    }\n  }\n\n  /**\n   * Builds query parameters including optional branch\n   */\n  private buildQueryParams(additionalParams: Record<string, string> = {}): string {\n    const params: Record<string, string> = { ...additionalParams };\n\n    if (this.config.branch) {\n      params.branch = this.config.branch;\n    }\n\n    const searchParams = new URLSearchParams(params);\n    const queryString = searchParams.toString();\n    return queryString ? `?${queryString}` : '';\n  }\n\n  /**\n   * Lists all apps in the project\n   *\n   * @returns Array of app items\n   *\n   * @example\n   * ```typescript\n   * const apps = await client.listApps();\n   * console.log('Available apps:', apps);\n   * ```\n   */\n  async listApps(): Promise<AppItem[]> {\n    const query = this.buildQueryParams();\n    return this.request<AppItem[]>(`/${this.config.projectId}/app${query}`);\n  }\n\n  /**\n   * Gets data for a specific app\n   *\n   * @param appPath - Relative path to the app file (e.g., 'my-app.app.yml')\n   * @returns App data response\n   *\n   * @example\n   * ```typescript\n   * const data = await client.getAppData('dashboard.app.yml');\n   * if (data.error) {\n   *   console.error('Error:', data.error);\n   * } else {\n   *   console.log('App data:', data.data);\n   * }\n   * ```\n   */\n  async getAppData(appPath: string): Promise<AppDataResponse> {\n    const pathb64 = this.encodePathBase64(appPath);\n    const query = this.buildQueryParams();\n    return this.request<AppDataResponse>(\n      `/${this.config.projectId}/app/${pathb64}${query}`\n    );\n  }\n\n  /**\n   * Runs an app and returns fresh data (bypasses cache)\n   *\n   * @param appPath - Relative path to the app file\n   * @returns App data response\n   *\n   * @example\n   * ```typescript\n   * const data = await client.runApp('dashboard.app.yml');\n   * console.log('Fresh app data:', data.data);\n   * ```\n   */\n  async runApp(appPath: string): Promise<AppDataResponse> {\n    const pathb64 = this.encodePathBase64(appPath);\n    const query = this.buildQueryParams();\n    return this.request<AppDataResponse>(\n      `/${this.config.projectId}/app/${pathb64}/run${query}`,\n      { method: 'POST' }\n    );\n  }\n\n  /**\n   * Gets display configurations for an app\n   *\n   * @param appPath - Relative path to the app file\n   * @returns Display configurations with potential errors\n   *\n   * @example\n   * ```typescript\n   * const displays = await client.getDisplays('dashboard.app.yml');\n   * displays.displays.forEach(d => {\n   *   if (d.error) {\n   *     console.error('Display error:', d.error);\n   *   } else {\n   *     console.log('Display:', d.display);\n   *   }\n   * });\n   * ```\n   */\n  async getDisplays(appPath: string): Promise<GetDisplaysResponse> {\n    const pathb64 = this.encodePathBase64(appPath);\n    const query = this.buildQueryParams();\n    return this.request<GetDisplaysResponse>(\n      `/${this.config.projectId}/app/${pathb64}/displays${query}`\n    );\n  }\n\n  /**\n   * Gets a file from the app state directory (e.g., generated charts, images)\n   *\n   * This is useful for retrieving generated assets like charts, images, or other\n   * files produced by app workflows and stored in the state directory.\n   *\n   * @param filePath - Relative path to the file in state directory\n   * @returns Blob containing the file data\n   *\n   * @example\n   * ```typescript\n   * // Get a generated chart image\n   * const blob = await client.getFile('charts/sales-chart.png');\n   * const imageUrl = URL.createObjectURL(blob);\n   *\n   * // Use in an img tag\n   * document.querySelector('img').src = imageUrl;\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Download a file\n   * const blob = await client.getFile('exports/data.csv');\n   * const a = document.createElement('a');\n   * a.href = URL.createObjectURL(blob);\n   * a.download = 'data.csv';\n   * a.click();\n   * ```\n   */\n  async getFile(filePath: string): Promise<Blob> {\n    const pathb64 = this.encodePathBase64(filePath);\n    const query = this.buildQueryParams();\n    return this.request<Blob>(\n      `/${this.config.projectId}/app/file/${pathb64}${query}`,\n      {\n        headers: {\n          'Accept': 'application/octet-stream',\n        },\n      }\n    );\n  }\n\n  /**\n   * Gets a file URL for direct browser access\n   *\n   * This returns a URL that can be used directly in img tags, fetch calls, etc.\n   * The URL includes authentication via query parameters.\n   *\n   * @param filePath - Relative path to the file in state directory\n   * @returns Full URL to the file\n   *\n   * @example\n   * ```typescript\n   * const imageUrl = client.getFileUrl('charts/sales-chart.png');\n   *\n   * // Use directly in img tag (in environments where query-based auth is supported)\n   * document.querySelector('img').src = imageUrl;\n   * ```\n   */\n  getFileUrl(filePath: string): string {\n    const pathb64 = this.encodePathBase64(filePath);\n    const query = this.buildQueryParams();\n    return `${this.config.baseUrl}/${this.config.projectId}/app/file/${pathb64}${query}`;\n  }\n\n  /**\n   * Fetches a parquet file and parses it into table data\n   *\n   * @param filePath - Relative path to the parquet file\n   * @param limit - Maximum number of rows to return (default: 100)\n   * @returns TableData with columns and rows\n   *\n   * @example\n   * ```typescript\n   * const tableData = await client.getTableData('data/sales.parquet', 50);\n   * console.log(tableData.columns);\n   * console.log(tableData.rows);\n   * console.log(`Total rows: ${tableData.total_rows}`);\n   * ```\n   */\n  async getTableData(filePath: string, limit: number = 100): Promise<TableData> {\n    const blob = await this.getFile(filePath);\n    const result = await readParquet(blob, limit);\n\n    return {\n      columns: result.columns,\n      rows: result.rows,\n      total_rows: result.rowCount,\n    };\n  }\n}\n","/**\n * Configuration for the Oxy SDK\n */\nexport interface OxyConfig {\n  /**\n   * Base URL of the Oxy API (e.g., 'https://api.oxy.tech' or 'http://localhost:3000')\n   */\n  baseUrl: string;\n\n  /**\n   * API key for authentication (optional for local development)\n   */\n  apiKey?: string;\n\n  /**\n   * Project ID (UUID)\n   */\n  projectId: string;\n\n  /**\n   * Optional branch name (defaults to current branch if not specified)\n   */\n  branch?: string;\n\n  /**\n   * Request timeout in milliseconds (default: 30000)\n   */\n  timeout?: number;\n}\n\n/**\n * Creates an Oxy configuration from environment variables\n *\n * Environment variables:\n * - OXY_URL: Base URL of the Oxy API\n * - OXY_API_KEY: API key for authentication\n * - OXY_PROJECT_ID: Project ID (UUID)\n * - OXY_BRANCH: (Optional) Branch name\n *\n * @param overrides - Optional configuration overrides\n * @returns OxyConfig object\n * @throws Error if required environment variables are missing\n */\nexport function createConfig(overrides?: Partial<OxyConfig>): OxyConfig {\n  const baseUrl = overrides?.baseUrl || process.env.OXY_URL;\n  const apiKey = overrides?.apiKey || process.env.OXY_API_KEY;\n  const projectId = overrides?.projectId || process.env.OXY_PROJECT_ID;\n\n  if (!baseUrl) {\n    throw new Error('OXY_URL environment variable or baseUrl config is required');\n  }\n\n  if (!projectId) {\n    throw new Error('OXY_PROJECT_ID environment variable or projectId config is required');\n  }\n\n  return {\n    baseUrl: baseUrl.replace(/\\/$/, ''), // Remove trailing slash\n    apiKey,\n    projectId,\n    branch: overrides?.branch || process.env.OXY_BRANCH,\n    timeout: overrides?.timeout || 30000,\n  };\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@oxy-hq/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for interacting with Oxy data platform",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "build:watch": "tsdown --watch",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build",
+    "publish:beta": "npm publish --tag beta",
+    "publish:latest": "npm publish --tag latest",
+    "demo:react": "cd examples/react-vite-demo && pnpm install --ignore-workspace && pnpm dev",
+    "demo:setup": "cd examples/react-vite-demo && pnpm install --ignore-workspace",
+    "example:basic": "tsx examples/basic-usage.ts",
+    "example:parquet": "tsx examples/parquet-usage.ts",
+    "example:v0": "tsx examples/v0-integration.ts"
+  },
+  "keywords": [
+    "oxy",
+    "data",
+    "analytics",
+    "sdk",
+    "parquet",
+    "duckdb"
+  ],
+  "author": "Oxy Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dataframehq/oxy-internal.git",
+    "directory": "sdk/typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/dataframehq/oxy-internal/issues"
+  },
+  "homepage": "https://oxy.tech",
+  "peerDependencies": {
+    "@duckdb/duckdb-wasm": "^1.29.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@duckdb/duckdb-wasm": "^1.29.0",
+    "@types/node": "^20.11.0",
+    "@typescript-eslint/eslint-plugin": "^6.19.0",
+    "@typescript-eslint/parser": "^6.19.0",
+    "eslint": "^8.56.0",
+    "tsdown": "^0.19.0-beta.2",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}