@superblocksteam/sdk-api 0.0.4

package/dist/api/streaming.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Streaming API definition function.
+ *
+ * This module provides the `streamingApi()` function used to define TypeScript-based APIs
+ * that yield chunks over time, enabling real-time streaming from LLMs and other sources.
+ */
+import type { z } from "zod";
+import type { ApiContext, AnyIntegrationRef } from "../types.js";
+import { type IntegrationDeclaration } from "../integrations/declarations.js";
+/**
+ * Configuration for defining a streaming TypeScript-based API.
+ *
+ * @template TInput - Zod schema type for input validation
+ * @template TChunk - Zod schema type for each streamed chunk
+ * @template TIntegrations - Record of integration declarations
+ *
+ * @example
+ * ```typescript
+ * import { streamingApi, z, anthropic } from '@superblocksteam/sdk-api';
+ *
+ * export default streamingApi({
+ *   integrations: {
+ *     ai: anthropic('Production Anthropic'),
+ *   },
+ *
+ *   input: z.object({
+ *     prompt: z.string(),
+ *   }),
+ *
+ *   chunk: z.object({
+ *     type: z.literal('text-delta'),
+ *     text: z.string(),
+ *   }),
+ *
+ *   async *run(ctx, { prompt }) {
+ *     const stream = ctx.integrations.ai.streamApiRequest(
+ *       {
+ *         method: 'POST',
+ *         path: '/v1/messages',
+ *         body: {
+ *           model: 'claude-3-5-sonnet-20241022',
+ *           max_tokens: 1024,
+ *           stream: true,
+ *           messages: [{ role: 'user', content: prompt }],
+ *         },
+ *       },
+ *       { chunk: AnthropicStreamEventSchema }
+ *     );
+ *
+ *     for await (const event of stream) {
+ *       if (event.type === 'content_block_delta') {
+ *         yield { type: 'text-delta' as const, text: event.delta.text };
+ *       }
+ *     }
+ *   },
+ * });
+ * ```
+ */
+export interface StreamingApiConfig<TInput extends z.ZodType, TChunk extends z.ZodType, TIntegrations extends Record<string, AnyIntegrationRef> = Record<string, never>> {
+    /**
+     * Name for this API.
+     *
+     * Used for identification in execution logs and debugging.
+     */
+    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.
+     *
+     * Declare integrations upfront to enable type-safe access via `ctx.integrations`
+     * and to allow the runtime to authenticate integrations before execution.
+     *
+     * @example
+     * ```typescript
+     * integrations: {
+     *   ai: anthropic('Production Anthropic'),
+     *   db: postgres('Cache DB'),
+     * }
+     * ```
+     */
+    integrations?: TIntegrations;
+    /** Zod schema for input validation */
+    input: TInput;
+    /**
+     * Zod schema for validating each streamed chunk.
+     *
+     * Every chunk yielded by the run function is validated against this schema.
+     * Validation errors will terminate the stream.
+     */
+    chunk: TChunk;
+    /**
+     * The streaming API implementation function (async generator).
+     *
+     * @param ctx - Execution context with access to integrations
+     * @param input - Validated input parameters (can be destructured)
+     * @yields Chunks that are validated against the chunk schema
+     */
+    run: (ctx: ApiContext<TIntegrations>, input: z.infer<TInput>) => AsyncIterable<z.infer<TChunk>>;
+}
+/**
+ * A compiled streaming API definition ready for execution.
+ *
+ * @template TInput - The inferred input type
+ * @template TChunk - The inferred chunk type
+ */
+export interface CompiledStreamingApi<TInput = unknown, TChunk = unknown> {
+    /** Name of the API for identification in logs and debugging */
+    readonly name: string;
+    /** Plain-language summary of what this API does */
+    readonly description?: string;
+    /**
+     * Source file path relative to the app root (e.g. "server/apis/Chat/api.ts").
+     * Injected automatically by the Vite plugin — not authored by the user.
+     */
+    readonly entryPoint?: string;
+    /** Zod schema for validating inputs */
+    readonly inputSchema: z.ZodType<TInput>;
+    /**
+     * Zod schema for validating each streamed chunk.
+     *
+     * Every chunk yielded by the API is validated against this schema
+     * before being sent to the client.
+     */
+    readonly chunkSchema: z.ZodType<TChunk>;
+    /**
+     * The streaming API implementation function.
+     *
+     * @param ctx - Execution context
+     * @param input - Validated input parameters
+     * @returns AsyncIterable yielding validated chunks
+     */
+    readonly run: (ctx: ApiContext<Record<string, AnyIntegrationRef>>, input: TInput) => AsyncIterable<TChunk>;
+    /**
+     * Declared integrations for upfront authentication.
+     *
+     * This array contains all integrations declared in the API config,
+     * allowing the runtime to authenticate them before API execution.
+     */
+    readonly integrations: ReadonlyArray<IntegrationDeclaration>;
+    /**
+     * Runtime flag indicating this is a streaming API.
+     *
+     * Always `true` for streaming APIs. Use `isStreamingApi()` type guard
+     * to distinguish streaming APIs from regular APIs at runtime.
+     */
+    readonly isStreaming: true;
+}
+/**
+ * Define a streaming TypeScript-based API with chunk validation.
+ *
+ * This function creates a compiled streaming API definition that yields
+ * chunks over time. Each chunk is validated against the provided schema.
+ *
+ * Use this for:
+ * - Real-time LLM token streaming (OpenAI, Anthropic, etc.)
+ * - Server-sent events
+ * - Long-running operations with progress updates
+ * - Any API that produces output incrementally
+ *
+ * @param config - The streaming API configuration
+ * @returns A compiled streaming API definition
+ *
+ * @example
+ * ```typescript
+ * import { streamingApi, z, openai } from '@superblocksteam/sdk-api';
+ *
+ * export default streamingApi({
+ *   integrations: {
+ *     ai: openai('Production OpenAI'),
+ *   },
+ *
+ *   input: z.object({
+ *     prompt: z.string(),
+ *   }),
+ *
+ *   chunk: z.object({
+ *     content: z.string(),
+ *   }),
+ *
+ *   async *run(ctx, { prompt }) {
+ *     const stream = ctx.integrations.ai.streamApiRequest(
+ *       {
+ *         method: 'POST',
+ *         path: '/v1/chat/completions',
+ *         body: {
+ *           model: 'gpt-4',
+ *           stream: true,
+ *           messages: [{ role: 'user', content: prompt }],
+ *         },
+ *       },
+ *       { chunk: OpenAIChunkSchema }
+ *     );
+ *
+ *     for await (const chunk of stream) {
+ *       const content = chunk.choices[0]?.delta?.content;
+ *       if (content) {
+ *         yield { content };
+ *       }
+ *     }
+ *   },
+ * });
+ * ```
+ */
+export declare function streamingApi<TInput extends z.ZodType, TChunk extends z.ZodType, TIntegrations extends Record<string, AnyIntegrationRef> = Record<string, never>>(config: StreamingApiConfig<TInput, TChunk, TIntegrations>): CompiledStreamingApi<z.infer<TInput>, z.infer<TChunk>>;
+/**
+ * Type guard to check if an API is a streaming API.
+ *
+ * @param api - The API to check
+ * @returns `true` if the API is a streaming API, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isStreamingApi, executeApi, executeStreamingApi } from '@superblocksteam/sdk-api';
+ *
+ * if (isStreamingApi(api)) {
+ *   await executeStreamingApi(api, request);
+ * } else {
+ *   await executeApi(api, request);
+ * }
+ * ```
+ */
+export declare function isStreamingApi(api: unknown): api is CompiledStreamingApi<unknown, unknown>;
+//# sourceMappingURL=streaming.d.ts.map

