@superblocksteam/sdk-api 0.0.4

package/src/runtime/streaming-context.ts

@@ -0,0 +1,164 @@
+/**
+ * Streaming API execution context factory.
+ *
+ * Creates the context object for streaming API functions, providing
+ * access to integrations (with streaming support), logging, and environment.
+ */
+
+import type {
+  ApiContext,
+  ApiUser,
+  Logger,
+  AnyIntegrationRef,
+} from "../types.js";
+import type {
+  IntegrationConfig,
+  IntegrationClientImpl,
+} from "../integrations/types.js";
+import type { IntegrationDeclaration } from "../integrations/declarations.js";
+import {
+  createClient,
+  type QueryExecutor,
+  type StreamingQueryExecutor,
+  type TraceMetadata,
+} from "../integrations/registry.js";
+import { createDefaultLogger } from "./logger.js";
+
+/**
+ * Options for creating a streaming API execution context.
+ */
+export interface CreateStreamingContextOptions {
+  /** Available integration configurations keyed by id */
+  integrations: Map<string, IntegrationConfig>;
+
+  /**
+   * Declared integrations from the API config.
+   */
+  integrationDeclarations: IntegrationDeclaration[];
+
+  /**
+   * Function to execute integration operations (non-streaming).
+   */
+  executeQuery: (
+    integrationId: string,
+    request: Record<string, unknown>,
+    bindings?: Record<string, unknown>,
+    metadata?: TraceMetadata,
+  ) => Promise<unknown>;
+
+  /**
+   * Function to execute streaming integration operations.
+   * Optional - if not provided, streaming operations will throw an error.
+   */
+  executeStreamingQuery?: (
+    integrationId: string,
+    request: Record<string, unknown>,
+    metadata?: TraceMetadata,
+  ) => AsyncIterable<unknown>;
+
+  /** Execution ID for logging correlation */
+  executionId: string;
+
+  /** Environment variables */
+  env: Record<string, string>;
+
+  /** User information from JWT */
+  user: ApiUser;
+
+  /** Optional custom logger */
+  logger?: Logger;
+}
+
+/**
+ * Creates a streaming API execution context.
+ *
+ * Similar to createApiContext but supports streaming query execution
+ * for integration clients that support it.
+ *
+ * @param options - Context creation options
+ * @returns The API context for streaming API execution
+ */
+export function createStreamingApiContext(
+  options: CreateStreamingContextOptions,
+): ApiContext<Record<string, AnyIntegrationRef>> {
+  const {
+    integrations,
+    integrationDeclarations,
+    executeQuery,
+    executeStreamingQuery,
+    executionId,
+    env,
+    user,
+    logger,
+  } = options;
+
+  // Cache for created integration clients
+  const clientCache = new Map<string, IntegrationClientImpl>();
+
+  // Create logger
+  const log = logger ?? createDefaultLogger(executionId);
+
+  /**
+   * Gets or creates a typed integration client by id and plugin ID.
+   * Supports streaming execution if provided.
+   */
+  function getTypedClient(id: string, pluginId: string): IntegrationClientImpl {
+    const cached = clientCache.get(id);
+    if (cached) {
+      return cached;
+    }
+
+    const config = integrations.get(id);
+
+    // Create executor bound to this integration
+    const boundExecutor: QueryExecutor = (
+      request: Record<string, unknown>,
+      bindings?: Record<string, unknown>,
+      metadata?: TraceMetadata,
+    ) => executeQuery(id, request, bindings, metadata);
+
+    // Create streaming executor if provided
+    const boundStreamingExecutor: StreamingQueryExecutor | undefined =
+      executeStreamingQuery
+        ? (request: Record<string, unknown>, metadata?: TraceMetadata) =>
+            executeStreamingQuery(id, request, metadata)
+        : undefined;
+
+    const clientConfig: IntegrationConfig = config ?? {
+      id,
+      name: id,
+      pluginId,
+      configuration: {},
+    };
+
+    // Create client with streaming support
+    const client = createClient({
+      config: clientConfig,
+      executeQuery: boundExecutor,
+      executeStreamingQuery: boundStreamingExecutor,
+    });
+
+    clientCache.set(id, client);
+    return client;
+  }
+
+  // Build the integrations object from declarations
+  const integrationsObject: Record<string, IntegrationClientImpl> = {};
+
+  for (const declaration of integrationDeclarations) {
+    Object.defineProperty(integrationsObject, declaration.key, {
+      get: () => getTypedClient(declaration.id, declaration.pluginId),
+      enumerable: true,
+      configurable: false,
+    });
+  }
+
+  return {
+    integrations: integrationsObject as ApiContext<
+      Record<string, AnyIntegrationRef>
+    >["integrations"],
+    log,
+    env: Object.freeze({ ...env }),
+    user,
+  };
+}

package/src/runtime/streaming-executor.ts

@@ -0,0 +1,367 @@
+/**
+ * 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);
+  }
+}