@superblocksteam/sdk-api 2.0.93 → 2.0.94-next.0

package/src/runtime/errors.ts

@@ -10,22 +10,22 @@
  */
 export const ErrorCode = {
   /** Input validation failed against the Zod schema */
-  INPUT_VALIDATION: 'INPUT_VALIDATION',
+  INPUT_VALIDATION: "INPUT_VALIDATION",
 
   /** Output validation failed against the Zod schema */
-  OUTPUT_VALIDATION: 'OUTPUT_VALIDATION',
+  OUTPUT_VALIDATION: "OUTPUT_VALIDATION",
 
   /** Integration not found or not configured */
-  INTEGRATION_NOT_FOUND: 'INTEGRATION_NOT_FOUND',
+  INTEGRATION_NOT_FOUND: "INTEGRATION_NOT_FOUND",
 
   /** Integration operation failed */
-  INTEGRATION_ERROR: 'INTEGRATION_ERROR',
+  INTEGRATION_ERROR: "INTEGRATION_ERROR",
 
   /** User code threw an error during execution */
-  EXECUTION_ERROR: 'EXECUTION_ERROR',
+  EXECUTION_ERROR: "EXECUTION_ERROR",
 
   /** Internal SDK error */
-  INTERNAL_ERROR: 'INTERNAL_ERROR',
+  INTERNAL_ERROR: "INTERNAL_ERROR",
 } as const;
 
 export type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode];
