@superblocksteam/sdk-api 0.0.6 → 0.0.8

package/src/runtime/streaming-executor.ts

@@ -1,367 +0,0 @@
-/**
- * Streaming API execution engine.
- *
- * Provides the entry point for executing compiled streaming APIs,
- * handling input validation, chunk validation, and error management.
- */
-
-import type { CompiledStreamingApi } from "../api/streaming.js";
-import { getIntegrationDeclarations } from "../integrations/declarations.js";
-import type { TraceMetadata } from "../integrations/registry.js";
-import type { IntegrationConfig } from "../integrations/types.js";
-import type { ApiUser } from "../types.js";
-import {
-  createStreamingApiContext,
-  type CreateStreamingContextOptions,
-} from "./streaming-context.js";
-import {
-  SdkError,
-  InputValidationError,
-  ExecutionError,
-  ErrorCode,
-  type ErrorCodeType,
-} from "./errors.js";
-
-/**
- * Request to execute a streaming API.
- */
-export interface ExecuteStreamingApiRequest {
-  /** Raw input data to be validated */
-  input: unknown;
-
-  /** Available integration configurations */
-  integrations: IntegrationConfig[];
-
-  /** Unique execution ID for tracing */
-  executionId: string;
-
-  /** Environment variables available to the API */
-  env: Record<string, string>;
-
-  /** User information extracted from the Superblocks JWT */
-  user: ApiUser;
-
-  /**
-   * Function to execute integration operations (non-streaming).
-   *
-   * @param integrationId - The integration ID
-   * @param request - Plugin-specific request object
-   * @param bindings - Optional bindings for language plugins
-   * @returns Promise resolving to the operation result
-   */
-  executeQuery: (
-    integrationId: string,
-    request: Record<string, unknown>,
-    bindings?: Record<string, unknown>,
-    metadata?: TraceMetadata,
-  ) => Promise<unknown>;
-
-  /**
-   * Function to execute streaming integration operations.
-   *
-   * @param integrationId - The integration ID
-   * @param request - Plugin-specific request object
-   * @param metadata - Optional trace metadata for diagnostics
-   * @returns AsyncIterable yielding raw chunks
-   */
-  executeStreamingQuery?: (
-    integrationId: string,
-    request: Record<string, unknown>,
-    metadata?: TraceMetadata,
-  ) => AsyncIterable<unknown>;
-}
-
-/**
- * Callback handlers for streaming API execution.
- */
-export interface StreamingApiCallbacks<TChunk = unknown> {
-  /**
-   * Called for each validated chunk.
-   *
-   * @param chunk - The validated chunk
-   * @param index - Zero-based index of this chunk
-   */
-  onChunk: (chunk: TChunk, index: number) => void;
-
-  /**
-   * Called when the stream completes successfully.
-   *
-   * @param totalChunks - Total number of chunks yielded
-   */
-  onComplete?: (totalChunks: number) => void;
-
-  /**
-   * Called when an error occurs.
-   *
-   * @param error - The error that occurred
-   */
-  onError?: (error: StreamingApiError) => void;
-}
-
-/**
- * Error details for streaming API execution.
- */
-export interface StreamingApiError {
-  code: ErrorCodeType;
-  message: string;
-  details?: unknown;
-  /** Number of chunks successfully yielded before the error */
-  chunksYielded?: number;
-}
-
-/**
- * Result of streaming API execution.
- *
- * Uses a discriminated union to prevent impossible states
- * like `{ success: true, error: {...} }`.
- */
-export type ExecuteStreamingApiResult =
-  | { success: true; totalChunks: number }
-  | { success: false; totalChunks: number; error: StreamingApiError };
-
-/**
- * Executes a compiled streaming API with the given request.
- *
- * This function handles:
- * 1. Input validation against the API's Zod schema
- * 2. Context creation with integration clients
- * 3. Iterating over the async generator
- * 4. Chunk validation against the API's chunk schema
- * 5. Calling callbacks for chunks, completion, and errors
- *
- * @param api - The compiled streaming API definition
- * @param request - The execution request
- * @param callbacks - Callbacks for chunks, completion, and errors
- * @returns Promise resolving to execution result
- *
- * @example
- * ```typescript
- * import { streamingApi, z, executeStreamingApi } from '@superblocksteam/sdk-api';
- *
- * const myApi = streamingApi({
- *   input: z.object({ prompt: z.string() }),
- *   chunk: z.object({ text: z.string() }),
- *   async *run(ctx) {
- *     yield { text: 'Hello' };
- *     yield { text: ' World' };
- *   },
- * });
- *
- * const result = await executeStreamingApi(
- *   myApi,
- *   {
- *     input: { prompt: 'Hi' },
- *     integrations: [],
- *     executionId: 'exec_123',
- *     env: {},
- *     executeQuery: async () => ({}),
- *   },
- *   {
- *     onChunk: (chunk, index) => console.log(`Chunk ${index}:`, chunk),
- *     onComplete: (total) => console.log(`Stream completed with ${total} chunks`),
- *     onError: (error) => console.error('Stream error:', error),
- *   }
- * );
- * ```
- */
-export async function executeStreamingApi<TInput = unknown, TChunk = unknown>(
-  api: CompiledStreamingApi<TInput, TChunk>,
-  request: ExecuteStreamingApiRequest,
-  callbacks: StreamingApiCallbacks<TChunk>,
-): Promise<ExecuteStreamingApiResult> {
-  let totalChunks = 0;
-
-  try {
-    // 1. Validate input
-    const inputResult = api.inputSchema.safeParse(request.input);
-    if (!inputResult.success) {
-      const error: StreamingApiError = {
-        code: ErrorCode.INPUT_VALIDATION,
-        message: "Input validation failed",
-        details: { issues: inputResult.error.issues },
-        chunksYielded: 0,
-      };
-      callbacks.onError?.(error);
-      return { success: false, totalChunks: 0, error };
-    }
-
-    // 2. Build integration map (keyed by id)
-    const integrations = new Map<string, IntegrationConfig>();
-    for (const config of request.integrations) {
-      integrations.set(config.id, config);
-    }
-
-    // 3. Create execution context with streaming support
-    const contextOptions: CreateStreamingContextOptions = {
-      integrations,
-      integrationDeclarations: getIntegrationDeclarations(api),
-      executeQuery: request.executeQuery,
-      executeStreamingQuery: request.executeStreamingQuery,
-      executionId: request.executionId,
-      env: request.env,
-      user: request.user,
-    };
-
-    const ctx = createStreamingApiContext(contextOptions);
-
-    // 4. Execute the streaming API
-    let iterator: AsyncIterable<TChunk>;
-    try {
-      iterator = api.run(ctx, inputResult.data as TInput);
-    } catch (err) {
-      if (err instanceof SdkError) {
-        const error: StreamingApiError = {
-          code: err.code,
-          message: err.message,
-          details: err.details,
-          chunksYielded: 0,
-        };
-        callbacks.onError?.(error);
-        return { success: false, totalChunks: 0, error };
-      }
-
-      const message = err instanceof Error ? err.message : String(err);
-      const error: StreamingApiError = {
-        code: ErrorCode.EXECUTION_ERROR,
-        message,
-        details: { cause: err },
-        chunksYielded: 0,
-      };
-      callbacks.onError?.(error);
-      return { success: false, totalChunks: 0, error };
-    }
-
-    // 5. Iterate over chunks, validate, and call callbacks
-    for await (const rawChunk of iterator) {
-      // Validate chunk against schema
-      const chunkResult = api.chunkSchema.safeParse(rawChunk);
-      if (!chunkResult.success) {
-        const error: StreamingApiError = {
-          code: ErrorCode.OUTPUT_VALIDATION,
-          message: `Chunk validation failed at index ${totalChunks}`,
-          details: {
-            issues: chunkResult.error.issues,
-            chunkIndex: totalChunks,
-            rawChunk,
-          },
-          chunksYielded: totalChunks,
-        };
-        callbacks.onError?.(error);
-        return { success: false, totalChunks, error };
-      }
-
-      // Call chunk callback
-      callbacks.onChunk(chunkResult.data as TChunk, totalChunks);
-      totalChunks++;
-    }
-
-    // 6. Stream completed successfully
-    callbacks.onComplete?.(totalChunks);
-    return { success: true, totalChunks };
-  } catch (err) {
-    // Handle unexpected errors
-    const message = err instanceof Error ? err.message : String(err);
-
-    let error: StreamingApiError;
-    if (err instanceof SdkError) {
-      error = {
-        code: err.code,
-        message: err.message,
-        details: err.details,
-        chunksYielded: totalChunks,
-      };
-    } else {
-      error = {
-        code: ErrorCode.INTERNAL_ERROR,
-        message: `Unexpected error: ${message}`,
-        details: err instanceof Error ? { stack: err.stack } : undefined,
-        chunksYielded: totalChunks,
-      };
-    }
-
-    callbacks.onError?.(error);
-    return { success: false, totalChunks, error };
-  }
-}
-
-/**
- * Creates an async generator that wraps streaming API execution.
- *
- * This is an alternative interface for consuming streaming APIs that returns
- * an AsyncGenerator directly, rather than using callbacks.
- *
- * @param api - The compiled streaming API definition
- * @param request - The execution request
- * @returns AsyncGenerator yielding validated chunks
- *
- * @example
- * ```typescript
- * const generator = createStreamingApiGenerator(myApi, request);
- *
- * for await (const chunk of generator) {
- *   console.log('Received chunk:', chunk);
- * }
- * ```
- */
-export async function* createStreamingApiGenerator<
-  TInput = unknown,
-  TChunk = unknown,
->(
-  api: CompiledStreamingApi<TInput, TChunk>,
-  request: ExecuteStreamingApiRequest,
-): AsyncGenerator<TChunk, void, undefined> {
-  // Validate input
-  const inputResult = api.inputSchema.safeParse(request.input);
-  if (!inputResult.success) {
-    throw new InputValidationError("Input validation failed", {
-      issues: inputResult.error.issues,
-    });
-  }
-
-  // Build integration map
-  const integrations = new Map<string, IntegrationConfig>();
-  for (const config of request.integrations) {
-    integrations.set(config.id, config);
-  }
-
-  // Create execution context
-  const ctx = createStreamingApiContext({
-    integrations,
-    integrationDeclarations: getIntegrationDeclarations(api),
-    executeQuery: request.executeQuery,
-    executeStreamingQuery: request.executeStreamingQuery,
-    executionId: request.executionId,
-    env: request.env,
-    user: request.user,
-  });
-
-  // Execute and yield validated chunks
-  let chunkIndex = 0;
-  try {
-    const iterator = api.run(ctx, inputResult.data as TInput);
-    for await (const rawChunk of iterator) {
-      const chunkResult = api.chunkSchema.safeParse(rawChunk);
-      if (!chunkResult.success) {
-        throw new SdkError(
-          ErrorCode.OUTPUT_VALIDATION,
-          `Chunk validation failed at index ${chunkIndex}`,
-          {
-            issues: chunkResult.error.issues,
-            chunkIndex,
-            rawChunk,
-          },
-        );
-      }
-
-      yield chunkResult.data as TChunk;
-      chunkIndex++;
-    }
-  } catch (err) {
-    if (err instanceof SdkError) {
-      throw err;
-    }
-
-    const message = err instanceof Error ? err.message : String(err);
-    throw new ExecutionError(message, err);
-  }
-}