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

package/src/api/streaming.test.ts

@@ -2,66 +2,66 @@
  * 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', () => {
+import { describe, it, expect, vi } from "vitest";
+import { z } from "zod";
+import { streamingApi, isStreamingApi } from "./streaming.js";
+import { api, __setEntryPoint } 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',
+        name: "TestStreamingApi",
         input: inputSchema,
         chunk: chunkSchema,
         async *run() {
-          yield { text: 'Hello' };
-          yield { text: ' World' };
+          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');
+      expect(typeof streamingApiDef.run).toBe("function");
     });
 
-    it('creates a streaming API with integrations', () => {
+    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',
+        name: "TestStreamingApi",
         integrations: {
-          ai: anthropic('Production Anthropic'),
+          ai: anthropic("Production Anthropic"),
         },
         input: inputSchema,
         chunk: chunkSchema,
         async *run() {
-          yield { text: 'test' };
+          yield { text: "test" };
         },
       });
 
       expect(streamingApiDef.integrations).toHaveLength(1);
       expect(streamingApiDef.integrations[0]).toMatchObject({
-        key: 'ai',
-        pluginId: 'anthropic',
-        id: 'Production Anthropic',
+        key: "ai",
+        pluginId: "anthropic",
+        id: "Production Anthropic",
       });
     });
 
