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

package/src/integrations/airtable/README.md

@@ -4,8 +4,8 @@ Create, read, update, and delete records in Airtable bases and tables.
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                          |
+| ----------------------------- | ---------------------------------------------------- |
 | `apiRequest(options, schema)` | Make any Airtable API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Create, read, update, and delete records in Airtable bases and tables.
 ### List Records
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, airtable } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_AIRTABLE = "a1b2c3d4-5678-90ab-cdef-airtable0001";
@@ -31,17 +31,20 @@ const ListRecordsResponseSchema = z.object({
 
 export default api({
   name: "AirtableExample",
+  integrations: {
+    airtable: airtable(PROD_AIRTABLE),
+  },
   input: z.object({
     baseId: z.string(),
     tableId: z.string(),
   }),
   output: z.object({
-    records: z.array(z.object({ id: z.string(), fields: z.record(z.unknown()) })),
+    records: z.array(
+      z.object({ id: z.string(), fields: z.record(z.unknown()) }),
+    ),
   }),
   async run(ctx, { baseId, tableId }) {
-    const airtable = ctx.airtable(PROD_AIRTABLE);
-
-    const result = await airtable.apiRequest(
+    const result = await ctx.integrations.airtable.apiRequest(
       {
         method: "GET",
         path: `/v0/${baseId}/${tableId}`,
@@ -49,7 +52,7 @@ export default api({
           maxRecords: 100,
         },
       },
-      { response: ListRecordsResponseSchema }
+      { response: ListRecordsResponseSchema },
     );
 
     return {
@@ -68,7 +71,7 @@ const CreateRecordResponseSchema = z.object({
   fields: z.record(z.unknown()),
 });
 
-const result = await airtable.apiRequest(
+const result = await ctx.integrations.airtable.apiRequest(
   {
     method: "POST",
     path: `/v0/${baseId}/${tableId}`,
@@ -82,7 +85,7 @@ const result = await airtable.apiRequest(
       },
     },
   },
-  { response: CreateRecordResponseSchema }
+  { response: CreateRecordResponseSchema },
 );
 
 console.log(`Created record: ${result.id}`);
@@ -95,7 +98,7 @@ const CreateMultipleResponseSchema = z.object({
   records: z.array(RecordSchema),
 });
 
-const result = await airtable.apiRequest(
+const result = await ctx.integrations.airtable.apiRequest(
   {
     method: "POST",
     path: `/v0/${baseId}/${tableId}`,
@@ -107,7 +110,7 @@ const result = await airtable.apiRequest(
       ],
     },
   },
-  { response: CreateMultipleResponseSchema }
+  { response: CreateMultipleResponseSchema },
 );
 
 console.log(`Created ${result.records.length} records`);
@@ -116,12 +119,12 @@ console.log(`Created ${result.records.length} records`);
 ### Get a Single Record
 
 ```typescript
-const result = await airtable.apiRequest(
+const result = await ctx.integrations.airtable.apiRequest(
   {
     method: "GET",
     path: `/v0/${baseId}/${tableId}/${recordId}`,
   },
-  { response: RecordSchema }
+  { response: RecordSchema },
 );
 
 console.log(`Record: ${result.fields.Name}`);
@@ -130,7 +133,7 @@ console.log(`Record: ${result.fields.Name}`);
 ### Update a Record
 
 ```typescript
-const result = await airtable.apiRequest(
+const result = await ctx.integrations.airtable.apiRequest(
   {
     method: "PATCH",
     path: `/v0/${baseId}/${tableId}/${recordId}`,
@@ -141,14 +144,14 @@ const result = await airtable.apiRequest(
       },
     },
   },
-  { response: RecordSchema }
+  { response: RecordSchema },
 );
 ```
 
 ### Update Multiple Records
 
 ```typescript
-const result = await airtable.apiRequest(
+const result = await ctx.integrations.airtable.apiRequest(
   {
     method: "PATCH",
     path: `/v0/${baseId}/${tableId}`,
@@ -159,7 +162,7 @@ const result = await airtable.apiRequest(
       ],
     },
   },
-  { response: z.object({ records: z.array(RecordSchema) }) }
+  { response: z.object({ records: z.array(RecordSchema) }) },
 );
 ```
 
@@ -171,11 +174,11 @@ const DeleteResponseSchema = z.object({
     z.object({
       id: z.string(),
       deleted: z.boolean(),
-    })
+    }),
   ),
 });
 
-const result = await airtable.apiRequest(
+const result = await ctx.integrations.airtable.apiRequest(
   {
     method: "DELETE",
     path: `/v0/${baseId}/${tableId}`,
@@ -183,14 +186,14 @@ const result = await airtable.apiRequest(
       "records[]": ["rec1", "rec2", "rec3"],
     },
   },
-  { response: DeleteResponseSchema }
+  { response: DeleteResponseSchema },
 );
 ```
 
 ### Filter and Sort Records
 
 ```typescript
-const result = await airtable.apiRequest(
+const result = await ctx.integrations.airtable.apiRequest(
   {
     method: "GET",
     path: `/v0/${baseId}/${tableId}`,
@@ -204,7 +207,7 @@ const result = await airtable.apiRequest(
       maxRecords: 50,
     },
   },
-  { response: ListRecordsResponseSchema }
+  { response: ListRecordsResponseSchema },
 );
 ```
 
@@ -223,18 +226,18 @@ const TableSchemaResponseSchema = z.object({
           name: z.string(),
           type: z.string(),
           options: z.unknown().optional(),
-        })
+        }),
       ),
-    })
+    }),
   ),
 });
 
