@superblocksteam/sdk-api 2.0.89-next.0

package/dist/runtime/executor.js

@@ -0,0 +1,121 @@
+/**
+ * API execution engine.
+ *
+ * Provides the main entry point for executing compiled APIs,
+ * handling input/output validation and error management.
+ */
+import { getIntegrationDeclarations } from '../integrations/declarations.js';
+import { createApiContext } from './context.js';
+import { SdkError, InputValidationError, OutputValidationError, ExecutionError, ErrorCode, } from './errors.js';
+/**
+ * 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(api, request) {
+    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();
+        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;
+        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,
+        };
+    }
+    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,
+            },
+        };
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/runtime/executor.js.map

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

package/dist/runtime/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Runtime execution module.
+ *
+ * Provides the execution engine for running compiled APIs,
+ * including context creation, validation, and error handling.
+ */
+export { execute, isStreamingApi, type UnifiedExecuteApiRequest, type AnyCompiledApi, } from './execute.js';
+export { executeApi, type ExecuteApiRequest, type ExecuteApiResponse, type ExecuteApiSuccessResponse, type ExecuteApiErrorResponse, } from './executor.js';
+export { executeStreamingApi, createStreamingApiGenerator, type ExecuteStreamingApiRequest, type StreamingApiCallbacks, type StreamingApiError, type ExecuteStreamingApiResult, } from './streaming-executor.js';
+export { createApiContext, type CreateContextOptions } from './context.js';
+export { createStreamingApiContext, type CreateStreamingContextOptions } from './streaming-context.js';
+export { SdkError, InputValidationError, OutputValidationError, IntegrationNotFoundError, IntegrationError, ExecutionError, ErrorCode, type ErrorCodeType, } from './errors.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,OAAO,EACP,cAAc,EACd,KAAK,wBAAwB,EAC7B,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,GAC7B,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,mBAAmB,EACnB,2BAA2B,EAC3B,KAAK,0BAA0B,EAC/B,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,yBAAyB,GAC/B,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,yBAAyB,EAAE,KAAK,6BAA6B,EAAE,MAAM,wBAAwB,CAAC;AAGvG,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACxB,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC"}

package/dist/runtime/index.js

@@ -0,0 +1,18 @@
+/**
+ * Runtime execution module.
+ *
+ * Provides the execution engine for running compiled APIs,
+ * including context creation, validation, and error handling.
+ */
+// Unified executor (recommended)
+export { execute, isStreamingApi, } from './execute.js';
+// Main executor (for non-streaming APIs)
+export { executeApi, } from './executor.js';
+// Streaming executor (for streaming APIs)
+export { executeStreamingApi, createStreamingApiGenerator, } from './streaming-executor.js';
+// Context factories
+export { createApiContext } from './context.js';
+export { createStreamingApiContext } from './streaming-context.js';
+// Error types
+export { SdkError, InputValidationError, OutputValidationError, IntegrationNotFoundError, IntegrationError, ExecutionError, ErrorCode, } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,iCAAiC;AACjC,OAAO,EACL,OAAO,EACP,cAAc,GAGf,MAAM,cAAc,CAAC;AAEtB,yCAAyC;AACzC,OAAO,EACL,UAAU,GAKX,MAAM,eAAe,CAAC;AAEvB,0CAA0C;AAC1C,OAAO,EACL,mBAAmB,EACnB,2BAA2B,GAK5B,MAAM,yBAAyB,CAAC;AAEjC,oBAAoB;AACpB,OAAO,EAAE,gBAAgB,EAA6B,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,yBAAyB,EAAsC,MAAM,wBAAwB,CAAC;AAEvG,cAAc;AACd,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACxB,gBAAgB,EAChB,cAAc,EACd,SAAS,GAEV,MAAM,aAAa,CAAC"}

package/dist/runtime/logger.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 declare function createDefaultLogger(executionId: string): Logger;
+//# sourceMappingURL=logger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/runtime/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAqB/D"}

package/dist/runtime/logger.js

