@superblocksteam/sdk-api 2.0.103 → 2.0.104-next.0

package/src/api/streaming.ts

@@ -1,303 +0,0 @@
-/**
- * Streaming API definition function.
- *
- * This module provides the `streamingApi()` function used to define TypeScript-based APIs
- * that yield chunks over time, enabling real-time streaming from LLMs and other sources.
- */
-
-import type { z } from "zod";
-
-import {
-  extractIntegrationDeclarations,
-  type IntegrationDeclaration,
-} from "../integrations/declarations.js";
-import type { ApiContext, AnyIntegrationRef } from "../types.js";
-import { consumeEntryPoint } from "./definition.js";
-
-/**
- * Configuration for defining a streaming TypeScript-based API.
- *
- * @template TInput - Zod schema type for input validation
- * @template TChunk - Zod schema type for each streamed chunk
- * @template TIntegrations - Record of integration declarations
- *
- * @example
- * ```typescript
- * import { streamingApi, z, anthropic } from '@superblocksteam/sdk-api';
- *
- * export default streamingApi({
- *   integrations: {
- *     ai: anthropic('Production Anthropic'),
- *   },
- *
- *   input: z.object({
- *     prompt: z.string(),
- *   }),
- *
- *   chunk: z.object({
- *     type: z.literal('text-delta'),
- *     text: z.string(),
- *   }),
- *
- *   async *run(ctx, { prompt }) {
- *     const stream = ctx.integrations.ai.streamApiRequest(
- *       {
- *         method: 'POST',
- *         path: '/v1/messages',
- *         body: {
- *           model: 'claude-3-5-sonnet-20241022',
- *           max_tokens: 1024,
- *           stream: true,
- *           messages: [{ role: 'user', content: prompt }],
- *         },
- *       },
- *       { chunk: AnthropicStreamEventSchema }
- *     );
- *
- *     for await (const event of stream) {
- *       if (event.type === 'content_block_delta') {
- *         yield { type: 'text-delta' as const, text: event.delta.text };
- *       }
- *     }
- *   },
- * });
- * ```
- */
-export interface StreamingApiConfig<
-  TInput extends z.ZodType,
-  TChunk 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;
-
-  /**
-   * Plain-language summary of what this API does and which integrations it uses,
-   * written for a non-technical audience.
-   *
-   * This field is auto-generated by the AI agent when creating or editing an API.
-   */
-  description?: 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: {
-   *   ai: anthropic('Production Anthropic'),
-   *   db: postgres('Cache DB'),
-   * }
-   * ```
-   */
-  integrations?: TIntegrations;
-
-  /** Zod schema for input validation */
-  input: TInput;
-
-  /**
-   * Zod schema for validating each streamed chunk.
-   *
-   * Every chunk yielded by the run function is validated against this schema.
-   * Validation errors will terminate the stream.
-   */
-  chunk: TChunk;
-
-  /**
-   * The streaming API implementation function (async generator).
-   *
-   * @param ctx - Execution context with access to integrations
-   * @param input - Validated input parameters (can be destructured)
-   * @yields Chunks that are validated against the chunk schema
-   */
-  run: (
-    ctx: ApiContext<TIntegrations>,
-    input: z.infer<TInput>,
-  ) => AsyncIterable<z.infer<TChunk>>;
-}
-
-/**
- * A compiled streaming API definition ready for execution.
- *
- * @template TInput - The inferred input type
- * @template TChunk - The inferred chunk type
- */
-export interface CompiledStreamingApi<TInput = unknown, TChunk = unknown> {
-  /** Name of the API for identification in logs and debugging */
-  readonly name: string;
-
-  /** Plain-language summary of what this API does */
-  readonly description?: string;
-  /**
-   * Source file path relative to the app root (e.g. "server/apis/Chat/api.ts").
-   * Injected automatically by the Vite plugin — not authored by the user.
-   */
-  readonly entryPoint?: string;
-
-  /** Zod schema for validating inputs */
-  readonly inputSchema: z.ZodType<TInput>;
-
-  /**
-   * Zod schema for validating each streamed chunk.
-   *
-   * Every chunk yielded by the API is validated against this schema
-   * before being sent to the client.
-   */
-  readonly chunkSchema: z.ZodType<TChunk>;
-
-  /**
-   * The streaming API implementation function.
-   *
-   * @param ctx - Execution context
-   * @param input - Validated input parameters
-   * @returns AsyncIterable yielding validated chunks
-   */
-  readonly run: (
-    ctx: ApiContext<Record<string, AnyIntegrationRef>>,
-    input: TInput,
-  ) => AsyncIterable<TChunk>;
-
-  /**
-   * Declared integrations for upfront authentication.
-   *
-   * This array contains all integrations declared in the API config,
-   * allowing the runtime to authenticate them before API execution.
-   */
-  readonly integrations: ReadonlyArray<IntegrationDeclaration>;
-
-  /**
-   * Runtime flag indicating this is a streaming API.
-   *
-   * Always `true` for streaming APIs. Use `isStreamingApi()` type guard
-   * to distinguish streaming APIs from regular APIs at runtime.
-   */
-  readonly isStreaming: true;
-}
-
-/**
- * Define a streaming TypeScript-based API with chunk validation.
- *
- * This function creates a compiled streaming API definition that yields
- * chunks over time. Each chunk is validated against the provided schema.
- *
- * Use this for:
- * - Real-time LLM token streaming (OpenAI, Anthropic, etc.)
- * - Server-sent events
- * - Long-running operations with progress updates
- * - Any API that produces output incrementally
- *
- * @param config - The streaming API configuration
- * @returns A compiled streaming API definition
- *
- * @example
- * ```typescript
- * import { streamingApi, z, openai } from '@superblocksteam/sdk-api';
- *
- * export default streamingApi({
- *   integrations: {
- *     ai: openai('Production OpenAI'),
- *   },
- *
- *   input: z.object({
- *     prompt: z.string(),
- *   }),
- *
- *   chunk: z.object({
- *     content: z.string(),
- *   }),
- *
- *   async *run(ctx, { prompt }) {
- *     const stream = ctx.integrations.ai.streamApiRequest(
- *       {
- *         method: 'POST',
- *         path: '/v1/chat/completions',
- *         body: {
- *           model: 'gpt-4',
- *           stream: true,
- *           messages: [{ role: 'user', content: prompt }],
- *         },
- *       },
- *       { chunk: OpenAIChunkSchema }
- *     );
- *
- *     for await (const chunk of stream) {
- *       const content = chunk.choices[0]?.delta?.content;
- *       if (content) {
- *         yield { content };
- *       }
- *     }
- *   },
- * });
- * ```
- */
-export function streamingApi<
-  TInput extends z.ZodType,
-  TChunk extends z.ZodType,
-  TIntegrations extends Record<string, AnyIntegrationRef> = Record<
-    string,
-    never
-  >,
->(
-  config: StreamingApiConfig<TInput, TChunk, TIntegrations>,
-): CompiledStreamingApi<z.infer<TInput>, z.infer<TChunk>> {
-  // Extract integration declarations for upfront auth
-  const integrations = extractIntegrationDeclarations(config.integrations);
-
-  const compiled: CompiledStreamingApi<z.infer<TInput>, z.infer<TChunk>> = {
-    name: config.name,
-    description: config.description,
-    entryPoint: consumeEntryPoint(),
-    inputSchema: config.input,
-    chunkSchema: config.chunk,
-    run: config.run as (
-      ctx: ApiContext<Record<string, AnyIntegrationRef>>,
-      input: z.infer<TInput>,
-    ) => AsyncIterable<z.infer<TChunk>>,
-    integrations,
-    isStreaming: true,
-  };
-
-  return compiled;
-}
-
-/**
- * Type guard to check if an API is a streaming API.
- *
- * @param api - The API to check
- * @returns `true` if the API is a streaming API, `false` otherwise
- *
- * @example
- * ```typescript
- * import { isStreamingApi, executeApi, executeStreamingApi } from '@superblocksteam/sdk-api';
- *
- * if (isStreamingApi(api)) {
- *   await executeStreamingApi(api, request);
- * } else {
- *   await executeApi(api, request);
- * }
- * ```
- */
-export function isStreamingApi(
-  api: unknown,
-): api is CompiledStreamingApi<unknown, unknown> {
-  return (
-    typeof api === "object" &&
-    api !== null &&
-    "isStreaming" in api &&
-    (api as Record<string, unknown>).isStreaming === true &&
-    "inputSchema" in api &&
-    "chunkSchema" in api &&
-    "run" in api &&
-    typeof (api as Record<string, unknown>).run === "function"
-  );
-}

package/src/runtime/execute.ts

@@ -1,221 +0,0 @@
-/**
- * Unified API execution function.
- *
- * Provides a single `execute()` function that handles both regular and streaming APIs,
- * detecting the API type at runtime and returning appropriate result types.
- */
-
-import type { CompiledApi } from "../api/definition.js";
-import { isStreamingApi, type CompiledStreamingApi } from "../api/streaming.js";
-import type { TraceMetadata } from "../integrations/registry.js";
-import type { IntegrationConfig } from "../integrations/types.js";
-import type { ApiUser } from "../types.js";
-import { executeApi, type ExecuteApiResponse } from "./executor.js";
-import { createStreamingApiGenerator } from "./streaming-executor.js";
-
-/**
- * Unified request for executing any API (regular or streaming).
- *
- * This interface combines the fields from both `ExecuteApiRequest` and
- * `ExecuteStreamingApiRequest` into a single type. The `executeStreamingQuery`
- * field is only required when executing streaming APIs that use streaming
- * integration support.
- */
-export interface UnifiedExecuteApiRequest {
-  /** 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.
-   * Optional - only needed for streaming APIs that use streaming integrations.
-   *
-   * @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>;
-}
-
-/**
- * Union type for any compiled API (regular or streaming).
- *
- * Note: This is a permissive type for runtime use. The `execute` function
- * provides overloads for proper type inference.
- */
-export type AnyCompiledApi =
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  | CompiledApi<any, any>
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  | CompiledStreamingApi<any, any>;
-
-/**
- * Execute a regular (non-streaming) compiled API.
- *
- * @param api - The compiled API definition
- * @param request - The execution request
- * @returns Promise resolving to execution response with success/error and output
- *
- * @example
- * ```typescript
- * const response = await execute(myApi, {
- *   input: { userId: '123' },
- *   integrations: [...],
- *   executionId: 'exec_abc',
- *   env: {},
- *   executeQuery: async (id, req) => orchestrator.execute(id, req),
- * });
- *
- * if (response.success) {
- *   console.log(response.output);
- * } else {
- *   console.error(response.error);
- * }
- * ```
- */
-export function execute<TInput, TOutput>(
-  api: CompiledApi<TInput, TOutput>,
-  request: UnifiedExecuteApiRequest,
-): Promise<ExecuteApiResponse<TOutput>>;
-
-/**
- * Execute a streaming compiled API.
- *
- * @param api - The compiled streaming API definition
- * @param request - The execution request
- * @returns AsyncGenerator that yields validated chunks
- *
- * @example
- * ```typescript
- * const stream = execute(myStreamingApi, {
- *   input: { prompt: 'Hello' },
- *   integrations: [...],
- *   executionId: 'exec_abc',
- *   env: {},
- *   executeQuery: async (id, req) => orchestrator.execute(id, req),
- *   executeStreamingQuery: (id, req) => orchestrator.stream(id, req),
- * });
- *
- * for await (const chunk of stream) {
- *   console.log(chunk.text);
- * }
- * ```
- */
-export function execute<TInput, TChunk>(
-  api: CompiledStreamingApi<TInput, TChunk>,
-  request: UnifiedExecuteApiRequest,
-): AsyncGenerator<TChunk, void, undefined>;
-
-/**
- * Execute any compiled API (regular or streaming).
- *
- * This unified function detects whether the API is streaming or regular
- * and returns the appropriate result type:
- *
- * - **Regular APIs**: Returns `Promise<ExecuteApiResponse<TOutput>>`
- * - **Streaming APIs**: Returns `AsyncGenerator<TChunk>`
- *
- * @param api - The compiled API definition (regular or streaming)
- * @param request - The execution request
- * @returns Promise for regular APIs, AsyncGenerator for streaming APIs
- *
- * @example Regular API
- * ```typescript
- * const response = await execute(myApi, {
- *   input: { userId: '123' },
- *   integrations: [...],
- *   executionId: 'exec_abc',
- *   env: {},
- *   executeQuery: async (id, req) => orchestrator.execute(id, req),
- * });
- *
- * if (response.success) {
- *   console.log(response.output);
- * }
- * ```
- *
- * @example Streaming API
- * ```typescript
- * const stream = execute(myStreamingApi, {
- *   input: { prompt: 'Hello' },
- *   integrations: [...],
- *   executionId: 'exec_abc',
- *   env: {},
- *   executeQuery: async (id, req) => orchestrator.execute(id, req),
- *   executeStreamingQuery: (id, req) => orchestrator.stream(id, req),
- * });
- *
- * for await (const chunk of stream) {
- *   console.log(chunk.text);
- * }
- * ```
- */
-export function execute(
-  api: AnyCompiledApi,
-  request: UnifiedExecuteApiRequest,
-):
-  | Promise<ExecuteApiResponse<unknown>>
-  | AsyncGenerator<unknown, void, undefined> {
-  if (isStreamingApi(api)) {
-    // Streaming API - return generator directly
-    return createStreamingApiGenerator(
-      api as CompiledStreamingApi<unknown, unknown>,
-      request,
-    );
-  } else {
-    // Regular API - return promise
-    return executeApi(api as CompiledApi<unknown, unknown>, request);
-  }
-}
-
-/**
- * Type guard to check if an API is a streaming API.
- *
- * Use this to determine which result type you'll get from `execute()`.
- *
- * @param api - The API to check
- * @returns `true` if the API is a streaming API
- *
- * @example
- * ```typescript
- * if (isStreamingApi(api)) {
- *   const stream = execute(api, request);
- *   for await (const chunk of stream) { ... }
- * } else {
- *   const response = await execute(api, request);
- *   if (response.success) { ... }
- * }
- * ```
- */
-export { isStreamingApi };

package/src/runtime/streaming-context.ts

@@ -1,164 +0,0 @@
-/**
- * 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 { IntegrationDeclaration } from "../integrations/declarations.js";
-import {
-  createClient,
-  type QueryExecutor,
-  type StreamingQueryExecutor,
-  type TraceMetadata,
-} from "../integrations/registry.js";
-import type {
-  IntegrationConfig,
-  IntegrationClientImpl,
-} from "../integrations/types.js";
-import type {
-  ApiContext,
-  ApiUser,
-  Logger,
-  AnyIntegrationRef,
-} from "../types.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,
-  };
-}