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

package/src/integrations/superblocks-ocr/README.md

@@ -4,8 +4,8 @@ Extract text from images using the Superblocks OCR service with full type safety
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                     |
+| ----------------------------- | ----------------------------------------------- |
 | `apiRequest(options, schema)` | Make any OCR API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Extract text from images using the Superblocks OCR service with full type safety
 ### Extract Text from Image URL
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, superblocksOcr } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_OCR = "a1b2c3d4-5678-90ab-cdef-sbocr0000001";
@@ -21,20 +21,25 @@ const PROD_OCR = "a1b2c3d4-5678-90ab-cdef-sbocr0000001";
 const OCRResponseSchema = z.object({
   text: z.string(),
   confidence: z.number(),
-  blocks: z.array(
-    z.object({
-      text: z.string(),
-      boundingBox: z.object({
-        x: z.number(),
-        y: z.number(),
-        width: z.number(),
-        height: z.number(),
+  blocks: z
+    .array(
+      z.object({
+        text: z.string(),
+        boundingBox: z.object({
+          x: z.number(),
+          y: z.number(),
+          width: z.number(),
+          height: z.number(),
+        }),
       }),
-    })
-  ).optional(),
+    )
+    .optional(),
 });
 
 export default api({
+  integrations: {
+    ocr: superblocksOcr(PROD_OCR),
+  },
   name: "SuperblocksOCRExample",
   input: z.object({
     imageUrl: z.string().url(),
@@ -44,9 +49,7 @@ export default api({
     confidence: z.number(),
   }),
   async run(ctx, { imageUrl }) {
-    const ocr = ctx.superblocksOcr(PROD_OCR);
-
-    const result = await ocr.apiRequest(
+    const result = await ctx.integrations.ocr.apiRequest(
       {
         method: "POST",
         path: "/extract",
@@ -54,7 +57,7 @@ export default api({
           imageUrl: imageUrl,
         },
       },
-      { response: OCRResponseSchema }
+      { response: OCRResponseSchema },
     );
 
     return {
@@ -68,7 +71,7 @@ export default api({
 ### Extract with Options
 
 ```typescript
-const result = await ocr.apiRequest(
+const result = await ctx.integrations.ocr.apiRequest(
   {
     method: "POST",
     path: "/extract",
@@ -81,14 +84,14 @@ const result = await ocr.apiRequest(
       },
     },
   },
-  { response: OCRResponseSchema }
+  { response: OCRResponseSchema },
 );
 ```
 
 ### Extract from Base64 Image
 
 ```typescript
-const result = await ocr.apiRequest(
+const result = await ctx.integrations.ocr.apiRequest(
   {
     method: "POST",
     path: "/extract",
@@ -97,7 +100,7 @@ const result = await ocr.apiRequest(
       mimeType: "image/png",
     },
   },
-  { response: OCRResponseSchema }
+  { response: OCRResponseSchema },
 );
 ```
 
@@ -106,15 +109,17 @@ const result = await ocr.apiRequest(
 ```typescript
 const StructuredResponseSchema = z.object({
   text: z.string(),
-  tables: z.array(
-    z.object({
-      rows: z.array(z.array(z.string())),
-    })
-  ).optional(),
+  tables: z
+    .array(
+      z.object({
+        rows: z.array(z.array(z.string())),
+      }),
+    )
+    .optional(),
   keyValuePairs: z.record(z.string()).optional(),
 });
 
-const result = await ocr.apiRequest(
+const result = await ctx.integrations.ocr.apiRequest(
   {
     method: "POST",
     path: "/extract/structured",
@@ -124,7 +129,7 @@ const result = await ocr.apiRequest(
       extractKeyValuePairs: true,
     },
   },
-  { response: StructuredResponseSchema }
+  { response: StructuredResponseSchema },
 );
 ```
 
@@ -142,7 +147,7 @@ Large images may take longer to process. Consider resizing before sending.
 
 ```typescript
 // CORRECT - Response schema is required
-await ocr.apiRequest(
+await ctx.integrations.ocr.apiRequest(
   { method: "POST", path: "/extract", body: { ... } },
   { response: ResponseSchema }
 );
@@ -154,7 +159,7 @@ await ocr.apiRequest(
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await ocr.apiRequest(
+  const result = await ctx.integrations.ocr.apiRequest(
     { method: "POST", path: "/extract", body: { ... } },
     { response: ResponseSchema }
   );

package/src/integrations/superblocks-ocr/client.ts

@@ -5,8 +5,8 @@
  * Superblocks OCR integrations use the REST API Integration plugin under the hood.
  */
 
-import { RestApiIntegrationClient } from '../base/index.js';
-import type { SuperblocksOCRClient } from './types.js';
+import { RestApiIntegrationClient } from "../base/index.js";
+import type { SuperblocksOCRClient } from "./types.js";
 
 /**
  * Internal implementation of SuperblocksOCRClient.
@@ -15,7 +15,6 @@ import type { SuperblocksOCRClient } from './types.js';
  */
 export class SuperblocksOCRClientImpl
   extends RestApiIntegrationClient
-  implements SuperblocksOCRClient
-{
+  implements SuperblocksOCRClient {
   // Inherits: name, pluginId, config, executeQuery, apiRequest()
 }

package/src/integrations/superblocks-ocr/index.ts

@@ -4,5 +4,5 @@
  * @module
  */
 
-export type { SuperblocksOCRClient } from './types.js';
-export { SuperblocksOCRClientImpl } from './client.js';
+export type { SuperblocksOCRClient } from "./types.js";
+export { SuperblocksOCRClientImpl } from "./client.js";

package/src/integrations/superblocks-ocr/types.ts

@@ -2,8 +2,8 @@
  * Superblocks OCR 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";
 
 /**
  * Superblocks OCR client for API interactions.
@@ -13,7 +13,8 @@ import type { SupportsApiRequest } from '../base/index.js';
  *
  * @example
  * ```typescript
- * const ocr = ctx.superblocksOcr('Production OCR');
+ * // Declare in api(): integrations: { ocr: superblocksOcr(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.ocr
  *
  * // Extract text from image
  * const OCRResponseSchema = z.object({
@@ -33,6 +34,7 @@ import type { SupportsApiRequest } from '../base/index.js';
  * );
  * ```
  */
-export interface SuperblocksOCRClient extends BaseIntegrationClient, SupportsApiRequest {
+export interface SuperblocksOCRClient
+  extends BaseIntegrationClient, SupportsApiRequest {
   // apiRequest() method inherited from SupportsApiRequest
 }

package/src/integrations/twilio/README.md

@@ -4,8 +4,8 @@ Send SMS messages, make calls, and interact with Twilio's communication APIs.
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                        |
+| ----------------------------- | -------------------------------------------------- |
 | `apiRequest(options, schema)` | Make any Twilio API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Send SMS messages, make calls, and interact with Twilio's communication APIs.
 ### Send an SMS
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, twilio } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_TWILIO = "a1b2c3d4-5678-90ab-cdef-twilio000001";
@@ -34,6 +34,9 @@ const MessageResponseSchema = z.object({
 });
 
 export default api({
+  integrations: {
+    twilio: twilio(PROD_TWILIO),
+  },
   name: "TwilioExample",
   input: z.object({
     to: z.string(),
@@ -44,12 +47,10 @@ export default api({
     status: z.string(),
   }),
   async run(ctx, { to, message }) {
-    const twilio = ctx.twilio(PROD_TWILIO);
-
     // Note: Account SID is part of the URL path
     const accountSid = ctx.env.TWILIO_ACCOUNT_SID;
 
-    const result = await twilio.apiRequest(
+    const result = await ctx.integrations.twilio.apiRequest(
       {
         method: "POST",
         path: `/2010-04-01/Accounts/${accountSid}/Messages.json`,
@@ -59,7 +60,7 @@ export default api({
           Body: message,
         },
       },
-      { response: MessageResponseSchema }
+      { response: MessageResponseSchema },
     );
 
     return { messageSid: result.sid, status: result.status };
@@ -70,7 +71,7 @@ export default api({
 ### Send MMS (with Media)
 
 ```typescript
-const result = await twilio.apiRequest(
+const result = await ctx.integrations.twilio.apiRequest(
   {
     method: "POST",
     path: `/2010-04-01/Accounts/${accountSid}/Messages.json`,
@@ -81,7 +82,7 @@ const result = await twilio.apiRequest(
       MediaUrl: "https://example.com/image.jpg",
     },
   },
-  { response: MessageResponseSchema }
+  { response: MessageResponseSchema },
 );
 ```
 
@@ -98,7 +99,7 @@ const ListMessagesResponseSchema = z.object({
   page_size: z.number(),
 });
 
-const result = await twilio.apiRequest(
+const result = await ctx.integrations.twilio.apiRequest(
   {
     method: "GET",
     path: `/2010-04-01/Accounts/${accountSid}/Messages.json`,
@@ -107,7 +108,7 @@ const result = await twilio.apiRequest(
       To: "+15559876543", // Filter by recipient
     },
   },
-  { response: ListMessagesResponseSchema }
+  { response: ListMessagesResponseSchema },
 );
 
 result.messages.forEach((msg) => {
@@ -131,7 +132,7 @@ const CallResponseSchema = z.object({
   price: z.string().nullable(),
 });
 
-const result = await twilio.apiRequest(
+const result = await ctx.integrations.twilio.apiRequest(
   {
     method: "POST",
     path: `/2010-04-01/Accounts/${accountSid}/Calls.json`,
@@ -141,7 +142,7 @@ const result = await twilio.apiRequest(
       Url: "http://demo.twilio.com/docs/voice.xml", // TwiML URL
     },
   },
-  { response: CallResponseSchema }
+  { response: CallResponseSchema },
 );
 
 console.log(`Call SID: ${result.sid}, Status: ${result.status}`);
@@ -174,7 +175,7 @@ const LookupResponseSchema = z.object({
     .optional(),
 });
 
-const result = await twilio.apiRequest(
+const result = await ctx.integrations.twilio.apiRequest(
   {
     method: "GET",
     path: `/v2/PhoneNumbers/+15559876543`,
@@ -182,7 +183,7 @@ const result = await twilio.apiRequest(
       Fields: "carrier,caller_name",
     },
   },
-  { response: LookupResponseSchema }
+  { response: LookupResponseSchema },
 );
 
 console.log(`Number: ${result.national_format}, Valid: ${result.valid}`);
@@ -194,12 +195,12 @@ if (result.carrier) {
 ### Get Message Status
 
 ```typescript
-const result = await twilio.apiRequest(
+const result = await ctx.integrations.twilio.apiRequest(
   {
     method: "GET",
     path: `/2010-04-01/Accounts/${accountSid}/Messages/${messageSid}.json`,
   },
-  { response: MessageResponseSchema }
+  { response: MessageResponseSchema },
 );
 
 console.log(`Message status: ${result.status}`);
@@ -216,7 +217,7 @@ await twilio.sendSms({ ... });
 await twilio.makeCall({ ... });
 
 // CORRECT - Use apiRequest
-await twilio.apiRequest(
+await ctx.integrations.twilio.apiRequest(
   { method: "POST", path: `/2010-04-01/Accounts/${accountSid}/Messages.json`, body: { ... } },
   { response: MessageResponseSchema }
 );
@@ -228,7 +229,7 @@ Twilio requires the Account SID in the URL path:
 
 ```typescript
 // WRONG - Missing account SID
-await twilio.apiRequest(
+await ctx.integrations.twilio.apiRequest(
   {
     method: "POST",
     path: "/Messages.json",
@@ -238,7 +239,7 @@ await twilio.apiRequest(
 );
 
 // CORRECT - Include account SID in path
-await twilio.apiRequest(
+await ctx.integrations.twilio.apiRequest(
   {
     method: "POST",
     path: `/2010-04-01/Accounts/${accountSid}/Messages.json`,
@@ -274,17 +275,10 @@ Use E.164 format for phone numbers:
 
 ```typescript
 // WRONG - Various formats
-const numbers = [
-  "(555) 123-4567",
-  "555-123-4567",
-  "5551234567",
-];
+const numbers = ["(555) 123-4567", "555-123-4567", "5551234567"];
 
 // CORRECT - E.164 format
-const numbers = [
-  "+15551234567",
-  "+442071234567",
-];
+const numbers = ["+15551234567", "+442071234567"];
 ```
 
 ### API Versions
@@ -307,7 +301,7 @@ const path = `/v2/Services/${serviceSid}/Verifications`;
 For delivery receipts, set a StatusCallback URL:
 
 ```typescript
-const result = await twilio.apiRequest(
+const result = await ctx.integrations.twilio.apiRequest(
   {
     method: "POST",
     path: `/2010-04-01/Accounts/${accountSid}/Messages.json`,
@@ -318,7 +312,7 @@ const result = await twilio.apiRequest(
       StatusCallback: "https://your-app.com/twilio/status",
     },
   },
-  { response: MessageResponseSchema }
+  { response: MessageResponseSchema },
 );
 ```
 
@@ -328,7 +322,7 @@ const result = await twilio.apiRequest(
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await twilio.apiRequest(
+  const result = await ctx.integrations.twilio.apiRequest(
     { method: "POST", path: `...`, body: { ... } },
     { response: MessageResponseSchema }
   );

package/src/integrations/twilio/client.ts

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

package/src/integrations/twilio/index.ts

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

package/src/integrations/twilio/types.ts

@@ -2,8 +2,8 @@
  * Twilio 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";
 
 /**
  * Twilio client for API interactions.
@@ -13,7 +13,8 @@ import type { SupportsApiRequest } from '../base/index.js';
  *
  * @example
  * ```typescript
- * const twilio = ctx.twilio('My Twilio');
+ * // Declare in api(): integrations: { twilio: twilio(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.twilio
  *
  * // Make API requests
  * const ResponseSchema = z.object({
@@ -29,6 +30,7 @@ import type { SupportsApiRequest } from '../base/index.js';
  * );
  * ```
  */
-export interface TwilioClient extends BaseIntegrationClient, SupportsApiRequest {
+export interface TwilioClient
+  extends BaseIntegrationClient, SupportsApiRequest {
   // apiRequest() method inherited from SupportsApiRequest
 }

package/src/integrations/types.ts

@@ -2,7 +2,7 @@
  * Base types for integration clients.
  */
 
-import type { BaseIntegrationClient } from '../types.js';
+import type { BaseIntegrationClient } from "../types.js";
 
 /**
  * Configuration for an integration, provided by the orchestrator at runtime.

package/src/integrations/utils.ts

@@ -10,15 +10,15 @@
  * @returns A type description string (e.g. "null", "object with keys [id, name]", "string")
  */
 export function describeType(value: unknown): string {
-  if (value === null) return 'null';
-  if (value === undefined) return 'undefined';
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
   if (Array.isArray(value)) return `array (length ${value.length})`;
 
   const t = typeof value;
-  if (t === 'object') {
+  if (t === "object") {
     const keys = Object.keys(value as Record<string, unknown>);
-    if (keys.length === 0) return 'empty object';
-    return `object with keys [${keys.slice(0, 5).join(', ')}${keys.length > 5 ? ', ...' : ''}]`;
+    if (keys.length === 0) return "empty object";
+    return `object with keys [${keys.slice(0, 5).join(", ")}${keys.length > 5 ? ", ..." : ""}]`;
   }
 
   return t;