@superblocksteam/sdk-api 0.0.12-body-types → 0.0.13

package/src/integrations/elasticsearch/overlays/bulk-unsupported.md

@@ -0,0 +1,3 @@
+## Bulk Operations
+
+This agent's sdk-api cannot call `/_bulk` through `apiRequest()` because it serializes every body as JSON, and the bulk API requires newline-delimited JSON. Do not generate bulk code until the agent is upgraded; index, update, or delete documents one call at a time as documented above.

package/src/integrations/elasticsearch/overlays/bulk.md

@@ -0,0 +1,80 @@
+## Bulk Operations
+
+`/_bulk` expects newline-delimited JSON, so pass `bodyType: "raw"` with the pre-built NDJSON string and set `Content-Type: application/x-ndjson`. Raw mode adds no headers of its own. Without `bodyType`, `apiRequest()` would JSON-encode the string a second time and Elasticsearch would reject it.
+
+Bulk operations require the request bodies to be newline-delimited JSON, not a JSON array:
+
+```typescript
+// WRONG - Regular JSON array
+const body = [{ index: { _index: "products" } }, { name: "Product" }];
+
+// CORRECT - Newline-delimited JSON
+const body = '{"index":{"_index":"products"}}\n{"name":"Product"}\n';
+
+// Or build programmatically
+const operations = [{ index: { _index: "products" } }, { name: "Product" }];
+const body = operations.map(JSON.stringify).join("\n") + "\n";
+```
+
+```typescript
+const BulkResponseSchema = z.object({
+  took: z.number(),
+  errors: z.boolean(),
+  items: z.array(
+    z.object({
+      index: z
+        .object({
+          _index: z.string(),
+          _id: z.string(),
+          status: z.number(),
+          result: z.string().optional(),
+          error: z
+            .object({
+              type: z.string(),
+              reason: z.string(),
+            })
+            .optional(),
+        })
+        .optional(),
+      delete: z
+        .object({
+          _index: z.string(),
+          _id: z.string(),
+          status: z.number(),
+          result: z.string().optional(),
+        })
+        .optional(),
+    }),
+  ),
+});
+
+// Bulk index
+const result = await ctx.integrations.es.apiRequest(
+  {
+    method: "POST",
+    path: "/_bulk",
+    headers: {
+      "Content-Type": "application/x-ndjson",
+    },
+    bodyType: "raw",
+    body:
+      [
+        { index: { _index: "products", _id: "1" } },
+        { name: "Product 1", price: 10 },
+        { index: { _index: "products", _id: "2" } },
+        { name: "Product 2", price: 20 },
+      ]
+        .map(JSON.stringify)
+        .join("\n") + "\n",
+  },
+  { response: BulkResponseSchema },
+);
+
+if (result.errors) {
+  result.items.forEach((item) => {
+    if (item.index?.error) {
+      console.error(`Failed to index: ${item.index.error.reason}`);
+    }
+  });
+}
+```

package/src/integrations/gcs/client.ts

@@ -9,7 +9,10 @@ import type { z } from "zod";
 
 import type { Plugin as GCSPlugin } from "@superblocksteam/types/dist/src/plugins/gcs/v1/plugin_pb";
 
-import { RestApiValidationError } from "../../errors.js";
+import {
+  RestApiValidationError,
+  restApiValidationErrorFromZodError,
+} from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
 import type { QueryExecutor, TraceMetadata } from "../registry.js";
 import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