-    it('has empty integrations array when none declared', () => {
+    it("has empty integrations array when none declared", () => {
       const streamingApiDef = streamingApi({
-        name: 'TestStreamingApi',
+        name: "TestStreamingApi",
         input: z.object({ prompt: z.string() }),
         chunk: z.object({ text: z.string() }),
         async *run() {
-          yield { text: 'test' };
+          yield { text: "test" };
         },
       });
 
@@ -69,15 +69,15 @@ describe('streamingApi()', () => {
     });
   });
 
-  describe('async generator execution', () => {
-    it('run function returns an async iterable', async () => {
+  describe("async generator execution", () => {
+    it("run function returns an async iterable", async () => {
       const streamingApiDef = streamingApi({
-        name: 'TestStreamingApi',
+        name: "TestStreamingApi",
         input: z.object({ prompt: z.string() }),
         chunk: z.object({ text: z.string() }),
         async *run() {
-          yield { text: 'Hello' };
-          yield { text: ' World' };
+          yield { text: "Hello" };
+          yield { text: " World" };
         },
       });
 
@@ -94,7 +94,7 @@ describe('streamingApi()', () => {
 
       const iterator = streamingApiDef.run(
         mockContext as unknown as ApiContext<Record<string, never>>,
-        { prompt: 'test' },
+        { prompt: "test" },
       );
 
       expect(Symbol.asyncIterator in iterator).toBe(true);
@@ -104,14 +104,14 @@ describe('streamingApi()', () => {
         chunks.push(chunk);
       }
 
-      expect(chunks).toEqual([{ text: 'Hello' }, { text: ' World' }]);
+      expect(chunks).toEqual([{ text: "Hello" }, { text: " World" }]);
     });
 
-    it('can access input in the run function', async () => {
+    it("can access input in the run function", async () => {
       const inputCapture: string[] = [];
 
       const streamingApiDef = streamingApi({
-        name: 'TestStreamingApi',
+        name: "TestStreamingApi",
         input: z.object({ prompt: z.string() }),
         chunk: z.object({ text: z.string() }),
         async *run(ctx, { prompt }) {
@@ -133,20 +133,20 @@ describe('streamingApi()', () => {
 
       const iterator = streamingApiDef.run(
         mockContext as unknown as ApiContext<Record<string, never>>,
-        { prompt: 'Hello, AI!' },
+        { 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!' }]);
+      expect(inputCapture).toEqual(["Hello, AI!"]);
+      expect(chunks).toEqual([{ text: "Hello, AI!" }]);
     });
 
-    it('yields multiple chunks over time', async () => {
+    it("yields multiple chunks over time", async () => {
       const streamingApiDef = streamingApi({
-        name: 'TestStreamingApi',
+        name: "TestStreamingApi",
         input: z.object({ count: z.number() }),
         chunk: z.object({ index: z.number(), text: z.string() }),
         async *run(ctx, { count }) {
@@ -177,45 +177,45 @@ describe('streamingApi()', () => {
       }
 
       expect(chunks).toHaveLength(5);
-      expect(chunks[0]).toEqual({ index: 0, text: 'Chunk 0' });
-      expect(chunks[4]).toEqual({ index: 4, text: 'Chunk 4' });
+      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', () => {
+  describe("readonly properties", () => {
+    it("inputSchema is readonly", () => {
       const streamingApiDef = streamingApi({
-        name: 'TestStreamingApi',
+        name: "TestStreamingApi",
         input: z.object({ prompt: z.string() }),
         chunk: z.object({ text: z.string() }),
         async *run() {
-          yield { text: 'test' };
+          yield { text: "test" };
         },
       });
 
       expect(streamingApiDef.inputSchema).toBeDefined();
     });
 
-    it('chunkSchema is readonly', () => {
+    it("chunkSchema is readonly", () => {
       const streamingApiDef = streamingApi({
-        name: 'TestStreamingApi',
+        name: "TestStreamingApi",
         input: z.object({ prompt: z.string() }),
         chunk: z.object({ text: z.string() }),
         async *run() {
-          yield { text: 'test' };
+          yield { text: "test" };
         },
       });
 
       expect(streamingApiDef.chunkSchema).toBeDefined();
     });
 
-    it('isStreaming is always true', () => {
+    it("isStreaming is always true", () => {
       const streamingApiDef = streamingApi({
-        name: 'TestStreamingApi',
+        name: "TestStreamingApi",
         input: z.object({ prompt: z.string() }),
         chunk: z.object({ text: z.string() }),
         async *run() {
-          yield { text: 'test' };
+          yield { text: "test" };
         },
       });
 
@@ -224,15 +224,15 @@ describe('streamingApi()', () => {
   });
 });
 
-describe('isStreamingApi()', () => {
-  describe('with streaming APIs', () => {
-    it('returns true for streaming API', () => {
+describe("isStreamingApi()", () => {
+  describe("with streaming APIs", () => {
+    it("returns true for streaming API", () => {
       const streamingApiDef = streamingApi({
-        name: 'TestStreamingApi',
+        name: "TestStreamingApi",
         input: z.object({ prompt: z.string() }),
         chunk: z.object({ text: z.string() }),
         async *run() {
-          yield { text: 'test' };
+          yield { text: "test" };
         },
       });
 
@@ -240,14 +240,14 @@ describe('isStreamingApi()', () => {
     });
   });
 
-  describe('with regular APIs', () => {
-    it('returns false for regular API', () => {
+  describe("with regular APIs", () => {
+    it("returns false for regular API", () => {
       const regularApi = api({
-        name: 'RegularApi',
+        name: "RegularApi",
         input: z.object({ userId: z.string() }),
         output: z.object({ name: z.string() }),
         async run() {
-          return { name: 'Test' };
+          return { name: "Test" };
         },
       });
 
@@ -255,50 +255,52 @@ describe('isStreamingApi()', () => {
     });
   });
 
-  describe('with non-API values', () => {
-    it('returns false for null', () => {
+  describe("with non-API values", () => {
+    it("returns false for null", () => {
       expect(isStreamingApi(null)).toBe(false);
     });
 
-    it('returns false for undefined', () => {
+    it("returns false for undefined", () => {
       expect(isStreamingApi(undefined)).toBe(false);
     });
 
-    it('returns false for plain object', () => {
+    it("returns false for plain object", () => {
       expect(isStreamingApi({ isStreaming: false })).toBe(false);
     });
 
-    it('returns false for number', () => {
+    it("returns false for number", () => {
       expect(isStreamingApi(42)).toBe(false);
     });
 
-    it('returns false for string', () => {
-      expect(isStreamingApi('streaming')).toBe(false);
+    it("returns false for string", () => {
+      expect(isStreamingApi("streaming")).toBe(false);
     });
 
-    it('returns false for object without isStreaming property', () => {
+    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', () => {
+    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);
+    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', () => {
+describe("type inference", () => {
+  it("infers input type from schema", () => {
     const streamingApiDef = streamingApi({
-      name: 'TestStreamingApi',
+      name: "TestStreamingApi",
       input: z.object({
         prompt: z.string(),
         maxTokens: z.number().optional(),
@@ -314,19 +316,19 @@ describe('type inference', () => {
     expect(streamingApiDef).toBeDefined();
   });
 
-  it('infers chunk type from schema', () => {
+  it("infers chunk type from schema", () => {
     const streamingApiDef = streamingApi({
-      name: 'TestStreamingApi',
+      name: "TestStreamingApi",
       input: z.object({ prompt: z.string() }),
       chunk: z.object({
-        type: z.literal('text-delta'),
+        type: z.literal("text-delta"),
         text: z.string(),
         index: z.number(),
       }),
       async *run() {
         yield {
-          type: 'text-delta' as const,
-          text: 'Hello',
+          type: "text-delta" as const,
+          text: "Hello",
           index: 0,
         };
       },
@@ -335,20 +337,96 @@ describe('type inference', () => {
     expect(streamingApiDef.chunkSchema).toBeDefined();
   });
 
-  it('infers integration types', () => {
+  it("infers integration types", () => {
     const streamingApiDef = streamingApi({
-      name: 'TestStreamingApi',
+      name: "TestStreamingApi",
       integrations: {
-        ai: anthropic('AI Service'),
-        db: postgres('Database'),
+        ai: anthropic("AI Service"),
+        db: postgres("Database"),
       },
       input: z.object({ prompt: z.string() }),
       chunk: z.object({ text: z.string() }),
       async *run() {
-        yield { text: 'test' };
+        yield { text: "test" };
       },
     });
 
     expect(streamingApiDef.integrations).toHaveLength(2);
   });
 });
+
+describe("entryPoint mechanism", () => {
+  it("streamingApi() has no entryPoint when __setEntryPoint was not called", () => {
+    const compiled = streamingApi({
+      name: "NoEntryPoint",
+      input: z.object({}),
+      chunk: z.object({ text: z.string() }),
+      async *run() {
+        yield { text: "hello" };
+      },
+    });
+
+    expect(compiled.entryPoint).toBeUndefined();
+  });
+
+  it("streamingApi() picks up entryPoint set via __setEntryPoint", () => {
+    __setEntryPoint("server/apis/Chat/api.ts");
+    const compiled = streamingApi({
+      name: "Chat",
+      input: z.object({ prompt: z.string() }),
+      chunk: z.object({ text: z.string() }),
+      async *run() {
+        yield { text: "hello" };
+      },
+    });
+
+    expect(compiled.entryPoint).toBe("server/apis/Chat/api.ts");
+  });
+
+  it("entryPoint is consumed once — second streamingApi() call gets undefined", () => {
+    __setEntryPoint("server/apis/Stream/api.ts");
+    const first = streamingApi({
+      name: "Stream",
+      input: z.object({}),
+      chunk: z.object({ text: z.string() }),
+      async *run() {
+        yield { text: "a" };
+      },
+    });
+    const second = streamingApi({
+      name: "Stream2",
+      input: z.object({}),
+      chunk: z.object({ text: z.string() }),
+      async *run() {
+        yield { text: "b" };
+      },
+    });
+
+    expect(first.entryPoint).toBe("server/apis/Stream/api.ts");
+    expect(second.entryPoint).toBeUndefined();
+  });
+
+  it("__setEntryPoint works across api() and streamingApi()", () => {
+    __setEntryPoint("server/apis/Mixed/api.ts");
+    const compiled = streamingApi({
+      name: "Mixed",
+      input: z.object({}),
+      chunk: z.object({ text: z.string() }),
+      async *run() {
+        yield { text: "mixed" };
+      },
+    });
+
+    expect(compiled.entryPoint).toBe("server/apis/Mixed/api.ts");
+
+    const afterConsume = api({
+      name: "After",
+      input: z.object({}),
+      output: z.object({}),
+      async run() {
+        return {};
+      },
+    });
+    expect(afterConsume.entryPoint).toBeUndefined();
+  });
+});

package/src/api/streaming.ts

@@ -5,12 +5,13 @@
  * 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 { z } from "zod";
+import type { ApiContext, AnyIntegrationRef } from "../types.js";
 import {
   extractIntegrationDeclarations,
   type IntegrationDeclaration,
-} from '../integrations/declarations.js';
+} from "../integrations/declarations.js";
+import { consumeEntryPoint } from "./definition.js";
 
 /**
  * Configuration for defining a streaming TypeScript-based API.
@@ -64,7 +65,10 @@ import {
 export interface StreamingApiConfig<
   TInput extends z.ZodType,
   TChunk extends z.ZodType,
-  TIntegrations extends Record<string, AnyIntegrationRef> = Record<string, never>,
+  TIntegrations extends Record<string, AnyIntegrationRef> = Record<
+    string,
+    never
+  >,
 > {
   /**
    * Name for this API.
@@ -73,6 +77,14 @@ export interface StreamingApiConfig<
    */
   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.
    *
@@ -107,7 +119,10 @@ export interface StreamingApiConfig<
    * @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>>;
+  run: (
+    ctx: ApiContext<TIntegrations>,
+    input: z.infer<TInput>,
+  ) => AsyncIterable<z.infer<TChunk>>;
 }
 
 /**
@@ -120,6 +135,14 @@ 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>;
 
@@ -219,7 +242,10 @@ export interface CompiledStreamingApi<TInput = unknown, TChunk = unknown> {
 export function streamingApi<
   TInput extends z.ZodType,
   TChunk extends z.ZodType,
-  TIntegrations extends Record<string, AnyIntegrationRef> = Record<string, never>,
+  TIntegrations extends Record<string, AnyIntegrationRef> = Record<
+    string,
+    never
+  >,
 >(
   config: StreamingApiConfig<TInput, TChunk, TIntegrations>,
 ): CompiledStreamingApi<z.infer<TInput>, z.infer<TChunk>> {
@@ -228,6 +254,8 @@ export function streamingApi<
 
   const compiled: CompiledStreamingApi<z.infer<TInput>, z.infer<TChunk>> = {
     name: config.name,
+    description: config.description,
+    entryPoint: consumeEntryPoint(),
     inputSchema: config.input,
     chunkSchema: config.chunk,
     run: config.run as (
@@ -259,16 +287,16 @@ export function streamingApi<
  * ```
  */
 export function isStreamingApi(
-  api: unknown
+  api: unknown,
 ): api is CompiledStreamingApi<unknown, unknown> {
   return (
-    typeof api === 'object' &&
+    typeof api === "object" &&
     api !== null &&
-    'isStreaming' in api &&
+    "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'
+    "inputSchema" in api &&
+    "chunkSchema" in api &&
+    "run" in api &&
+    typeof (api as Record<string, unknown>).run === "function"
   );
 }

package/src/errors.ts

@@ -2,7 +2,7 @@
  * Error classes for SDK runtime errors.
  */
 
-import type { z } from 'zod';
+import type { z } from "zod";
 
 /**
  * Error thrown when REST API response or request body validation fails.
@@ -21,7 +21,7 @@ export class RestApiValidationError extends Error {
     },
   ) {
     super(message);
-    this.name = 'RestApiValidationError';
+    this.name = "RestApiValidationError";
     // Ensure proper prototype chain for instanceof checks
     Object.setPrototypeOf(this, RestApiValidationError.prototype);
   }
@@ -46,7 +46,7 @@ export class QueryValidationError extends Error {
     },
   ) {
     super(message);
-    this.name = 'QueryValidationError';
+    this.name = "QueryValidationError";
     // Ensure proper prototype chain for instanceof checks
     Object.setPrototypeOf(this, QueryValidationError.prototype);
   }
@@ -75,7 +75,7 @@ export class CodeExecutionError extends Error {
     },
   ) {
     super(message);
-    this.name = 'CodeExecutionError';
+    this.name = "CodeExecutionError";
     // Ensure proper prototype chain for instanceof checks
     Object.setPrototypeOf(this, CodeExecutionError.prototype);
   }
@@ -100,7 +100,7 @@ export class StreamChunkValidationError extends Error {
     },
   ) {
     super(message);
-    this.name = 'StreamChunkValidationError';
+    this.name = "StreamChunkValidationError";
     // Ensure proper prototype chain for instanceof checks
     Object.setPrototypeOf(this, StreamChunkValidationError.prototype);
   }
@@ -123,7 +123,7 @@ export class StreamError extends Error {
     },
   ) {
     super(message);
-    this.name = 'StreamError';
+    this.name = "StreamError";
     // Ensure proper prototype chain for instanceof checks
     Object.setPrototypeOf(this, StreamError.prototype);
   }

package/src/index.ts

@@ -57,6 +57,7 @@ export { z } from "zod";
 // API definition and registry
 export {
   api,
+  __setEntryPoint,
   type CompiledApi,
   // Streaming API support
   streamingApi,
@@ -245,9 +246,15 @@ export type { ZoomClient } from "./integrations/zoom/index.js";
 export type { GraphQLClient } from "./integrations/graphql/index.js";
 
 // Dedicated plugin client types and parameter types
-export type { DynamoDBClient, DynamoDBAttributeValue } from "./integrations/dynamodb/index.js";
+export type {
+  DynamoDBClient,
+  DynamoDBAttributeValue,
+} from "./integrations/dynamodb/index.js";
 export type { CosmosDBClient } from "./integrations/cosmosdb/index.js";
-export type { CouchbaseClient, CouchbaseIdentifier } from "./integrations/couchbase/index.js";
+export type {
+  CouchbaseClient,
+  CouchbaseIdentifier,
+} from "./integrations/couchbase/index.js";
 export type {
   KinesisClient,
   KinesisPutParams,
@@ -255,7 +262,11 @@ export type {
   KinesisStreamIdentifier,
   KinesisShardIteratorType,
 } from "./integrations/kinesis/index.js";
-export type { SalesforceClient, SalesforceCrudAction, SalesforceBulkAction } from "./integrations/salesforce/index.js";
+export type {
+  SalesforceClient,
+  SalesforceCrudAction,
+  SalesforceBulkAction,
+} from "./integrations/salesforce/index.js";
 export type { RedisClient } from "./integrations/redis/index.js";
 export type { KafkaClient } from "./integrations/kafka/index.js";
 export type { S3Client } from "./integrations/s3/index.js";