@robosystems/client 0.1.17 → 0.1.18

package/sdk-extensions/hooks.d.ts

@@ -1,3 +1,6 @@
+import type { S3CopyRequest } from '../sdk/types.gen';
+import type { CopyOptions, CopyResult } from './CopyClient';
+import { CopyClient } from './CopyClient';
 import type { OperationProgress, OperationResult } from './OperationClient';
 import { OperationClient } from './OperationClient';
 import type { QueryOptions, QueryResult } from './QueryClient';
@@ -105,6 +108,38 @@ export declare function useMultipleOperations<T = any>(): {
  * ```
  */
 export declare function useSDKClients(): {
+    copy: CopyClient | null;
     query: QueryClient | null;
     operations: OperationClient | null;
 };
+/**
+ * Hook for copying data from S3 to graph database with progress monitoring
+ *
+ * @example
+ * ```tsx
+ * const { copyFromS3, loading, progress, error, result } = useCopy('graph_123')
+ *
+ * const handleImport = async () => {
+ *   const result = await copyFromS3({
+ *     table_name: 'companies',
+ *     source_type: 's3',
+ *     s3_uri: 's3://my-bucket/data.csv',
+ *     aws_access_key_id: 'KEY',
+ *     aws_secret_access_key: 'SECRET',
+ *   })
+ * }
+ * ```
+ */
+export declare function useCopy(graphId: string): {
+    copyFromS3: (request: S3CopyRequest, options?: CopyOptions) => Promise<CopyResult | null>;
+    copyWithRetry: (request: S3CopyRequest, maxRetries?: number) => Promise<CopyResult | null>;
+    getStatistics: () => import("./CopyClient").CopyStatistics;
+    loading: boolean;
+    error: Error;
+    result: CopyResult;
+    progress: {
+        message: string;
+        percent?: number;
+    };
+    queuePosition: number;
+};

package/sdk-extensions/hooks.js

@@ -6,6 +6,7 @@ exports.useStreamingQuery = useStreamingQuery;
 exports.useOperation = useOperation;
 exports.useMultipleOperations = useMultipleOperations;
 exports.useSDKClients = useSDKClients;
+exports.useCopy = useCopy;
 /**
  * React hooks for SDK extensions
  * Provides easy-to-use hooks for Next.js/React applications
@@ -13,6 +14,7 @@ exports.useSDKClients = useSDKClients;
 const react_1 = require("react");
 const client_gen_1 = require("../sdk/client.gen");
 const config_1 = require("./config");
+const CopyClient_1 = require("./CopyClient");
 const OperationClient_1 = require("./OperationClient");
 const QueryClient_1 = require("./QueryClient");
 /**
@@ -345,6 +347,7 @@ function useMultipleOperations() {
  */
 function useSDKClients() {
     const [clients, setClients] = (0, react_1.useState)({
+        copy: null,
         query: null,
         operations: null,
     });
@@ -356,16 +359,136 @@ function useSDKClients() {
             credentials: sdkConfig.credentials,
             headers: sdkConfig.headers,
         };
+        const copyClient = new CopyClient_1.CopyClient(baseConfig);
         const queryClient = new QueryClient_1.QueryClient(baseConfig);
         const operationsClient = new OperationClient_1.OperationClient(baseConfig);
         setClients({
+            copy: copyClient,
             query: queryClient,
             operations: operationsClient,
         });
         return () => {
+            copyClient.close();
             queryClient.close();
             operationsClient.closeAll();
         };
     }, []);
     return clients;
 }
+/**
+ * Hook for copying data from S3 to graph database with progress monitoring
+ *
+ * @example
+ * ```tsx
+ * const { copyFromS3, loading, progress, error, result } = useCopy('graph_123')
+ *
+ * const handleImport = async () => {
+ *   const result = await copyFromS3({
+ *     table_name: 'companies',
+ *     source_type: 's3',
+ *     s3_uri: 's3://my-bucket/data.csv',
+ *     aws_access_key_id: 'KEY',
+ *     aws_secret_access_key: 'SECRET',
+ *   })
+ * }
+ * ```
+ */
+function useCopy(graphId) {
+    const [loading, setLoading] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    const [result, setResult] = (0, react_1.useState)(null);
+    const [progress, setProgress] = (0, react_1.useState)(null);
+    const [queuePosition, setQueuePosition] = (0, react_1.useState)(null);
+    const clientRef = (0, react_1.useRef)(null);
+    // Initialize client
+    (0, react_1.useEffect)(() => {
+        const sdkConfig = (0, config_1.getSDKExtensionsConfig)();
+        const clientConfig = client_gen_1.client.getConfig();
+        clientRef.current = new CopyClient_1.CopyClient({
+            baseUrl: sdkConfig.baseUrl || clientConfig.baseUrl || 'http://localhost:8000',
+            credentials: sdkConfig.credentials,
+            headers: sdkConfig.headers,
+        });
+        return () => {
+            clientRef.current?.close();
+        };
+    }, []);
+    const copyFromS3 = (0, react_1.useCallback)(async (request, options) => {
+        if (!clientRef.current)
+            return null;
+        setLoading(true);
+        setError(null);
+        setResult(null);
+        setProgress(null);
+        setQueuePosition(null);
+        try {
+            const copyResult = await clientRef.current.copyFromS3(graphId, request, {
+                ...options,
+                onProgress: (message, progressPercent) => {
+                    setProgress({ message, percent: progressPercent });
+                    setQueuePosition(null); // Clear queue position when executing
+                },
+                onQueueUpdate: (position, estimatedWait) => {
+                    setQueuePosition(position);
+                    setProgress({
+                        message: `Queue position: ${position} (est. ${estimatedWait}s)`,
+                    });
+                },
+                onWarning: (warning) => {
+                    console.warn('Copy warning:', warning);
+                },
+            });
+            setResult(copyResult);
+            return copyResult;
+        }
+        catch (err) {
+            const error = err;
+            setError(error);
+            return null;
+        }
+        finally {
+            setLoading(false);
+            setQueuePosition(null);
+        }
+    }, [graphId]);
+    // Simple copy method with retry logic
+    const copyWithRetry = (0, react_1.useCallback)(async (request, maxRetries = 3) => {
+        if (!clientRef.current)
+            return null;
+        setLoading(true);
+        setError(null);
+        try {
+            const result = await clientRef.current.copyWithRetry(graphId, request, 's3', maxRetries, {
+                onProgress: (message, progressPercent) => {
+                    setProgress({ message, percent: progressPercent });
+                },
+            });
+            setResult(result);
+            return result;
+        }
+        catch (err) {
+            const error = err;
+            setError(error);
+            return null;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [graphId]);
+    // Get statistics from the last copy operation
+    const getStatistics = (0, react_1.useCallback)(() => {
+        if (!clientRef.current || !result)
+            return null;
+        return clientRef.current.calculateStatistics(result);
+    }, [result]);
+    return {
+        copyFromS3,
+        copyWithRetry,
+        getStatistics,
+        loading,
+        error,
+        result,
+        progress,
+        queuePosition,
+    };
+}

package/sdk-extensions/hooks.ts

@@ -7,7 +7,10 @@
 
 import { useCallback, useEffect, useRef, useState } from 'react'
 import { client } from '../sdk/client.gen'
+import type { S3CopyRequest } from '../sdk/types.gen'
 import { getSDKExtensionsConfig } from './config'
+import type { CopyOptions, CopyResult } from './CopyClient'
+import { CopyClient } from './CopyClient'
 import type { OperationProgress, OperationResult } from './OperationClient'
 import { OperationClient } from './OperationClient'
 import type { QueryOptions, QueryResult } from './QueryClient'
@@ -404,9 +407,11 @@ export function useMultipleOperations<T = any>() {
  */
 export function useSDKClients() {
   const [clients, setClients] = useState<{
+    copy: CopyClient | null
     query: QueryClient | null
     operations: OperationClient | null
   }>({
+    copy: null,
     query: null,
     operations: null,
   })
@@ -420,15 +425,18 @@ export function useSDKClients() {
       headers: sdkConfig.headers,
     }
 
+    const copyClient = new CopyClient(baseConfig)
     const queryClient = new QueryClient(baseConfig)
     const operationsClient = new OperationClient(baseConfig)
 
     setClients({
+      copy: copyClient,
       query: queryClient,
       operations: operationsClient,
     })
 
     return () => {
+      copyClient.close()
       queryClient.close()
       operationsClient.closeAll()
     }
@@ -436,3 +444,134 @@ export function useSDKClients() {
 
   return clients
 }
+
+/**
+ * Hook for copying data from S3 to graph database with progress monitoring
+ *
+ * @example
+ * ```tsx
+ * const { copyFromS3, loading, progress, error, result } = useCopy('graph_123')
+ *
+ * const handleImport = async () => {
+ *   const result = await copyFromS3({
+ *     table_name: 'companies',
+ *     source_type: 's3',
+ *     s3_uri: 's3://my-bucket/data.csv',
+ *     aws_access_key_id: 'KEY',
+ *     aws_secret_access_key: 'SECRET',
+ *   })
+ * }
+ * ```
+ */
+export function useCopy(graphId: string) {
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<Error | null>(null)
+  const [result, setResult] = useState<CopyResult | null>(null)
+  const [progress, setProgress] = useState<{
+    message: string
+    percent?: number
+  } | null>(null)
+  const [queuePosition, setQueuePosition] = useState<number | null>(null)
+  const clientRef = useRef<CopyClient>(null)
+
+  // Initialize client
+  useEffect(() => {
+    const sdkConfig = getSDKExtensionsConfig()
+    const clientConfig = client.getConfig()
+    clientRef.current = new CopyClient({
+      baseUrl: sdkConfig.baseUrl || clientConfig.baseUrl || 'http://localhost:8000',
+      credentials: sdkConfig.credentials,
+      headers: sdkConfig.headers,
+    })
+
+    return () => {
+      clientRef.current?.close()
+    }
+  }, [])
+
+  const copyFromS3 = useCallback(
+    async (request: S3CopyRequest, options?: CopyOptions): Promise<CopyResult | null> => {
+      if (!clientRef.current) return null
+
+      setLoading(true)
+      setError(null)
+      setResult(null)
+      setProgress(null)
+      setQueuePosition(null)
+
+      try {
+        const copyResult = await clientRef.current.copyFromS3(graphId, request, {
+          ...options,
+          onProgress: (message, progressPercent) => {
+            setProgress({ message, percent: progressPercent })
+            setQueuePosition(null) // Clear queue position when executing
+          },
+          onQueueUpdate: (position, estimatedWait) => {
+            setQueuePosition(position)
+            setProgress({
+              message: `Queue position: ${position} (est. ${estimatedWait}s)`,
+            })
+          },
+          onWarning: (warning) => {
+            console.warn('Copy warning:', warning)
+          },
+        })
+
+        setResult(copyResult)
+        return copyResult
+      } catch (err) {
+        const error = err as Error
+        setError(error)
+        return null
+      } finally {
+        setLoading(false)
+        setQueuePosition(null)
+      }
+    },
+    [graphId]
+  )
+
+  // Simple copy method with retry logic
+  const copyWithRetry = useCallback(
+    async (request: S3CopyRequest, maxRetries: number = 3): Promise<CopyResult | null> => {
+      if (!clientRef.current) return null
+
+      setLoading(true)
+      setError(null)
+
+      try {
+        const result = await clientRef.current.copyWithRetry(graphId, request, 's3', maxRetries, {
+          onProgress: (message, progressPercent) => {
+            setProgress({ message, percent: progressPercent })
+          },
+        })
+        setResult(result)
+        return result
+      } catch (err) {
+        const error = err as Error
+        setError(error)
+        return null
+      } finally {
+        setLoading(false)
+      }
+    },
+    [graphId]
+  )
+
+  // Get statistics from the last copy operation
+  const getStatistics = useCallback(() => {
+    if (!clientRef.current || !result) return null
+    return clientRef.current.calculateStatistics(result)
+  }, [result])
+
+  return {
+    copyFromS3,
+    copyWithRetry,
+    getStatistics,
+    loading,
+    error,
+    result,
+    progress,
+    queuePosition,
+  }
+}

package/sdk-extensions/index.d.ts

@@ -2,6 +2,7 @@
  * RoboSystems SDK Extensions
  * Enhanced clients with SSE support for the RoboSystems API
  */
+import { CopyClient } from './CopyClient';
 import { OperationClient } from './OperationClient';
 import { QueryClient } from './QueryClient';
 import { SSEClient } from './SSEClient';
@@ -12,6 +13,7 @@ export interface RoboSystemsExtensionConfig {
     retryDelay?: number;
 }
 export declare class RoboSystemsExtensions {
+    readonly copy: CopyClient;
     readonly query: QueryClient;
     readonly operations: OperationClient;
     private config;
@@ -29,12 +31,14 @@ export declare class RoboSystemsExtensions {
      */
     close(): void;
 }
+export * from './CopyClient';
 export * from './OperationClient';
 export * from './QueryClient';
 export * from './SSEClient';
-export { OperationClient, QueryClient, SSEClient };
-export { useMultipleOperations, useOperation, useQuery, useSDKClients, useStreamingQuery, } from './hooks';
+export { CopyClient, OperationClient, QueryClient, SSEClient };
+export { useCopy, useMultipleOperations, useOperation, useQuery, useSDKClients, useStreamingQuery, } from './hooks';
 export declare const extensions: {
+    readonly copy: CopyClient;
     readonly query: QueryClient;
     readonly operations: OperationClient;
     monitorOperation: (operationId: string, onProgress?: (progress: any) => void) => Promise<any>;
@@ -44,3 +48,4 @@ export declare const extensions: {
 export declare const monitorOperation: (operationId: string, onProgress?: (progress: any) => void) => Promise<any>;
 export declare const executeQuery: (graphId: string, query: string, parameters?: Record<string, any>) => Promise<import("./QueryClient").QueryResult>;
 export declare const streamQuery: (graphId: string, query: string, parameters?: Record<string, any>, chunkSize?: number) => AsyncIterableIterator<any>;
+export declare const copyFromS3: (graphId: string, tableName: string, s3Uri: string, accessKeyId: string, secretAccessKey: string, options?: Parameters<CopyClient["copyS3"]>[5]) => Promise<import("./CopyClient").CopyResult>;

package/sdk-extensions/index.js

@@ -18,8 +18,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.streamQuery = exports.executeQuery = exports.monitorOperation = exports.extensions = exports.useStreamingQuery = exports.useSDKClients = exports.useQuery = exports.useOperation = exports.useMultipleOperations = exports.SSEClient = exports.QueryClient = exports.OperationClient = exports.RoboSystemsExtensions = void 0;
+exports.copyFromS3 = exports.streamQuery = exports.executeQuery = exports.monitorOperation = exports.extensions = exports.useStreamingQuery = exports.useSDKClients = exports.useQuery = exports.useOperation = exports.useMultipleOperations = exports.useCopy = exports.SSEClient = exports.QueryClient = exports.OperationClient = exports.CopyClient = exports.RoboSystemsExtensions = void 0;
 const client_gen_1 = require("../sdk/client.gen");
+const CopyClient_1 = require("./CopyClient");
+Object.defineProperty(exports, "CopyClient", { enumerable: true, get: function () { return CopyClient_1.CopyClient; } });
 const OperationClient_1 = require("./OperationClient");
 Object.defineProperty(exports, "OperationClient", { enumerable: true, get: function () { return OperationClient_1.OperationClient; } });
 const QueryClient_1 = require("./QueryClient");
@@ -36,6 +38,10 @@ class RoboSystemsExtensions {
             maxRetries: config.maxRetries || 5,
             retryDelay: config.retryDelay || 1000,
         };
+        this.copy = new CopyClient_1.CopyClient({
+            baseUrl: this.config.baseUrl,
+            credentials: this.config.credentials,
+        });
         this.query = new QueryClient_1.QueryClient({
             baseUrl: this.config.baseUrl,
             credentials: this.config.credentials,
@@ -66,17 +72,20 @@ class RoboSystemsExtensions {
      * Clean up all active connections
      */
     close() {
+        this.copy.close();
         this.query.close();
         this.operations.closeAll();
     }
 }
 exports.RoboSystemsExtensions = RoboSystemsExtensions;
 // Export all types and classes
+__exportStar(require("./CopyClient"), exports);
 __exportStar(require("./OperationClient"), exports);
 __exportStar(require("./QueryClient"), exports);
 __exportStar(require("./SSEClient"), exports);
 // Export React hooks
 var hooks_1 = require("./hooks");
+Object.defineProperty(exports, "useCopy", { enumerable: true, get: function () { return hooks_1.useCopy; } });
 Object.defineProperty(exports, "useMultipleOperations", { enumerable: true, get: function () { return hooks_1.useMultipleOperations; } });
 Object.defineProperty(exports, "useOperation", { enumerable: true, get: function () { return hooks_1.useOperation; } });
 Object.defineProperty(exports, "useQuery", { enumerable: true, get: function () { return hooks_1.useQuery; } });
@@ -91,6 +100,9 @@ function getExtensions() {
     return _extensions;
 }
 exports.extensions = {
+    get copy() {
+        return getExtensions().copy;
+    },
     get query() {
         return getExtensions().query;
     },
@@ -108,3 +120,5 @@ const executeQuery = (graphId, query, parameters) => getExtensions().query.query
 exports.executeQuery = executeQuery;
 const streamQuery = (graphId, query, parameters, chunkSize) => getExtensions().query.streamQuery(graphId, query, parameters, chunkSize);
 exports.streamQuery = streamQuery;
+const copyFromS3 = (graphId, tableName, s3Uri, accessKeyId, secretAccessKey, options) => getExtensions().copy.copyS3(graphId, tableName, s3Uri, accessKeyId, secretAccessKey, options);
+exports.copyFromS3 = copyFromS3;

package/sdk-extensions/index.ts

@@ -4,6 +4,7 @@
  */
 
 import { client } from '../sdk/client.gen'
+import { CopyClient } from './CopyClient'
 import { OperationClient } from './OperationClient'
 import { QueryClient } from './QueryClient'
 import { SSEClient } from './SSEClient'
@@ -16,6 +17,7 @@ export interface RoboSystemsExtensionConfig {
 }
 
 export class RoboSystemsExtensions {
+  public readonly copy: CopyClient
   public readonly query: QueryClient
   public readonly operations: OperationClient
   private config: Required<RoboSystemsExtensionConfig>
@@ -31,6 +33,11 @@ export class RoboSystemsExtensions {
       retryDelay: config.retryDelay || 1000,
     }
 
+    this.copy = new CopyClient({
+      baseUrl: this.config.baseUrl,
+      credentials: this.config.credentials,
+    })
+
     this.query = new QueryClient({
       baseUrl: this.config.baseUrl,
       credentials: this.config.credentials,
@@ -65,19 +72,22 @@ export class RoboSystemsExtensions {
    * Clean up all active connections
    */
   close(): void {
+    this.copy.close()
     this.query.close()
     this.operations.closeAll()
   }
 }
 
 // Export all types and classes
+export * from './CopyClient'
 export * from './OperationClient'
 export * from './QueryClient'
 export * from './SSEClient'
-export { OperationClient, QueryClient, SSEClient }
+export { CopyClient, OperationClient, QueryClient, SSEClient }
 
 // Export React hooks
 export {
+  useCopy,
   useMultipleOperations,
   useOperation,
   useQuery,
@@ -96,6 +106,9 @@ function getExtensions(): RoboSystemsExtensions {
 }
 
 export const extensions = {
+  get copy() {
+    return getExtensions().copy
+  },
   get query() {
     return getExtensions().query
   },
@@ -121,3 +134,12 @@ export const streamQuery = (
   parameters?: Record<string, any>,
   chunkSize?: number
 ) => getExtensions().query.streamQuery(graphId, query, parameters, chunkSize)
+
+export const copyFromS3 = (
+  graphId: string,
+  tableName: string,
+  s3Uri: string,
+  accessKeyId: string,
+  secretAccessKey: string,
+  options?: Parameters<CopyClient['copyS3']>[5]
+) => getExtensions().copy.copyS3(graphId, tableName, s3Uri, accessKeyId, secretAccessKey, options)

package/sdk.gen.d.ts

@@ -1092,9 +1092,44 @@ export declare const getSubgraphQuota: <ThrowOnError extends boolean = false>(op
  * - Premium: 100GB max file size, 60 min timeout
  *
  * **Copy Options:**
- * - `ignore_errors`: Skip duplicate/invalid rows (enables upsert-like behavior)
+ * - `ignore_errors`: Skip duplicate/invalid rows (enables upsert-like behavior). Note: When enabled, row counts may not be accurately reported
  * - `extended_timeout`: Use extended timeout for large datasets
  * - `validate_schema`: Validate source schema against target table
+ *
+ * **Asynchronous Execution with SSE:**
+ * For large data imports, this endpoint returns immediately with an operation ID
+ * and SSE monitoring endpoint. Connect to the returned stream URL for real-time updates:
+ *
+ * ```javascript
+ * const eventSource = new EventSource('/v1/operations/{operation_id}/stream');
+ * eventSource.onmessage = (event) => {
+ * const data = JSON.parse(event.data);
+ * console.log('Progress:', data.message);
+ * };
+ * ```
+ *
+ * **SSE Events Emitted:**
+ * - `operation_started`: Copy operation begins
+ * - `operation_progress`: Progress updates during data transfer
+ * - `operation_completed`: Copy successful with statistics
+ * - `operation_error`: Copy failed with error details
+ *
+ * **SSE Connection Limits:**
+ * - Maximum 5 concurrent SSE connections per user
+ * - Rate limited to 10 new connections per minute
+ * - Automatic circuit breaker for Redis failures
+ * - Graceful degradation if event system unavailable
+ *
+ * **Error Handling:**
+ * - `403 Forbidden`: Attempted copy to shared repository
+ * - `408 Request Timeout`: Operation exceeded timeout limit
+ * - `429 Too Many Requests`: Rate limit exceeded
+ * - `503 Service Unavailable`: Circuit breaker open or service unavailable
+ * - Clients should implement exponential backoff on errors
+ *
+ * **Note:**
+ * Copy operations are FREE - no credit consumption required.
+ * All copy operations are performed asynchronously with progress monitoring.
  */
 export declare const copyDataToGraph: <ThrowOnError extends boolean = false>(options: Options<CopyDataToGraphData, ThrowOnError>) => import("./client").RequestResult<CopyDataToGraphResponses, CopyDataToGraphErrors, ThrowOnError, "fields">;
 /**

package/sdk.gen.js

@@ -2305,9 +2305,44 @@ exports.getSubgraphQuota = getSubgraphQuota;
  * - Premium: 100GB max file size, 60 min timeout
  *
  * **Copy Options:**
- * - `ignore_errors`: Skip duplicate/invalid rows (enables upsert-like behavior)
+ * - `ignore_errors`: Skip duplicate/invalid rows (enables upsert-like behavior). Note: When enabled, row counts may not be accurately reported
  * - `extended_timeout`: Use extended timeout for large datasets
  * - `validate_schema`: Validate source schema against target table
+ *
+ * **Asynchronous Execution with SSE:**
+ * For large data imports, this endpoint returns immediately with an operation ID
+ * and SSE monitoring endpoint. Connect to the returned stream URL for real-time updates:
+ *
+ * ```javascript
+ * const eventSource = new EventSource('/v1/operations/{operation_id}/stream');
+ * eventSource.onmessage = (event) => {
+ * const data = JSON.parse(event.data);
+ * console.log('Progress:', data.message);
+ * };
+ * ```
+ *
+ * **SSE Events Emitted:**
+ * - `operation_started`: Copy operation begins
+ * - `operation_progress`: Progress updates during data transfer
+ * - `operation_completed`: Copy successful with statistics
+ * - `operation_error`: Copy failed with error details
+ *
+ * **SSE Connection Limits:**
+ * - Maximum 5 concurrent SSE connections per user
+ * - Rate limited to 10 new connections per minute
+ * - Automatic circuit breaker for Redis failures
+ * - Graceful degradation if event system unavailable
+ *
+ * **Error Handling:**
+ * - `403 Forbidden`: Attempted copy to shared repository
+ * - `408 Request Timeout`: Operation exceeded timeout limit
+ * - `429 Too Many Requests`: Rate limit exceeded
+ * - `503 Service Unavailable`: Circuit breaker open or service unavailable
+ * - Clients should implement exponential backoff on errors
+ *
+ * **Note:**
+ * Copy operations are FREE - no credit consumption required.
+ * All copy operations are performed asynchronously with progress monitoring.
  */
 const copyDataToGraph = (options) => {
     return (options.client ?? client_gen_1.client).post({

package/sdk.gen.ts

@@ -2319,9 +2319,44 @@ export const getSubgraphQuota = <ThrowOnError extends boolean = false>(options:
  * - Premium: 100GB max file size, 60 min timeout
  *
  * **Copy Options:**
- * - `ignore_errors`: Skip duplicate/invalid rows (enables upsert-like behavior)
+ * - `ignore_errors`: Skip duplicate/invalid rows (enables upsert-like behavior). Note: When enabled, row counts may not be accurately reported
  * - `extended_timeout`: Use extended timeout for large datasets
  * - `validate_schema`: Validate source schema against target table
+ *
+ * **Asynchronous Execution with SSE:**
+ * For large data imports, this endpoint returns immediately with an operation ID
+ * and SSE monitoring endpoint. Connect to the returned stream URL for real-time updates:
+ *
+ * ```javascript
+ * const eventSource = new EventSource('/v1/operations/{operation_id}/stream');
+ * eventSource.onmessage = (event) => {
+ * const data = JSON.parse(event.data);
+ * console.log('Progress:', data.message);
+ * };
+ * ```
+ *
+ * **SSE Events Emitted:**
+ * - `operation_started`: Copy operation begins
+ * - `operation_progress`: Progress updates during data transfer
+ * - `operation_completed`: Copy successful with statistics
+ * - `operation_error`: Copy failed with error details
+ *
+ * **SSE Connection Limits:**
+ * - Maximum 5 concurrent SSE connections per user
+ * - Rate limited to 10 new connections per minute
+ * - Automatic circuit breaker for Redis failures
+ * - Graceful degradation if event system unavailable
+ *
+ * **Error Handling:**
+ * - `403 Forbidden`: Attempted copy to shared repository
+ * - `408 Request Timeout`: Operation exceeded timeout limit
+ * - `429 Too Many Requests`: Rate limit exceeded
+ * - `503 Service Unavailable`: Circuit breaker open or service unavailable
+ * - Clients should implement exponential backoff on errors
+ *
+ * **Note:**
+ * Copy operations are FREE - no credit consumption required.
+ * All copy operations are performed asynchronously with progress monitoring.
  */
 export const copyDataToGraph = <ThrowOnError extends boolean = false>(options: Options<CopyDataToGraphData, ThrowOnError>) => {
     return (options.client ?? _heyApiClient).post<CopyDataToGraphResponses, CopyDataToGraphErrors, ThrowOnError>({