@robosystems/client 0.2.24 → 0.2.25

package/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/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.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/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', () => {

package/extensions/GraphClient.ts

@@ -2,13 +2,25 @@
 
 /**
  * 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.
  */
 
 import { createGraph, getGraphs, getOperationStatus } from '../sdk.gen'
 import type { GraphMetadata, InitialEntityData } from '../types.gen'
 import { OperationClient } from './OperationClient'
 
+/**
+ * Error thrown when a graph operation fails (as reported by the server)
+ * This is distinct from connection/SSE errors
+ */
+export class GraphOperationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'GraphOperationError'
+  }
+}
+
 // API Response Types
 interface GraphCreateResponse {
   graph_id?: string
@@ -70,6 +82,7 @@ export interface CreateGraphOptions {
   timeout?: number
   pollInterval?: number
   onProgress?: (message: string) => void
+  useSSE?: boolean
 }
 
 export class GraphClient {
@@ -94,6 +107,9 @@ export 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:
@@ -102,8 +118,9 @@ export 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(
@@ -111,7 +128,13 @@ export class GraphClient {
     initialEntity?: InitialEntityInput,
     options: CreateGraphOptions = {}
   ): Promise<string> {
-    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.')
@@ -160,51 +183,118 @@ export class GraphClient {
     }
 
     // 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})`)
-      }
-
-      // Poll operation status
-      const maxAttempts = Math.floor(timeout / pollInterval)
-      for (let attempt = 0; attempt < maxAttempts; attempt++) {
-        await new Promise((resolve) => setTimeout(resolve, pollInterval))
+    if (!responseData?.operation_id) {
+      throw new Error('No graph_id or operation_id in response')
+    }
 
-        const statusResponse = await getOperationStatus({
-          path: { operation_id: operationId },
-        })
+    const operationId = responseData.operation_id
 
-        const statusData = statusResponse.data as OperationStatusResponse
-        const status = statusData?.status
+    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)
+      } 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
+    // Fallback to polling
+    return await this.waitWithPolling(operationId, timeout, pollInterval, onProgress)
+  }
 
-          if (graphId) {
-            if (onProgress) {
-              onProgress(`Graph created: ${graphId}`)
-            }
-            return graphId
+  /**
+   * Wait for operation completion using SSE stream
+   */
+  private async waitWithSSE(
+    operationId: string,
+    timeout: number,
+    onProgress?: (message: string) => void
+  ): Promise<string> {
+    const result = await this.operationClient.monitorOperation<{ graph_id?: string }>(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
+   */
+  private async waitWithPolling(
+    operationId: string,
+    timeout: number,
+    pollInterval: number,
+    onProgress?: (message: string) => void
+  ): Promise<string> {
+    const maxAttempts = Math.floor(timeout / pollInterval)
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      await new Promise((resolve) => setTimeout(resolve, pollInterval))
+
+      const statusResponse = await getOperationStatus({
+        path: { operation_id: operationId },
+      })
+
+      const statusData = statusResponse.data as OperationStatusResponse
+      const status = statusData?.status
+
+      if (onProgress) {
+        onProgress(`Status: ${status} (attempt ${attempt + 1}/${maxAttempts})`)
       }
 
-      throw new Error(`Graph creation timed out after ${timeout}ms`)
+      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')
+        }
+      } 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`)
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robosystems/client",
-  "version": "0.2.24",
+  "version": "0.2.25",
   "description": "TypeScript client library for RoboSystems Financial Knowledge Graph API",
   "main": "index.js",
   "types": "index.d.ts",
@@ -70,11 +70,11 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "typecheck": "tsc --noEmit",
-    "validate": "npm run format:check && npm run lint && npm run typecheck",
+    "validate": "npm run validate:fix && npm run lint && npm run typecheck",
     "feature:create": "./bin/create-feature",
     "release:create": "./bin/create-release",
     "pr:create": "./bin/create-pr",
-    "validate:fix": "npm run format && npm run lint:fix && npm run typecheck",
+    "validate:fix": "npm run format && npm run lint:fix",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:all": "npm run validate && npm run test && npm run build",

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', () => {

package/sdk-extensions/GraphClient.ts

@@ -2,13 +2,25 @@
 
 /**
  * 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.
  */
 
 import { createGraph, getGraphs, getOperationStatus } from '../sdk/sdk.gen'
 import type { GraphMetadata, InitialEntityData } from '../sdk/types.gen'
 import { OperationClient } from './OperationClient'
 
+/**
+ * Error thrown when a graph operation fails (as reported by the server)
+ * This is distinct from connection/SSE errors
+ */
+export class GraphOperationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'GraphOperationError'
+  }
+}
+
 // API Response Types
 interface GraphCreateResponse {
   graph_id?: string
@@ -70,6 +82,7 @@ export interface CreateGraphOptions {
   timeout?: number
   pollInterval?: number
   onProgress?: (message: string) => void
+  useSSE?: boolean
 }
 
 export class GraphClient {
@@ -94,6 +107,9 @@ export 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:
@@ -102,8 +118,9 @@ export 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(
@@ -111,7 +128,13 @@ export class GraphClient {
     initialEntity?: InitialEntityInput,
     options: CreateGraphOptions = {}
   ): Promise<string> {
-    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.')
@@ -160,51 +183,118 @@ export class GraphClient {
     }
 
     // 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})`)
-      }
-
-      // Poll operation status
-      const maxAttempts = Math.floor(timeout / pollInterval)
-      for (let attempt = 0; attempt < maxAttempts; attempt++) {
-        await new Promise((resolve) => setTimeout(resolve, pollInterval))
+    if (!responseData?.operation_id) {
+      throw new Error('No graph_id or operation_id in response')
+    }
 
-        const statusResponse = await getOperationStatus({
-          path: { operation_id: operationId },
-        })
+    const operationId = responseData.operation_id
 
-        const statusData = statusResponse.data as OperationStatusResponse
-        const status = statusData?.status
+    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)
+      } 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
+    // Fallback to polling
+    return await this.waitWithPolling(operationId, timeout, pollInterval, onProgress)
+  }
 
-          if (graphId) {
-            if (onProgress) {
-              onProgress(`Graph created: ${graphId}`)
-            }
-            return graphId
+  /**
+   * Wait for operation completion using SSE stream
+   */
+  private async waitWithSSE(
+    operationId: string,
+    timeout: number,
+    onProgress?: (message: string) => void
+  ): Promise<string> {
+    const result = await this.operationClient.monitorOperation<{ graph_id?: string }>(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
+   */
+  private async waitWithPolling(
+    operationId: string,
+    timeout: number,
+    pollInterval: number,
+    onProgress?: (message: string) => void
+  ): Promise<string> {
+    const maxAttempts = Math.floor(timeout / pollInterval)
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      await new Promise((resolve) => setTimeout(resolve, pollInterval))
+
+      const statusResponse = await getOperationStatus({
+        path: { operation_id: operationId },
+      })
+
+      const statusData = statusResponse.data as OperationStatusResponse
+      const status = statusData?.status
+
+      if (onProgress) {
+        onProgress(`Status: ${status} (attempt ${attempt + 1}/${maxAttempts})`)
       }
 
-      throw new Error(`Graph creation timed out after ${timeout}ms`)
+      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')
+        }
+      } 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`)
   }
 
   /**