@@ -71,12 +74,10 @@ export class GCSClientImpl implements GCSClient, IntegrationClientImpl {
     const parseResult = schema.safeParse(result);
 
     if (!parseResult.success) {
-      throw new RestApiValidationError(
-        `Result validation failed: ${parseResult.error.message}`,
-        {
-          zodError: parseResult.error,
-          data: result,
-        },
+      throw restApiValidationErrorFromZodError(
+        "Result validation failed",
+        parseResult.error,
+        result,
       );
     }
 

package/src/integrations/googledrive/README.md

@@ -1,6 +1,6 @@
 # Google Drive Client
 
-Upload, download, and manage files in Google Drive.
+Download and manage files in Google Drive. File content uploads are not available through this integration; see [File Content Uploads Are Not Available](#file-content-uploads-are-not-available).
 
 ## Methods
 
@@ -162,32 +162,6 @@ const folder = await ctx.integrations.drive.apiRequest(
 console.log(`Created folder: ${folder.id}`);
 ```
 
-### Upload a File
-
-```typescript
-// For simple uploads (< 5MB)
-const uploadedFile = await ctx.integrations.drive.apiRequest(
-  {
-    method: "POST",
-    path: "/upload/drive/v3/files",
-    params: {
-      uploadType: "multipart",
-    },
-    body: {
-      metadata: {
-        name: "report.txt",
-        parents: [folderId],
-      },
-      media: {
-        mimeType: "text/plain",
-        body: "File content here",
-      },
-    },
-  },
-  { response: FileSchema },
-);
-```
-
 ### Update File Metadata
 
 ```typescript
@@ -300,7 +274,7 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 ```typescript
 // WRONG - These methods do not exist
 await drive.listFiles({ ... });
-await drive.uploadFile({ ... });
+await drive.createFolder({ ... });
 
 // CORRECT - Use apiRequest
 await ctx.integrations.drive.apiRequest(
@@ -394,21 +368,22 @@ const sizeBytes = parseInt(file.size, 10);
 const sizeMB = sizeBytes / (1024 * 1024);
 ```
 
-### Upload Path vs Regular Path
+### Base URL Prefix
 
-The base URL already includes `/drive/v3`, so regular API paths omit this prefix. However, uploads use a different URL root (`/upload/drive/v3/...` instead of `/drive/v3/...`) and require the full path:
+The base URL already includes `/drive/v3`, so regular API paths omit this prefix:
 
 ```typescript
-// Regular API calls (base URL already has /drive/v3)
+// CORRECT - base URL already has /drive/v3
 const path = "/files";
 
-// Upload calls use a different URL root — include the full path
-const path = "/upload/drive/v3/files";
-
-// WRONG - Duplicates base URL prefix for regular calls
+// WRONG - duplicates the base URL prefix
 const path = "/drive/v3/files";
 ```
 
+### File Content Uploads Are Not Available
+
+Google Drive serves every content upload endpoint (`uploadType=media`, `multipart`, and `resumable`) from `https://www.googleapis.com/upload/drive/v3`. This integration's base URL is fixed by the Google Drive integration template to `https://www.googleapis.com/drive/v3`, and `apiRequest` cannot target another URL root, so a path such as `/upload/drive/v3/files` resolves to `https://www.googleapis.com/drive/v3/upload/drive/v3/files` and fails. Do not generate content upload code for this integration. Metadata-only creation through `POST /files` (for example, creating a folder) works. If an app must upload file content to Drive, ask the user to configure a REST API integration with base URL `https://www.googleapis.com/upload/drive/v3` using the same OAuth client, then call it through that integration.
+
 ### Folder MIME Type
 
 Folders have a special MIME type:
@@ -481,4 +456,3 @@ try {
 - [Google Drive API Documentation](https://developers.google.com/drive/api/reference/rest/v3)
 - [Files Resource](https://developers.google.com/drive/api/reference/rest/v3/files)
 - [Query String Syntax](https://developers.google.com/drive/api/guides/search-files)
-- [Upload Files](https://developers.google.com/drive/api/guides/manage-uploads)

package/src/integrations/gsheets/client.ts

@@ -9,7 +9,10 @@ import type { z } from "zod";
 
 import type { Plugin as GSheetsPlugin } from "@superblocksteam/types/dist/src/plugins/gsheets/v1/plugin_pb";
 
-import { RestApiValidationError } from "../../errors.js";
+import {
+  RestApiValidationError,
+  restApiValidationErrorFromZodError,
+} from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
 import type { QueryExecutor, TraceMetadata } from "../registry.js";
 import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
@@ -113,12 +116,10 @@ export class GoogleSheetsClientImpl
       const parseResult = schema.safeParse(result);
 
       if (!parseResult.success) {
-        throw new RestApiValidationError(
-          `Result validation failed: ${parseResult.error.message}`,
-          {
-            zodError: parseResult.error,
-            data: result,
-          },
+        throw restApiValidationErrorFromZodError(
+          "Result validation failed",
+          parseResult.error,
+          result,
         );
       }
 

package/src/integrations/index.ts

@@ -363,6 +363,7 @@ export { MongoDBClientImpl } from "./mongodb/index.js";
 export type {
   DynamoDBClient,
   DynamoDBAttributeValue,
+  DynamoDBScanOptions,
 } from "./dynamodb/index.js";
 export { DynamoDBClientImpl } from "./dynamodb/index.js";
 

package/src/integrations/jira/README.md

@@ -259,32 +259,6 @@ const result = await ctx.integrations.jira.apiRequest(
 );
 ```
 
-### Add Attachment
-
-```typescript
-// Note: Attachments require multipart/form-data
-// The body should be the file content
-const AttachmentResponseSchema = z.array(
-  z.object({
-    id: z.string(),
-    filename: z.string(),
-    size: z.number(),
-  }),
-);
-
-const result = await ctx.integrations.jira.apiRequest(
-  {
-    method: "POST",
-    path: `/rest/api/3/issue/${issueKey}/attachments`,
-    headers: {
-      "X-Atlassian-Token": "no-check",
-    },
-    body: fileContent, // Multipart form data
-  },
-  { response: AttachmentResponseSchema },
-);
-```
-
 ## 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.

package/src/integrations/jira/docs.manifest.json

@@ -1,5 +1,14 @@
 {
   "pluginId": "jira",
   "base": "README.md",
-  "overlays": []
+  "overlays": [
+    {
+      "file": "overlays/attachments.md",
+      "sdkVersionRange": ">=0.0.7"
+    },
+    {
+      "file": "overlays/attachments-unsupported.md",
+      "sdkVersionRange": "<0.0.7"
+    }
+  ]
 }

package/src/integrations/jira/overlays/attachments-unsupported.md

@@ -0,0 +1,3 @@
+## Add Attachment
+
+This agent's sdk-api cannot upload Jira attachments through `apiRequest()` because it serializes every body as JSON. Do not generate attachment upload code until the agent is upgraded.

package/src/integrations/jira/overlays/attachments.md

@@ -0,0 +1,30 @@
+## Add Attachment
+
+Attachments are multipart uploads, so pass `bodyType: "multipartForm"` and the `X-Atlassian-Token: no-check` header.
+
+```typescript
+const AttachmentResponseSchema = z.array(
+  z.object({
+    id: z.string(),
+    filename: z.string(),
+    size: z.number(),
+  }),
+);
+
+const file = input.upload.files[0];
+
+const result = await ctx.integrations.jira.apiRequest(
+  {
+    method: "POST",
+    path: `/rest/api/3/issue/${issueKey}/attachments`,
+    headers: { "X-Atlassian-Token": "no-check" },
+    bodyType: "multipartForm",
+    body: {
+      file: { value: await file.readContentsAsync("raw"), filename: file.name },
+    },
+  },
+  { response: AttachmentResponseSchema },
+);
+```
+
+Do not set `Content-Type`. The worker generates the multipart boundary.

package/src/integrations/mongodb/client.ts

@@ -9,7 +9,10 @@ import type { z } from "zod";
 
 import type { Plugin as MongoDBPlugin } from "@superblocksteam/types/dist/src/plugins/mongodb/v1/plugin_pb";
 
-import { RestApiValidationError } from "../../errors.js";
+import {
+  RestApiValidationError,
+  restApiValidationErrorFromZodError,
+} from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
 import type { QueryExecutor, TraceMetadata } from "../registry.js";
 import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
@@ -115,12 +118,10 @@ export class MongoDBClientImpl implements MongoDBClient, IntegrationClientImpl {
       const parseResult = schema.safeParse(result);
 
       if (!parseResult.success) {
-        throw new RestApiValidationError(
-          `Result validation failed: ${parseResult.error.message}`,
-          {
-            zodError: parseResult.error,
-            data: result,
-          },
+        throw restApiValidationErrorFromZodError(
+          "Result validation failed",
+          parseResult.error,
+          result,
         );
       }
 

package/src/integrations/restapiintegration/client.body-types.test.ts

@@ -1,7 +1,10 @@
 import { describe, expect, it, vi } from "vitest";
 import { z } from "zod";
 
-import { RestApiValidationError } from "../../errors.js";
+import {
+  REDACTED_BINARY_RESPONSE_DATA,
+  RestApiValidationError,
+} from "../../errors.js";
 import type { IntegrationConfig } from "../types.js";
 import { RestApiIntegrationPluginClientImpl } from "./client.js";
 
@@ -94,49 +97,51 @@ describe("RestApiIntegrationPluginClientImpl request body types", () => {
     );
   });
 
-  it("sends binary bodies as base64 binaryBody with default Content-Type", async () => {
-    const bytes = Uint8Array.from([137, 80, 78, 71]);
+  it("appends the injected Content-Type after caller headers", async () => {
     const { client, executeQuery } = createClient();
     await client.apiRequest(
       {
-        method: "PUT",
-        path: "/files/report.png",
-        body: bytes,
-        bodyType: "binary",
+        method: "POST",
+        path: "/charges",
+        headers: { Authorization: "Bearer x" },
+        body: { amount: 2000 },
+        bodyType: "formUrlencoded",
       },
       { response: JsonResponseSchema },
     );
     expect(executeQuery).toHaveBeenCalledWith(
       expect.objectContaining({
-        body: Buffer.from(bytes).toString("base64"),
-        bodyType: "binaryBody",
-        headers: [{ key: "Content-Type", value: "application/octet-stream" }],
+        headers: [
+          { key: "Authorization", value: "Bearer x" },
+          { key: "Content-Type", value: "application/x-www-form-urlencoded" },
+        ],
       }),
       undefined,
       undefined,
     );
   });
 
-  it("sends text multipart file parts as formData", async () => {
+  it("keeps a caller Content-Type of any case and injects nothing", async () => {
     const { client, executeQuery } = createClient();
     await client.apiRequest(
       {
         method: "POST",
-        path: "/upload",
-        body: {
-          note: "hello",
-          file: { value: "contents", filename: "note.txt" },
+        path: "/charges",
+        headers: {
+          "content-type": "application/x-www-form-urlencoded; charset=utf-8",
         },
-        bodyType: "multipartForm",
+        body: { amount: 2000 },
+        bodyType: "formUrlencoded",
       },
       { response: JsonResponseSchema },
     );
     expect(executeQuery).toHaveBeenCalledWith(
       expect.objectContaining({
-        bodyType: "formData",
-        formData: [
-          { key: "note", value: "hello" },
-          { key: "file", value: "contents", file: { filename: "note.txt" } },
+        headers: [
+          {
+            key: "content-type",
+            value: "application/x-www-form-urlencoded; charset=utf-8",
+          },
         ],
       }),
       undefined,
@@ -144,14 +149,41 @@ describe("RestApiIntegrationPluginClientImpl request body types", () => {
     );
   });
 
-  it("sends mixed multipart file parts as formDataBase64 with no top-level body", async () => {
+  it("sends binary bodies as base64 binaryBody with default Content-Type", async () => {
+    const bytes = Uint8Array.from([137, 80, 78, 71]);
+    const { client, executeQuery } = createClient();
+    await client.apiRequest(
+      {
+        method: "PUT",
+        path: "/files/report.png",
+        body: bytes,
+        bodyType: "binary",
+      },
+      { response: JsonResponseSchema },
+    );
+    expect(executeQuery).toHaveBeenCalledWith(
+      expect.objectContaining({
+        body: expect.any(String),
+        bodyType: "binaryBody",
+        headers: [{ key: "Content-Type", value: "application/octet-stream" }],
+      }),
+      undefined,
+      undefined,
+    );
+  });
+
+  it("sends multipart bodies as formDataBase64 with base64 file parts and no top-level body", async () => {
     const bytes = Uint8Array.from([137, 80, 78, 71]);
     const { client, executeQuery } = createClient();
     await client.apiRequest(
       {
         method: "POST",
         path: "/upload",
-        body: { note: "mixed", image: { value: bytes, filename: "b.png" } },
+        body: {
+          note: "mixed",
+          file: { value: "contents", filename: "note.txt" },
+          image: { value: bytes, filename: "b.png" },
+        },
         bodyType: "multipartForm",
       },
       { response: JsonResponseSchema },
@@ -161,11 +193,14 @@ describe("RestApiIntegrationPluginClientImpl request body types", () => {
         bodyType: "formDataBase64",
         formData: [
           { key: "note", value: "mixed" },
-          {
+          expect.objectContaining({
+            key: "file",
+            file: { filename: "note.txt" },
+          }),
+          expect.objectContaining({
             key: "image",
-            value: Buffer.from(bytes).toString("base64"),
             file: { filename: "b.png" },
-          },
+          }),
         ],
       }),
       undefined,
@@ -197,7 +232,6 @@ describe("RestApiIntegrationPluginClientImpl request body types", () => {
 
     const invalidCases = [
       { method: "POST", path: "/bad", body: Uint8Array.from([1]) },
-      { method: "POST", path: "/bad", body: () => undefined },
       { method: "POST", path: "/bad", bodyType: "raw" },
       { method: "POST", path: "/bad", bodyType: "formUrlencoded" },
       { method: "POST", path: "/bad", bodyType: "multipartForm" },
@@ -211,4 +245,79 @@ describe("RestApiIntegrationPluginClientImpl request body types", () => {
       expect(executeQuery).not.toHaveBeenCalled();
     }
   });
+
+  it("redacts request bodies that contain binary from bodySchema validation errors", async () => {
+    const bytes = Uint8Array.from([1, 2, 3, 4]);
+    const binaryBodies: {
+      body: unknown;
+      bodyType: string;
+      expectedData: unknown;
+    }[] = [
+      {
+        body: bytes,
+        bodyType: "binary",
+        expectedData: REDACTED_BINARY_RESPONSE_DATA,
+      },
+      {
+        body: bytes.buffer,
+        bodyType: "binary",
+        expectedData: REDACTED_BINARY_RESPONSE_DATA,
+      },
+      {
+        body: { file: { value: bytes, filename: "a.bin" }, note: "hello" },
+        bodyType: "multipartForm",
+        expectedData: {
+          file: { value: REDACTED_BINARY_RESPONSE_DATA, filename: "a.bin" },
+          note: "hello",
+        },
+      },
+      {
+        body: { files: [{ value: bytes.buffer, filename: "a.bin" }] },
+        bodyType: "multipartForm",
+        expectedData: {
+          files: [{ value: REDACTED_BINARY_RESPONSE_DATA, filename: "a.bin" }],
+        },
+      },
+    ];
+    for (const { body, bodyType, expectedData } of binaryBodies) {
+      const { client, executeQuery } = createClient();
+      const error = await callApiRequest(
+        client,
+        { method: "POST", path: "/upload", body, bodyType },
+        { body: z.never(), response: JsonResponseSchema },
+      ).catch((caught: unknown) => caught);
+      expect(error).toBeInstanceOf(RestApiValidationError);
+      if (!(error instanceof RestApiValidationError)) throw error;
+      expect(error.details.data).toEqual(expectedData);
+      expect(executeQuery).not.toHaveBeenCalled();
+    }
+
+    const { client } = createClient();
+    const error = await callApiRequest(
+      client,
+      { method: "POST", path: "/orders", body: { amount: "not-a-number" } },
+      { body: z.object({ amount: z.number() }), response: JsonResponseSchema },
+    ).catch((caught: unknown) => caught);
+    expect(error).toBeInstanceOf(RestApiValidationError);
+    if (!(error instanceof RestApiValidationError)) throw error;
+    expect(error.details.data).toEqual({ amount: "not-a-number" });
+  });
+
+  it("does not leak binary bytes into the thrown message or zodError for a literal-schema mismatch", async () => {
+    const bytes = Uint8Array.from([137, 80, 78, 71]);
+    const { client } = createClient();
+    const error = await callApiRequest(
+      client,
+      { method: "PUT", path: "/upload", body: bytes, bodyType: "binary" },
+      {
+        body: z.literal("none"),
+        response: JsonResponseSchema,
+      },
+    ).catch((caught: unknown) => caught);
+    expect(error).toBeInstanceOf(RestApiValidationError);
+    if (!(error instanceof RestApiValidationError)) throw error;
+    expect(error.details.data).toBe(REDACTED_BINARY_RESPONSE_DATA);
+    expect(error.message).not.toContain("137");
+    expect(JSON.stringify(error.details.zodError.issues)).not.toContain("137");
+  });
 });

package/src/integrations/restapiintegration/client.test.ts

@@ -284,6 +284,29 @@ describe("RestApiIntegrationPluginClientImpl", () => {
       }
       throw new Error("Expected binary response validation to fail");
     });
+
+    it("keeps binary bytes out of the thrown message, not just details.zodError", async () => {
+      const bytes = [137, 80, 78, 71];
+      const { client } = createClient(workerBufferPayload(bytes));
+
+      let caught: unknown;
+      try {
+        await callApiRequest(
+          client,
+          { method: "GET", path: "/file.png", responseType: "binary" },
+          { response: z.literal("unexpected") },
+        );
+      } catch (error) {
+        caught = error;
+      }
+
+      expect(caught).toBeInstanceOf(RestApiValidationError);
+      if (!(caught instanceof RestApiValidationError)) throw caught;
+      expect(caught.message).not.toContain("137");
+      expect(JSON.stringify(caught.details.zodError.issues)).not.toContain(
+        "137",
+      );
+    });
   });
 
   describe("request body validation", () => {

package/src/integrations/restapiintegration/docs.manifest.json

@@ -16,11 +16,11 @@
     },
     {
       "file": "overlays/request-body-types.md",
-      "sdkVersionRange": ">=0.0.5"
+      "sdkVersionRange": ">=0.0.7"
     },
     {
       "file": "overlays/request-body-types-unsupported.md",
-      "sdkVersionRange": "<0.0.5"
+      "sdkVersionRange": "<0.0.7"
     }
   ]
 }