@superblocksteam/sdk-api 2.0.89-next.0

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

@@ -0,0 +1,8 @@
+/**
+ * Superblocks OCR integration client.
+ *
+ * @module
+ */
+
+export type { SuperblocksOCRClient } from './types.js';
+export { SuperblocksOCRClientImpl } from './client.js';

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

@@ -0,0 +1,38 @@
+/**
+ * Superblocks OCR client types.
+ */
+
+import type { BaseIntegrationClient } from '../../types.js';
+import type { SupportsApiRequest } from '../base/index.js';
+
+/**
+ * Superblocks OCR client for API interactions.
+ *
+ * Provides generic API request method for interacting with Superblocks OCR service.
+ * Use apiRequest() to make calls to any OCR API endpoint.
+ *
+ * @example
+ * ```typescript
+ * const ocr = ctx.superblocksOcr('Production OCR');
+ *
+ * // Extract text from image
+ * const OCRResponseSchema = z.object({
+ *   text: z.string(),
+ *   confidence: z.number(),
+ * });
+ *
+ * const result = await ocr.apiRequest(
+ *   {
+ *     method: 'POST',
+ *     path: '/extract',
+ *     body: {
+ *       imageUrl: 'https://example.com/image.png',
+ *     },
+ *   },
+ *   { response: OCRResponseSchema }
+ * );
+ * ```
+ */
+export interface SuperblocksOCRClient extends BaseIntegrationClient, SupportsApiRequest {
+  // apiRequest() method inherited from SupportsApiRequest
+}

package/src/integrations/twilio/README.md

