@superblocksteam/sdk-api 2.0.101-next.0 → 2.0.101-next.1

package/src/integrations/restapiintegration/README.md

@@ -0,0 +1,359 @@
+# REST API Integration Client
+
+Make HTTP requests to any REST API configured with a base URL and authentication in the integrations page.
+
+This is the generic REST API Integration plugin. Unlike named integrations (Slack, GitHub, etc.) which target a specific service, this plugin works with **any** HTTP API you configure as an integration.
+
+## Methods
+
+| Method                                         | Description                                      |
+| ---------------------------------------------- | ------------------------------------------------ |
+| `apiRequest(options, schema, metadata?)`       | Make any HTTP request with schema validation     |
+| `streamApiRequest(options, schema, metadata?)` | Stream responses with real-time chunk validation |
+
+## Usage
+
+### Basic GET Request
+
+```typescript
+import { api, z, restApiIntegration } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const MY_API = "a1b2c3d4-5678-90ab-cdef-111111111111";
+
+const UsersResponseSchema = z.object({
+  users: z.array(
+    z.object({
+      id: z.string(),
+      name: z.string(),
+      email: z.string(),
+    }),
+  ),
+});
+
+export default api({
+  name: "FetchUsers",
+  integrations: {
+    myApi: restApiIntegration(MY_API),
+  },
+  input: z.object({}),
+  output: z.object({
+    users: z.array(
+      z.object({ id: z.string(), name: z.string(), email: z.string() }),
+    ),
+  }),
+  async run(ctx) {
+    const result = await ctx.integrations.myApi.apiRequest(
+      {
+        method: "GET",
+        path: "/users",
+        params: { limit: 50 },
+      },
+      { response: UsersResponseSchema },
+    );
+
+    return { users: result.users };
+  },
+});
+```
+
+### POST Request with Body
+
+```typescript
+const CreateRecordSchema = z.object({
+  id: z.string(),
+  created_at: z.string(),
+});
+
+const record = await ctx.integrations.myApi.apiRequest(
+  {
+    method: "POST",
+    path: "/records",
+    body: {
+      title: "New Record",
+      description: "Created via Superblocks",
+      tags: ["automated"],
+    },
+    headers: {
+      "Content-Type": "application/json",
+    },
+  },
+  { response: CreateRecordSchema },
+);
+
+console.log(`Created record: ${record.id}`);
+```
+
+### PATCH/PUT Request
+
+```typescript
+const UpdateResponseSchema = z.object({
+  id: z.string(),
+  updated_at: z.string(),
+});
+
+await ctx.integrations.myApi.apiRequest(
+  {
+    method: "PATCH",
+    path: `/records/${recordId}`,
+    body: {
+      title: "Updated Title",
+      status: "published",
+    },
+    headers: {
+      "Content-Type": "application/json",
+    },
+  },
+  { response: UpdateResponseSchema },
+);
+```
+
+### DELETE Request
+
+```typescript
+await ctx.integrations.myApi.apiRequest(
+  {
+    method: "DELETE",
+    path: `/records/${recordId}`,
+  },
+  { response: z.object({}).passthrough() },
+);
+```
+
+### Search with Query Parameters
+
+```typescript
+const SearchResponseSchema = z.object({
+  items: z.array(
+    z.object({
+      id: z.string(),
+      title: z.string(),
+      score: z.number().optional(),
+    }),
+  ),
+  total: z.number(),
+});
+
+const results = await ctx.integrations.myApi.apiRequest(
+  {
+    method: "GET",
+    path: "/search",
+    params: {
+      q: "my query",
+      page: 1,
+      per_page: 25,
+    },
+  },
+  { response: SearchResponseSchema },
+);
+
+console.log(`Found ${results.total} results`);
+```
+
+### Using Multiple Integrations
+
+You can use multiple REST API Integrations in a single API, each targeting a different service:
+
+```typescript
+import { api, z, restApiIntegration, postgres } from "@superblocksteam/sdk-api";
+
+const EXTERNAL_API = "a1b2c3d4-5678-90ab-cdef-111111111111";
+const INTERNAL_API = "e5f6a7b8-9012-34cd-ef56-222222222222";
+const MY_DB = "c3d4e5f6-7890-12ab-cdef-333333333333";
+
+export default api({
+  name: "SyncData",
+  integrations: {
+    externalApi: restApiIntegration(EXTERNAL_API),
+    internalApi: restApiIntegration(INTERNAL_API),
+    db: postgres(MY_DB),
+  },
+  input: z.object({ query: z.string() }),
+  output: z.object({ synced: z.number() }),
+  async run(ctx, { query }) {
+    // Fetch from external API
+    const external = await ctx.integrations.externalApi.apiRequest(
+      { method: "GET", path: "/data", params: { q: query } },
+      { response: z.object({ items: z.array(z.unknown()) }) },
+    );
+
+    // Push to internal API
+    await ctx.integrations.internalApi.apiRequest(
+      { method: "POST", path: "/import", body: { items: external.items } },
+      { response: z.object({ imported: z.number() }) },
+    );
+
+    return { synced: external.items.length };
+  },
+});
+```
+
+### Streaming Responses
+
+For APIs that return streaming data (e.g., Server-Sent Events), use `streamApiRequest()`:
+
+```typescript
+import { streamingApi, z, restApiIntegration } from "@superblocksteam/sdk-api";
+
+const MY_API = "a1b2c3d4-5678-90ab-cdef-111111111111";
+
+const StreamChunkSchema = z.object({
+  id: z.string(),
+  data: z.string(),
+});
+
+export default streamingApi({
+  integrations: {
+    myApi: restApiIntegration(MY_API),
+  },
+  input: z.object({ prompt: z.string() }),
+  chunk: z.object({ text: z.string() }),
+
+  async *run(ctx, { prompt }) {
+    const stream = ctx.integrations.myApi.streamApiRequest(
+      {
+        method: "POST",
+        path: "/stream",
+        body: { prompt },
+      },
+      { chunk: StreamChunkSchema },
+    );
+
+    for await (const chunk of stream) {
+      yield { text: chunk.data };
+    }
+  },
+});
+```
+
+## Trace Metadata
+
+All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling. See the [root SDK README](../../../README.md#trace-metadata) for details.
+
+```typescript
+const result = await ctx.integrations.myApi.apiRequest(
+  { method: "GET", path: "/users" },
+  { response: UsersResponseSchema },
+  { label: "myApi.getUsers", description: "Fetch all active users" },
+);
+```
+
+## Common Pitfalls
+
+### No `.request()` Method
+
+The only public methods are `apiRequest()` and `streamApiRequest()`. There is no `.request()` method:
+
+```typescript
+// WRONG - .request() does not exist
+await ctx.integrations.myApi.request({
+  method: "GET",
+  path: "/users",
+});
+
+// CORRECT - Use apiRequest with a response schema
+await ctx.integrations.myApi.apiRequest(
+  { method: "GET", path: "/users" },
+  { response: UsersResponseSchema },
+);
+```
+
+### Response Schema is Required
+
+`apiRequest()` requires a response schema for type safety:
+
+```typescript
+// WRONG - Missing response schema
+const result = await ctx.integrations.myApi.apiRequest({
+  method: "GET",
+  path: "/users",
+});
+
+// CORRECT - Provide a response schema
+const result = await ctx.integrations.myApi.apiRequest(
+  { method: "GET", path: "/users" },
+  { response: z.object({ users: z.array(z.unknown()) }) },
+);
+```
+
+### Use `body` Instead of `JSON.stringify`
+
+The `body` field is automatically serialized. Do not stringify it manually:
+
+```typescript
+// WRONG - Manual stringify
+await ctx.integrations.myApi.apiRequest(
+  {
+    method: "POST",
+    path: "/records",
+    body: JSON.stringify({ title: "New" }),
+  },
+  { response: ResponseSchema },
+);
+
+// CORRECT - Pass object directly
+await ctx.integrations.myApi.apiRequest(
+  {
+    method: "POST",
+    path: "/records",
+    body: { title: "New" },
+  },
+  { response: ResponseSchema },
+);
+```
+
+### Use `params` for Query Parameters
+
+Query parameters go in the `params` field, not in the URL path:
+
+```typescript
+// WRONG - Query params in path
+await ctx.integrations.myApi.apiRequest(
+  { method: "GET", path: "/search?q=hello&limit=10" },
+  { response: ResponseSchema },
+);
+
+// CORRECT - Use params field
+await ctx.integrations.myApi.apiRequest(
+  {
+    method: "GET",
+    path: "/search",
+    params: { q: "hello", limit: 10 },
+  },
+  { response: ResponseSchema },
+);
+```
+
+### Use `.passthrough()` for Flexible Schemas
+
+When the response contains fields you don't need to validate, use `.passthrough()`:
+
+```typescript
+// Strict schema - will reject unknown fields
+const StrictSchema = z.object({ id: z.string() });
+
+// Flexible schema - allows additional fields
+const FlexibleSchema = z.object({ id: z.string() }).passthrough();
+
+// For dynamic responses
+const GenericSchema = z.record(z.unknown());
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.myApi.apiRequest(
+    { method: "GET", path: "/users" },
+    { response: UsersResponseSchema },
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    // Response didn't match the schema
+    console.error("Validation failed:", error.details.zodError);
+    console.error("Actual response:", error.details.data);
+  }
+}
+```

package/src/integrations/s3/client.ts

@@ -4,13 +4,15 @@
  * Uses the native S3 plugin type from @superblocksteam/types.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as S3Plugin } from "@superblocksteam/types/dist/src/plugins/s3/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { RestApiValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import type {
   S3Client,
   S3Action,

