@robosystems/client 0.1.15 → 0.1.16

package/sdk-extensions/hooks.ts

@@ -0,0 +1,438 @@
+'use client'
+
+/**
+ * React hooks for SDK extensions
+ * Provides easy-to-use hooks for Next.js/React applications
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { client } from '../sdk/client.gen'
+import { getSDKExtensionsConfig } from './config'
+import type { OperationProgress, OperationResult } from './OperationClient'
+import { OperationClient } from './OperationClient'
+import type { QueryOptions, QueryResult } from './QueryClient'
+import { QueryClient } from './QueryClient'
+
+/**
+ * Hook for executing Cypher queries with loading states and error handling
+ *
+ * @example
+ * ```tsx
+ * const { execute, loading, error, data } = useQuery('graph_123')
+ *
+ * const handleSearch = async () => {
+ *   const result = await execute('MATCH (n:Company) RETURN n LIMIT 10')
+ *   console.log(result.data)
+ * }
+ * ```
+ */
+export function useQuery(graphId: string) {
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<Error | null>(null)
+  const [data, setData] = useState<QueryResult | null>(null)
+  const [queuePosition, setQueuePosition] = useState<number | null>(null)
+  const clientRef = useRef<QueryClient>(null)
+
+  // Initialize client
+  useEffect(() => {
+    const sdkConfig = getSDKExtensionsConfig()
+    const clientConfig = client.getConfig()
+    clientRef.current = new QueryClient({
+      baseUrl: sdkConfig.baseUrl || clientConfig.baseUrl || 'http://localhost:8000',
+      credentials: sdkConfig.credentials,
+      headers: sdkConfig.headers,
+    })
+
+    return () => {
+      clientRef.current?.close()
+    }
+  }, [])
+
+  const execute = useCallback(
+    async (
+      query: string,
+      parameters?: Record<string, any>,
+      options?: QueryOptions
+    ): Promise<QueryResult | null> => {
+      if (!clientRef.current) return null
+
+      setLoading(true)
+      setError(null)
+      setData(null)
+      setQueuePosition(null)
+
+      try {
+        const result = (await clientRef.current.executeQuery(
+          graphId,
+          { query, parameters },
+          {
+            ...options,
+            onQueueUpdate: (position) => {
+              setQueuePosition(position)
+            },
+            onProgress: () => {
+              setQueuePosition(null) // Clear queue position when executing
+            },
+          }
+        )) as QueryResult
+
+        setData(result)
+        return result
+      } catch (err) {
+        const error = err as Error
+        setError(error)
+        return null
+      } finally {
+        setLoading(false)
+        setQueuePosition(null)
+      }
+    },
+    [graphId]
+  )
+
+  // Simple query method that returns just the data
+  const query = useCallback(
+    async (cypher: string, parameters?: Record<string, any>) => {
+      const result = await execute(cypher, parameters)
+      return result?.data || []
+    },
+    [execute]
+  )
+
+  return {
+    execute,
+    query,
+    loading,
+    error,
+    data,
+    queuePosition,
+  }
+}
+
+/**
+ * Hook for streaming large query results
+ *
+ * @example
+ * ```tsx
+ * const { stream, isStreaming, error, cancel } = useStreamingQuery('graph_123')
+ *
+ * const handleStream = async () => {
+ *   const iterator = stream('MATCH (n) RETURN n')
+ *   for await (const batch of iterator) {
+ *     console.log('Received batch:', batch)
+ *   }
+ * }
+ * ```
+ */
+export function useStreamingQuery(graphId: string) {
+  const [isStreaming, setIsStreaming] = useState(false)
+  const [error, setError] = useState<Error | null>(null)
+  const [rowsReceived, setRowsReceived] = useState(0)
+  const clientRef = useRef<QueryClient>(null)
+
+  useEffect(() => {
+    const sdkConfig = getSDKExtensionsConfig()
+    const clientConfig = client.getConfig()
+    clientRef.current = new QueryClient({
+      baseUrl: sdkConfig.baseUrl || clientConfig.baseUrl || 'http://localhost:8000',
+      credentials: sdkConfig.credentials,
+      headers: sdkConfig.headers,
+    })
+
+    return () => {
+      clientRef.current?.close()
+    }
+  }, [])
+
+  const stream = useCallback(
+    async function* (
+      query: string,
+      parameters?: Record<string, any>,
+      chunkSize: number = 100
+    ): AsyncIterableIterator<any[]> {
+      if (!clientRef.current) return
+
+      setIsStreaming(true)
+      setError(null)
+      setRowsReceived(0)
+
+      try {
+        const iterator = clientRef.current.streamQuery(graphId, query, parameters, chunkSize)
+
+        let buffer: any[] = []
+        let count = 0
+
+        for await (const row of iterator) {
+          buffer.push(row)
+          count++
+
+          if (buffer.length >= chunkSize) {
+            setRowsReceived(count)
+            yield buffer
+            buffer = []
+          }
+        }
+
+        // Yield any remaining items
+        if (buffer.length > 0) {
+          setRowsReceived(count)
+          yield buffer
+        }
+      } catch (err) {
+        setError(err as Error)
+        throw err
+      } finally {
+        setIsStreaming(false)
+      }
+    },
+    [graphId]
+  )
+
+  const cancel = useCallback(() => {
+    clientRef.current?.close()
+    setIsStreaming(false)
+  }, [])
+
+  return {
+    stream,
+    isStreaming,
+    error,
+    rowsReceived,
+    cancel,
+  }
+}
+
+/**
+ * Hook for monitoring long-running operations
+ *
+ * @example
+ * ```tsx
+ * const { monitor, status, progress, error, result } = useOperation<BackupResult>()
+ *
+ * const handleBackup = async () => {
+ *   const { operation_id } = await createBackup({ ... })
+ *   const result = await monitor(operation_id)
+ *   console.log('Backup completed:', result)
+ * }
+ * ```
+ */
+export function useOperation<T = any>(operationId?: string) {
+  const [status, setStatus] = useState<'idle' | 'running' | 'completed' | 'error'>('idle')
+  const [progress, setProgress] = useState<OperationProgress | null>(null)
+  const [error, setError] = useState<Error | null>(null)
+  const [result, setResult] = useState<OperationResult<T> | null>(null)
+  const clientRef = useRef<OperationClient>(null)
+
+  useEffect(() => {
+    const sdkConfig = getSDKExtensionsConfig()
+    const clientConfig = client.getConfig()
+    clientRef.current = new OperationClient({
+      baseUrl: sdkConfig.baseUrl || clientConfig.baseUrl || 'http://localhost:8000',
+      credentials: sdkConfig.credentials,
+      maxRetries: sdkConfig.maxRetries,
+      retryDelay: sdkConfig.retryDelay,
+    })
+
+    return () => {
+      clientRef.current?.closeAll()
+    }
+  }, [])
+
+  const monitor = useCallback(
+    async (id: string, timeout?: number): Promise<OperationResult<T> | null> => {
+      if (!clientRef.current) return null
+
+      setStatus('running')
+      setError(null)
+      setResult(null)
+      setProgress(null)
+
+      try {
+        const opResult = await clientRef.current.monitorOperation<T>(id, {
+          onProgress: (p) => {
+            setProgress(p)
+          },
+          onQueueUpdate: (position, estimatedWait) => {
+            setProgress({
+              message: `Queue position: ${position}`,
+              progressPercent: 0,
+              details: { position, estimatedWait },
+            })
+          },
+          timeout,
+        })
+
+        setResult(opResult)
+        setStatus(opResult.success ? 'completed' : 'error')
+
+        if (!opResult.success && opResult.error) {
+          setError(new Error(opResult.error))
+        }
+
+        return opResult
+      } catch (err) {
+        const error = err as Error
+        setError(error)
+        setStatus('error')
+        return null
+      }
+    },
+    []
+  )
+
+  const cancel = useCallback(async (id: string) => {
+    if (!clientRef.current) return
+
+    try {
+      await clientRef.current.cancelOperation(id)
+      setStatus('idle')
+    } catch (err) {
+      setError(err as Error)
+    }
+  }, [])
+
+  // Auto-monitor if operationId is provided
+  useEffect(() => {
+    if (operationId && status === 'idle') {
+      monitor(operationId)
+    }
+  }, [operationId, monitor, status])
+
+  return {
+    monitor,
+    cancel,
+    status,
+    progress,
+    error,
+    result,
+  }
+}
+
+/**
+ * Hook for monitoring multiple operations concurrently
+ *
+ * @example
+ * ```tsx
+ * const { monitorAll, results, allCompleted, hasErrors } = useMultipleOperations()
+ *
+ * const handleMultiple = async () => {
+ *   const operations = await Promise.all([
+ *     createBackup(...),
+ *     createExport(...),
+ *   ])
+ *
+ *   const results = await monitorAll(operations.map(op => op.operation_id))
+ * }
+ * ```
+ */
+export function useMultipleOperations<T = any>() {
+  const [results, setResults] = useState<Map<string, OperationResult<T>>>(new Map())
+  const [loading, setLoading] = useState(false)
+  const [errors, setErrors] = useState<Map<string, Error>>(new Map())
+  const clientRef = useRef<OperationClient>(null)
+
+  useEffect(() => {
+    const sdkConfig = getSDKExtensionsConfig()
+    const clientConfig = client.getConfig()
+    clientRef.current = new OperationClient({
+      baseUrl: sdkConfig.baseUrl || clientConfig.baseUrl || 'http://localhost:8000',
+      credentials: sdkConfig.credentials,
+      maxRetries: sdkConfig.maxRetries,
+      retryDelay: sdkConfig.retryDelay,
+    })
+
+    return () => {
+      clientRef.current?.closeAll()
+    }
+  }, [])
+
+  const monitorAll = useCallback(
+    async (operationIds: string[]): Promise<Map<string, OperationResult<T>>> => {
+      if (!clientRef.current) return new Map()
+
+      setLoading(true)
+      setResults(new Map())
+      setErrors(new Map())
+
+      try {
+        const allResults = await clientRef.current.monitorMultiple<T>(operationIds)
+        setResults(allResults)
+
+        // Extract any errors
+        const newErrors = new Map<string, Error>()
+        allResults.forEach((result, id) => {
+          if (!result.success && result.error) {
+            newErrors.set(id, new Error(result.error))
+          }
+        })
+        setErrors(newErrors)
+
+        return allResults
+      } finally {
+        setLoading(false)
+      }
+    },
+    []
+  )
+
+  const allCompleted =
+    results.size > 0 && Array.from(results.values()).every((r) => r.success || r.error)
+
+  const hasErrors = errors.size > 0
+
+  return {
+    monitorAll,
+    results,
+    errors,
+    loading,
+    allCompleted,
+    hasErrors,
+  }
+}
+
+/**
+ * Hook that provides access to all SDK extension clients
+ * Useful when you need direct access to the underlying clients
+ *
+ * @example
+ * ```tsx
+ * const clients = useSDKClients()
+ *
+ * // Direct access to clients
+ * const result = await clients.query.query('graph_123', 'MATCH (n) RETURN n')
+ * ```
+ */
+export function useSDKClients() {
+  const [clients, setClients] = useState<{
+    query: QueryClient | null
+    operations: OperationClient | null
+  }>({
+    query: null,
+    operations: null,
+  })
+
+  useEffect(() => {
+    const sdkConfig = getSDKExtensionsConfig()
+    const clientConfig = client.getConfig()
+    const baseConfig = {
+      baseUrl: sdkConfig.baseUrl || clientConfig.baseUrl || 'http://localhost:8000',
+      credentials: sdkConfig.credentials,
+      headers: sdkConfig.headers,
+    }
+
+    const queryClient = new QueryClient(baseConfig)
+    const operationsClient = new OperationClient(baseConfig)
+
+    setClients({
+      query: queryClient,
+      operations: operationsClient,
+    })
+
+    return () => {
+      queryClient.close()
+      operationsClient.closeAll()
+    }
+  }, [])
+
+  return clients
+}