@@ -0,0 +1,348 @@
+# Twilio Client
+
+Send SMS messages, make calls, and interact with Twilio's communication APIs.
+
+## Methods
+
+| Method | Description |
+| ------ | ----------- |
+| `apiRequest(options, schema)` | Make any Twilio API request with schema validation |
+
+## Usage
+
+### Send an SMS
+
+```typescript
+import { api, z } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_TWILIO = "a1b2c3d4-5678-90ab-cdef-twilio000001";
+
+const MessageResponseSchema = z.object({
+  sid: z.string(),
+  date_created: z.string(),
+  date_updated: z.string(),
+  date_sent: z.string().nullable(),
+  account_sid: z.string(),
+  to: z.string(),
+  from: z.string(),
+  body: z.string(),
+  status: z.string(),
+  direction: z.string(),
+  price: z.string().nullable(),
+  price_unit: z.string().nullable(),
+});
+
+export default api({
+  name: "TwilioExample",
+  input: z.object({
+    to: z.string(),
+    message: z.string(),
+  }),
+  output: z.object({
+    messageSid: z.string(),
+    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(
+      {
+        method: "POST",
+        path: `/2010-04-01/Accounts/${accountSid}/Messages.json`,
+        body: {
+          To: to,
+          From: "+15551234567", // Your Twilio phone number
+          Body: message,
+        },
+      },
+      { response: MessageResponseSchema }
+    );
+
+    return { messageSid: result.sid, status: result.status };
+  },
+});
+```
+
+### Send MMS (with Media)
+
+```typescript
+const result = await twilio.apiRequest(
+  {
+    method: "POST",
+    path: `/2010-04-01/Accounts/${accountSid}/Messages.json`,
+    body: {
+      To: "+15559876543",
+      From: "+15551234567",
+      Body: "Check out this image!",
+      MediaUrl: "https://example.com/image.jpg",
+    },
+  },
+  { response: MessageResponseSchema }
+);
+```
+
+### List Messages
+
+```typescript
+const ListMessagesResponseSchema = z.object({
+  messages: z.array(MessageResponseSchema),
+  uri: z.string(),
+  first_page_uri: z.string(),
+  next_page_uri: z.string().nullable(),
+  previous_page_uri: z.string().nullable(),
+  page: z.number(),
+  page_size: z.number(),
+});
+
+const result = await twilio.apiRequest(
+  {
+    method: "GET",
+    path: `/2010-04-01/Accounts/${accountSid}/Messages.json`,
+    params: {
+      PageSize: 50,
+      To: "+15559876543", // Filter by recipient
+    },
+  },
+  { response: ListMessagesResponseSchema }
+);
+
+result.messages.forEach((msg) => {
+  console.log(`${msg.from} -> ${msg.to}: ${msg.body}`);
+});
+```
+
+### Make a Voice Call
+
+```typescript
+const CallResponseSchema = z.object({
+  sid: z.string(),
+  date_created: z.string(),
+  date_updated: z.string(),
+  account_sid: z.string(),
+  to: z.string(),
+  from: z.string(),
+  status: z.string(),
+  direction: z.string(),
+  duration: z.string().nullable(),
+  price: z.string().nullable(),
+});
+
+const result = await twilio.apiRequest(
+  {
+    method: "POST",
+    path: `/2010-04-01/Accounts/${accountSid}/Calls.json`,
+    body: {
+      To: "+15559876543",
+      From: "+15551234567",
+      Url: "http://demo.twilio.com/docs/voice.xml", // TwiML URL
+    },
+  },
+  { response: CallResponseSchema }
+);
+
+console.log(`Call SID: ${result.sid}, Status: ${result.status}`);
+```
+
+### Lookup Phone Number
+
+```typescript
+const LookupResponseSchema = z.object({
+  calling_country_code: z.string(),
+  country_code: z.string(),
+  phone_number: z.string(),
+  national_format: z.string(),
+  valid: z.boolean(),
+  caller_name: z
+    .object({
+      caller_name: z.string().nullable(),
+      caller_type: z.string().nullable(),
+    })
+    .nullable()
+    .optional(),
+  carrier: z
+    .object({
+      name: z.string().nullable(),
+      type: z.string().nullable(),
+      mobile_country_code: z.string().nullable(),
+      mobile_network_code: z.string().nullable(),
+    })
+    .nullable()
+    .optional(),
+});
+
+const result = await twilio.apiRequest(
+  {
+    method: "GET",
+    path: `/v2/PhoneNumbers/+15559876543`,
+    params: {
+      Fields: "carrier,caller_name",
+    },
+  },
+  { response: LookupResponseSchema }
+);
+
+console.log(`Number: ${result.national_format}, Valid: ${result.valid}`);
+if (result.carrier) {
+  console.log(`Carrier: ${result.carrier.name}`);
+}
+```
+
+### Get Message Status
+
+```typescript
+const result = await twilio.apiRequest(
+  {
+    method: "GET",
+    path: `/2010-04-01/Accounts/${accountSid}/Messages/${messageSid}.json`,
+  },
+  { response: MessageResponseSchema }
+);
+
+console.log(`Message status: ${result.status}`);
+// Statuses: queued, sending, sent, delivered, undelivered, failed
+```
+
+## Common Pitfalls
+
+### No Specialized Methods
+
+```typescript
+// WRONG - These methods do not exist
+await twilio.sendSms({ ... });
+await twilio.makeCall({ ... });
+
+// CORRECT - Use apiRequest
+await twilio.apiRequest(
+  { method: "POST", path: `/2010-04-01/Accounts/${accountSid}/Messages.json`, body: { ... } },
+  { response: MessageResponseSchema }
+);
+```
+
+### Account SID in URL Path
+
+Twilio requires the Account SID in the URL path:
+
+```typescript
+// WRONG - Missing account SID
+await twilio.apiRequest(
+  {
+    method: "POST",
+    path: "/Messages.json",
+    body: { ... },
+  },
+  { response: schema }
+);
+
+// CORRECT - Include account SID in path
+await twilio.apiRequest(
+  {
+    method: "POST",
+    path: `/2010-04-01/Accounts/${accountSid}/Messages.json`,
+    body: { ... },
+  },
+  { response: schema }
+);
+```
+
+### Parameter Naming (PascalCase)
+
+Twilio uses PascalCase for parameters:
+
+```typescript
+// WRONG - lowercase parameters
+const body = {
+  to: "+15559876543",
+  from: "+15551234567",
+  body: "Hello",
+};
+
+// CORRECT - PascalCase parameters
+const body = {
+  To: "+15559876543",
+  From: "+15551234567",
+  Body: "Hello",
+};
+```
+
+### Phone Number Format
+
+Use E.164 format for phone numbers:
+
+```typescript
+// WRONG - Various formats
+const numbers = [
+  "(555) 123-4567",
+  "555-123-4567",
+  "5551234567",
+];
+
+// CORRECT - E.164 format
+const numbers = [
+  "+15551234567",
+  "+442071234567",
+];
+```
+
+### API Versions
+
+Different APIs use different path prefixes:
+
+```typescript
+// Messaging/Voice API (older)
+const path = `/2010-04-01/Accounts/${accountSid}/Messages.json`;
+
+// Lookup API (v2)
+const path = `/v2/PhoneNumbers/${phoneNumber}`;
+
+// Verify API (v2)
+const path = `/v2/Services/${serviceSid}/Verifications`;
+```
+
+### Message Status Callbacks
+
+For delivery receipts, set a StatusCallback URL:
+
+```typescript
+const result = await twilio.apiRequest(
+  {
+    method: "POST",
+    path: `/2010-04-01/Accounts/${accountSid}/Messages.json`,
+    body: {
+      To: "+15559876543",
+      From: "+15551234567",
+      Body: "Hello",
+      StatusCallback: "https://your-app.com/twilio/status",
+    },
+  },
+  { response: MessageResponseSchema }
+);
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await twilio.apiRequest(
+    { method: "POST", path: `...`, body: { ... } },
+    { response: MessageResponseSchema }
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  }
+}
+```
+
+## API Reference
+
+- [Twilio API Documentation](https://www.twilio.com/docs/api)
+- [Send SMS](https://www.twilio.com/docs/sms/api/message-resource)
+- [Make Calls](https://www.twilio.com/docs/voice/api/call-resource)
+- [Lookup API](https://www.twilio.com/docs/lookup/v2-api)
+- [Error Codes](https://www.twilio.com/docs/api/errors)

package/src/integrations/twilio/client.ts

@@ -0,0 +1,21 @@
+/**
+ * Twilio client implementation.
+ *
+ * Uses the proto-generated REST API Integration Plugin type from @superblocksteam/types.
+ * Twilio integrations use the REST API Integration plugin under the hood.
+ */
+
+import { RestApiIntegrationClient } from '../base/index.js';
+import type { TwilioClient } from './types.js';
+
+/**
+ * Internal implementation of TwilioClient.
+ *
+ * Extends RestApiIntegrationClient to inherit the generic apiRequest() method.
+ * This implementation communicates with the orchestrator to execute
+ * Twilio API calls. At runtime, the orchestrator handles authentication
+ * and API request execution.
+ */
+export class TwilioClientImpl extends RestApiIntegrationClient implements TwilioClient {
+  // Inherits: name, pluginId, config, executeQuery, apiRequest()
+}

package/src/integrations/twilio/index.ts

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

package/src/integrations/twilio/types.ts

@@ -0,0 +1,34 @@
+/**
+ * Twilio client types.
+ */
+
+import type { BaseIntegrationClient } from '../../types.js';
+import type { SupportsApiRequest } from '../base/index.js';
+
+/**
+ * Twilio client for API interactions.
+ *
+ * Provides generic API request method for interacting with Twilio's API.
+ * Use apiRequest() to make calls to any Twilio API endpoint.
+ *
+ * @example
+ * ```typescript
+ * const twilio = ctx.twilio('My Twilio');
+ *
+ * // Make API requests
+ * const ResponseSchema = z.object({
+ *   // Define your response schema
+ * });
+ *
+ * const result = await twilio.apiRequest(
+ *   {
+ *     method: 'POST',
+ *     path: '/2010-04-01/Accounts/{AccountSid}/Messages.json',
+ *   },
+ *   { response: ResponseSchema }
+ * );
+ * ```
+ */
+export interface TwilioClient extends BaseIntegrationClient, SupportsApiRequest {
+  // apiRequest() method inherited from SupportsApiRequest
+}

package/src/integrations/types.ts

@@ -0,0 +1,40 @@
+/**
+ * Base types for integration clients.
+ */
+
+import type { BaseIntegrationClient } from '../types.js';
+
+/**
+ * Configuration for an integration, provided by the orchestrator at runtime.
+ */
+export interface IntegrationConfig {
+  /** Unique integration ID */
+  id: string;
+
+  /** User-defined integration name (e.g., "Production Postgres") */
+  name: string;
+
+  /** Plugin type ID (e.g., "postgres", "slack") */
+  pluginId: string;
+
+  /** OAuth or other auth token (injected by orchestrator) */
+  authToken?: string;
+
+  /** Plugin-specific configuration (connection details, etc.) */
+  configuration: Record<string, unknown>;
+}
+
+/**
+ * Interface that all integration client implementations must satisfy.
+ */
+export interface IntegrationClientImpl extends BaseIntegrationClient {
+  /** The integration configuration */
+  readonly config: IntegrationConfig;
+}
+
+/**
+ * Factory function type for creating integration clients.
+ */
+export type IntegrationClientFactory = (
+  config: IntegrationConfig,
+) => IntegrationClientImpl;

package/src/integrations/utils.ts

@@ -0,0 +1,25 @@
+/**
+ * Integration utility functions.
+ */
+
+/**
+ * Produces a safe, human-readable description of a value's type
+ * without exposing potentially sensitive data.
+ *
+ * @param value - The value to describe
+ * @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 (Array.isArray(value)) return `array (length ${value.length})`;
+
+  const t = typeof value;
+  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 ? ', ...' : ''}]`;
+  }
+
+  return t;
+}