package/src/integrations/s3/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 
@@ -129,7 +130,9 @@ export interface S3Client extends BaseIntegrationClient {
    *
    * @param bucket - Bucket name
    * @param path - Object key/path
-   * @param body - File content (base64 or text)
+   * @param body - String content stored verbatim (no base64 decoding is performed).
+   *   Suitable for plain text, JSON, or CSV. For binary files (PDF, DOCX, images),
+   *   use {@link S3Client.uploadMultipleObjects | uploadMultipleObjects} with file references instead.
    * @param metadata - Optional trace metadata for diagnostics
    */
   uploadObject(

package/src/integrations/salesforce/client.ts

@@ -6,10 +6,11 @@
  */
 
 import type { z } from "zod";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { QueryValidationError, RestApiValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import { describeType } from "../utils.js";
 import type { SalesforceClient } from "./types.js";
 

package/src/integrations/salesforce/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 

package/src/integrations/smtp/README.md

@@ -0,0 +1,220 @@
+# SMTP Client
+
+Send emails via SMTP with support for HTML content, CC/BCC, reply-to, and attachments.
+
+## Methods
+
+| Method                     | Description            |
+| -------------------------- | ---------------------- |
+| `send(options, metadata?)` | Send an email via SMTP |
+
+## Usage
+
+### Send a Simple Email
+
+```typescript
+import { api, z, smtp } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const MAILER = "a1b2c3d4-5678-90ab-cdef-111111111111";
+
+export default api({
+  name: "SendEmail",
+  integrations: {
+    mailer: smtp(MAILER),
+  },
+  input: z.object({
+    to: z.string(),
+    subject: z.string(),
+    body: z.string(),
+  }),
+  output: z.object({ success: z.boolean() }),
+
+  async run(ctx, { to, subject, body }) {
+    await ctx.integrations.mailer.send({
+      from: "noreply@example.com",
+      to,
+      subject,
+      body,
+    });
+
+    return { success: true };
+  },
+});
+```
+
+### Send HTML Email
+
+```typescript
+await ctx.integrations.mailer.send({
+  from: "noreply@example.com",
+  to: "user@example.com",
+  subject: "Welcome!",
+  body: "<h1>Welcome!</h1><p>Thank you for signing up.</p>",
+});
+```
+
+### Send with CC and BCC
+
+```typescript
+await ctx.integrations.mailer.send({
+  from: "noreply@example.com",
+  to: "user@example.com",
+  subject: "Team Update",
+  body: "Hello team!",
+  cc: "manager@example.com,lead@example.com",
+  bcc: "archive@example.com",
+  replyTo: "support@example.com",
+});
+```
+
+### Send to Multiple Recipients
+
+Use comma-separated email addresses:
+
+```typescript
+await ctx.integrations.mailer.send({
+  from: "noreply@example.com",
+  to: "user1@example.com,user2@example.com,user3@example.com",
+  subject: "Announcement",
+  body: "<p>Important update for the team.</p>",
+});
+```
+
+### Send with Attachments
+
+Attachments are passed as a JSON string containing an array of objects with `content` (base64-encoded), `name` (filename), and `type` (MIME type):
+
+```typescript
+const attachments = JSON.stringify([
+  {
+    content: base64EncodedPdf, // Base64-encoded file content
+    name: "report.pdf",
+    type: "application/pdf",
+  },
+  {
+    content: base64EncodedCsv,
+    name: "data.csv",
+    type: "text/csv",
+  },
+]);
+
+await ctx.integrations.mailer.send({
+  from: "reports@example.com",
+  to: "user@example.com",
+  subject: "Your Report",
+  body: "<p>Please find the attached report.</p>",
+  attachments,
+});
+```
+
+## Trace Metadata
+
+The `send` method accepts an optional `metadata` parameter as the last argument for diagnostics labeling:
+
+```typescript
+await ctx.integrations.mailer.send(
+  {
+    from: "noreply@example.com",
+    to: "user@example.com",
+    subject: "Welcome",
+    body: "Hello!",
+  },
+  { label: "Send welcome email" },
+);
+```
+
+When `includeDiagnostics` is enabled, `label` and `description` appear in the trace view. See the [root SDK README](../../../README.md#trace-metadata) for details.
+
+## Send Options Reference
+
+| Option        | Type     | Required | Description                                   |
+| ------------- | -------- | -------- | --------------------------------------------- |
+| `from`        | `string` | Yes      | Sender email address                          |
+| `to`          | `string` | Yes      | Recipient(s), comma-separated for multiple    |
+| `subject`     | `string` | Yes      | Email subject line                            |
+| `body`        | `string` | Yes      | Email body (HTML or plain text)               |
+| `cc`          | `string` | No       | CC recipient(s), comma-separated              |
+| `bcc`         | `string` | No       | BCC recipient(s), comma-separated             |
+| `replyTo`     | `string` | No       | Reply-to email address                        |
+| `attachments` | `string` | No       | JSON array of `{content, name, type}` objects |
+
+## Common Pitfalls
+
+### Use the `send` Method, Not `apiRequest`
+
+Unlike most integrations, SMTP has a dedicated `send()` method:
+
+```typescript
+// WRONG - apiRequest does not exist on SmtpClient
+await ctx.integrations.mailer.apiRequest({ ... });
+
+// CORRECT - Use send()
+await ctx.integrations.mailer.send({
+  from: "noreply@example.com",
+  to: "user@example.com",
+  subject: "Hello",
+  body: "World",
+});
+```
+
+### Attachments Must Be a JSON String
+
+```typescript
+// WRONG - Passing an array directly
+await ctx.integrations.mailer.send({
+  from: "noreply@example.com",
+  to: "user@example.com",
+  subject: "Report",
+  body: "See attached",
+  attachments: [{ content: "...", name: "file.pdf", type: "application/pdf" }],
+});
+
+// CORRECT - JSON.stringify the array
+await ctx.integrations.mailer.send({
+  from: "noreply@example.com",
+  to: "user@example.com",
+  subject: "Report",
+  body: "See attached",
+  attachments: JSON.stringify([
+    { content: "...", name: "file.pdf", type: "application/pdf" },
+  ]),
+});
+```
+
+### Multiple Recipients Use Comma Separation
+
+```typescript
+// WRONG - Array of recipients
+await ctx.integrations.mailer.send({
+  to: ["user1@example.com", "user2@example.com"],
+  // ...
+});
+
+// CORRECT - Comma-separated string
+await ctx.integrations.mailer.send({
+  to: "user1@example.com,user2@example.com",
+  // ...
+});
+```
+
+## Error Handling
+
+```typescript
+import { IntegrationError } from "@superblocksteam/sdk-api";
+
+try {
+  await ctx.integrations.mailer.send({
+    from: "noreply@example.com",
+    to: "user@example.com",
+    subject: "Test",
+    body: "Hello",
+  });
+} catch (error) {
+  if (error instanceof IntegrationError) {
+    console.error(
+      `SMTP error in ${error.integrationName}.${error.method}: ${error.message}`,
+    );
+  }
+}
+```

package/src/integrations/smtp/client.ts

@@ -6,10 +6,12 @@
  */
 
 import type { PartialMessage } from "@bufbuild/protobuf";
+
 import type { Plugin as SmtpPlugin } from "@superblocksteam/types/dist/src/plugins/smtp/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import type { SmtpClient, SmtpSendOptions } from "./types.js";
 
 /**

package/src/integrations/snowflake/client.ts

@@ -5,13 +5,15 @@
  * runtime validation using Zod schemas.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as SnowflakePlugin } from "@superblocksteam/types/dist/src/plugins/snowflake/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { QueryValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import { describeType } from "../utils.js";
 import type { SnowflakeClient } from "./types.js";
 

package/src/integrations/snowflake/types.ts

@@ -5,6 +5,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types";
 import type { TraceMetadata } from "../registry.js";