package/dist/api/streaming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../../src/api/streaming.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,iCAAiC,CAAC;AAGzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,WAAW,kBAAkB,CACjC,MAAM,SAAS,CAAC,CAAC,OAAO,EACxB,MAAM,SAAS,CAAC,CAAC,OAAO,EACxB,aAAa,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,MAAM,CAC9D,MAAM,EACN,KAAK,CACN;IAED;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,aAAa,CAAC;IAE7B,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;OAMG;IACH,GAAG,EAAE,CACH,GAAG,EAAE,UAAU,CAAC,aAAa,CAAC,EAC9B,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,KACnB,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO;IACtE,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,mDAAmD;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,uCAAuC;IACvC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAExC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAExC;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,CACZ,GAAG,EAAE,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,EAClD,KAAK,EAAE,MAAM,KACV,aAAa,CAAC,MAAM,CAAC,CAAC;IAE3B;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC;IAE7D;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,YAAY,CAC1B,MAAM,SAAS,CAAC,CAAC,OAAO,EACxB,MAAM,SAAS,CAAC,CAAC,OAAO,EACxB,aAAa,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,MAAM,CAC9D,MAAM,EACN,KAAK,CACN,EAED,MAAM,EAAE,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,GACxD,oBAAoB,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAmBxD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,OAAO,GACX,GAAG,IAAI,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,CAW/C"}

package/dist/api/streaming.js