package/sdk-extensions/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * RoboSystems SDK Extensions
+ * Enhanced clients with SSE support for the RoboSystems API
+ */
+import { OperationClient } from './OperationClient';
+import { QueryClient } from './QueryClient';
+import { SSEClient } from './SSEClient';
+export interface RoboSystemsExtensionConfig {
+    baseUrl?: string;
+    credentials?: 'include' | 'same-origin' | 'omit';
+    maxRetries?: number;
+    retryDelay?: number;
+}
+export declare class RoboSystemsExtensions {
+    readonly query: QueryClient;
+    readonly operations: OperationClient;
+    private config;
+    constructor(config?: RoboSystemsExtensionConfig);
+    /**
+     * Convenience method to monitor any operation
+     */
+    monitorOperation(operationId: string, onProgress?: (progress: any) => void): Promise<any>;
+    /**
+     * Create custom SSE client for advanced use cases
+     */
+    createSSEClient(): SSEClient;
+    /**
+     * Clean up all active connections
+     */
+    close(): void;
+}
+export * from './OperationClient';
+export * from './QueryClient';
+export * from './SSEClient';
+export { OperationClient, QueryClient, SSEClient };
+export { useMultipleOperations, useOperation, useQuery, useSDKClients, useStreamingQuery, } from './hooks';
+export declare const extensions: {
+    readonly query: QueryClient;
+    readonly operations: OperationClient;
+    monitorOperation: (operationId: string, onProgress?: (progress: any) => void) => Promise<any>;
+    createSSEClient: () => SSEClient;
+    close: () => void;
+};
+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>;

