@superblocksteam/sdk-api 0.0.4

package/src/runtime/errors.ts

@@ -0,0 +1,132 @@
+/**
+ * Runtime error types.
+ *
+ * Provides structured error types for validation failures,
+ * integration errors, and execution errors.
+ */
+
+/**
+ * Error codes for categorizing runtime errors.
+ */
+export const ErrorCode = {
+  /** Input validation failed against the Zod schema */
+  INPUT_VALIDATION: "INPUT_VALIDATION",
+
+  /** Output validation failed against the Zod schema */
+  OUTPUT_VALIDATION: "OUTPUT_VALIDATION",
+
+  /** Integration not found or not configured */
+  INTEGRATION_NOT_FOUND: "INTEGRATION_NOT_FOUND",
+
+  /** Integration operation failed */
+  INTEGRATION_ERROR: "INTEGRATION_ERROR",
+
+  /** User code threw an error during execution */
+  EXECUTION_ERROR: "EXECUTION_ERROR",
+
+  /** Internal SDK error */
+  INTERNAL_ERROR: "INTERNAL_ERROR",
+} as const;
+
+export type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode];
+
+/**
+ * Base class for SDK runtime errors.
+ */
+export class SdkError extends Error {
+  readonly code: ErrorCodeType;
+  readonly details?: unknown;
+
+  constructor(code: ErrorCodeType, message: string, details?: unknown) {
+    super(message);
+    this.name = "SdkError";
+    this.code = code;
+    this.details = details;
+
+    // Fix prototype chain for proper instanceof checks in transpiled output
+    Object.setPrototypeOf(this, new.target.prototype);
+
+    // Maintain proper stack trace in V8 environments
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  /**
+   * Converts the error to a plain object for serialization.
+   */
+  toJSON(): { code: ErrorCodeType; message: string; details?: unknown } {
+    return {
+      code: this.code,
+      message: this.message,
+      details: this.details,
+    };
+  }
+}
+
+/**
+ * Error thrown when input validation fails.
+ */
+export class InputValidationError extends SdkError {
+  constructor(message: string, details?: unknown) {
+    super(ErrorCode.INPUT_VALIDATION, message, details);
+    this.name = "InputValidationError";
+  }
+}
+
+/**
+ * Error thrown when output validation fails.
+ */
+export class OutputValidationError extends SdkError {
+  constructor(message: string, details?: unknown) {
+    super(ErrorCode.OUTPUT_VALIDATION, message, details);
+    this.name = "OutputValidationError";
+  }
+}
+
+/**
+ * Error thrown when a requested integration is not found.
+ */
+export class IntegrationNotFoundError extends SdkError {
+  readonly integrationName: string;
+
+  constructor(integrationName: string) {
+    super(
+      ErrorCode.INTEGRATION_NOT_FOUND,
+      `Integration not found: "${integrationName}"`,
+      { integrationName },
+    );
+    this.name = "IntegrationNotFoundError";
+    this.integrationName = integrationName;
+  }
+}
+
+/**
+ * Error thrown when an integration operation fails.
+ */
+export class IntegrationError extends SdkError {
+  readonly integrationName: string;
+  readonly operation: string;
+
+  constructor(integrationName: string, operation: string, cause?: unknown) {
+    const message = `Integration "${integrationName}" failed during "${operation}"`;
+    super(ErrorCode.INTEGRATION_ERROR, message, {
+      integrationName,
+      operation,
+      cause,
+    });
+    this.name = "IntegrationError";
+    this.integrationName = integrationName;
+    this.operation = operation;
+  }
+}
+
+/**
+ * Error thrown when user code fails during execution.
+ */
+export class ExecutionError extends SdkError {
+  constructor(message: string, cause?: unknown) {
+    super(ErrorCode.EXECUTION_ERROR, message, { cause });
+    this.name = "ExecutionError";
+  }
+}

package/src/runtime/execute.ts

@@ -0,0 +1,221 @@
+/**
+ * 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/executor.ts

@@ -0,0 +1,214 @@
+/**
+ * API execution engine.
+ *
+ * Provides the main entry point for executing compiled APIs,
+ * handling input/output validation and error management.
+ */
+
+import type { CompiledApi } from "../api/definition.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 { createApiContext } from "./context.js";
+import {
+  SdkError,
+  InputValidationError,
+  OutputValidationError,
+  ExecutionError,
+  ErrorCode,
+  type ErrorCodeType,
+} from "./errors.js";
+
+/**
+ * Request to execute an API.
+ */
+export interface ExecuteApiRequest {
+  /** 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.
+   * Called by integration clients to perform actual operations.
+   *
+   * The request object should match the protobuf Plugin schema for the
+   * specific integration type (e.g., postgresql.v1.Plugin for Postgres).
+   *
+   * For language plugins (Python, JavaScript), the bindings parameter should be
+   * passed to the API execution request as `input` or `inputs` field for
+   * binding resolution.
+   *
+   * @param integrationId - The integration ID
+   * @param request - Plugin-specific request object matching the proto schema
+   * @param bindings - Optional bindings data for binding resolution (e.g., Python/JavaScript bindings)
+   * @returns Promise resolving to the operation result
+   */
+  executeQuery: (
+    integrationId: string,
+    request: Record<string, unknown>,
+    bindings?: Record<string, unknown>,
+    metadata?: TraceMetadata,
+  ) => Promise<unknown>;
+}
+
+/**
+ * Successful API execution response.
+ *
+ * @template TOutput - The output type from the API
+ */
+export interface ExecuteApiSuccessResponse<TOutput = unknown> {
+  success: true;
+  output: TOutput;
+}
+
+/**
+ * Failed API execution response.
+ */
+export interface ExecuteApiErrorResponse {
+  success: false;
+  error: {
+    code: ErrorCodeType;
+    message: string;
+    details?: unknown;
+  };
+}
+
+/**
+ * API execution response.
+ *
+ * @template TOutput - The output type from the API
+ */
+export type ExecuteApiResponse<TOutput = unknown> =
+  | ExecuteApiSuccessResponse<TOutput>
+  | ExecuteApiErrorResponse;
+
+/**
+ * Executes a compiled API with the given request.
+ *
+ * This is the main entry point called by the orchestrator to execute
+ * TypeScript-based APIs. It handles:
+ *
+ * 1. Input validation against the API's Zod schema
+ * 2. Context creation with integration clients
+ * 3. API function execution
+ * 4. Output validation against the API's Zod schema
+ * 5. Error handling and categorization
+ *
+ * @param api - The compiled API definition
+ * @param request - The execution request with input and integrations
+ * @returns Promise resolving to success or error response
+ *
+ * @example
+ * ```typescript
+ * import { api, z } from '@superblocksteam/sdk-api';
+ * import { executeApi } from '@superblocksteam/sdk-api/runtime';
+ *
+ * const myApi = api({
+ *   input: z.object({ userId: z.string() }),
+ *   output: z.object({ name: z.string() }),
+ *   async run(ctx, { userId }) {
+ *     const [user] = await ctx.integrations.db.query(
+ *       'SELECT name FROM users WHERE id = $1',
+ *       [userId]
+ *     );
+ *     return { name: user.name };
+ *   },
+ * });
+ *
+ * const result = await executeApi(myApi, {
+ *   input: { userId: '123' },
+ *   integrations: [...],
+ *   executionId: 'exec_abc',
+ *   env: {},
+ *   executeQuery: orchestratorExecutor,
+ * });
+ * ```
+ */
+export async function executeApi<TInput = unknown, TOutput = unknown>(
+  api: CompiledApi<TInput, TOutput>,
+  request: ExecuteApiRequest,
+): Promise<ExecuteApiResponse<TOutput>> {
+  try {
+    // 1. Validate input
+    const inputResult = api.inputSchema.safeParse(request.input);
+    if (!inputResult.success) {
+      throw new InputValidationError("Input validation failed", {
+        issues: inputResult.error.issues,
+      });
+    }
+
+    // 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
+    const ctx = createApiContext({
+      integrations,
+      integrationDeclarations: getIntegrationDeclarations(api),
+      executeQuery: request.executeQuery,
+      executionId: request.executionId,
+      env: request.env,
+      user: request.user,
+    });
+
+    // 4. Execute the API
+    let rawOutput: unknown;
+    try {
+      rawOutput = await api.run(ctx, inputResult.data);
+    } catch (err) {
+      // Re-throw SDK errors as-is
+      if (err instanceof SdkError) {
+        throw err;
+      }
+      // Wrap user errors
+      const message = err instanceof Error ? err.message : String(err);
+      throw new ExecutionError(message, err);
+    }
+
+    // 5. Validate output
+    const outputResult = api.outputSchema.safeParse(rawOutput);
+    if (!outputResult.success) {
+      throw new OutputValidationError("Output validation failed", {
+        issues: outputResult.error.issues,
+      });
+    }
+
+    return {
+      success: true,
+      output: outputResult.data as TOutput,
+    };
+  } catch (err) {
+    // Handle SDK errors
+    if (err instanceof SdkError) {
+      return {
+        success: false,
+        error: err.toJSON(),
+      };
+    }
+
+    // Handle unexpected errors
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      success: false,
+      error: {
+        code: ErrorCode.INTERNAL_ERROR,
+        message: `Unexpected error: ${message}`,
+        details: err instanceof Error ? { stack: err.stack } : undefined,
+      },
+    };
+  }
+}