-const result = await airtable.apiRequest(
+const result = await ctx.integrations.airtable.apiRequest(
   {
     method: "GET",
     path: `/v0/meta/bases/${baseId}/tables`,
   },
-  { response: TableSchemaResponseSchema }
+  { response: TableSchemaResponseSchema },
 );
 
 result.tables.forEach((table) => {
@@ -251,11 +254,11 @@ result.tables.forEach((table) => {
 
 ```typescript
 // WRONG - These methods do not exist
-await airtable.listRecords({ ... });
-await airtable.createRecord({ ... });
+await ctx.integrations.airtable.listRecords({ ... });
+await ctx.integrations.airtable.createRecord({ ... });
 
 // CORRECT - Use apiRequest
-await airtable.apiRequest(
+await ctx.integrations.airtable.apiRequest(
   { method: "GET", path: `/v0/${baseId}/${tableId}` },
   { response: ListRecordsResponseSchema }
 );
@@ -279,8 +282,8 @@ const path = `/v0/${baseId}/tbl123abc`;
 ```typescript
 // WRONG - Wrong case
 const fields = {
-  name: "Task",      // Should be "Name"
-  STATUS: "To Do",   // Should be "Status"
+  name: "Task", // Should be "Name"
+  STATUS: "To Do", // Should be "Status"
 };
 
 // CORRECT - Match exact field names from Airtable
@@ -296,8 +299,8 @@ const fields = {
 // For linked record fields, use an array of record IDs
 const fields = {
   Name: "New Task",
-  Project: ["recABC123"],        // Single link
-  Assignees: ["recDEF456", "recGHI789"],  // Multiple links
+  Project: ["recABC123"], // Single link
+  Assignees: ["recDEF456", "recGHI789"], // Multiple links
 };
 ```
 
@@ -332,7 +335,11 @@ const filter8 = "NOT({Assignee} = BLANK())";
 Airtable returns max 100 records per request:
 
 ```typescript
-async function getAllRecords(airtable: AirtableClient, baseId: string, tableId: string) {
+async function getAllRecords(
+  airtable: AirtableClient,
+  baseId: string,
+  tableId: string,
+) {
   const allRecords: Record[] = [];
   let offset: string | undefined;
 
@@ -346,7 +353,7 @@ async function getAllRecords(airtable: AirtableClient, baseId: string, tableId:
           ...(offset && { offset }),
         },
       },
-      { response: ListRecordsResponseSchema }
+      { response: ListRecordsResponseSchema },
     );
 
     allRecords.push(...result.records);
@@ -364,7 +371,7 @@ Airtable has a rate limit of 5 requests per second per base:
 ```typescript
 // Add delays for bulk operations
 for (const batch of batches) {
-  await airtable.apiRequest(...);
+  await ctx.integrations.airtable.apiRequest(...);
   await new Promise((r) => setTimeout(r, 200)); // 5 req/sec = 200ms delay
 }
 ```
@@ -391,9 +398,9 @@ for (let i = 0; i < records.length; i += 10) {
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await airtable.apiRequest(
+  const result = await ctx.integrations.airtable.apiRequest(
     { method: "GET", path: `/v0/${baseId}/${tableId}` },
-    { response: ListRecordsResponseSchema }
+    { response: ListRecordsResponseSchema },
   );
 } catch (error) {
   if (error instanceof RestApiValidationError) {

package/src/integrations/airtable/client.ts

@@ -5,8 +5,8 @@
  * Airtable integrations use the REST API Integration plugin under the hood.
  */
 
-import { RestApiIntegrationClient } from '../base/index.js';
-import type { AirtableClient } from './types.js';
+import { RestApiIntegrationClient } from "../base/index.js";
+import type { AirtableClient } from "./types.js";
 
 /**
  * Internal implementation of AirtableClient.
@@ -16,6 +16,8 @@ import type { AirtableClient } from './types.js';
  * Airtable API calls. At runtime, the orchestrator handles authentication
  * and API request execution.
  */
-export class AirtableClientImpl extends RestApiIntegrationClient implements AirtableClient {
+export class AirtableClientImpl
+  extends RestApiIntegrationClient
+  implements AirtableClient {
   // Inherits: name, pluginId, config, executeQuery, apiRequest()
 }

package/src/integrations/airtable/index.ts

@@ -1,2 +1,2 @@
-export { AirtableClientImpl } from './client.js';
-export type { AirtableClient } from './types.js';
+export { AirtableClientImpl } from "./client.js";
+export type { AirtableClient } from "./types.js";

package/src/integrations/airtable/types.ts

@@ -2,8 +2,8 @@
  * Airtable client types.
  */
 
-import type { BaseIntegrationClient } from '../../types.js';
-import type { SupportsApiRequest } from '../base/index.js';
+import type { BaseIntegrationClient } from "../../types.js";
+import type { SupportsApiRequest } from "../base/index.js";
 
 /**
  * Airtable client for API interactions.
@@ -13,14 +13,9 @@ import type { SupportsApiRequest } from '../base/index.js';
  *
  * @example
  * ```typescript
- * const airtable = ctx.airtable('My Airtable');
- *
- * // Make API requests
- * const ResponseSchema = z.object({
- *   // Define your response schema
- * });
- *
- * const result = await airtable.apiRequest(
+ * // Declare in api(): integrations: { airtable: airtable(INTEGRATION_ID) }
+ * // In run(), access via: ctx.integrations.airtable
+ * const result = await ctx.integrations.airtable.apiRequest(
  *   {
  *     method: 'GET',
  *     path: '/v0/{baseId}/{tableName}',
@@ -29,6 +24,7 @@ import type { SupportsApiRequest } from '../base/index.js';
  * );
  * ```
  */
-export interface AirtableClient extends BaseIntegrationClient, SupportsApiRequest {
+export interface AirtableClient
+  extends BaseIntegrationClient, SupportsApiRequest {
   // apiRequest() method inherited from SupportsApiRequest
 }

package/src/integrations/anthropic/README.md

@@ -4,17 +4,17 @@ Interact with Anthropic's Claude API for powerful AI conversations and text gene
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
-| `apiRequest(options, schema)` | Make any Anthropic API request with schema validation |
-| `streamApiRequest(options, schema)` | Stream responses with real-time chunk validation |
+| Method                              | Description                                           |
+| ----------------------------------- | ----------------------------------------------------- |
+| `apiRequest(options, schema)`       | Make any Anthropic API request with schema validation |
+| `streamApiRequest(options, schema)` | Stream responses with real-time chunk validation      |
 
 ## Usage
 
 ### Create a Message
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, anthropic } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_ANTHROPIC = "a1b2c3d4-5678-90ab-cdef-444444444444";
@@ -27,7 +27,7 @@ const MessageResponseSchema = z.object({
     z.object({
       type: z.literal("text"),
       text: z.string(),
-    })
+    }),
   ),
   model: z.string(),
   stop_reason: z.string().nullable(),
@@ -40,6 +40,9 @@ const MessageResponseSchema = z.object({
 
 export default api({
   name: "AnthropicExample",
+  integrations: {
+    ai: anthropic(PROD_ANTHROPIC),
+  },
   input: z.object({
     prompt: z.string(),
   }),
@@ -47,9 +50,7 @@ export default api({
     response: z.string(),
   }),
   async run(ctx, { prompt }) {
-    const anthropic = ctx.anthropic(PROD_ANTHROPIC);
-
-    const result = await anthropic.apiRequest(
+    const result = await ctx.integrations.ai.apiRequest(
       {
         method: "POST",
         path: "/v1/messages",
@@ -59,7 +60,7 @@ export default api({
           messages: [{ role: "user", content: prompt }],
         },
       },
-      { response: MessageResponseSchema }
+      { response: MessageResponseSchema },
     );
 
     const textContent = result.content.find((c) => c.type === "text");
@@ -71,14 +72,15 @@ export default api({
 ### Conversation with System Prompt
 
 ```typescript
-const result = await anthropic.apiRequest(
+const result = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
     path: "/v1/messages",
     body: {
       model: "claude-3-5-sonnet-20241022",
       max_tokens: 2048,
-      system: "You are a helpful coding assistant. Always provide code examples.",
+      system:
+        "You are a helpful coding assistant. Always provide code examples.",
       messages: [
         { role: "user", content: "How do I read a file in Python?" },
         {
@@ -89,7 +91,7 @@ const result = await anthropic.apiRequest(
       ],
     },
   },
-  { response: MessageResponseSchema }
+  { response: MessageResponseSchema },
 );
 ```
 
@@ -111,7 +113,7 @@ const ToolUseResponseSchema = z.object({
         name: z.string(),
         input: z.record(z.unknown()),
       }),
-    ])
+    ]),
   ),
   stop_reason: z.string().nullable(),
   usage: z.object({
@@ -120,7 +122,7 @@ const ToolUseResponseSchema = z.object({
   }),
 });
 
-const result = await anthropic.apiRequest(
+const result = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
     path: "/v1/messages",
@@ -148,7 +150,7 @@ const result = await anthropic.apiRequest(
       ],
     },
   },
-  { response: ToolUseResponseSchema }
+  { response: ToolUseResponseSchema },
 );
 
 // Check if Claude wants to use a tool
@@ -161,7 +163,7 @@ if (toolUse && toolUse.type === "tool_use") {
 ### Vision (Image Analysis)
 
 ```typescript
-const result = await anthropic.apiRequest(
+const result = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
     path: "/v1/messages",
@@ -189,7 +191,7 @@ const result = await anthropic.apiRequest(
       ],
     },
   },
-  { response: MessageResponseSchema }
+  { response: MessageResponseSchema },
 );
 ```
 
@@ -209,7 +211,7 @@ const ExtendedThinkingResponseSchema = z.object({
         type: z.literal("text"),
         text: z.string(),
       }),
-    ])
+    ]),
   ),
   usage: z.object({
     input_tokens: z.number(),
@@ -217,7 +219,7 @@ const ExtendedThinkingResponseSchema = z.object({
   }),
 });
 
-const result = await anthropic.apiRequest(
+const result = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
     path: "/v1/messages",
@@ -236,7 +238,7 @@ const result = await anthropic.apiRequest(
       ],
     },
   },
-  { response: ExtendedThinkingResponseSchema }
+  { response: ExtendedThinkingResponseSchema },
 );
 ```
 
@@ -261,9 +263,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") }),
 ]);
@@ -288,7 +298,7 @@ export default streamingApi({
           messages: [{ role: "user", content: prompt }],
         },
       },
-      { chunk: AnthropicStreamEventSchema }
+      { chunk: AnthropicStreamEventSchema },
     );
 
     // Yield text chunks as they arrive
@@ -305,15 +315,15 @@ export default streamingApi({
 
 Claude's streaming API sends these event types:
 
-| Event Type | Description |
-| ---------- | ----------- |
-| `message_start` | Initial message metadata (model, id, usage) |
-| `content_block_start` | Start of a content block (text, tool_use) |
-| `content_block_delta` | Incremental text or tool input |
-| `content_block_stop` | End of a content block |
-| `message_delta` | Final message metadata (stop_reason, usage) |
-| `message_stop` | Stream complete |
-| `ping` | Keep-alive ping |
+| Event Type            | Description                                 |
+| --------------------- | ------------------------------------------- |
+| `message_start`       | Initial message metadata (model, id, usage) |
+| `content_block_start` | Start of a content block (text, tool_use)   |
+| `content_block_delta` | Incremental text or tool input              |
+| `content_block_stop`  | End of a content block                      |
+| `message_delta`       | Final message metadata (stop_reason, usage) |
+| `message_stop`        | Stream complete                             |
+| `ping`                | Keep-alive ping                             |
 
 ## Common Pitfalls
 
@@ -327,7 +337,7 @@ await anthropic.createMessage({ ... });
 await anthropic.complete({ ... });
 
 // CORRECT - Use apiRequest for all operations
-await anthropic.apiRequest(
+await ctx.integrations.ai.apiRequest(
   { method: "POST", path: "/v1/messages", body: { ... } },
   { response: MessageResponseSchema }
 );
@@ -339,7 +349,7 @@ Unlike some other APIs, `max_tokens` is a required parameter:
 
 ```typescript
 // WRONG - Missing max_tokens
-const result = await anthropic.apiRequest(
+const result = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
     path: "/v1/messages",
@@ -349,11 +359,11 @@ const result = await anthropic.apiRequest(
       // max_tokens is missing!
     },
   },
-  { response: MessageResponseSchema }
+  { response: MessageResponseSchema },
 );
 
 // CORRECT - Include max_tokens
-const result = await anthropic.apiRequest(
+const result = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
     path: "/v1/messages",
@@ -363,7 +373,7 @@ const result = await anthropic.apiRequest(
       messages: [{ role: "user", content: "Hello" }],
     },
   },
-  { response: MessageResponseSchema }
+  { response: MessageResponseSchema },
 );
 ```
 
@@ -383,7 +393,7 @@ const schema = z.object({
     z.object({
       type: z.literal("text"),
       text: z.string(),
-    })
+    }),
   ),
 });
 
@@ -419,7 +429,7 @@ const body = {
 For specific API versions or beta features:
 
 ```typescript
-const result = await anthropic.apiRequest(
+const result = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
     path: "/v1/messages",
@@ -435,15 +445,15 @@ const result = await anthropic.apiRequest(
 
 ### Model Token Limits
 
-| Model | Max Output Tokens |
-|-------|-------------------|
-| claude-3-5-sonnet | 8,192 |
-| claude-3-opus | 4,096 |
-| claude-3-haiku | 4,096 |
+| Model             | Max Output Tokens |
+| ----------------- | ----------------- |
+| claude-3-5-sonnet | 8,192             |
+| claude-3-opus     | 4,096             |
+| claude-3-haiku    | 4,096             |
 
 ```typescript
 // Be mindful of token limits
-const result = await anthropic.apiRequest(
+const result = await ctx.integrations.ai.apiRequest(
   {
     method: "POST",
     path: "/v1/messages",
@@ -463,7 +473,7 @@ const result = await anthropic.apiRequest(
 import { RestApiValidationError, StreamChunkValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await anthropic.apiRequest(
+  const result = await ctx.integrations.ai.apiRequest(
     { method: "POST", path: "/v1/messages", body: { ... } },
     { response: MessageResponseSchema }
   );

package/src/integrations/anthropic/client.ts

@@ -5,8 +5,8 @@
  * Anthropic integrations use the REST API Integration plugin under the hood.
  */
 
-import { RestApiIntegrationClient } from '../base/index.js';
-import type { AnthropicClient } from './types.js';
+import { RestApiIntegrationClient } from "../base/index.js";
+import type { AnthropicClient } from "./types.js";
 
 /**
  * Internal implementation of AnthropicClient.
@@ -16,7 +16,9 @@ import type { AnthropicClient } from './types.js';
  * Anthropic API calls. At runtime, the orchestrator handles authentication
  * and API request execution.
  */
-export class AnthropicClientImpl extends RestApiIntegrationClient implements AnthropicClient {
+export class AnthropicClientImpl
+  extends RestApiIntegrationClient
+  implements AnthropicClient {
   // Inherits: name, pluginId, config, executeQuery, createParam(), apiRequest()
   // Can add Anthropic-specific methods here in the future if needed
 }

package/src/integrations/anthropic/index.ts

@@ -1,2 +1,2 @@
-export { AnthropicClientImpl } from './client.js';
-export type { AnthropicClient } from './types.js';
+export { AnthropicClientImpl } from "./client.js";
+export type { AnthropicClient } from "./types.js";