@oxy-hq/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,367 @@
+
+//#region src/config.d.ts
+/**
+ * Configuration for the Oxy SDK
+ */
+interface OxyConfig {
+  /**
+   * Base URL of the Oxy API (e.g., 'https://api.oxy.tech' or 'http://localhost:3000')
+   */
+  baseUrl: string;
+  /**
+   * API key for authentication (optional for local development)
+   */
+  apiKey?: string;
+  /**
+   * Project ID (UUID)
+   */
+  projectId: string;
+  /**
+   * Optional branch name (defaults to current branch if not specified)
+   */
+  branch?: string;
+  /**
+   * Request timeout in milliseconds (default: 30000)
+   */
+  timeout?: number;
+}
+/**
+ * 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
+ */
+declare function createConfig(overrides?: Partial<OxyConfig>): OxyConfig;
+//#endregion
+//#region src/types.d.ts
+/**
+ * Represents an app item in the project
+ */
+interface AppItem {
+  name: string;
+  path: string;
+}
+/**
+ * Reference to a data file (usually parquet)
+ */
+interface FileReference {
+  file_path: string;
+}
+/**
+ * Table data structure for in-memory tables
+ * (used when data is fetched and parsed)
+ */
+interface TableData {
+  columns: string[];
+  rows: any[][];
+  total_rows?: number;
+}
+type DataContainer = Record<string, FileReference>;
+/**
+ * Response from app data endpoints
+ */
+interface AppDataResponse {
+  data: DataContainer | null;
+  error: string | null;
+}
+/**
+ * Display with potential error
+ */
+interface DisplayWithError {
+  display?: DisplayData;
+  error?: string;
+}
+/**
+ * Display data structure
+ */
+interface DisplayData {
+  type: string;
+  content: any;
+}
+/**
+ * Response from get displays endpoint
+ */
+interface GetDisplaysResponse {
+  displays: DisplayWithError[];
+}
+/**
+ * Query result from ParquetReader
+ */
+interface QueryResult$1 {
+  columns: string[];
+  rows: any[][];
+  rowCount: number;
+}
+//#endregion
+//#region src/client.d.ts
+/**
+ * Oxy API Client for interacting with Oxy data
+ */
+declare class OxyClient {
+  private config;
+  constructor(config: OxyConfig);
+  /**
+   * Encodes a file path to base64 for use in API URLs
+   */
+  private encodePathBase64;
+  /**
+   * Makes an authenticated HTTP request to the Oxy API
+   */
+  private request;
+  /**
+   * Builds query parameters including optional branch
+   */
+  private buildQueryParams;
+  /**
+   * Lists all apps in the project
+   *
+   * @returns Array of app items
+   *
+   * @example
+   * ```typescript
+   * const apps = await client.listApps();
+   * console.log('Available apps:', apps);
+   * ```
+   */
+  listApps(): Promise<AppItem[]>;
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  getAppData(appPath: string): Promise<AppDataResponse>;
+  /**
+   * 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);
+   * ```
+   */
+  runApp(appPath: string): Promise<AppDataResponse>;
+  /**
+   * 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);
+   *   }
+   * });
+   * ```
+   */
+  getDisplays(appPath: string): Promise<GetDisplaysResponse>;
+  /**
+   * 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();
+   * ```
+   */
+  getFile(filePath: string): Promise<Blob>;
+  /**
+   * 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: string): string;
+  /**
+   * 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}`);
+   * ```
+   */
+  getTableData(filePath: string, limit?: number): Promise<TableData>;
+}
+//#endregion
+//#region src/parquet.d.ts
+/**
+ * Query result interface
+ */
+interface QueryResult {
+  columns: string[];
+  rows: any[][];
+  rowCount: number;
+}
+/**
+ * ParquetReader provides methods to read and query Parquet files
+ */
+declare class ParquetReader {
+  private tableName;
+  private registered;
+  constructor(tableName?: string);
+  /**
+   * 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);
+   * ```
+   */
+  registerParquet(blob: Blob): Promise<void>;
+  /**
+   * 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);
+   * ```
+   */
+  query(sql: string): Promise<QueryResult>;
+  /**
+   * 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);
+   * ```
+   */
+  getAll(limit?: number): Promise<QueryResult>;
+  /**
+   * 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'], ...]
+   * ```
+   */
+  getSchema(): Promise<QueryResult>;
+  /**
+   * Get row count
+   *
+   * @returns Number of rows in the table
+   *
+   * @example
+   * ```typescript
+   * const count = await reader.count();
+   * console.log(`Total rows: ${count}`);
+   * ```
+   */
+  count(): Promise<number>;
+  /**
+   * Close and cleanup resources
+   */
+  close(): Promise<void>;
+}
+/**
+ * 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);
+ * ```
+ */
+declare function queryParquet(blob: Blob, sql?: string): Promise<QueryResult>;
+/**
+ * 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`);
+ * ```
+ */
+declare function readParquet(blob: Blob, limit?: number): Promise<QueryResult>;
+//#endregion
+export { type AppDataResponse, type AppItem, type DataContainer, type DisplayData, type DisplayWithError, type FileReference, OxyClient, type OxyConfig, type QueryResult as ParquetQueryResult, ParquetReader, type QueryResult$1 as QueryResult, type TableData, createConfig, queryParquet, readParquet };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/config.ts","../src/types.ts","../src/client.ts","../src/parquet.ts"],"sourcesContent":[],"mappings":"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"}