@superblocksteam/sdk-api 2.0.89-next.0

package/src/runtime/streaming-context.ts

@@ -0,0 +1,146 @@
+/**
+ * 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 } 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>,
+  ) => 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>,
+  ) => 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>,
+    ) => executeQuery(id, request, bindings);
+
+    // Create streaming executor if provided
+    const boundStreamingExecutor: StreamingQueryExecutor | undefined = executeStreamingQuery
+      ? (request: Record<string, unknown>) => executeStreamingQuery(id, request)
+      : 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,357 @@
+/**
+ * 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 { 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>,
+  ) => Promise<unknown>;
+
+  /**
+   * Function to execute streaming integration operations.
+   *
+   * @param integrationId - The integration ID
+   * @param request - Plugin-specific request object
+   * @returns AsyncIterable yielding raw chunks
+   */
+  executeStreamingQuery?: (
+    integrationId: string,
+    request: Record<string, unknown>,
+  ) => 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);
+  }
+}

package/src/types.ts

@@ -0,0 +1,193 @@
+/**
+ * Core type definitions for the Superblocks SDK.
+ *
+ * This module provides the public types used to define TypeScript-based APIs.
+ */
+
+import type { z } from 'zod';
+import type {
+  IntegrationRef,
+  AnyIntegrationRef,
+  IntegrationsMap,
+} from './integrations/declarations.js';
+
+/**
+ * Configuration for defining a TypeScript-based API.
+ *
+ * @template TInput - Zod schema type for input validation
+ * @template TOutput - Zod schema type for output validation
+ * @template TIntegrations - Record of integration declarations
+ *
+ * @example
+ * ```typescript
+ * import { api, z, postgres, slack } from '@superblocksteam/sdk-api';
+ *
+ * const UserSchema = z.object({
+ *   id: z.string(),
+ *   name: z.string(),
+ * });
+ *
+ * export default api({
+ *   integrations: {
+ *     db: postgres('Production Postgres'),
+ *     notifier: slack('Ops Slack'),
+ *   },
+ *   input: z.object({ userId: z.string() }),
+ *   output: z.object({ user: UserSchema }),
+ *   async run(ctx, { userId }) {
+ *     const users = await ctx.integrations.db.query(
+ *       'SELECT * FROM users WHERE id = $1',
+ *       UserSchema,  // Schema is REQUIRED
+ *       [userId]
+ *     );
+ *     if (users.length === 0) {
+ *       throw new Error('User not found');
+ *     }
+ *     await ctx.integrations.notifier.postMessage({
+ *       channel: '#alerts',
+ *       text: `Fetched user ${users[0].name}`,
+ *     });
+ *     return { user: users[0] };
+ *   },
+ * });
+ * ```
+ */
+export interface ApiConfig<
+  TInput extends z.ZodType,
+  TOutput extends z.ZodType,
+  TIntegrations extends Record<string, AnyIntegrationRef> = Record<string, never>,
+> {
+  /**
+   * Name for this API.
+   *
+   * Used for identification in execution logs and debugging.
+   */
+  name: string;
+
+  /**
+   * Integration declarations for this API.
+   *
+   * Declare integrations upfront to enable type-safe access via `ctx.integrations`
+   * and to allow the runtime to authenticate integrations before execution.
+   *
+   * @example
+   * ```typescript
+   * integrations: {
+   *   db: postgres('Production Postgres'),
+   *   cache: redis('Cache Redis'),
+   * }
+   * ```
+   */
+  integrations?: TIntegrations;
+
+  /** Zod schema for input validation */
+  input: TInput;
+
+  /** Zod schema for output validation */
+  output: TOutput;
+
+  /**
+   * The API implementation function.
+   *
+   * @param ctx - Execution context with access to integrations, logging, and environment
+   * @param input - Validated input parameters (can be destructured)
+   * @returns Promise resolving to the validated output
+   */
+  run: (ctx: ApiContext<TIntegrations>, input: z.infer<TInput>) => Promise<z.infer<TOutput>>;
+}
+
+/**
+ * User information extracted from the Superblocks JWT.
+ *
+ * This information is passed to the API context and is available
+ * as `ctx.user` in API implementations.
+ */
+export interface ApiUser {
+  /** Unique user identifier from JWT */
+  readonly userId: string;
+
+  /** User's email address (if available) */
+  readonly email?: string;
+
+  /** User's display name (if available) */
+  readonly name?: string;
+
+  /** User's group memberships from JWT */
+  readonly groups: readonly string[];
+
+  /** Custom claims from JWT */
+  readonly customClaims: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Execution context passed to the API run function.
+ *
+ * Provides access to integration clients, logging, environment variables,
+ * and user information.
+ *
+ * @template TIntegrations - Record of integration declarations
+ */
+export interface ApiContext<
+  TIntegrations extends Record<string, AnyIntegrationRef> = Record<string, never>,
+> {
+  /**
+   * Typed integration clients declared in the API config.
+   *
+   * Access integrations by the key you defined in the `integrations` config.
+   * Each client is fully typed based on the declaration function used.
+   *
+   * @example
+   * ```typescript
+   * // Given: integrations: { db: postgres('My Postgres'), notifier: slack('My Slack') }
+   *
+   * // ctx.integrations.db is PostgresClient
+   * const users = await ctx.integrations.db.query('SELECT * FROM users', UserSchema);
+   *
+   * // ctx.integrations.notifier is SlackClient
+   * await ctx.integrations.notifier.postMessage({ channel: '#alerts', text: 'Hello!' });
+   * ```
+   */
+  readonly integrations: IntegrationsMap<TIntegrations>;
+
+  /** Logger for structured logging */
+  readonly log: Logger;
+
+  /** Access to environment variables */
+  readonly env: Readonly<Record<string, string>>;
+
+  /** User information from the Superblocks JWT */
+  readonly user: ApiUser;
+}
+
+/**
+ * Logger interface for API execution.
+ *
+ * All log methods accept an optional data object for structured logging.
+ */
+export interface Logger {
+  /** Log an info message */
+  info(message: string, data?: Record<string, unknown>): void;
+
+  /** Log a warning message */
+  warn(message: string, data?: Record<string, unknown>): void;
+
+  /** Log an error message */
+  error(message: string, data?: Record<string, unknown>): void;
+
+  /** Log a debug message */
+  debug(message: string, data?: Record<string, unknown>): void;
+}
+
+/**
+ * Base interface for all integration clients.
+ */
+export interface BaseIntegrationClient {
+  /** The integration name */
+  readonly name: string;
+
+  /** The plugin type ID (e.g., 'postgres', 'slack') */
+  readonly pluginId: string;
+}
+
+// Re-export integration ref type for advanced use cases
+export type { IntegrationRef, AnyIntegrationRef, IntegrationsMap };