@superblocksteam/sdk-api 2.0.89-next.0

package/src/api/streaming.test.ts

@@ -0,0 +1,354 @@
+/**
+ * Tests for streaming API definition.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { z } from 'zod';
+import { streamingApi, isStreamingApi } from './streaming.js';
+import { api } from './definition.js';
+import { postgres, anthropic } from '../integrations/declarations.js';
+import type { ApiContext } from '../types.js';
+
+describe('streamingApi()', () => {
+  describe('basic creation', () => {
+    it('creates a streaming API with input and chunk schemas', () => {
+      const inputSchema = z.object({ prompt: z.string() });
+      const chunkSchema = z.object({ text: z.string() });
+
+      const streamingApiDef = streamingApi({
+        name: 'TestStreamingApi',
+        input: inputSchema,
+        chunk: chunkSchema,
+        async *run() {
+          yield { text: 'Hello' };
+          yield { text: ' World' };
+        },
+      });
+
+      expect(streamingApiDef.inputSchema).toBe(inputSchema);
+      expect(streamingApiDef.chunkSchema).toBe(chunkSchema);
+      expect(streamingApiDef.isStreaming).toBe(true);
+      expect(typeof streamingApiDef.run).toBe('function');
+    });
+
+    it('creates a streaming API with integrations', () => {
+      const inputSchema = z.object({ prompt: z.string() });
+      const chunkSchema = z.object({ text: z.string() });
+
+      const streamingApiDef = streamingApi({
+        name: 'TestStreamingApi',
+        integrations: {
+          ai: anthropic('Production Anthropic'),
+        },
+        input: inputSchema,
+        chunk: chunkSchema,
+        async *run() {
+          yield { text: 'test' };
+        },
+      });
+
+      expect(streamingApiDef.integrations).toHaveLength(1);
+      expect(streamingApiDef.integrations[0]).toMatchObject({
+        key: 'ai',
+        pluginId: 'anthropic',
+        id: 'Production Anthropic',
+      });
+    });
+
+    it('has empty integrations array when none declared', () => {
+      const streamingApiDef = streamingApi({
+        name: 'TestStreamingApi',
+        input: z.object({ prompt: z.string() }),
+        chunk: z.object({ text: z.string() }),
+        async *run() {
+          yield { text: 'test' };
+        },
+      });
+
+      expect(streamingApiDef.integrations).toEqual([]);
+    });
+  });
+
+  describe('async generator execution', () => {
+    it('run function returns an async iterable', async () => {
+      const streamingApiDef = streamingApi({
+        name: 'TestStreamingApi',
+        input: z.object({ prompt: z.string() }),
+        chunk: z.object({ text: z.string() }),
+        async *run() {
+          yield { text: 'Hello' };
+          yield { text: ' World' };
+        },
+      });
+
+      const mockContext = {
+        integrations: {} as Record<string, unknown>,
+        log: {
+          info: vi.fn(),
+          warn: vi.fn(),
+          error: vi.fn(),
+          debug: vi.fn(),
+        },
+        env: {},
+      };
+
+      const iterator = streamingApiDef.run(
+        mockContext as unknown as ApiContext<Record<string, never>>,
+        { prompt: 'test' },
+      );
+
+      expect(Symbol.asyncIterator in iterator).toBe(true);
+
+      const chunks: { text: string }[] = [];
+      for await (const chunk of iterator) {
+        chunks.push(chunk);
+      }
+
+      expect(chunks).toEqual([{ text: 'Hello' }, { text: ' World' }]);
+    });
+
+    it('can access input in the run function', async () => {
+      const inputCapture: string[] = [];
+
+      const streamingApiDef = streamingApi({
+        name: 'TestStreamingApi',
+        input: z.object({ prompt: z.string() }),
+        chunk: z.object({ text: z.string() }),
+        async *run(ctx, { prompt }) {
+          inputCapture.push(prompt);
+          yield { text: prompt };
+        },
+      });
+
+      const mockContext = {
+        integrations: {} as Record<string, unknown>,
+        log: {
+          info: vi.fn(),
+          warn: vi.fn(),
+          error: vi.fn(),
+          debug: vi.fn(),
+        },
+        env: {},
+      };
+
+      const iterator = streamingApiDef.run(
+        mockContext as unknown as ApiContext<Record<string, never>>,
+        { prompt: 'Hello, AI!' },
+      );
+      const chunks: { text: string }[] = [];
+      for await (const chunk of iterator) {
+        chunks.push(chunk);
+      }
+
+      expect(inputCapture).toEqual(['Hello, AI!']);
+      expect(chunks).toEqual([{ text: 'Hello, AI!' }]);
+    });
+
+    it('yields multiple chunks over time', async () => {
+      const streamingApiDef = streamingApi({
+        name: 'TestStreamingApi',
+        input: z.object({ count: z.number() }),
+        chunk: z.object({ index: z.number(), text: z.string() }),
+        async *run(ctx, { count }) {
+          for (let i = 0; i < count; i++) {
+            yield { index: i, text: `Chunk ${i}` };
+          }
+        },
+      });
+
+      const mockContext = {
+        integrations: {} as Record<string, unknown>,
+        log: {
+          info: vi.fn(),
+          warn: vi.fn(),
+          error: vi.fn(),
+          debug: vi.fn(),
+        },
+        env: {},
+      };
+
+      const iterator = streamingApiDef.run(
+        mockContext as unknown as ApiContext<Record<string, never>>,
+        { count: 5 },
+      );
+      const chunks: { index: number; text: string }[] = [];
+      for await (const chunk of iterator) {
+        chunks.push(chunk);
+      }
+
+      expect(chunks).toHaveLength(5);
+      expect(chunks[0]).toEqual({ index: 0, text: 'Chunk 0' });
+      expect(chunks[4]).toEqual({ index: 4, text: 'Chunk 4' });
+    });
+  });
+
+  describe('readonly properties', () => {
+    it('inputSchema is readonly', () => {
+      const streamingApiDef = streamingApi({
+        name: 'TestStreamingApi',
+        input: z.object({ prompt: z.string() }),
+        chunk: z.object({ text: z.string() }),
+        async *run() {
+          yield { text: 'test' };
+        },
+      });
+
+      expect(streamingApiDef.inputSchema).toBeDefined();
+    });
+
+    it('chunkSchema is readonly', () => {
+      const streamingApiDef = streamingApi({
+        name: 'TestStreamingApi',
+        input: z.object({ prompt: z.string() }),
+        chunk: z.object({ text: z.string() }),
+        async *run() {
+          yield { text: 'test' };
+        },
+      });
+
+      expect(streamingApiDef.chunkSchema).toBeDefined();
+    });
+
+    it('isStreaming is always true', () => {
+      const streamingApiDef = streamingApi({
+        name: 'TestStreamingApi',
+        input: z.object({ prompt: z.string() }),
+        chunk: z.object({ text: z.string() }),
+        async *run() {
+          yield { text: 'test' };
+        },
+      });
+
+      expect(streamingApiDef.isStreaming).toBe(true);
+    });
+  });
+});
+
+describe('isStreamingApi()', () => {
+  describe('with streaming APIs', () => {
+    it('returns true for streaming API', () => {
+      const streamingApiDef = streamingApi({
+        name: 'TestStreamingApi',
+        input: z.object({ prompt: z.string() }),
+        chunk: z.object({ text: z.string() }),
+        async *run() {
+          yield { text: 'test' };
+        },
+      });
+
+      expect(isStreamingApi(streamingApiDef)).toBe(true);
+    });
+  });
+
+  describe('with regular APIs', () => {
+    it('returns false for regular API', () => {
+      const regularApi = api({
+        name: 'RegularApi',
+        input: z.object({ userId: z.string() }),
+        output: z.object({ name: z.string() }),
+        async run() {
+          return { name: 'Test' };
+        },
+      });
+
+      expect(isStreamingApi(regularApi)).toBe(false);
+    });
+  });
+
+  describe('with non-API values', () => {
+    it('returns false for null', () => {
+      expect(isStreamingApi(null)).toBe(false);
+    });
+
+    it('returns false for undefined', () => {
+      expect(isStreamingApi(undefined)).toBe(false);
+    });
+
+    it('returns false for plain object', () => {
+      expect(isStreamingApi({ isStreaming: false })).toBe(false);
+    });
+
+    it('returns false for number', () => {
+      expect(isStreamingApi(42)).toBe(false);
+    });
+
+    it('returns false for string', () => {
+      expect(isStreamingApi('streaming')).toBe(false);
+    });
+
+    it('returns false for object without isStreaming property', () => {
+      expect(isStreamingApi({ inputSchema: z.string() })).toBe(false);
+    });
+
+    it('returns false for object with only isStreaming true but missing required fields', () => {
+      expect(isStreamingApi({ isStreaming: true })).toBe(false);
+    });
+
+    it('returns true for object with isStreaming true and all required fields', () => {
+      expect(isStreamingApi({
+        isStreaming: true,
+        inputSchema: z.string(),
+        chunkSchema: z.string(),
+        run: () => {},
+      })).toBe(true);
+    });
+  });
+});
+
+describe('type inference', () => {
+  it('infers input type from schema', () => {
+    const streamingApiDef = streamingApi({
+      name: 'TestStreamingApi',
+      input: z.object({
+        prompt: z.string(),
+        maxTokens: z.number().optional(),
+      }),
+      chunk: z.object({ text: z.string() }),
+      async *run(ctx, { prompt, maxTokens }) {
+        const p: string = prompt;
+        const m: number | undefined = maxTokens;
+        yield { text: `${p} ${m ?? 100}` };
+      },
+    });
+
+    expect(streamingApiDef).toBeDefined();
+  });
+
+  it('infers chunk type from schema', () => {
+    const streamingApiDef = streamingApi({
+      name: 'TestStreamingApi',
+      input: z.object({ prompt: z.string() }),
+      chunk: z.object({
+        type: z.literal('text-delta'),
+        text: z.string(),
+        index: z.number(),
+      }),
+      async *run() {
+        yield {
+          type: 'text-delta' as const,
+          text: 'Hello',
+          index: 0,
+        };
+      },
+    });
+
+    expect(streamingApiDef.chunkSchema).toBeDefined();
+  });
+
+  it('infers integration types', () => {
+    const streamingApiDef = streamingApi({
+      name: 'TestStreamingApi',
+      integrations: {
+        ai: anthropic('AI Service'),
+        db: postgres('Database'),
+      },
+      input: z.object({ prompt: z.string() }),
+      chunk: z.object({ text: z.string() }),
+      async *run() {
+        yield { text: 'test' };
+      },
+    });
+
+    expect(streamingApiDef.integrations).toHaveLength(2);
+  });
+});

package/src/api/streaming.ts

@@ -0,0 +1,274 @@
+/**
+ * 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 {
+  extractIntegrationDeclarations,
+  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;
+
+  /**
+   * 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;
+
+  /** 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 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>> {
+  // Extract integration declarations for upfront auth
+  const integrations = extractIntegrationDeclarations(config.integrations);
+
+  const compiled: CompiledStreamingApi<z.infer<TInput>, z.infer<TChunk>> = {
+    name: config.name,
+    inputSchema: config.input,
+    chunkSchema: config.chunk,
+    run: config.run as (
+      ctx: ApiContext<Record<string, AnyIntegrationRef>>,
+      input: z.infer<TInput>,
+    ) => AsyncIterable<z.infer<TChunk>>,
+    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: unknown
+): api is CompiledStreamingApi<unknown, unknown> {
+  return (
+    typeof api === 'object' &&
+    api !== null &&
+    'isStreaming' in api &&
+    (api as Record<string, unknown>).isStreaming === true &&
+    'inputSchema' in api &&
+    'chunkSchema' in api &&
+    'run' in api &&
+    typeof (api as Record<string, unknown>).run === 'function'
+  );
+}