@superblocksteam/sdk-api 2.0.89-next.0

package/dist/runtime/context.js

@@ -0,0 +1,93 @@
+/**
+ * API execution context factory.
+ *
+ * Creates the context object that is passed to user API functions,
+ * providing access to integrations, logging, and environment.
+ */
+import { createClient } from '../integrations/registry.js';
+import { createDefaultLogger } from './logger.js';
+/**
+ * Creates an API execution context.
+ *
+ * The context provides user code with access to:
+ * - Integration clients (built from declarations)
+ * - Logging utilities
+ * - Environment variables
+ *
+ * @param options - Context creation options
+ * @returns The API context for user code execution
+ *
+ * @example
+ * ```typescript
+ * const ctx = createApiContext({
+ *   integrations: new Map([
+ *     ['int_1', { id: 'int_1', name: 'Production Postgres', pluginId: 'postgres', configuration: {} }],
+ *   ]),
+ *   integrationDeclarations: [
+ *     { key: 'db', pluginId: 'postgres', id: 'int_1' },
+ *   ],
+ *   executeQuery: orchestratorExecutor,
+ *   executionId: 'exec_abc',
+ *   env: { NODE_ENV: 'production' },
+ * });
+ *
+ * // User code can access: ctx.integrations.db (typed as PostgresClient)
+ * ```
+ */
+export function createApiContext(options) {
+    const { integrations, integrationDeclarations, executeQuery, executionId, env, user, logger } = options;
+    // Cache for created integration clients
+    const clientCache = new Map();
+    // Create logger
+    const log = logger ?? createDefaultLogger(executionId);
+    /**
+     * Gets or creates a typed integration client by id and plugin ID.
+     *
+     * Supports two modes:
+     * 1. Pre-loaded configs: Integration configs are provided upfront (orchestrator use)
+     * 2. Lazy resolution: Configs are empty, executeQuery handles ID resolution (library use)
+     */
+    function getTypedClient(id, pluginId) {
+        // Check cache first
+        const cached = clientCache.get(id);
+        if (cached) {
+            return cached;
+        }
+        // Look up integration config (may be undefined for lazy resolution)
+        const config = integrations.get(id);
+        // Create executor bound to this integration
+        const boundExecutor = (request, bindings) => executeQuery(id, request, bindings);
+        // Create config for client - use pre-loaded config or create synthetic one
+        const clientConfig = config ?? {
+            id,
+            name: id, // Use ID as name placeholder for lazy resolution
+            pluginId,
+            configuration: {},
+        };
+        // Create and cache the client
+        const client = createClient({
+            config: clientConfig,
+            executeQuery: boundExecutor,
+        });
+        clientCache.set(id, client);
+        return client;
+    }
+    // Build the integrations object from declarations
+    // Each key maps to a lazily-created typed client
+    const integrationsObject = {};
+    for (const declaration of integrationDeclarations) {
+        // Use Object.defineProperty to create a getter that lazily creates the client
+        Object.defineProperty(integrationsObject, declaration.key, {
+            get: () => getTypedClient(declaration.id, declaration.pluginId),
+            enumerable: true,
+            configurable: false,
+        });
+    }
+    return {
+        integrations: integrationsObject,
+        log,
+        env: Object.freeze({ ...env }),
+        user,
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/runtime/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,YAAY,EAAsB,MAAM,6BAA6B,CAAC;AAC/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AA0ClD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAA6B;IAE7B,MAAM,EAAE,YAAY,EAAE,uBAAuB,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,GAC3F,OAAO,CAAC;IAEV,wCAAwC;IACxC,MAAM,WAAW,GAAG,IAAI,GAAG,EAAiC,CAAC;IAE7D,gBAAgB;IAChB,MAAM,GAAG,GAAG,MAAM,IAAI,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAEvD;;;;;;OAMG;IACH,SAAS,cAAc,CAAC,EAAU,EAAE,QAAgB;QAClD,oBAAoB;QACpB,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnC,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,oEAAoE;QACpE,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAEpC,4CAA4C;QAC5C,MAAM,aAAa,GAAkB,CACnC,OAAgC,EAChC,QAAkC,EAClC,EAAE,CAAC,YAAY,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;QAEzC,2EAA2E;QAC3E,MAAM,YAAY,GAAsB,MAAM,IAAI;YAChD,EAAE;YACF,IAAI,EAAE,EAAE,EAAE,iDAAiD;YAC3D,QAAQ;YACR,aAAa,EAAE,EAAE;SAClB,CAAC;QAEF,8BAA8B;QAC9B,MAAM,MAAM,GAAG,YAAY,CAAC;YAC1B,MAAM,EAAE,YAAY;YACpB,YAAY,EAAE,aAAa;SAC5B,CAAC,CAAC;QAEH,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QAC5B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,kDAAkD;IAClD,iDAAiD;IACjD,MAAM,kBAAkB,GAA0C,EAAE,CAAC;IAErE,KAAK,MAAM,WAAW,IAAI,uBAAuB,EAAE,CAAC;QAClD,8EAA8E;QAC9E,MAAM,CAAC,cAAc,CAAC,kBAAkB,EAAE,WAAW,CAAC,GAAG,EAAE;YACzD,GAAG,EAAE,GAAG,EAAE,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,EAAE,WAAW,CAAC,QAAQ,CAAC;YAC/D,UAAU,EAAE,IAAI;YAChB,YAAY,EAAE,KAAK;SACpB,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,YAAY,EAAE,kBAEG;QACjB,GAAG;QACH,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC;QAC9B,IAAI;KACL,CAAC;AACJ,CAAC"}

package/dist/runtime/errors.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Runtime error types.
+ *
+ * Provides structured error types for validation failures,
+ * integration errors, and execution errors.
+ */
+/**
+ * Error codes for categorizing runtime errors.
+ */
+export declare const ErrorCode: {
+    /** Input validation failed against the Zod schema */
+    readonly INPUT_VALIDATION: "INPUT_VALIDATION";
+    /** Output validation failed against the Zod schema */
+    readonly OUTPUT_VALIDATION: "OUTPUT_VALIDATION";
+    /** Integration not found or not configured */
+    readonly INTEGRATION_NOT_FOUND: "INTEGRATION_NOT_FOUND";
+    /** Integration operation failed */
+    readonly INTEGRATION_ERROR: "INTEGRATION_ERROR";
+    /** User code threw an error during execution */
+    readonly EXECUTION_ERROR: "EXECUTION_ERROR";
+    /** Internal SDK error */
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
+export type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode];
+/**
+ * Base class for SDK runtime errors.
+ */
+export declare class SdkError extends Error {
+    readonly code: ErrorCodeType;
+    readonly details?: unknown;
+    constructor(code: ErrorCodeType, message: string, details?: unknown);
+    /**
+     * Converts the error to a plain object for serialization.
+     */
+    toJSON(): {
+        code: ErrorCodeType;
+        message: string;
+        details?: unknown;
+    };
+}
+/**
+ * Error thrown when input validation fails.
+ */
+export declare class InputValidationError extends SdkError {
+    constructor(message: string, details?: unknown);
+}
+/**
+ * Error thrown when output validation fails.
+ */
+export declare class OutputValidationError extends SdkError {
+    constructor(message: string, details?: unknown);
+}
+/**
+ * Error thrown when a requested integration is not found.
+ */
+export declare class IntegrationNotFoundError extends SdkError {
+    readonly integrationName: string;
+    constructor(integrationName: string);
+}
+/**
+ * Error thrown when an integration operation fails.
+ */
+export declare class IntegrationError extends SdkError {
+    readonly integrationName: string;
+    readonly operation: string;
+    constructor(integrationName: string, operation: string, cause?: unknown);
+}
+/**
+ * Error thrown when user code fails during execution.
+ */
+export declare class ExecutionError extends SdkError {
+    constructor(message: string, cause?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/runtime/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/runtime/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,eAAO,MAAM,SAAS;IACpB,qDAAqD;;IAGrD,sDAAsD;;IAGtD,8CAA8C;;IAG9C,mCAAmC;;IAGnC,gDAAgD;;IAGhD,yBAAyB;;CAEjB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAEvE;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;gBAEf,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;IAenE;;OAEG;IACH,MAAM,IAAI;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE;CAOtE;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,QAAQ;gBACpC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAI/C;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,QAAQ;gBACrC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAI/C;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,QAAQ;IACpD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;gBAErB,eAAe,EAAE,MAAM;CASpC;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,QAAQ;IAC5C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,eAAe,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAOxE;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,QAAQ;gBAC9B,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI7C"}

package/dist/runtime/errors.js

@@ -0,0 +1,105 @@
+/**
+ * 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',
+};
+/**
+ * Base class for SDK runtime errors.
+ */
+export class SdkError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        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() {
+        return {
+            code: this.code,
+            message: this.message,
+            details: this.details,
+        };
+    }
+}
+/**
+ * Error thrown when input validation fails.
+ */
+export class InputValidationError extends SdkError {
+    constructor(message, details) {
+        super(ErrorCode.INPUT_VALIDATION, message, details);
+        this.name = 'InputValidationError';
+    }
+}
+/**
+ * Error thrown when output validation fails.
+ */
+export class OutputValidationError extends SdkError {
+    constructor(message, details) {
+        super(ErrorCode.OUTPUT_VALIDATION, message, details);
+        this.name = 'OutputValidationError';
+    }
+}
+/**
+ * Error thrown when a requested integration is not found.
+ */
+export class IntegrationNotFoundError extends SdkError {
+    integrationName;
+    constructor(integrationName) {
+        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 {
+    integrationName;
+    operation;
+    constructor(integrationName, operation, cause) {
+        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, cause) {
+        super(ErrorCode.EXECUTION_ERROR, message, { cause });
+        this.name = 'ExecutionError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/runtime/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/runtime/errors.ts"],"names":[],"mappings":"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"}

package/dist/runtime/execute.d.ts

@@ -0,0 +1,126 @@
+/**
+ * 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 { IntegrationConfig } from '../integrations/types.js';
+import type { ApiUser } from '../types.js';
+import { type ExecuteApiResponse } from './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>) => 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
+     * @returns AsyncIterable yielding raw chunks
+     */
+    executeStreamingQuery?: (integrationId: string, request: Record<string, unknown>) => 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 = CompiledApi<any, 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 declare 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 declare function execute<TInput, TChunk>(api: CompiledStreamingApi<TInput, TChunk>, request: UnifiedExecuteApiRequest): AsyncGenerator<TChunk, void, undefined>;
+/**
+ * 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 };
+//# sourceMappingURL=execute.d.ts.map

package/dist/runtime/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/runtime/execute.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAc,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGpE;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACvC,qCAAqC;IACrC,KAAK,EAAE,OAAO,CAAC;IAEf,2CAA2C;IAC3C,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAElC,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IAEpB,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE5B,0DAA0D;IAC1D,IAAI,EAAE,OAAO,CAAC;IAEd;;;;;;;OAOG;IACH,YAAY,EAAE,CACZ,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC/B,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtB;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,CACtB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,aAAa,CAAC,OAAO,CAAC,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAEtB,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,GAErB,oBAAoB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,OAAO,EACrC,GAAG,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EACpC,GAAG,EAAE,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,EACzC,OAAO,EAAE,wBAAwB,GAChC,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;AAiE3C;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/runtime/execute.js

@@ -0,0 +1,84 @@
+/**
+ * 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 { isStreamingApi } from '../api/streaming.js';
+import { executeApi } from './executor.js';
+import { createStreamingApiGenerator } from './streaming-executor.js';
+/**
+ * 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, request) {
+    if (isStreamingApi(api)) {
+        // Streaming API - return generator directly
+        return createStreamingApiGenerator(api, request);
+    }
+    else {
+        // Regular API - return promise
+        return executeApi(api, 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 };
+//# sourceMappingURL=execute.js.map

package/dist/runtime/execute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.js","sourceRoot":"","sources":["../../src/runtime/execute.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,cAAc,EAA6B,MAAM,qBAAqB,CAAC;AAGhF,OAAO,EAAE,UAAU,EAA2B,MAAM,eAAe,CAAC;AACpE,OAAO,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AA2HtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,UAAU,OAAO,CACrB,GAAmB,EACnB,OAAiC;IAEjC,IAAI,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,4CAA4C;QAC5C,OAAO,2BAA2B,CAChC,GAA6C,EAC7C,OAAO,CACR,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,+BAA+B;QAC/B,OAAO,UAAU,CACf,GAAoC,EACpC,OAAO,CACR,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/runtime/executor.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 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 type { IntegrationConfig } from '../integrations/types.js';
+import type { ApiUser } from '../types.js';
+import { 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>) => 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 declare function executeApi<TInput = unknown, TOutput = unknown>(api: CompiledApi<TInput, TOutput>, request: ExecuteApiRequest): Promise<ExecuteApiResponse<TOutput>>;
+//# sourceMappingURL=executor.d.ts.map

package/dist/runtime/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/runtime/executor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAML,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAErB;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,qCAAqC;IACrC,KAAK,EAAE,OAAO,CAAC;IAEf,2CAA2C;IAC3C,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAElC,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IAEpB,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE5B,0DAA0D;IAC1D,IAAI,EAAE,OAAO,CAAC;IAEd;;;;;;;;;;;;;;;OAeG;IACH,YAAY,EAAE,CACZ,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC/B,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB,CAAC,OAAO,GAAG,OAAO;IAC1D,OAAO,EAAE,IAAI,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE;QACL,IAAI,EAAE,aAAa,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;CACH;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,CAAC,OAAO,GAAG,OAAO,IAC5C,yBAAyB,CAAC,OAAO,CAAC,GAClC,uBAAuB,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAsB,UAAU,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAClE,GAAG,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAwEtC"}