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

package/README.md

@@ -26,6 +26,7 @@ An **API** in this SDK is a self-contained, typed function definition that:
 4. **Is portable** - Can be executed by any compatible runtime (local, server, orchestrator)
 
 An API is **not** just a function - it's a complete definition that includes metadata, schemas, and dependencies, enabling the runtime to:
+
 - Validate inputs before execution
 - Pre-authenticate integrations
 - Validate outputs after execution
@@ -59,22 +60,24 @@ interface CompiledApi<TInput, TOutput> {
 You can inspect a `CompiledApi` to understand what it is:
 
 ```typescript
-import { api, z, postgres } from '@superblocksteam/sdk-api';
+import { api, z, postgres } from "@superblocksteam/sdk-api";
 
 const myApi = api({
-  name: 'GetUsers',
-  integrations: { db: postgres('prod-postgres-id') },
+  name: "GetUsers",
+  integrations: { db: postgres("prod-postgres-id") },
   input: z.object({ limit: z.number() }),
   output: z.object({ users: z.array(z.object({ id: z.string() })) }),
-  async run(ctx, { limit }) { /* ... */ },
+  async run(ctx, { limit }) {
+    /* ... */
+  },
 });
 
 // Inspect the compiled API
-console.log(myApi.name);          // 'GetUsers'
-console.log(myApi.integrations);  // [{ key: 'db', pluginId: 'postgres', integrationId: 'prod-postgres-id' }]
+console.log(myApi.name); // 'GetUsers'
+console.log(myApi.integrations); // [{ key: 'db', pluginId: 'postgres', integrationId: 'prod-postgres-id' }]
 
 // Schemas can be used for validation or type extraction
-type Input = z.infer<typeof myApi.inputSchema>;   // { limit: number }
+type Input = z.infer<typeof myApi.inputSchema>; // { limit: number }
 type Output = z.infer<typeof myApi.outputSchema>; // { users: { id: string }[] }
 ```
 
@@ -133,21 +136,24 @@ When an integration client (like `ctx.integrations.db`) makes a request, it call
 ```typescript
 // Inside PostgresClient.query():
 const result = await executeQuery(
-  'prod-postgres-id',           // Integration ID
-  {                             // Plugin-specific request (matches protobuf schema)
-    body: 'SELECT * FROM users WHERE id = $1',
+  "prod-postgres-id", // Integration ID
+  {
+    // Plugin-specific request (matches protobuf schema)
+    body: "SELECT * FROM users WHERE id = $1",
   },
-  { userId: '123' }             // Optional bindings for language plugins
+  { userId: "123" }, // Optional bindings for language plugins
 );
 ```
 
 The runtime (orchestrator) receives this callback and:
+
 1. Looks up the integration configuration
 2. Authenticates with the external service
 3. Executes the actual operation (SQL query, API call, etc.)
 4. Returns the result to the SDK
 
 This architecture means:
+
 - **SDK is environment-agnostic** - Same code runs locally, in tests, or in production
 - **Authentication is centralized** - The runtime handles all credentials
 - **Operations are auditable** - The runtime can log/trace all operations
@@ -197,8 +203,8 @@ interface UnifiedExecuteApiRequest {
    */
   executeQuery: (
     integrationId: string,
-    request: Record<string, unknown>,  // Plugin-specific request matching protobuf schema
-    bindings?: Record<string, unknown> // For language plugins (Python/JavaScript)
+    request: Record<string, unknown>, // Plugin-specific request matching protobuf schema
+    bindings?: Record<string, unknown>, // For language plugins (Python/JavaScript)
   ) => Promise<unknown>;
 
   /**
@@ -207,7 +213,7 @@ interface UnifiedExecuteApiRequest {
    */
   executeStreamingQuery?: (
     integrationId: string,
-    request: Record<string, unknown>
+    request: Record<string, unknown>,
   ) => AsyncIterable<unknown>;
 }
 ```
@@ -219,7 +225,10 @@ Regular APIs return a discriminated union:
 ```typescript
 type ExecuteApiResponse<TOutput> =
   | { success: true; output: TOutput }
-  | { success: false; error: { code: string; message: string; details?: unknown } };
+  | {
+      success: false;
+      error: { code: string; message: string; details?: unknown };
+    };
 ```
 
 Streaming APIs return an `AsyncGenerator`:
@@ -318,13 +327,13 @@ For streaming responses (e.g., LLM token streaming), see [`streamingApi()`](#str
 
 #### Required Fields
 
-| Field    | Type                              | Description                                        |
-| -------- | --------------------------------- | -------------------------------------------------- |
-| `name`   | `string`                          | **Required.** Unique identifier for the API        |
-| `input`  | `z.ZodType`                       | **Required.** Zod schema for input validation      |
-| `output` | `z.ZodType`                       | **Required.** Zod schema for output validation     |
-| `run`    | `(ctx, input) => Promise<Output>` | **Required.** The implementation function          |
-| `integrations` | `Record<string, IntegrationRef>` | Optional. Integration declarations for the API |
+| Field          | Type                              | Description                                    |
+| -------------- | --------------------------------- | ---------------------------------------------- |
+| `name`         | `string`                          | **Required.** Unique identifier for the API    |
+| `input`        | `z.ZodType`                       | **Required.** Zod schema for input validation  |
+| `output`       | `z.ZodType`                       | **Required.** Zod schema for output validation |
+| `run`          | `(ctx, input) => Promise<Output>` | **Required.** The implementation function      |
+| `integrations` | `Record<string, IntegrationRef>`  | Optional. Integration declarations for the API |
 
 ```typescript
 import { api, z } from "@superblocksteam/sdk-api";
@@ -399,12 +408,15 @@ export default streamingApi({
           messages: [{ role: "user", content: prompt }],
         },
       },
-      { chunk: AnthropicStreamEventSchema }
+      { chunk: AnthropicStreamEventSchema },
     );
 
     // Process and yield each chunk
     for await (const event of stream) {
-      if (event.type === "content_block_delta" && event.delta?.type === "text_delta") {
+      if (
+        event.type === "content_block_delta" &&
+        event.delta?.type === "text_delta"
+      ) {
         yield { type: "text" as const, text: event.delta.text };
       }
     }
@@ -414,11 +426,11 @@ export default streamingApi({
 
 #### Streaming API Configuration
 
-| Property       | Type                                   | Description                                    |
-| -------------- | -------------------------------------- | ---------------------------------------------- |
-| `integrations` | `Record<string, IntegrationRef>`       | Integration declarations (same as `api()`)     |
-| `input`        | `z.ZodType`                            | Zod schema for input validation                |
-| `chunk`        | `z.ZodType`                            | Zod schema for each yielded chunk              |
+| Property       | Type                                       | Description                                     |
+| -------------- | ------------------------------------------ | ----------------------------------------------- |
+| `integrations` | `Record<string, IntegrationRef>`           | Integration declarations (same as `api()`)      |
+| `input`        | `z.ZodType`                                | Zod schema for input validation                 |
+| `chunk`        | `z.ZodType`                                | Zod schema for each yielded chunk               |
 | `run`          | `(ctx, input) => AsyncIterable<ChunkType>` | Generator function that yields validated chunks |
 
 #### Key Differences from `api()`
@@ -431,6 +443,7 @@ export default streamingApi({
 ### Context (`ctx`) and Input
 
 The `run` function receives two arguments:
+
 1. **`ctx`** - Context object with integrations, logging, and environment
 2. **`input`** - Typed, validated input data matching your input schema
 
@@ -443,7 +456,7 @@ async run(ctx, { userId, options }) {
 
 #### `ctx.integrations`
 
-Access typed integration clients via the `integrations` object. Integrations must be declared upfront in the API config to enable type-safe access and pre-authentication.
+Access typed integration clients via the **name (key)** you declared in the API config: `ctx.integrations.<name>`. For example, if you declared `integrations: { db: postgres(...), notifier: slack(...) }`, use `ctx.integrations.db` and `ctx.integrations.notifier` in your `run` function. Integrations must be declared upfront to enable type-safe access and pre-authentication.
 
 ```typescript
 import { api, z, postgres, slack, openai, anthropic, stripe, github, notion, python } from "@superblocksteam/sdk-api";
@@ -521,47 +534,47 @@ async run(ctx, { userId }) {
 
 #### Method Availability by Client
 
-| Client                    | Available Methods                                                              | Notes                                                   |
-| ------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------- |
-| **PostgresClient**        | `query<T>(sql, schema, params?)`, `execute(sql, params?)`                      | Schema parameter is REQUIRED for query()                |
-| **SnowflakeClient**       | `query<T>(sql, schema, params?)`, `execute(sql, params?)`                      | Schema parameter is REQUIRED for query()                |
-| **PythonClient**          | `run<T>(code, schema, bindings?)`                                              | Schema parameter is REQUIRED, bindings via {{}} syntax  |
-| **AirtableClient**        | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **AnthropicClient**       | `apiRequest(options, schema)`, `streamApiRequest(options, schema)`             | Supports streaming for real-time token output           |
-| **AsanaClient**           | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **BitbucketClient**       | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **BoxClient**             | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **CircleCIClient**        | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **CohereClient**          | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **ConfluenceClient**      | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **DatadogClient**         | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **DropboxClient**         | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **ElasticSearchClient**   | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **FireworksClient**       | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **FrontClient**           | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **GeminiClient**          | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **GitHubClient**          | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest - no createIssue, etc.          |
-| **GoogleAnalyticsClient** | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **GoogleDriveClient**     | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **GraphQLClient**         | `query(query, variables?, schema?)`, `mutation(mutation, variables?, schema?)` | GraphQL-specific methods                                |
-| **GroqClient**            | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **HubSpotClient**         | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **IntercomClient**        | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **JiraClient**            | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **LaunchDarklyClient**    | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **MistralClient**         | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **NotionClient**          | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest - no queryDatabase, etc.        |
-| **OpenAIClient**          | `apiRequest(options, schema)`, `streamApiRequest(options, schema)`             | Supports streaming for real-time token output           |
-| **PagerDutyClient**       | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **PerplexityClient**      | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **SegmentClient**         | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **SendGridClient**        | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **SlackClient**           | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest - no specialized methods        |
-| **StabilityAIClient**     | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **StripeClient**          | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest - no createCustomer, etc.       |
-| **TwilioClient**          | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **ZendeskClient**         | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
-| **ZoomClient**            | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                 |
+| Client                    | Available Methods                                                              | Notes                                                  |
+| ------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------ |
+| **PostgresClient**        | `query<T>(sql, schema, params?)`, `execute(sql, params?)`                      | Schema parameter is REQUIRED for query()               |
+| **SnowflakeClient**       | `query<T>(sql, schema, params?)`, `execute(sql, params?)`                      | Schema parameter is REQUIRED for query()               |
+| **PythonClient**          | `run<T>(code, schema, bindings?)`                                              | Schema parameter is REQUIRED, bindings via {{}} syntax |
+| **AirtableClient**        | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **AnthropicClient**       | `apiRequest(options, schema)`, `streamApiRequest(options, schema)`             | Supports streaming for real-time token output          |
+| **AsanaClient**           | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **BitbucketClient**       | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **BoxClient**             | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **CircleCIClient**        | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **CohereClient**          | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **ConfluenceClient**      | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **DatadogClient**         | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **DropboxClient**         | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **ElasticSearchClient**   | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **FireworksClient**       | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **FrontClient**           | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **GeminiClient**          | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **GitHubClient**          | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest - no createIssue, etc.         |
+| **GoogleAnalyticsClient** | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **GoogleDriveClient**     | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **GraphQLClient**         | `query(query, variables?, schema?)`, `mutation(mutation, variables?, schema?)` | GraphQL-specific methods                               |
+| **GroqClient**            | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **HubSpotClient**         | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **IntercomClient**        | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **JiraClient**            | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **LaunchDarklyClient**    | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **MistralClient**         | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **NotionClient**          | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest - no queryDatabase, etc.       |
+| **OpenAIClient**          | `apiRequest(options, schema)`, `streamApiRequest(options, schema)`             | Supports streaming for real-time token output          |
+| **PagerDutyClient**       | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **PerplexityClient**      | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **SegmentClient**         | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **SendGridClient**        | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **SlackClient**           | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest - no specialized methods       |
+| **StabilityAIClient**     | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **StripeClient**          | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest - no createCustomer, etc.      |
+| **TwilioClient**          | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **ZendeskClient**         | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
+| **ZoomClient**            | `apiRequest(options, schema?)`                                                 | ONLY generic apiRequest                                |
 
 #### Common Mistakes to Avoid
 
@@ -593,9 +606,10 @@ await openai.apiRequest(
 
 ```typescript
 // Schema is REQUIRED for query()
-const users = await ctx.integrations.db.query("SELECT * FROM users WHERE id = $1", [
-  userId,
-]);
+const users = await ctx.integrations.db.query(
+  "SELECT * FROM users WHERE id = $1",
+  [userId],
+);
 ```
 
 **CORRECT - Include schema:**
@@ -622,13 +636,16 @@ To verify available methods and signatures:
 Each integration client has detailed documentation with examples and common pitfalls. Click on an integration below for its full README:
 
 #### SQL Databases
+
 - [PostgreSQL](./src/integrations/postgres/README.md) - Query PostgreSQL databases with schema validation
 - [Snowflake](./src/integrations/snowflake/README.md) - Query Snowflake data warehouses
 
 #### GraphQL
+
 - [GraphQL](./src/integrations/graphql/README.md) - Execute queries and mutations against GraphQL endpoints
 
 #### AI/LLM
+
 - [OpenAI](./src/integrations/openai_v2/README.md) - Chat completions, embeddings, DALL-E, and more
 - [Anthropic](./src/integrations/anthropic/README.md) - Claude models for chat and analysis
 - [Cohere](./src/integrations/cohere/README.md) - Text generation, embeddings, classification
@@ -639,6 +656,7 @@ Each integration client has detailed documentation with examples and common pitf
 - [Fireworks](./src/integrations/fireworks/README.md) - Fast model inference
 
 #### Messaging & Communication
+
 - [Slack](./src/integrations/slack/README.md) - Send messages, manage channels, Block Kit
 - [Twilio](./src/integrations/twilio/README.md) - SMS, voice calls, phone lookups
 - [SendGrid](./src/integrations/sendgrid/README.md) - Transactional and marketing emails
@@ -646,6 +664,7 @@ Each integration client has detailed documentation with examples and common pitf
 - [Front](./src/integrations/front/README.md) - Shared inbox and team communication
 
 #### Productivity & Collaboration
+
 - [Notion](./src/integrations/notion/README.md) - Databases, pages, and blocks
 - [Airtable](./src/integrations/airtable/README.md) - Spreadsheet-database hybrid
 - [Asana](./src/integrations/asana/README.md) - Project and task management
@@ -654,11 +673,13 @@ Each integration client has detailed documentation with examples and common pitf
 - [Zoom](./src/integrations/zoom/README.md) - Video meetings and webinars
 
 #### Developer Tools
+
 - [GitHub](./src/integrations/github/README.md) - Repositories, issues, pull requests
 - [Bitbucket](./src/integrations/bitbucket/README.md) - Git repositories and pipelines
 - [CircleCI](./src/integrations/circleci/README.md) - CI/CD pipelines and jobs
 
 #### Business & Enterprise
+
 - [Stripe](./src/integrations/stripe/README.md) - Payments, subscriptions, invoicing
 - [HubSpot](./src/integrations/hubspot/README.md) - CRM, contacts, deals
 - [Zendesk](./src/integrations/zendesk/README.md) - Support tickets and customer service
@@ -666,19 +687,23 @@ Each integration client has detailed documentation with examples and common pitf
 - [LaunchDarkly](./src/integrations/launchdarkly/README.md) - Feature flags and experimentation
 
 #### Analytics & Monitoring
+
 - [Google Analytics](./src/integrations/googleanalytics/README.md) - GA4 reports and real-time data
 - [Datadog](./src/integrations/datadog/README.md) - Metrics, monitors, and logs
 - [Segment](./src/integrations/segment/README.md) - Customer data platform
 
 #### Cloud Storage
+
 - [Google Drive](./src/integrations/googledrive/README.md) - Files, folders, and sharing
 - [Dropbox](./src/integrations/dropbox/README.md) - Cloud file storage
 - [Box](./src/integrations/box/README.md) - Enterprise content management
 
 #### Code Execution
+
 - [Python](./src/integrations/python/README.md) - Execute Python scripts with type-safe inputs and outputs
 
 #### Other
+
 - [Elasticsearch](./src/integrations/elasticsearch/README.md) - Search and analytics engine
 - [Stability AI](./src/integrations/stabilityai/README.md) - Image generation and editing
 
@@ -776,9 +801,17 @@ const AnthropicStreamEventSchema = z.discriminatedUnion("type", [
     }),
   }),
   z.object({ type: z.literal("message_start"), message: z.any() }),
-  z.object({ type: z.literal("content_block_start"), index: z.number(), content_block: z.any() }),
+  z.object({
+    type: z.literal("content_block_start"),
+    index: z.number(),
+    content_block: z.any(),
+  }),
   z.object({ type: z.literal("content_block_stop"), index: z.number() }),
-  z.object({ type: z.literal("message_delta"), delta: z.any(), usage: z.any() }),
+  z.object({
+    type: z.literal("message_delta"),
+    delta: z.any(),
+    usage: z.any(),
+  }),
   z.object({ type: z.literal("message_stop") }),
   z.object({ type: z.literal("ping") }),
 ]);
@@ -805,7 +838,7 @@ export default streamingApi({
           messages: [{ role: "user", content: prompt }],
         },
       },
-      { chunk: AnthropicStreamEventSchema }
+      { chunk: AnthropicStreamEventSchema },
     );
 
     for await (const event of stream) {
@@ -823,10 +856,10 @@ Same as `ApiRequestOptions` - see above.
 
 ### StreamApiRequestSchema
 
-| Property | Type                   | Description                                                                    |
-| -------- | ---------------------- | ------------------------------------------------------------------------------ |
-| `body?`  | `z.ZodSchema<TBody>`   | Optional Zod schema for request body validation (required if body is provided) |
-| `chunk`  | `z.ZodSchema<TChunk>`  | **Required** Zod schema for validating each streamed chunk                     |
+| Property | Type                  | Description                                                                    |
+| -------- | --------------------- | ------------------------------------------------------------------------------ |
+| `body?`  | `z.ZodSchema<TBody>`  | Optional Zod schema for request body validation (required if body is provided) |
+| `chunk`  | `z.ZodSchema<TChunk>` | **Required** Zod schema for validating each streamed chunk                     |
 
 ### Supported Integrations
 
@@ -857,16 +890,16 @@ import {
 } from "@superblocksteam/sdk-api";
 ```
 
-| Error Type                 | Code                    | Description                                        |
-| -------------------------- | ----------------------- | -------------------------------------------------- |
-| `InputValidationError`     | `INPUT_VALIDATION`      | Input failed Zod validation                        |
-| `OutputValidationError`    | `OUTPUT_VALIDATION`     | Output failed Zod validation                       |
-| `QueryValidationError`     | N/A                     | Database query result validation failed (Postgres) |
-| `RestApiValidationError`   | N/A                     | REST API request/response validation failed        |
-| `StreamChunkValidationError` | N/A                   | Streaming chunk failed schema validation           |
-| `IntegrationNotFoundError` | `INTEGRATION_NOT_FOUND` | Integration not configured                         |
-| `IntegrationError`         | `INTEGRATION_ERROR`     | Integration operation failed                       |
-| `ExecutionError`           | `EXECUTION_ERROR`       | User code threw an error                           |
+| Error Type                   | Code                    | Description                                        |
+| ---------------------------- | ----------------------- | -------------------------------------------------- |
+| `InputValidationError`       | `INPUT_VALIDATION`      | Input failed Zod validation                        |
+| `OutputValidationError`      | `OUTPUT_VALIDATION`     | Output failed Zod validation                       |
+| `QueryValidationError`       | N/A                     | Database query result validation failed (Postgres) |
+| `RestApiValidationError`     | N/A                     | REST API request/response validation failed        |
+| `StreamChunkValidationError` | N/A                     | Streaming chunk failed schema validation           |
+| `IntegrationNotFoundError`   | `INTEGRATION_NOT_FOUND` | Integration not configured                         |
+| `IntegrationError`           | `INTEGRATION_ERROR`     | Integration operation failed                       |
+| `ExecutionError`             | `EXECUTION_ERROR`       | User code threw an error                           |
 
 ### QueryValidationError (Postgres)
 
@@ -1089,7 +1122,10 @@ Don't fetch related data one item at a time in a loop. Use JOINs or batch querie
 **N+1 Problem - One query per order:**
 
 ```typescript
-const orders = await ctx.integrations.db.query("SELECT * FROM orders", OrderSchema);
+const orders = await ctx.integrations.db.query(
+  "SELECT * FROM orders",
+  OrderSchema,
+);
 
 // BAD: This makes N additional queries!
 for (const order of orders) {
@@ -1126,7 +1162,10 @@ const rows = await ctx.integrations.db.query(
 **Alternative - Batch fetch with IN clause:**
 
 ```typescript
-const orders = await ctx.integrations.db.query("SELECT * FROM orders", OrderSchema);
+const orders = await ctx.integrations.db.query(
+  "SELECT * FROM orders",
+  OrderSchema,
+);
 const orderIds = orders.map((o) => o.id);
 
 // Single query for all items
@@ -1211,8 +1250,8 @@ The app template provides automatic type inference for API calls using a tRPC-st
 **Step 2**: Add it to the registry at `server/apis/index.ts`:
 
 ```typescript
-import GetUsers from './GetUsers/api.js';
-import CreateOrder from './CreateOrder/api.js';
+import GetUsers from "./GetUsers/api.js";
+import CreateOrder from "./CreateOrder/api.js";
 
 const apis = {
   GetUsers,
@@ -1263,6 +1302,7 @@ The template includes two files that work together:
 The hook uses `import type` to pull in only the type information from the registry, keeping server code out of the client bundle.
 
 **Key benefits**:
+
 - **Single source of truth**: Just update `server/apis/index.ts`
 - **No server code in client bundle**: Type-only imports are erased at compile time
 - **Full type safety**: Autocomplete for API names, type errors for invalid inputs/outputs
@@ -1272,8 +1312,8 @@ The hook uses `import type` to pull in only the type information from the regist
 For testing or when the registry isn't available:
 
 ```typescript
-import { useApi } from '@superblocksteam/library';
-import type GetUsersApi from '../../server/apis/GetUsers/api.js';
+import { useApi } from "@superblocksteam/library";
+import type GetUsersApi from "../../server/apis/GetUsers/api.js";
 
 const { run } = useApi<typeof GetUsersApi>("GetUsers");
 ```
@@ -1348,7 +1388,6 @@ export default api({
   }),
 
   async run(ctx, { customerId, items, sendAiSummary }) {
-
     ctx.log.info("Creating order", { customerId, itemCount: items.length });
 
     // Get customer from database

package/dist/api/definition.d.ts

@@ -39,6 +39,9 @@ export type ExtractApiInput<T> = T extends CompiledApi<infer TInput, any> ? TInp
 export type ExtractApiOutput<T> = T extends CompiledApi<any, infer TOutput> ? TOutput : never;
 import type { ApiConfig, ApiContext, AnyIntegrationRef } from "../types.js";
 import { type IntegrationDeclaration } from "../integrations/declarations.js";
+/** Called by the Vite plugin to set the entry point for the next api() call. */
+export declare function __setEntryPoint(entryPoint: string): void;
+export declare function consumeEntryPoint(): string | undefined;
 /**
  * A compiled API definition ready for execution.
  *
@@ -48,6 +51,13 @@ import { type IntegrationDeclaration } from "../integrations/declarations.js";
 export interface CompiledApi<TInput = unknown, TOutput = 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/GetUsers/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 outputs */

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

@@ -1 +1 @@
-{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/api/definition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAE3B,CAAC,SAAS,WAAW,CAAC,MAAM,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC;AAE5D;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAE5B,CAAC,SAAS,WAAW,CAAC,GAAG,EAAE,MAAM,OAAO,CAAC,GAAG,OAAO,GAAG,KAAK,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,iCAAiC,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC9D,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,uCAAuC;IACvC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAExC,wCAAwC;IACxC,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAE1C;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtG;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC;CAC9D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,GAAG,CACjB,MAAM,SAAS,CAAC,CAAC,OAAO,EACxB,OAAO,SAAS,CAAC,CAAC,OAAO,EACzB,aAAa,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,MAAM,CAC9D,MAAM,EACN,KAAK,CACN,EAED,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,GAChD,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAgBhD"}
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/api/definition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAE3B,CAAC,SAAS,WAAW,CAAC,MAAM,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC;AAE5D;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAE5B,CAAC,SAAS,WAAW,CAAC,GAAG,EAAE,MAAM,OAAO,CAAC,GAAG,OAAO,GAAG,KAAK,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,iCAAiC,CAAC;AAUzC,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAExD;AAED,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAItD;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC9D,+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,wCAAwC;IACxC,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAE1C;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,CACZ,GAAG,EAAE,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,EAClD,KAAK,EAAE,MAAM,KACV,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtB;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC;CAC9D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,GAAG,CACjB,MAAM,SAAS,CAAC,CAAC,OAAO,EACxB,OAAO,SAAS,CAAC,CAAC,OAAO,EACzB,aAAa,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,MAAM,CAC9D,MAAM,EACN,KAAK,CACN,EAED,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,GAChD,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAkBhD"}

package/dist/api/definition.js

@@ -5,6 +5,21 @@
  * with input/output validation using Zod schemas and upfront integration declarations.
  */
 import { extractIntegrationDeclarations, } from "../integrations/declarations.js";
+// ---------------------------------------------------------------------------
+// Entry point setter — used by the Vite plugin to stamp the source file path
+// onto the next api()/streamingApi() call. ESM top-level execution is
+// synchronous, so the prepended __setEntryPoint() always runs before api().
+// ---------------------------------------------------------------------------
+let __pendingEntryPoint;
+/** Called by the Vite plugin to set the entry point for the next api() call. */
+export function __setEntryPoint(entryPoint) {
+    __pendingEntryPoint = entryPoint;
+}
+export function consumeEntryPoint() {
+    const ep = __pendingEntryPoint;
+    __pendingEntryPoint = undefined;
+    return ep;
+}
 /**
  * Define a TypeScript-based API with input/output validation.
  *
@@ -64,6 +79,8 @@ export function api(config) {
     const integrations = extractIntegrationDeclarations(config.integrations);
     const compiled = {
         name: config.name,
+        description: config.description,
+        entryPoint: consumeEntryPoint(),
         inputSchema: config.input,
         outputSchema: config.output,
         run: config.run,

package/dist/api/definition.js.map

@@ -1 +1 @@
-{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../src/api/definition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA0CH,OAAO,EACL,8BAA8B,GAE/B,MAAM,iCAAiC,CAAC;AAgDzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,UAAU,GAAG,CAQjB,MAAiD;IAEjD,oDAAoD;IACpD,MAAM,YAAY,GAAG,8BAA8B,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAEzE,MAAM,QAAQ,GAAmD;QAC/D,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,WAAW,EAAE,MAAM,CAAC,KAAK;QACzB,YAAY,EAAE,MAAM,CAAC,MAAM;QAC3B,GAAG,EAAE,MAAM,CAAC,GAGkB;QAC9B,YAAY;KACb,CAAC;IAEF,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../src/api/definition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA0CH,OAAO,EACL,8BAA8B,GAE/B,MAAM,iCAAiC,CAAC;AAEzC,8EAA8E;AAC9E,6EAA6E;AAC7E,sEAAsE;AACtE,4EAA4E;AAC5E,8EAA8E;AAE9E,IAAI,mBAAuC,CAAC;AAE5C,gFAAgF;AAChF,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,mBAAmB,GAAG,UAAU,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,MAAM,EAAE,GAAG,mBAAmB,CAAC;IAC/B,mBAAmB,GAAG,SAAS,CAAC;IAChC,OAAO,EAAE,CAAC;AACZ,CAAC;AA2DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,UAAU,GAAG,CAQjB,MAAiD;IAEjD,oDAAoD;IACpD,MAAM,YAAY,GAAG,8BAA8B,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAEzE,MAAM,QAAQ,GAAmD;QAC/D,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,YAAY,EAAE,MAAM,CAAC,MAAM;QAC3B,GAAG,EAAE,MAAM,CAAC,GAGkB;QAC9B,YAAY;KACb,CAAC;IAEF,OAAO,QAAQ,CAAC;AAClB,CAAC"}

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

@@ -1,5 +1,5 @@
 /**
- * Tests for API definition utility types.
+ * Tests for API definition utility types and entry point mechanism.
  */
 export {};
 //# sourceMappingURL=definition.test.d.ts.map

package/dist/api/definition.test.js

@@ -1,10 +1,10 @@
 /**
- * Tests for API definition utility types.
+ * Tests for API definition utility types and entry point mechanism.
  */
 /* eslint-disable @typescript-eslint/no-unused-vars */
-import { describe, it, expectTypeOf } from "vitest";
+import { describe, it, expect, expectTypeOf } from "vitest";
 import { z } from "zod";
-import { api, } from "./definition.js";
+import { api, __setEntryPoint, consumeEntryPoint, } from "./definition.js";
 describe("ExtractApiInput", () => {
     it("extracts input type from simple API", () => {
         const _SimpleApi = api({
@@ -207,4 +207,57 @@ describe("ExtractApiInput and ExtractApiOutput together", () => {
         expectTypeOf().toEqualTypeOf();
     });
 });
+describe("entryPoint mechanism", () => {
+    it("api() has no entryPoint when __setEntryPoint was not called", () => {
+        const compiled = api({
+            name: "NoEntryPoint",
+            input: z.object({}),
+            output: z.object({ ok: z.boolean() }),
+            async run() {
+                return { ok: true };
+            },
+        });
+        expect(compiled.entryPoint).toBeUndefined();
+    });
+    it("api() picks up entryPoint set via __setEntryPoint", () => {
+        __setEntryPoint("server/apis/GetUsers/api.ts");
+        const compiled = api({
+            name: "GetUsers",
+            input: z.object({}),
+            output: z.object({ users: z.array(z.string()) }),
+            async run() {
+                return { users: [] };
+            },
+        });
+        expect(compiled.entryPoint).toBe("server/apis/GetUsers/api.ts");
+    });
+    it("consumeEntryPoint clears the pending value", () => {
+        __setEntryPoint("server/apis/Temp/api.ts");
+        const first = consumeEntryPoint();
+        const second = consumeEntryPoint();
+        expect(first).toBe("server/apis/Temp/api.ts");
+        expect(second).toBeUndefined();
+    });
+    it("entryPoint is consumed once — second api() call gets undefined", () => {
+        __setEntryPoint("server/apis/First/api.ts");
+        const first = api({
+            name: "First",
+            input: z.object({}),
+            output: z.object({}),
+            async run() {
+                return {};
+            },
+        });
+        const second = api({
+            name: "Second",
+            input: z.object({}),
+            output: z.object({}),
+            async run() {
+                return {};
+            },
+        });
+        expect(first.entryPoint).toBe("server/apis/First/api.ts");
+        expect(second.entryPoint).toBeUndefined();
+    });
+});
 //# sourceMappingURL=definition.test.js.map