@@ -0,0 +1,34 @@
+/**
+ * Default logger factory for API execution contexts.
+ *
+ * Provides a simple console-based logger implementation
+ * with structured output including timestamps and execution IDs.
+ */
+/**
+ * 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) {
+    const formatMessage = (level, message, data) => {
+        const timestamp = new Date().toISOString();
+        const dataStr = data ? ` ${JSON.stringify(data)}` : '';
+        return `[${timestamp}] [${executionId}] [${level}] ${message}${dataStr}`;
+    };
+    return {
+        info(message, data) {
+            console.log(formatMessage('INFO', message, data));
+        },
+        warn(message, data) {
+            console.warn(formatMessage('WARN', message, data));
+        },
+        error(message, data) {
+            console.error(formatMessage('ERROR', message, data));
+        },
+        debug(message, data) {
+            console.debug(formatMessage('DEBUG', message, data));
+        },
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/runtime/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/runtime/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,MAAM,aAAa,GAAG,CAAC,KAAa,EAAE,OAAe,EAAE,IAA8B,EAAU,EAAE;QAC/F,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,OAAO,IAAI,SAAS,MAAM,WAAW,MAAM,KAAK,KAAK,OAAO,GAAG,OAAO,EAAE,CAAC;IAC3E,CAAC,CAAC;IAEF,OAAO;QACL,IAAI,CAAC,OAAe,EAAE,IAA8B;YAClD,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QACpD,CAAC;QACD,IAAI,CAAC,OAAe,EAAE,IAA8B;YAClD,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QACrD,CAAC;QACD,KAAK,CAAC,OAAe,EAAE,IAA8B;YACnD,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QACvD,CAAC;QACD,KAAK,CAAC,OAAe,EAAE,IAA8B;YACnD,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QACvD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/runtime/streaming-context.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 } from '../integrations/types.js';
+import type { IntegrationDeclaration } from '../integrations/declarations.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 declare function createStreamingApiContext(options: CreateStreamingContextOptions): ApiContext<Record<string, AnyIntegrationRef>>;
+//# sourceMappingURL=streaming-context.d.ts.map

package/dist/runtime/streaming-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-context.d.ts","sourceRoot":"","sources":["../../src/runtime/streaming-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAClF,OAAO,KAAK,EAAE,iBAAiB,EAAyB,MAAM,0BAA0B,CAAC;AACzF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAI9E;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,uDAAuD;IACvD,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAE7C;;OAEG;IACH,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;IAElD;;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;IAEtB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,CACtB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,aAAa,CAAC,OAAO,CAAC,CAAC;IAE5B,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IAEpB,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE5B,gCAAgC;IAChC,IAAI,EAAE,OAAO,CAAC;IAEd,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,6BAA6B,GACrC,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CA8E/C"}

package/dist/runtime/streaming-context.js

@@ -0,0 +1,71 @@
+/**
+ * Streaming API execution context factory.
+ *
+ * Creates the context object for streaming API functions, providing
+ * access to integrations (with streaming support), logging, and environment.
+ */
+import { createClient } from '../integrations/registry.js';
+import { createDefaultLogger } from './logger.js';
+/**
+ * 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) {
+    const { integrations, integrationDeclarations, executeQuery, executeStreamingQuery, 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 streaming execution if provided.
+     */
+    function getTypedClient(id, pluginId) {
+        const cached = clientCache.get(id);
+        if (cached) {
+            return cached;
+        }
+        const config = integrations.get(id);
+        // Create executor bound to this integration
+        const boundExecutor = (request, bindings) => executeQuery(id, request, bindings);
+        // Create streaming executor if provided
+        const boundStreamingExecutor = executeStreamingQuery
+            ? (request) => executeStreamingQuery(id, request)
+            : undefined;
+        const clientConfig = 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 = {};
+    for (const declaration of integrationDeclarations) {
+        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=streaming-context.js.map

package/dist/runtime/streaming-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-context.js","sourceRoot":"","sources":["../../src/runtime/streaming-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,YAAY,EAAmD,MAAM,6BAA6B,CAAC;AAC5G,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AA6ClD;;;;;;;;GAQG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAsC;IAEtC,MAAM,EACJ,YAAY,EACZ,uBAAuB,EACvB,YAAY,EACZ,qBAAqB,EACrB,WAAW,EACX,GAAG,EACH,IAAI,EACJ,MAAM,GACP,GAAG,OAAO,CAAC;IAEZ,wCAAwC;IACxC,MAAM,WAAW,GAAG,IAAI,GAAG,EAAiC,CAAC;IAE7D,gBAAgB;IAChB,MAAM,GAAG,GAAG,MAAM,IAAI,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAEvD;;;OAGG;IACH,SAAS,cAAc,CAAC,EAAU,EAAE,QAAgB;QAClD,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnC,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,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,wCAAwC;QACxC,MAAM,sBAAsB,GAAuC,qBAAqB;YACtF,CAAC,CAAC,CAAC,OAAgC,EAAE,EAAE,CAAC,qBAAqB,CAAC,EAAE,EAAE,OAAO,CAAC;YAC1E,CAAC,CAAC,SAAS,CAAC;QAEd,MAAM,YAAY,GAAsB,MAAM,IAAI;YAChD,EAAE;YACF,IAAI,EAAE,EAAE;YACR,QAAQ;YACR,aAAa,EAAE,EAAE;SAClB,CAAC;QAEF,uCAAuC;QACvC,MAAM,MAAM,GAAG,YAAY,CAAC;YAC1B,MAAM,EAAE,YAAY;YACpB,YAAY,EAAE,aAAa;YAC3B,qBAAqB,EAAE,sBAAsB;SAC9C,CAAC,CAAC;QAEH,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QAC5B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,kDAAkD;IAClD,MAAM,kBAAkB,GAA0C,EAAE,CAAC;IAErE,KAAK,MAAM,WAAW,IAAI,uBAAuB,EAAE,CAAC;QAClD,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/streaming-executor.d.ts

@@ -0,0 +1,157 @@
+/**
+ * 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 type { IntegrationConfig } from '../integrations/types.js';
+import type { ApiUser } from '../types.js';
+import { 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 declare function executeStreamingApi<TInput = unknown, TChunk = unknown>(api: CompiledStreamingApi<TInput, TChunk>, request: ExecuteStreamingApiRequest, callbacks: StreamingApiCallbacks<TChunk>): Promise<ExecuteStreamingApiResult>;
+/**
+ * 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 declare function createStreamingApiGenerator<TInput = unknown, TChunk = unknown>(api: CompiledStreamingApi<TInput, TChunk>, request: ExecuteStreamingApiRequest): AsyncGenerator<TChunk, void, undefined>;
+//# sourceMappingURL=streaming-executor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-executor.d.ts","sourceRoot":"","sources":["../../src/runtime/streaming-executor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEhE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAErB;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,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;;;;;;OAMG;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;;GAEG;AACH,MAAM,WAAW,qBAAqB,CAAC,MAAM,GAAG,OAAO;IACrD;;;;;OAKG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEhD;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IAE3C;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GACjC;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO,EAC1E,GAAG,EAAE,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,EACzC,OAAO,EAAE,0BAA0B,EACnC,SAAS,EAAE,qBAAqB,CAAC,MAAM,CAAC,GACvC,OAAO,CAAC,yBAAyB,CAAC,CAkHpC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAuB,2BAA2B,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO,EACnF,GAAG,EAAE,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,EACzC,OAAO,EAAE,0BAA0B,GAClC,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAuDzC"}