package/sdk-extensions/index.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * RoboSystems SDK Extensions
+ * Enhanced clients with SSE support for the RoboSystems API
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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;
+const client_gen_1 = require("../sdk/client.gen");
+const OperationClient_1 = require("./OperationClient");
+Object.defineProperty(exports, "OperationClient", { enumerable: true, get: function () { return OperationClient_1.OperationClient; } });
+const QueryClient_1 = require("./QueryClient");
+Object.defineProperty(exports, "QueryClient", { enumerable: true, get: function () { return QueryClient_1.QueryClient; } });
+const SSEClient_1 = require("./SSEClient");
+Object.defineProperty(exports, "SSEClient", { enumerable: true, get: function () { return SSEClient_1.SSEClient; } });
+class RoboSystemsExtensions {
+    constructor(config = {}) {
+        // Get base URL from SDK client config or use provided/default
+        const sdkConfig = client_gen_1.client.getConfig();
+        this.config = {
+            baseUrl: config.baseUrl || sdkConfig.baseUrl || 'http://localhost:8000',
+            credentials: config.credentials || 'include',
+            maxRetries: config.maxRetries || 5,
+            retryDelay: config.retryDelay || 1000,
+        };
+        this.query = new QueryClient_1.QueryClient({
+            baseUrl: this.config.baseUrl,
+            credentials: this.config.credentials,
+        });
+        this.operations = new OperationClient_1.OperationClient({
+            baseUrl: this.config.baseUrl,
+            credentials: this.config.credentials,
+        });
+    }
+    /**
+     * Convenience method to monitor any operation
+     */
+    async monitorOperation(operationId, onProgress) {
+        return this.operations.monitorOperation(operationId, { onProgress });
+    }
+    /**
+     * Create custom SSE client for advanced use cases
+     */
+    createSSEClient() {
+        return new SSEClient_1.SSEClient({
+            baseUrl: this.config.baseUrl,
+            credentials: this.config.credentials,
+            maxRetries: this.config.maxRetries,
+            retryDelay: this.config.retryDelay,
+        });
+    }
+    /**
+     * Clean up all active connections
+     */
+    close() {
+        this.query.close();
+        this.operations.closeAll();
+    }
+}
+exports.RoboSystemsExtensions = RoboSystemsExtensions;
+// Export all types and classes
+__exportStar(require("./OperationClient"), exports);
+__exportStar(require("./QueryClient"), exports);
+__exportStar(require("./SSEClient"), exports);
+// Export React hooks
+var hooks_1 = require("./hooks");
+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; } });
+Object.defineProperty(exports, "useSDKClients", { enumerable: true, get: function () { return hooks_1.useSDKClients; } });
+Object.defineProperty(exports, "useStreamingQuery", { enumerable: true, get: function () { return hooks_1.useStreamingQuery; } });
+// Lazy initialization of default instance
+let _extensions = null;
+function getExtensions() {
+    if (!_extensions) {
+        _extensions = new RoboSystemsExtensions();
+    }
+    return _extensions;
+}
+exports.extensions = {
+    get query() {
+        return getExtensions().query;
+    },
+    get operations() {
+        return getExtensions().operations;
+    },
+    monitorOperation: (operationId, onProgress) => getExtensions().monitorOperation(operationId, onProgress),
+    createSSEClient: () => getExtensions().createSSEClient(),
+    close: () => getExtensions().close(),
+};
+// Export convenience functions that use the default instance
+const monitorOperation = (operationId, onProgress) => getExtensions().monitorOperation(operationId, onProgress);
+exports.monitorOperation = monitorOperation;
+const executeQuery = (graphId, query, parameters) => getExtensions().query.query(graphId, query, parameters);
+exports.executeQuery = executeQuery;
+const streamQuery = (graphId, query, parameters, chunkSize) => getExtensions().query.streamQuery(graphId, query, parameters, chunkSize);
+exports.streamQuery = streamQuery;