@@ -39,7 +39,7 @@ export class SdkError extends Error {
 
   constructor(code: ErrorCodeType, message: string, details?: unknown) {
     super(message);
-    this.name = 'SdkError';
+    this.name = "SdkError";
     this.code = code;
     this.details = details;
 
@@ -70,7 +70,7 @@ export class SdkError extends Error {
 export class InputValidationError extends SdkError {
   constructor(message: string, details?: unknown) {
     super(ErrorCode.INPUT_VALIDATION, message, details);
-    this.name = 'InputValidationError';
+    this.name = "InputValidationError";
   }
 }
 
@@ -80,7 +80,7 @@ export class InputValidationError extends SdkError {
 export class OutputValidationError extends SdkError {
   constructor(message: string, details?: unknown) {
     super(ErrorCode.OUTPUT_VALIDATION, message, details);
-    this.name = 'OutputValidationError';
+    this.name = "OutputValidationError";
   }
 }
 
@@ -96,7 +96,7 @@ export class IntegrationNotFoundError extends SdkError {
       `Integration not found: "${integrationName}"`,
       { integrationName },
     );
-    this.name = 'IntegrationNotFoundError';
+    this.name = "IntegrationNotFoundError";
     this.integrationName = integrationName;
   }
 }
@@ -110,8 +110,12 @@ export class IntegrationError extends SdkError {
 
   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';
+    super(ErrorCode.INTEGRATION_ERROR, message, {
+      integrationName,
+      operation,
+      cause,
+    });
+    this.name = "IntegrationError";
     this.integrationName = integrationName;
     this.operation = operation;
   }
@@ -123,6 +127,6 @@ export class IntegrationError extends SdkError {
 export class ExecutionError extends SdkError {
   constructor(message: string, cause?: unknown) {
     super(ErrorCode.EXECUTION_ERROR, message, { cause });
-    this.name = 'ExecutionError';
+    this.name = "ExecutionError";
   }
 }

package/src/runtime/execute.ts

@@ -5,12 +5,12 @@
  * 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 { executeApi, type ExecuteApiResponse } from './executor.js';
-import { createStreamingApiGenerator } from './streaming-executor.js';
+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 { executeApi, type ExecuteApiResponse } from "./executor.js";
+import { createStreamingApiGenerator } from "./streaming-executor.js";
 
 /**
  * Unified request for executing any API (regular or streaming).
@@ -180,7 +180,9 @@ export function execute<TInput, TChunk>(
 export function execute(
   api: AnyCompiledApi,
   request: UnifiedExecuteApiRequest,
-): Promise<ExecuteApiResponse<unknown>> | AsyncGenerator<unknown, void, undefined> {
+):
+  | Promise<ExecuteApiResponse<unknown>>
+  | AsyncGenerator<unknown, void, undefined> {
   if (isStreamingApi(api)) {
     // Streaming API - return generator directly
     return createStreamingApiGenerator(
@@ -189,10 +191,7 @@ export function execute(
     );
   } else {
     // Regular API - return promise
-    return executeApi(
-      api as CompiledApi<unknown, unknown>,
-      request,
-    );
+    return executeApi(api as CompiledApi<unknown, unknown>, request);
   }
 }
 

package/src/runtime/executor.ts

@@ -5,11 +5,11 @@
  * handling input/output validation and error management.
  */
 
-import type { CompiledApi } from '../api/definition.js';
-import { getIntegrationDeclarations } from '../integrations/declarations.js';
-import type { IntegrationConfig } from '../integrations/types.js';
-import type { ApiUser } from '../types.js';
-import { createApiContext } from './context.js';
+import type { CompiledApi } from "../api/definition.js";
+import { getIntegrationDeclarations } from "../integrations/declarations.js";
+import type { IntegrationConfig } from "../integrations/types.js";
+import type { ApiUser } from "../types.js";
+import { createApiContext } from "./context.js";
 import {
   SdkError,
   InputValidationError,
@@ -17,7 +17,7 @@ import {
   ExecutionError,
   ErrorCode,
   type ErrorCodeType,
-} from './errors.js';
+} from "./errors.js";
 
 /**
  * Request to execute an API.
@@ -57,7 +57,7 @@ export interface ExecuteApiRequest {
   executeQuery: (
     integrationId: string,
     request: Record<string, unknown>,
-    bindings?: Record<string, unknown>
+    bindings?: Record<string, unknown>,
   ) => Promise<unknown>;
 }
 
@@ -142,7 +142,7 @@ export async function executeApi<TInput = unknown, TOutput = unknown>(
     // 1. Validate input
     const inputResult = api.inputSchema.safeParse(request.input);
     if (!inputResult.success) {
-      throw new InputValidationError('Input validation failed', {
+      throw new InputValidationError("Input validation failed", {
         issues: inputResult.error.issues,
       });
     }
@@ -180,7 +180,7 @@ export async function executeApi<TInput = unknown, TOutput = unknown>(
     // 5. Validate output
     const outputResult = api.outputSchema.safeParse(rawOutput);
     if (!outputResult.success) {
-      throw new OutputValidationError('Output validation failed', {
+      throw new OutputValidationError("Output validation failed", {
         issues: outputResult.error.issues,
       });
     }

package/src/runtime/index.ts

@@ -11,7 +11,7 @@ export {
   isStreamingApi,
   type UnifiedExecuteApiRequest,
   type AnyCompiledApi,
-} from './execute.js';
+} from "./execute.js";
 
 // Main executor (for non-streaming APIs)
 export {
@@ -20,7 +20,7 @@ export {
   type ExecuteApiResponse,
   type ExecuteApiSuccessResponse,
   type ExecuteApiErrorResponse,
-} from './executor.js';
+} from "./executor.js";
 
 // Streaming executor (for streaming APIs)
 export {
@@ -30,11 +30,14 @@ export {
   type StreamingApiCallbacks,
   type StreamingApiError,
   type ExecuteStreamingApiResult,
-} from './streaming-executor.js';
+} from "./streaming-executor.js";
 
 // Context factories
-export { createApiContext, type CreateContextOptions } from './context.js';
-export { createStreamingApiContext, type CreateStreamingContextOptions } from './streaming-context.js';
+export { createApiContext, type CreateContextOptions } from "./context.js";
+export {
+  createStreamingApiContext,
+  type CreateStreamingContextOptions,
+} from "./streaming-context.js";
 
 // Error types
 export {
@@ -46,4 +49,4 @@ export {
   ExecutionError,
   ErrorCode,
   type ErrorCodeType,
-} from './errors.js';
+} from "./errors.js";

package/src/runtime/logger.ts

@@ -5,7 +5,7 @@
  * with structured output including timestamps and execution IDs.
  */
 
-import type { Logger } from '../types.js';
+import type { Logger } from "../types.js";
 
 /**
  * Creates a default logger that outputs to console.
@@ -14,24 +14,28 @@ import type { Logger } from '../types.js';
  * @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 formatMessage = (
+    level: string,
+    message: string,
+    data?: Record<string, unknown>,
+  ): string => {
     const timestamp = new Date().toISOString();
-    const dataStr = data ? ` ${JSON.stringify(data)}` : '';
+    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));
+      console.log(formatMessage("INFO", message, data));
     },
     warn(message: string, data?: Record<string, unknown>): void {
-      console.warn(formatMessage('WARN', message, data));
+      console.warn(formatMessage("WARN", message, data));
     },
     error(message: string, data?: Record<string, unknown>): void {
-      console.error(formatMessage('ERROR', message, data));
+      console.error(formatMessage("ERROR", message, data));
     },
     debug(message: string, data?: Record<string, unknown>): void {
-      console.debug(formatMessage('DEBUG', message, data));
+      console.debug(formatMessage("DEBUG", message, data));
     },
   };
 }

package/src/runtime/streaming-context.ts

@@ -5,11 +5,23 @@
  * access to integrations (with streaming support), logging, and environment.
  */
 
-import type { ApiContext, ApiUser, Logger, AnyIntegrationRef } from '../types.js';
-import type { IntegrationConfig, IntegrationClientImpl } from '../integrations/types.js';
-import type { IntegrationDeclaration } from '../integrations/declarations.js';
-import { createClient, type QueryExecutor, type StreamingQueryExecutor } from '../integrations/registry.js';
-import { createDefaultLogger } from './logger.js';
+import type {
+  ApiContext,
+  ApiUser,
+  Logger,
+  AnyIntegrationRef,
+} from "../types.js";
+import type {
+  IntegrationConfig,
+  IntegrationClientImpl,
+} from "../integrations/types.js";
+import type { IntegrationDeclaration } from "../integrations/declarations.js";
+import {
+  createClient,
+  type QueryExecutor,
+  type StreamingQueryExecutor,
+} from "../integrations/registry.js";
+import { createDefaultLogger } from "./logger.js";
 
 /**
  * Options for creating a streaming API execution context.
@@ -102,9 +114,11 @@ export function createStreamingApiContext(
     ) => executeQuery(id, request, bindings);
 
     // Create streaming executor if provided
-    const boundStreamingExecutor: StreamingQueryExecutor | undefined = executeStreamingQuery
-      ? (request: Record<string, unknown>) => executeStreamingQuery(id, request)
-      : undefined;
+    const boundStreamingExecutor: StreamingQueryExecutor | undefined =
+      executeStreamingQuery
+        ? (request: Record<string, unknown>) =>
+            executeStreamingQuery(id, request)
+        : undefined;
 
     const clientConfig: IntegrationConfig = config ?? {
       id,
@@ -138,7 +152,7 @@ export function createStreamingApiContext(
   return {
     integrations: integrationsObject as ApiContext<
       Record<string, AnyIntegrationRef>
-    >['integrations'],
+    >["integrations"],
     log,
     env: Object.freeze({ ...env }),
     user,

package/src/runtime/streaming-executor.ts

@@ -5,18 +5,21 @@
  * handling input validation, chunk validation, and error management.
  */
 
-import type { CompiledStreamingApi } from '../api/streaming.js';
-import { getIntegrationDeclarations } from '../integrations/declarations.js';
-import type { IntegrationConfig } from '../integrations/types.js';
-import type { ApiUser } from '../types.js';
-import { createStreamingApiContext, type CreateStreamingContextOptions } from './streaming-context.js';
+import type { CompiledStreamingApi } from "../api/streaming.js";
+import { getIntegrationDeclarations } from "../integrations/declarations.js";
+import type { IntegrationConfig } from "../integrations/types.js";
+import type { ApiUser } from "../types.js";
+import {
+  createStreamingApiContext,
+  type CreateStreamingContextOptions,
+} from "./streaming-context.js";
 import {
   SdkError,
   InputValidationError,
   ExecutionError,
   ErrorCode,
   type ErrorCodeType,
-} from './errors.js';
+} from "./errors.js";
 
 /**
  * Request to execute a streaming API.
@@ -170,7 +173,7 @@ export async function executeStreamingApi<TInput = unknown, TChunk = unknown>(
     if (!inputResult.success) {
       const error: StreamingApiError = {
         code: ErrorCode.INPUT_VALIDATION,
-        message: 'Input validation failed',
+        message: "Input validation failed",
         details: { issues: inputResult.error.issues },
         chunksYielded: 0,
       };
@@ -296,14 +299,17 @@ export async function executeStreamingApi<TInput = unknown, TChunk = unknown>(
  * }
  * ```
  */
-export async function* createStreamingApiGenerator<TInput = unknown, TChunk = unknown>(
+export async function* createStreamingApiGenerator<
+  TInput = unknown,
+  TChunk = unknown,
+>(
   api: CompiledStreamingApi<TInput, TChunk>,
   request: ExecuteStreamingApiRequest,
 ): AsyncGenerator<TChunk, void, undefined> {
   // Validate input
   const inputResult = api.inputSchema.safeParse(request.input);
   if (!inputResult.success) {
-    throw new InputValidationError('Input validation failed', {
+    throw new InputValidationError("Input validation failed", {
       issues: inputResult.error.issues,
     });
   }

package/src/types.ts

@@ -4,12 +4,12 @@
  * This module provides the public types used to define TypeScript-based APIs.
  */
 
-import type { z } from 'zod';
+import type { z } from "zod";
 import type {
   IntegrationRef,
   AnyIntegrationRef,
   IntegrationsMap,
-} from './integrations/declarations.js';
+} from "./integrations/declarations.js";
 
 /**
  * Configuration for defining a TypeScript-based API.
@@ -55,7 +55,10 @@ import type {
 export interface ApiConfig<
   TInput extends z.ZodType,
   TOutput extends z.ZodType,
-  TIntegrations extends Record<string, AnyIntegrationRef> = Record<string, never>,
+  TIntegrations extends Record<string, AnyIntegrationRef> = Record<
+    string,
+    never
+  >,
 > {
   /**
    * Name for this API.
@@ -64,6 +67,14 @@ export interface ApiConfig<
    */
   name: string;
 
+  /**
+   * Plain-language summary of what this API does and which integrations it uses,
+   * written for a non-technical audience.
+   *
+   * This field is auto-generated by the AI agent when creating or editing an API.
+   */
+  description?: string;
+
   /**
    * Integration declarations for this API.
    *
@@ -93,7 +104,10 @@ export interface ApiConfig<
    * @param input - Validated input parameters (can be destructured)
    * @returns Promise resolving to the validated output
    */
-  run: (ctx: ApiContext<TIntegrations>, input: z.infer<TInput>) => Promise<z.infer<TOutput>>;
+  run: (
+    ctx: ApiContext<TIntegrations>,
+    input: z.infer<TInput>,
+  ) => Promise<z.infer<TOutput>>;
 }
 
 /**
@@ -128,12 +142,15 @@ export interface ApiUser {
  * @template TIntegrations - Record of integration declarations
  */
 export interface ApiContext<
-  TIntegrations extends Record<string, AnyIntegrationRef> = Record<string, never>,
+  TIntegrations extends Record<string, AnyIntegrationRef> = Record<
+    string,
+    never
+  >,
 > {
   /**
    * Typed integration clients declared in the API config.
    *
-   * Access integrations by the key you defined in the `integrations` config.
+   * Access each integration by the name (key) you declared: `ctx.integrations.<name>`.
    * Each client is fully typed based on the declaration function used.
    *
    * @example