@robosystems/client 0.2.23 → 0.2.25

package/sdk/types.gen.d.ts

@@ -3018,43 +3018,24 @@ export type MaterializeRequest = {
 };
 /**
  * MaterializeResponse
+ * Response for queued materialization operation.
  */
 export type MaterializeResponse = {
     /**
      * Status
-     * Materialization status
+     * Operation status
      */
-    status: string;
+    status?: string;
     /**
      * Graph Id
      * Graph database identifier
      */
     graph_id: string;
     /**
-     * Was Stale
-     * Whether graph was stale before materialization
-     */
-    was_stale: boolean;
-    /**
-     * Stale Reason
-     * Reason graph was stale
-     */
-    stale_reason?: string | null;
-    /**
-     * Tables Materialized
-     * List of tables successfully materialized
-     */
-    tables_materialized: Array<string>;
-    /**
-     * Total Rows
-     * Total rows materialized across all tables
-     */
-    total_rows: number;
-    /**
-     * Execution Time Ms
-     * Total materialization time
+     * Operation Id
+     * SSE operation ID for progress tracking
      */
-    execution_time_ms: number;
+    operation_id: string;
     /**
      * Message
      * Human-readable status message

package/sdk/types.gen.ts

@@ -3112,43 +3112,24 @@ export type MaterializeRequest = {
 
 /**
  * MaterializeResponse
+ * Response for queued materialization operation.
  */
 export type MaterializeResponse = {
     /**
      * Status
-     * Materialization status
+     * Operation status
      */
-    status: string;
+    status?: string;
     /**
      * Graph Id
      * Graph database identifier
      */
     graph_id: string;
     /**
-     * Was Stale
-     * Whether graph was stale before materialization
-     */
-    was_stale: boolean;
-    /**
-     * Stale Reason
-     * Reason graph was stale
-     */
-    stale_reason?: string | null;
-    /**
-     * Tables Materialized
-     * List of tables successfully materialized
-     */
-    tables_materialized: Array<string>;
-    /**
-     * Total Rows
-     * Total rows materialized across all tables
-     */
-    total_rows: number;
-    /**
-     * Execution Time Ms
-     * Total materialization time
+     * Operation Id
+     * SSE operation ID for progress tracking
      */
-    execution_time_ms: number;
+    operation_id: string;
     /**
      * Message
      * Human-readable status message

package/sdk-extensions/AgentClient.js

@@ -43,7 +43,7 @@ class AgentClient {
                 timestamp: new Date().toISOString(),
             };
         }
-        // Check if this is a queued response (async Celery execution)
+        // Check if this is a queued response (async background task execution)
         if (responseData?.operation_id) {
             const queuedResponse = responseData;
             // If user doesn't want to wait, throw with queue info
@@ -87,7 +87,7 @@ class AgentClient {
                 timestamp: new Date().toISOString(),
             };
         }
-        // Check if this is a queued response (async Celery execution)
+        // Check if this is a queued response (async background task execution)
         if (responseData?.operation_id) {
             const queuedResponse = responseData;
             // If user doesn't want to wait, throw with queue info

package/sdk-extensions/AgentClient.ts

@@ -102,7 +102,7 @@ export class AgentClient {
       }
     }
 
-    // Check if this is a queued response (async Celery execution)
+    // Check if this is a queued response (async background task execution)
     if (responseData?.operation_id) {
       const queuedResponse = responseData as QueuedAgentResponse
 
@@ -158,7 +158,7 @@ export class AgentClient {
       }
     }
 
-    // Check if this is a queued response (async Celery execution)
+    // Check if this is a queued response (async background task execution)
     if (responseData?.operation_id) {
       const queuedResponse = responseData as QueuedAgentResponse
 

package/sdk-extensions/GraphClient.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Error thrown when a graph operation fails (as reported by the server)
+ * This is distinct from connection/SSE errors
+ */
+export declare class GraphOperationError extends Error {
+    constructor(message: string);
+}
 export interface GraphMetadataInput {
     graphName: string;
     description?: string;
@@ -25,6 +32,7 @@ export interface CreateGraphOptions {
     timeout?: number;
     pollInterval?: number;
     onProgress?: (message: string) => void;
+    useSSE?: boolean;
 }
 export declare class GraphClient {
     private operationClient;
@@ -38,6 +46,9 @@ export declare class GraphClient {
     /**
      * Create a graph and wait for completion
      *
+     * Uses SSE (Server-Sent Events) for real-time progress updates with
+     * automatic fallback to polling if SSE connection fails.
+     *
      * @param metadata - Graph metadata (name, description, etc.)
      * @param initialEntity - Optional initial entity to create
      * @param options - Additional options including:
@@ -46,11 +57,20 @@ export declare class GraphClient {
      *                   create graph without populating entity data (useful for file-based ingestion).
      *                   Defaults to true.
      *   - timeout: Maximum time to wait in milliseconds (default: 60000)
-     *   - pollInterval: Time between status checks in milliseconds (default: 2000)
+     *   - pollInterval: Time between status checks in milliseconds (default: 2000, for polling fallback)
      *   - onProgress: Callback for progress updates
+     *   - useSSE: Whether to try SSE first (default: true). Falls back to polling on failure.
      * @returns The graph ID when creation completes
      */
     createGraphAndWait(metadata: GraphMetadataInput, initialEntity?: InitialEntityInput, options?: CreateGraphOptions): Promise<string>;
+    /**
+     * Wait for operation completion using SSE stream
+     */
+    private waitWithSSE;
+    /**
+     * Wait for operation completion using polling
+     */
+    private waitWithPolling;
     /**
      * Get information about a graph
      */

package/sdk-extensions/GraphClient.js

@@ -1,13 +1,25 @@
 'use client';
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GraphClient = void 0;
+exports.GraphClient = exports.GraphOperationError = void 0;
 /**
  * Graph Management Client
- * Provides high-level graph management operations with automatic operation monitoring
+ * Provides high-level graph management operations with automatic operation monitoring.
+ * Supports SSE (Server-Sent Events) for real-time updates with polling fallback.
  */
 const sdk_gen_1 = require("../sdk/sdk.gen");
 const OperationClient_1 = require("./OperationClient");
+/**
+ * Error thrown when a graph operation fails (as reported by the server)
+ * This is distinct from connection/SSE errors
+ */
+class GraphOperationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GraphOperationError';
+    }
+}
+exports.GraphOperationError = GraphOperationError;
 class GraphClient {
     constructor(config) {
         this.config = config;
@@ -16,6 +28,9 @@ class GraphClient {
     /**
      * Create a graph and wait for completion
      *
+     * Uses SSE (Server-Sent Events) for real-time progress updates with
+     * automatic fallback to polling if SSE connection fails.
+     *
      * @param metadata - Graph metadata (name, description, etc.)
      * @param initialEntity - Optional initial entity to create
      * @param options - Additional options including:
@@ -24,12 +39,13 @@ class GraphClient {
      *                   create graph without populating entity data (useful for file-based ingestion).
      *                   Defaults to true.
      *   - timeout: Maximum time to wait in milliseconds (default: 60000)
-     *   - pollInterval: Time between status checks in milliseconds (default: 2000)
+     *   - pollInterval: Time between status checks in milliseconds (default: 2000, for polling fallback)
      *   - onProgress: Callback for progress updates
+     *   - useSSE: Whether to try SSE first (default: true). Falls back to polling on failure.
      * @returns The graph ID when creation completes
      */
     async createGraphAndWait(metadata, initialEntity, options = {}) {
-        const { createEntity = true, timeout = 60000, pollInterval = 2000, onProgress } = options;
+        const { createEntity = true, timeout = 60000, pollInterval = 2000, onProgress, useSSE = true, } = options;
         if (!this.config.token) {
             throw new Error('No API key provided. Set token in config.');
         }
@@ -71,44 +87,96 @@ class GraphClient {
             return responseData.graph_id;
         }
         // Otherwise, we have an operation_id to monitor
-        if (responseData?.operation_id) {
-            const operationId = responseData.operation_id;
-            if (onProgress) {
-                onProgress(`Graph creation queued (operation: ${operationId})`);
+        if (!responseData?.operation_id) {
+            throw new Error('No graph_id or operation_id in response');
+        }
+        const operationId = responseData.operation_id;
+        if (onProgress) {
+            onProgress(`Graph creation queued (operation: ${operationId})`);
+        }
+        // Try SSE first, fall back to polling
+        if (useSSE) {
+            try {
+                return await this.waitWithSSE(operationId, timeout, onProgress);
             }
-            // Poll operation status
-            const maxAttempts = Math.floor(timeout / pollInterval);
-            for (let attempt = 0; attempt < maxAttempts; attempt++) {
-                await new Promise((resolve) => setTimeout(resolve, pollInterval));
-                const statusResponse = await (0, sdk_gen_1.getOperationStatus)({
-                    path: { operation_id: operationId },
-                });
-                const statusData = statusResponse.data;
-                const status = statusData?.status;
+            catch (error) {
+                // Only fall back to polling for SSE connection failures
+                // If it's a GraphOperationError, the operation actually failed - don't retry with polling
+                if (error instanceof GraphOperationError) {
+                    throw error;
+                }
+                // SSE connection failed, fall back to polling
                 if (onProgress) {
-                    onProgress(`Status: ${status} (attempt ${attempt + 1}/${maxAttempts})`);
+                    onProgress('SSE unavailable, using polling...');
                 }
-                if (status === 'completed') {
-                    const result = statusData?.result;
-                    const graphId = result?.graph_id;
-                    if (graphId) {
-                        if (onProgress) {
-                            onProgress(`Graph created: ${graphId}`);
-                        }
-                        return graphId;
+            }
+        }
+        // Fallback to polling
+        return await this.waitWithPolling(operationId, timeout, pollInterval, onProgress);
+    }
+    /**
+     * Wait for operation completion using SSE stream
+     */
+    async waitWithSSE(operationId, timeout, onProgress) {
+        const result = await this.operationClient.monitorOperation(operationId, {
+            timeout,
+            onProgress: (progress) => {
+                if (onProgress) {
+                    if (progress.progressPercent !== undefined) {
+                        onProgress(`${progress.message} (${Math.round(progress.progressPercent)}%)`);
                     }
                     else {
-                        throw new Error('Operation completed but no graph_id in result');
+                        onProgress(progress.message);
                     }
                 }
-                else if (status === 'failed') {
-                    const error = statusData?.error || statusData?.message || 'Unknown error';
-                    throw new Error(`Graph creation failed: ${error}`);
+            },
+        });
+        if (!result.success) {
+            throw new GraphOperationError(result.error || 'Graph creation failed');
+        }
+        const graphId = result.result?.graph_id;
+        if (!graphId) {
+            throw new GraphOperationError('Operation completed but no graph_id in result');
+        }
+        if (onProgress) {
+            onProgress(`Graph created: ${graphId}`);
+        }
+        return graphId;
+    }
+    /**
+     * Wait for operation completion using polling
+     */
+    async waitWithPolling(operationId, timeout, pollInterval, onProgress) {
+        const maxAttempts = Math.floor(timeout / pollInterval);
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            await new Promise((resolve) => setTimeout(resolve, pollInterval));
+            const statusResponse = await (0, sdk_gen_1.getOperationStatus)({
+                path: { operation_id: operationId },
+            });
+            const statusData = statusResponse.data;
+            const status = statusData?.status;
+            if (onProgress) {
+                onProgress(`Status: ${status} (attempt ${attempt + 1}/${maxAttempts})`);
+            }
+            if (status === 'completed') {
+                const result = statusData?.result;
+                const graphId = result?.graph_id;
+                if (graphId) {
+                    if (onProgress) {
+                        onProgress(`Graph created: ${graphId}`);
+                    }
+                    return graphId;
+                }
+                else {
+                    throw new GraphOperationError('Operation completed but no graph_id in result');
                 }
             }
-            throw new Error(`Graph creation timed out after ${timeout}ms`);
+            else if (status === 'failed') {
+                const error = statusData?.error || statusData?.message || 'Unknown error';
+                throw new GraphOperationError(`Graph creation failed: ${error}`);
+            }
         }
-        throw new Error('No graph_id or operation_id in response');
+        throw new GraphOperationError(`Graph creation timed out after ${timeout}ms`);
     }
     /**
      * Get information about a graph

package/sdk-extensions/GraphClient.test.ts

@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi, type MockInstance } from 'vitest'
 import type { GraphMetadataInput, InitialEntityInput } from './GraphClient'
 import { GraphClient } from './GraphClient'
 
@@ -19,20 +19,29 @@ function createMockResponse(data: any, options: { ok?: boolean; status?: number
 describe('GraphClient', () => {
   let graphClient: GraphClient
   let mockFetch: any
+  let mockMonitorOperation: MockInstance
+  let mockCloseAll: MockInstance
 
   beforeEach(() => {
+    // Mock global fetch first
+    mockFetch = vi.fn()
+    global.fetch = mockFetch
+
+    // Create graphClient
     graphClient = new GraphClient({
       baseUrl: 'http://localhost:8000',
       token: 'test-api-key',
       headers: { 'X-API-Key': 'test-api-key' },
     })
 
-    // Mock global fetch
-    mockFetch = vi.fn()
-    global.fetch = mockFetch
+    // Access the internal operationClient and spy on its methods
+    const internalOperationClient = (graphClient as any).operationClient
+    mockMonitorOperation = vi.spyOn(internalOperationClient, 'monitorOperation')
+    mockCloseAll = vi.spyOn(internalOperationClient, 'closeAll').mockImplementation(() => {})
+  })
 
-    // Reset all mocks
-    vi.clearAllMocks()
+  afterEach(() => {
+    vi.restoreAllMocks()
   })
 
   describe('createGraphAndWait', () => {
@@ -174,6 +183,167 @@ describe('GraphClient', () => {
         'No API key provided'
       )
     })
+
+    describe('SSE mode', () => {
+      it('should use SSE when operation_id is returned and SSE succeeds', async () => {
+        // createGraph returns operation_id
+        mockFetch.mockResolvedValueOnce(
+          createMockResponse({
+            operation_id: 'op_sse_success',
+          })
+        )
+
+        mockMonitorOperation.mockResolvedValueOnce({
+          success: true,
+          result: { graph_id: 'graph_from_sse' },
+        })
+
+        const graphId = await graphClient.createGraphAndWait(mockMetadata)
+
+        expect(graphId).toBe('graph_from_sse')
+        expect(mockMonitorOperation).toHaveBeenCalledWith(
+          'op_sse_success',
+          expect.objectContaining({ timeout: 60000 })
+        )
+        // Should only call fetch once (createGraph), no polling calls
+        expect(mockFetch).toHaveBeenCalledTimes(1)
+      })
+
+      it('should format SSE progress with percentage', async () => {
+        mockFetch.mockResolvedValueOnce(
+          createMockResponse({
+            operation_id: 'op_progress',
+          })
+        )
+
+        mockMonitorOperation.mockImplementationOnce(
+          async (_opId: string, options: { onProgress?: (p: any) => void }) => {
+            // Simulate progress callback with percentage
+            if (options.onProgress) {
+              options.onProgress({ message: 'Processing', progressPercent: 50 })
+            }
+            return { success: true, result: { graph_id: 'graph_progress' } }
+          }
+        )
+
+        const onProgress = vi.fn()
+        await graphClient.createGraphAndWait(mockMetadata, undefined, { onProgress })
+
+        expect(onProgress).toHaveBeenCalledWith('Processing (50%)')
+      })
+
+      it('should format SSE progress without percentage', async () => {
+        mockFetch.mockResolvedValueOnce(
+          createMockResponse({
+            operation_id: 'op_no_percent',
+          })
+        )
+
+        mockMonitorOperation.mockImplementationOnce(
+          async (_opId: string, options: { onProgress?: (p: any) => void }) => {
+            if (options.onProgress) {
+              options.onProgress({ message: 'Initializing' })
+            }
+            return { success: true, result: { graph_id: 'graph_init' } }
+          }
+        )
+
+        const onProgress = vi.fn()
+        await graphClient.createGraphAndWait(mockMetadata, undefined, { onProgress })
+
+        expect(onProgress).toHaveBeenCalledWith('Initializing')
+      })
+
+      it('should fall back to polling when SSE fails', async () => {
+        // createGraph returns operation_id
+        mockFetch.mockResolvedValueOnce(
+          createMockResponse({
+            operation_id: 'op_sse_fail',
+          })
+        )
+
+        // SSE fails
+        mockMonitorOperation.mockRejectedValueOnce(new Error('SSE connection failed'))
+
+        // Polling succeeds
+        mockFetch.mockResolvedValueOnce(
+          createMockResponse({
+            status: 'completed',
+            result: { graph_id: 'graph_from_polling' },
+          })
+        )
+
+        const onProgress = vi.fn()
+        const graphId = await graphClient.createGraphAndWait(mockMetadata, undefined, {
+          pollInterval: 100,
+          onProgress,
+        })
+
+        expect(graphId).toBe('graph_from_polling')
+        expect(onProgress).toHaveBeenCalledWith('SSE unavailable, using polling...')
+        // createGraph + 1 polling call
+        expect(mockFetch).toHaveBeenCalledTimes(2)
+      })
+
+      it('should skip SSE when useSSE is false', async () => {
+        mockFetch.mockResolvedValueOnce(
+          createMockResponse({
+            operation_id: 'op_no_sse',
+          })
+        )
+
+        // Polling succeeds
+        mockFetch.mockResolvedValueOnce(
+          createMockResponse({
+            status: 'completed',
+            result: { graph_id: 'graph_polling_only' },
+          })
+        )
+
+        const graphId = await graphClient.createGraphAndWait(mockMetadata, undefined, {
+          useSSE: false,
+          pollInterval: 100,
+        })
+
+        expect(graphId).toBe('graph_polling_only')
+        // SSE should never be called
+        expect(mockMonitorOperation).not.toHaveBeenCalled()
+      })
+
+      it('should throw error when SSE operation fails', async () => {
+        mockFetch.mockResolvedValueOnce(
+          createMockResponse({
+            operation_id: 'op_sse_error',
+          })
+        )
+
+        mockMonitorOperation.mockResolvedValueOnce({
+          success: false,
+          error: 'Operation failed on server',
+        })
+
+        await expect(
+          graphClient.createGraphAndWait(mockMetadata, undefined, { useSSE: true })
+        ).rejects.toThrow('Operation failed on server')
+      })
+
+      it('should throw error when SSE completes but no graph_id in result', async () => {
+        mockFetch.mockResolvedValueOnce(
+          createMockResponse({
+            operation_id: 'op_no_graph_id',
+          })
+        )
+
+        mockMonitorOperation.mockResolvedValueOnce({
+          success: true,
+          result: {}, // No graph_id
+        })
+
+        await expect(graphClient.createGraphAndWait(mockMetadata)).rejects.toThrow(
+          'Operation completed but no graph_id in result'
+        )
+      })
+    })
   })
 
   describe('getGraphInfo', () => {