@robosystems/client 0.2.15 → 0.2.17

package/extensions/MaterializationClient.js

@@ -0,0 +1,107 @@
+'use client';
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MaterializationClient = void 0;
+/**
+ * Materialization Client for RoboSystems API
+ *
+ * Manages graph materialization from DuckDB staging tables.
+ * Treats the graph database as a materialized view of the mutable DuckDB data lake.
+ */
+const sdk_gen_1 = require("../sdk.gen");
+class MaterializationClient {
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Materialize graph from DuckDB staging tables
+     *
+     * Rebuilds the complete graph database from the current state of DuckDB
+     * staging tables. Automatically discovers all tables, materializes them in
+     * the correct order (nodes before relationships), and clears the staleness flag.
+     */
+    async materialize(graphId, options = {}) {
+        try {
+            options.onProgress?.('Starting graph materialization...');
+            const request = {
+                ignore_errors: options.ignoreErrors ?? true,
+                rebuild: options.rebuild ?? false,
+                force: options.force ?? false,
+            };
+            const response = await (0, sdk_gen_1.materializeGraph)({
+                path: { graph_id: graphId },
+                body: request,
+            });
+            if (response.error || !response.data) {
+                return {
+                    status: 'failed',
+                    wasStale: false,
+                    tablesMaterialized: [],
+                    totalRows: 0,
+                    executionTimeMs: 0,
+                    message: `Failed to materialize graph: ${response.error}`,
+                    success: false,
+                    error: `Failed to materialize graph: ${response.error}`,
+                };
+            }
+            const result = response.data;
+            options.onProgress?.(`✅ Materialization complete: ${result.tables_materialized?.length || 0} tables, ` +
+                `${result.total_rows?.toLocaleString() || 0} rows in ${result.execution_time_ms?.toFixed(2) || 0}ms`);
+            return {
+                status: result.status,
+                wasStale: result.was_stale,
+                staleReason: result.stale_reason,
+                tablesMaterialized: result.tables_materialized || [],
+                totalRows: result.total_rows || 0,
+                executionTimeMs: result.execution_time_ms || 0,
+                message: result.message || 'Materialization complete',
+                success: true,
+            };
+        }
+        catch (error) {
+            return {
+                status: 'failed',
+                wasStale: false,
+                tablesMaterialized: [],
+                totalRows: 0,
+                executionTimeMs: 0,
+                message: error instanceof Error ? error.message : String(error),
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Get current materialization status for the graph
+     *
+     * Shows whether the graph is stale (DuckDB has changes not yet in graph database),
+     * when it was last materialized, and how long since last materialization.
+     */
+    async status(graphId) {
+        try {
+            const response = await (0, sdk_gen_1.getMaterializationStatus)({
+                path: { graph_id: graphId },
+            });
+            if (response.error || !response.data) {
+                console.error('Failed to get materialization status:', response.error);
+                return null;
+            }
+            const status = response.data;
+            return {
+                graphId: status.graph_id,
+                isStale: status.is_stale,
+                staleReason: status.stale_reason,
+                staleSince: status.stale_since,
+                lastMaterializedAt: status.last_materialized_at,
+                materializationCount: status.materialization_count || 0,
+                hoursSinceMaterialization: status.hours_since_materialization,
+                message: status.message,
+            };
+        }
+        catch (error) {
+            console.error('Failed to get materialization status:', error);
+            return null;
+        }
+    }
+}
+exports.MaterializationClient = MaterializationClient;

package/extensions/MaterializationClient.ts

@@ -0,0 +1,163 @@
+'use client'
+
+/**
+ * Materialization Client for RoboSystems API
+ *
+ * Manages graph materialization from DuckDB staging tables.
+ * Treats the graph database as a materialized view of the mutable DuckDB data lake.
+ */
+
+import { getMaterializationStatus, materializeGraph } from '../sdk.gen'
+import type { MaterializeRequest } from '../types.gen'
+
+export interface MaterializationOptions {
+  ignoreErrors?: boolean
+  rebuild?: boolean
+  force?: boolean
+  onProgress?: (message: string) => void
+}
+
+export interface MaterializationResult {
+  status: string
+  wasStale: boolean
+  staleReason?: string
+  tablesMaterialized: string[]
+  totalRows: number
+  executionTimeMs: number
+  message: string
+  success: boolean
+  error?: string
+}
+
+export interface MaterializationStatus {
+  graphId: string
+  isStale: boolean
+  staleReason?: string
+  staleSince?: string
+  lastMaterializedAt?: string
+  materializationCount: number
+  hoursSinceMaterialization?: number
+  message: string
+}
+
+export class MaterializationClient {
+  private config: {
+    baseUrl: string
+    credentials?: 'include' | 'same-origin' | 'omit'
+    headers?: Record<string, string>
+    token?: string
+  }
+
+  constructor(config: {
+    baseUrl: string
+    credentials?: 'include' | 'same-origin' | 'omit'
+    headers?: Record<string, string>
+    token?: string
+  }) {
+    this.config = config
+  }
+
+  /**
+   * Materialize graph from DuckDB staging tables
+   *
+   * Rebuilds the complete graph database from the current state of DuckDB
+   * staging tables. Automatically discovers all tables, materializes them in
+   * the correct order (nodes before relationships), and clears the staleness flag.
+   */
+  async materialize(
+    graphId: string,
+    options: MaterializationOptions = {}
+  ): Promise<MaterializationResult> {
+    try {
+      options.onProgress?.('Starting graph materialization...')
+
+      const request: MaterializeRequest = {
+        ignore_errors: options.ignoreErrors ?? true,
+        rebuild: options.rebuild ?? false,
+        force: options.force ?? false,
+      }
+
+      const response = await materializeGraph({
+        path: { graph_id: graphId },
+        body: request,
+      })
+
+      if (response.error || !response.data) {
+        return {
+          status: 'failed',
+          wasStale: false,
+          tablesMaterialized: [],
+          totalRows: 0,
+          executionTimeMs: 0,
+          message: `Failed to materialize graph: ${response.error}`,
+          success: false,
+          error: `Failed to materialize graph: ${response.error}`,
+        }
+      }
+
+      const result = response.data as any
+
+      options.onProgress?.(
+        `✅ Materialization complete: ${result.tables_materialized?.length || 0} tables, ` +
+          `${result.total_rows?.toLocaleString() || 0} rows in ${result.execution_time_ms?.toFixed(2) || 0}ms`
+      )
+
+      return {
+        status: result.status,
+        wasStale: result.was_stale,
+        staleReason: result.stale_reason,
+        tablesMaterialized: result.tables_materialized || [],
+        totalRows: result.total_rows || 0,
+        executionTimeMs: result.execution_time_ms || 0,
+        message: result.message || 'Materialization complete',
+        success: true,
+      }
+    } catch (error) {
+      return {
+        status: 'failed',
+        wasStale: false,
+        tablesMaterialized: [],
+        totalRows: 0,
+        executionTimeMs: 0,
+        message: error instanceof Error ? error.message : String(error),
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      }
+    }
+  }
+
+  /**
+   * Get current materialization status for the graph
+   *
+   * Shows whether the graph is stale (DuckDB has changes not yet in graph database),
+   * when it was last materialized, and how long since last materialization.
+   */
+  async status(graphId: string): Promise<MaterializationStatus | null> {
+    try {
+      const response = await getMaterializationStatus({
+        path: { graph_id: graphId },
+      })
+
+      if (response.error || !response.data) {
+        console.error('Failed to get materialization status:', response.error)
+        return null
+      }
+
+      const status = response.data as any
+
+      return {
+        graphId: status.graph_id,
+        isStale: status.is_stale,
+        staleReason: status.stale_reason,
+        staleSince: status.stale_since,
+        lastMaterializedAt: status.last_materialized_at,
+        materializationCount: status.materialization_count || 0,
+        hoursSinceMaterialization: status.hours_since_materialization,
+        message: status.message,
+      }
+    } catch (error) {
+      console.error('Failed to get materialization status:', error)
+      return null
+    }
+  }
+}

package/extensions/TableClient.d.ts

@@ -0,0 +1,38 @@
+export interface TableInfo {
+    tableName: string;
+    rowCount: number;
+    fileCount: number;
+    totalSizeBytes: number;
+    s3Location?: string | null;
+}
+export interface TableQueryResult {
+    columns: string[];
+    rows: any[][];
+    rowCount: number;
+    executionTimeMs: number;
+    success: boolean;
+    error?: string;
+}
+export declare class TableClient {
+    private config;
+    constructor(config: {
+        baseUrl: string;
+        credentials?: 'include' | 'same-origin' | 'omit';
+        headers?: Record<string, string>;
+        token?: string;
+    });
+    /**
+     * List all DuckDB staging tables in a graph
+     */
+    list(graphId: string): Promise<TableInfo[]>;
+    /**
+     * Execute SQL query against DuckDB staging tables
+     *
+     * Example:
+     *   const result = await client.tables.query(
+     *     graphId,
+     *     "SELECT * FROM Entity WHERE entity_type = 'CORPORATION'"
+     *   )
+     */
+    query(graphId: string, sqlQuery: string, limit?: number): Promise<TableQueryResult>;
+}

package/extensions/TableClient.js

@@ -0,0 +1,92 @@
+'use client';
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TableClient = void 0;
+/**
+ * Table Client for RoboSystems API
+ *
+ * Manages DuckDB staging table operations.
+ * Tables provide SQL-queryable staging layer before graph materialization.
+ */
+const sdk_gen_1 = require("../sdk.gen");
+class TableClient {
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * List all DuckDB staging tables in a graph
+     */
+    async list(graphId) {
+        try {
+            const response = await (0, sdk_gen_1.listTables)({
+                path: { graph_id: graphId },
+            });
+            if (response.error || !response.data) {
+                console.error('Failed to list tables:', response.error);
+                return [];
+            }
+            const tableData = response.data;
+            return (tableData.tables?.map((table) => ({
+                tableName: table.table_name,
+                rowCount: table.row_count,
+                fileCount: table.file_count || 0,
+                totalSizeBytes: table.total_size_bytes || 0,
+                s3Location: table.s3_location,
+            })) || []);
+        }
+        catch (error) {
+            console.error('Failed to list tables:', error);
+            return [];
+        }
+    }
+    /**
+     * Execute SQL query against DuckDB staging tables
+     *
+     * Example:
+     *   const result = await client.tables.query(
+     *     graphId,
+     *     "SELECT * FROM Entity WHERE entity_type = 'CORPORATION'"
+     *   )
+     */
+    async query(graphId, sqlQuery, limit) {
+        try {
+            const finalQuery = limit !== undefined ? `${sqlQuery.replace(/;?\s*$/, '')} LIMIT ${limit}` : sqlQuery;
+            const request = {
+                sql: finalQuery,
+            };
+            const response = await (0, sdk_gen_1.queryTables)({
+                path: { graph_id: graphId },
+                body: request,
+            });
+            if (response.error || !response.data) {
+                return {
+                    columns: [],
+                    rows: [],
+                    rowCount: 0,
+                    executionTimeMs: 0,
+                    success: false,
+                    error: `Query failed: ${response.error}`,
+                };
+            }
+            const result = response.data;
+            return {
+                columns: result.columns || [],
+                rows: result.rows || [],
+                rowCount: result.rows?.length || 0,
+                executionTimeMs: result.execution_time_ms || 0,
+                success: true,
+            };
+        }
+        catch (error) {
+            return {
+                columns: [],
+                rows: [],
+                rowCount: 0,
+                executionTimeMs: 0,
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+}
+exports.TableClient = TableClient;

package/extensions/TableClient.ts

@@ -0,0 +1,132 @@
+'use client'
+
+/**
+ * Table Client for RoboSystems API
+ *
+ * Manages DuckDB staging table operations.
+ * Tables provide SQL-queryable staging layer before graph materialization.
+ */
+
+import { listTables, queryTables } from '../sdk.gen'
+import type { TableListResponse, TableQueryRequest } from '../types.gen'
+
+export interface TableInfo {
+  tableName: string
+  rowCount: number
+  fileCount: number
+  totalSizeBytes: number
+  s3Location?: string | null
+}
+
+export interface TableQueryResult {
+  columns: string[]
+  rows: any[][]
+  rowCount: number
+  executionTimeMs: number
+  success: boolean
+  error?: string
+}
+
+export class TableClient {
+  private config: {
+    baseUrl: string
+    credentials?: 'include' | 'same-origin' | 'omit'
+    headers?: Record<string, string>
+    token?: string
+  }
+
+  constructor(config: {
+    baseUrl: string
+    credentials?: 'include' | 'same-origin' | 'omit'
+    headers?: Record<string, string>
+    token?: string
+  }) {
+    this.config = config
+  }
+
+  /**
+   * List all DuckDB staging tables in a graph
+   */
+  async list(graphId: string): Promise<TableInfo[]> {
+    try {
+      const response = await listTables({
+        path: { graph_id: graphId },
+      })
+
+      if (response.error || !response.data) {
+        console.error('Failed to list tables:', response.error)
+        return []
+      }
+
+      const tableData = response.data as TableListResponse
+
+      return (
+        tableData.tables?.map((table) => ({
+          tableName: table.table_name,
+          rowCount: table.row_count,
+          fileCount: table.file_count || 0,
+          totalSizeBytes: table.total_size_bytes || 0,
+          s3Location: table.s3_location,
+        })) || []
+      )
+    } catch (error) {
+      console.error('Failed to list tables:', error)
+      return []
+    }
+  }
+
+  /**
+   * Execute SQL query against DuckDB staging tables
+   *
+   * Example:
+   *   const result = await client.tables.query(
+   *     graphId,
+   *     "SELECT * FROM Entity WHERE entity_type = 'CORPORATION'"
+   *   )
+   */
+  async query(graphId: string, sqlQuery: string, limit?: number): Promise<TableQueryResult> {
+    try {
+      const finalQuery =
+        limit !== undefined ? `${sqlQuery.replace(/;?\s*$/, '')} LIMIT ${limit}` : sqlQuery
+
+      const request: TableQueryRequest = {
+        sql: finalQuery,
+      }
+
+      const response = await queryTables({
+        path: { graph_id: graphId },
+        body: request,
+      })
+
+      if (response.error || !response.data) {
+        return {
+          columns: [],
+          rows: [],
+          rowCount: 0,
+          executionTimeMs: 0,
+          success: false,
+          error: `Query failed: ${response.error}`,
+        }
+      }
+
+      const result = response.data as any
+
+      return {
+        columns: result.columns || [],
+        rows: result.rows || [],
+        rowCount: result.rows?.length || 0,
+        executionTimeMs: result.execution_time_ms || 0,
+        success: true,
+      }
+    } catch (error) {
+      return {
+        columns: [],
+        rows: [],
+        rowCount: 0,
+        executionTimeMs: 0,
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      }
+    }
+  }
+}

package/extensions/hooks.d.ts

@@ -1,8 +1,10 @@
+import type { FileInput, FileUploadOptions, FileUploadResult } from './FileClient';
+import type { MaterializationOptions } from './MaterializationClient';
 import type { OperationProgress, OperationResult } from './OperationClient';
 import { OperationClient } from './OperationClient';
 import type { QueryOptions, QueryResult } from './QueryClient';
 import { QueryClient } from './QueryClient';
-import type { FileInput, IngestOptions, UploadOptions, UploadResult } from './TableIngestClient';
+import type { TableInfo } from './TableClient';
 /**
  * Hook for executing Cypher queries with loading states and error handling
  *
@@ -110,11 +112,11 @@ export declare function useSDKClients(): {
     operations: OperationClient | null;
 };
 /**
- * Hook for uploading Parquet files to staging tables
+ * Hook for uploading Parquet files to staging and materializing graphs
  *
  * @example
  * ```tsx
- * const { upload, uploadAndIngest, loading, error, progress } = useTableUpload('graph_123')
+ * const { upload, listTables, materialize, loading, error, progress } = useTableUpload('graph_123')
  *
  * const handleFileUpload = async (file: File) => {
  *   const result = await upload('Entity', file, {
@@ -129,15 +131,11 @@ export declare function useSDKClients(): {
  * ```
  */
 export declare function useTableUpload(graphId: string): {
-    upload: (tableName: string, fileOrBuffer: FileInput, options?: UploadOptions) => Promise<UploadResult | null>;
-    uploadAndIngest: (tableName: string, fileOrBuffer: FileInput, uploadOptions?: UploadOptions, ingestOptions?: IngestOptions) => Promise<{
-        upload: UploadResult;
-        ingest: any;
-    } | null>;
-    listTables: () => Promise<import("./TableIngestClient").TableInfo[]>;
-    ingestAllTables: (options?: IngestOptions) => Promise<import("./TableIngestClient").IngestResult>;
+    upload: (tableName: string, fileOrBuffer: FileInput, options?: FileUploadOptions) => Promise<FileUploadResult | null>;
+    listTables: () => Promise<TableInfo[]>;
+    materialize: (options?: MaterializationOptions) => Promise<import("./MaterializationClient").MaterializationResult>;
     loading: boolean;
     error: Error;
     progress: string;
-    uploadResult: UploadResult;
+    uploadResult: FileUploadResult;
 };