package/src/runtime/index.ts

@@ -0,0 +1,52 @@
+/**
+ * Runtime execution module.
+ *
+ * Provides the execution engine for running compiled APIs,
+ * including context creation, validation, and error handling.
+ */
+
+// Unified executor (recommended)
+export {
+  execute,
+  isStreamingApi,
+  type UnifiedExecuteApiRequest,
+  type AnyCompiledApi,
+} from "./execute.js";
+
+// Main executor (for non-streaming APIs)
+export {
+  executeApi,
+  type ExecuteApiRequest,
+  type ExecuteApiResponse,
+  type ExecuteApiSuccessResponse,
+  type ExecuteApiErrorResponse,
+} from "./executor.js";
+
+// Streaming executor (for streaming APIs)
+export {
+  executeStreamingApi,
+  createStreamingApiGenerator,
+  type ExecuteStreamingApiRequest,
+  type StreamingApiCallbacks,
+  type StreamingApiError,
+  type ExecuteStreamingApiResult,
+} from "./streaming-executor.js";
+
+// Context factories
+export { createApiContext, type CreateContextOptions } from "./context.js";
+export {
+  createStreamingApiContext,
+  type CreateStreamingContextOptions,
+} from "./streaming-context.js";
+
+// Error types
+export {
+  SdkError,
+  InputValidationError,
+  OutputValidationError,
+  IntegrationNotFoundError,
+  IntegrationError,
+  ExecutionError,
+  ErrorCode,
+  type ErrorCodeType,
+} from "./errors.js";

