@superblocksteam/sdk-api 2.0.103 → 2.0.104-next.0

package/dist/api/streaming.d.ts

@@ -1,229 +0,0 @@
-/**
- * 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 IntegrationDeclaration } from "../integrations/declarations.js";
-import type { ApiContext, AnyIntegrationRef } from "../types.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

@@ -1 +0,0 @@
-{"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;AAE7B,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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

@@ -1,107 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"version":3,"file":"streaming.js","sourceRoot":"","sources":["../../src/api/streaming.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EACL,8BAA8B,GAE/B,MAAM,iCAAiC,CAAC;AAEzC,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

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

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

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