@superblocksteam/sdk-api 0.0.6 → 0.0.7

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 {
-  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,
-  };
-}