package/src/runtime/logger.ts

@@ -0,0 +1,41 @@
+/**
+ * Default logger factory for API execution contexts.
+ *
+ * Provides a simple console-based logger implementation
+ * with structured output including timestamps and execution IDs.
+ */
+
+import type { Logger } from "../types.js";
+
+/**
+ * Creates a default logger that outputs to console.
+ *
+ * @param executionId - Execution ID for log correlation
+ * @returns A Logger instance using console output
+ */
+export function createDefaultLogger(executionId: string): Logger {
+  const formatMessage = (
+    level: string,
+    message: string,
+    data?: Record<string, unknown>,
+  ): string => {
+    const timestamp = new Date().toISOString();
+    const dataStr = data ? ` ${JSON.stringify(data)}` : "";
+    return `[${timestamp}] [${executionId}] [${level}] ${message}${dataStr}`;
+  };
+
+  return {
+    info(message: string, data?: Record<string, unknown>): void {
+      console.log(formatMessage("INFO", message, data));
+    },
+    warn(message: string, data?: Record<string, unknown>): void {
+      console.warn(formatMessage("WARN", message, data));
+    },
+    error(message: string, data?: Record<string, unknown>): void {
+      console.error(formatMessage("ERROR", message, data));
+    },
+    debug(message: string, data?: Record<string, unknown>): void {
+      console.debug(formatMessage("DEBUG", message, data));
+    },
+  };
+}