@@ -0,0 +1,107 @@
+/**
+ * Streaming API definition function.
+ *
+ * This module provides the `streamingApi()` function used to define TypeScript-based APIs
+ * that yield chunks over time, enabling real-time streaming from LLMs and other sources.
+ */
+import { extractIntegrationDeclarations, } from "../integrations/declarations.js";
+import { consumeEntryPoint } from "./definition.js";
+/**
+ * Define a streaming TypeScript-based API with chunk validation.
+ *
+ * This function creates a compiled streaming API definition that yields
+ * chunks over time. Each chunk is validated against the provided schema.
+ *
+ * Use this for:
+ * - Real-time LLM token streaming (OpenAI, Anthropic, etc.)
+ * - Server-sent events
+ * - Long-running operations with progress updates
+ * - Any API that produces output incrementally
+ *
+ * @param config - The streaming API configuration
+ * @returns A compiled streaming API definition
+ *
+ * @example
+ * ```typescript
+ * import { streamingApi, z, openai } from '@superblocksteam/sdk-api';
+ *
+ * export default streamingApi({
+ *   integrations: {
+ *     ai: openai('Production OpenAI'),
+ *   },
+ *
+ *   input: z.object({
+ *     prompt: z.string(),
+ *   }),
+ *
+ *   chunk: z.object({
+ *     content: z.string(),
+ *   }),
+ *
+ *   async *run(ctx, { prompt }) {
+ *     const stream = ctx.integrations.ai.streamApiRequest(
+ *       {
+ *         method: 'POST',
+ *         path: '/v1/chat/completions',
+ *         body: {
+ *           model: 'gpt-4',
+ *           stream: true,
+ *           messages: [{ role: 'user', content: prompt }],
+ *         },
+ *       },
+ *       { chunk: OpenAIChunkSchema }
+ *     );
+ *
+ *     for await (const chunk of stream) {
+ *       const content = chunk.choices[0]?.delta?.content;
+ *       if (content) {
+ *         yield { content };
+ *       }
+ *     }
+ *   },
+ * });
+ * ```
+ */
+export function streamingApi(config) {
+    // Extract integration declarations for upfront auth
+    const integrations = extractIntegrationDeclarations(config.integrations);
+    const compiled = {
+        name: config.name,
+        description: config.description,
+        entryPoint: consumeEntryPoint(),
+        inputSchema: config.input,
+        chunkSchema: config.chunk,
+        run: config.run,
+        integrations,
+        isStreaming: true,
+    };
+    return compiled;
+}
+/**
+ * Type guard to check if an API is a streaming API.
+ *
+ * @param api - The API to check
+ * @returns `true` if the API is a streaming API, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isStreamingApi, executeApi, executeStreamingApi } from '@superblocksteam/sdk-api';
+ *
+ * if (isStreamingApi(api)) {
+ *   await executeStreamingApi(api, request);
+ * } else {
+ *   await executeApi(api, request);
+ * }
+ * ```
+ */
+export function isStreamingApi(api) {
+    return (typeof api === "object" &&
+        api !== null &&
+        "isStreaming" in api &&
+        api.isStreaming === true &&
+        "inputSchema" in api &&
+        "chunkSchema" in api &&
+        "run" in api &&
+        typeof api.run === "function");
+}
+//# sourceMappingURL=streaming.js.map

package/dist/api/streaming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.js","sourceRoot":"","sources":["../../src/api/streaming.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EACL,8BAA8B,GAE/B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AA4KpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAM,UAAU,YAAY,CAQ1B,MAAyD;IAEzD,oDAAoD;IACpD,MAAM,YAAY,GAAG,8BAA8B,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAEzE,MAAM,QAAQ,GAA2D;QACvE,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,UAAU,EAAE,iBAAiB,EAAE;QAC/B,WAAW,EAAE,MAAM,CAAC,KAAK;QACzB,WAAW,EAAE,MAAM,CAAC,KAAK;QACzB,GAAG,EAAE,MAAM,CAAC,GAGuB;QACnC,YAAY;QACZ,WAAW,EAAE,IAAI;KAClB,CAAC;IAEF,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAY;IAEZ,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,aAAa,IAAI,GAAG;QACnB,GAA+B,CAAC,WAAW,KAAK,IAAI;QACrD,aAAa,IAAI,GAAG;QACpB,aAAa,IAAI,GAAG;QACpB,KAAK,IAAI,GAAG;QACZ,OAAQ,GAA+B,CAAC,GAAG,KAAK,UAAU,CAC3D,CAAC;AACJ,CAAC"}

package/dist/api/streaming.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for streaming API definition.
+ */
+export {};
+//# sourceMappingURL=streaming.test.d.ts.map

package/dist/api/streaming.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.test.d.ts","sourceRoot":"","sources":["../../src/api/streaming.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}