@superblocksteam/sdk-api 0.0.4

package/dist/integrations/zoom/client.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Zoom client implementation.
+ *
+ * Uses the proto-generated REST API Integration Plugin type from @superblocksteam/types.
+ * Zoom integrations use the REST API Integration plugin under the hood.
+ */
+import { RestApiIntegrationClient } from "../base/index.js";
+import type { ZoomClient } from "./types.js";
+/**
+ * Internal implementation of ZoomClient.
+ *
+ * Extends RestApiIntegrationClient to inherit the generic apiRequest() method.
+ * This implementation communicates with the orchestrator to execute
+ * Zoom API calls. At runtime, the orchestrator handles authentication
+ * and API request execution.
+ */
+export declare class ZoomClientImpl extends RestApiIntegrationClient implements ZoomClient {
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/integrations/zoom/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/integrations/zoom/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;GAOG;AACH,qBAAa,cACX,SAAQ,wBACR,YAAW,UAAU;CAEtB"}

package/dist/integrations/zoom/client.js

@@ -0,0 +1,18 @@
+/**
+ * Zoom client implementation.
+ *
+ * Uses the proto-generated REST API Integration Plugin type from @superblocksteam/types.
+ * Zoom integrations use the REST API Integration plugin under the hood.
+ */
+import { RestApiIntegrationClient } from "../base/index.js";
+/**
+ * Internal implementation of ZoomClient.
+ *
+ * Extends RestApiIntegrationClient to inherit the generic apiRequest() method.
+ * This implementation communicates with the orchestrator to execute
+ * Zoom API calls. At runtime, the orchestrator handles authentication
+ * and API request execution.
+ */
+export class ZoomClientImpl extends RestApiIntegrationClient {
+}
+//# sourceMappingURL=client.js.map

package/dist/integrations/zoom/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/integrations/zoom/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAG5D;;;;;;;GAOG;AACH,MAAM,OAAO,cACX,SAAQ,wBAAwB;CAGjC"}

package/dist/integrations/zoom/index.d.ts

@@ -0,0 +1,3 @@
+export { ZoomClientImpl } from "./client.js";
+export type { ZoomClient } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/integrations/zoom/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/integrations/zoom/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/integrations/zoom/index.js

@@ -0,0 +1,2 @@
+export { ZoomClientImpl } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/integrations/zoom/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/integrations/zoom/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/integrations/zoom/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Zoom client types.
+ */
+import type { BaseIntegrationClient } from "../../types.js";
+import type { SupportsApiRequest } from "../base/index.js";
+/**
+ * Zoom client for API interactions.
+ *
+ * Provides generic API request method for interacting with Zoom's API.
+ * Use apiRequest() to make calls to any Zoom API endpoint.
+ *
+ * @example
+ * ```typescript
+ * // Declare in api(): integrations: { zoom: zoom(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.zoom
+ *
+ * // Make API requests
+ * const ResponseSchema = z.object({
+ *   // Define your response schema
+ * });
+ *
+ * const result = await ctx.integrations.zoom.apiRequest(
+ *   {
+ *     method: 'GET',
+ *     path: '/users',
+ *   },
+ *   { response: ResponseSchema }
+ * );
+ * ```
+ */
+export interface ZoomClient extends BaseIntegrationClient, SupportsApiRequest {
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/integrations/zoom/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/integrations/zoom/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,UAAW,SAAQ,qBAAqB,EAAE,kBAAkB;CAE5E"}

package/dist/integrations/zoom/types.js

@@ -0,0 +1,5 @@
+/**
+ * Zoom client types.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/integrations/zoom/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/integrations/zoom/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/runtime/context.d.ts

@@ -0,0 +1,69 @@
+/**
+ * API execution context factory.
+ *
+ * Creates the context object that is passed to user API functions,
+ * providing access to integrations, 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";
+import { type TraceMetadata } from "../integrations/registry.js";
+/**
+ * Options for creating an API execution context.
+ */
+export interface CreateContextOptions {
+    /** Available integration configurations keyed by id */
+    integrations: Map<string, IntegrationConfig>;
+    /**
+     * Declared integrations from the API config.
+     *
+     * These are the integrations specified in the `integrations` field of the API config.
+     * The context will only expose these declared integrations via `ctx.integrations`.
+     */
+    integrationDeclarations: IntegrationDeclaration[];
+    /**
+     * Function to execute integration operations.
+     *
+     * For language plugins (Python, JavaScript), pass the bindings parameter
+     * to the API execution request as `input` field for binding resolution.
+     */
+    executeQuery: (integrationId: string, request: Record<string, unknown>, bindings?: Record<string, unknown>, metadata?: TraceMetadata) => Promise<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 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 declare function createApiContext(options: CreateContextOptions): ApiContext<Record<string, AnyIntegrationRef>>;
+//# sourceMappingURL=context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,OAAO,EACP,MAAM,EACN,iBAAiB,EAClB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACV,iBAAiB,EAElB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC9E,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,6BAA6B,CAAC;AAGrC;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,uDAAuD;IACvD,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAE7C;;;;;OAKG;IACH,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;IAElD;;;;;OAKG;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,EAClC,QAAQ,CAAC,EAAE,aAAa,KACrB,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtB,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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,oBAAoB,GAC5B,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAgF/C"}

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, metadata) => executeQuery(id, request, bindings, metadata);
+        // 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;AAaH,OAAO,EACL,YAAY,GAGb,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AA2ClD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAA6B;IAE7B,MAAM,EACJ,YAAY,EACZ,uBAAuB,EACvB,YAAY,EACZ,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;;;;;;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,QAAwB,EACxB,EAAE,CAAC,YAAY,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAEnD,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;CAWxE;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,109 @@
+/**
+ * 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,128 @@
+/**
+ * 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 { 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>, 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 = 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,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,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,EAClC,QAAQ,CAAC,EAAE,aAAa,KACrB,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtB;;;;;;;;OAQG;IACH,qBAAqB,CAAC,EAAE,CACtB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,CAAC,EAAE,aAAa,KACrB,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;AAgE3C;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,cAAc,EAAE,CAAC"}