@superblocksteam/sdk-api 0.0.12 → 0.0.13

package/src/integrations/cosmosdb/client.ts

@@ -11,7 +11,10 @@ import type { z } from "zod";
 
 import type { Plugin as CosmosDBPlugin } from "@superblocksteam/types/dist/src/plugins/cosmosdb/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";
@@ -80,12 +83,10 @@ export class CosmosDBClientImpl
     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/documentation-resolver.test.ts

@@ -859,6 +859,42 @@ describe("resolveIntegrationDocumentation", () => {
       expect(docs).not.toContain("does not support the `responseType`");
     });
 
+    it("documents request bodyType only for agents whose sdk-api supports it", async () => {
+      const docs = await resolveIntegrationDocumentation("restapiintegration", {
+        sdkVersion: "0.0.7",
+      });
+
+      expect(docs).toContain('responseType: "binary"');
+      expect(docs).toContain('bodyType: "formUrlencoded"');
+      expect(docs).toContain('bodyType: "multipartForm"');
+      expect(docs).toContain('bodyType: "binary"');
+      expect(docs).not.toContain("does not support the `bodyType`");
+    });
+
+    it("documents binary request bodies with direct raw file bytes", async () => {
+      const docs = await resolveIntegrationDocumentation("restapiintegration", {
+        sdkVersion: "0.0.7",
+      });
+
+      expect(docs).not.toContain("Buffer.from(raw");
+      expect(docs).not.toContain("Buffer.isBuffer(raw");
+      expect(docs).toContain(
+        'pass the `Uint8Array` returned by `await file.readContentsAsync("raw")` directly as the body',
+      );
+      expect(docs).toContain('bodyType: "binary"');
+      expect(docs).toContain('body: await file.readContentsAsync("raw")');
+    });
+
+    it("notes bodyType non-support before sdk-api request body support", async () => {
+      const docs = await resolveIntegrationDocumentation("restapiintegration", {
+        sdkVersion: "0.0.6",
+      });
+
+      expect(docs).toContain('responseType: "binary"');
+      expect(docs).toContain("does not support the `bodyType` option");
+      expect(docs).not.toContain('bodyType: "formUrlencoded"');
+    });
+
     it("notes non-support instead of documenting responseType on older agents", async () => {
       const docs = await resolveIntegrationDocumentation("restapiintegration", {
         sdkVersion: "0.0.2",
@@ -869,13 +905,106 @@ describe("resolveIntegrationDocumentation", () => {
       expect(docs).not.toContain('responseType: "binary"');
     });
 
-    it("stays silent about responseType when the agent reports no sdk-api version", async () => {
+    it("stays silent about responseType and request bodyType when the agent reports no sdk-api version", async () => {
       const docs = await resolveIntegrationDocumentation("restapiintegration");
 
       expect(docs).not.toContain("responseType");
+      expect(docs).not.toContain("bodyType");
     });
   });
 
+  describe("non-JSON request body gating (real docs)", () => {
+    it.each([
+      {
+        pluginId: "jira",
+        supportedMarker: 'bodyType: "multipartForm"',
+        unsupportedMarker: "cannot upload",
+        expectFileRead: true,
+      },
+      {
+        pluginId: "stabilityai",
+        supportedMarker: 'bodyType: "multipartForm"',
+        unsupportedMarker: "cannot upload",
+        expectFileRead: true,
+      },
+      {
+        pluginId: "dropbox",
+        supportedMarker: 'bodyType: "binary"',
+        unsupportedMarker: "cannot upload",
+        expectFileRead: true,
+      },
+      {
+        pluginId: "elasticsearch",
+        supportedMarker: 'bodyType: "raw"',
+        unsupportedMarker: "cannot call `/_bulk`",
+        expectFileRead: false,
+      },
+      {
+        pluginId: "stripe",
+        supportedMarker: 'bodyType: "formUrlencoded"',
+        unsupportedMarker: "cannot send that encoding",
+        expectFileRead: false,
+      },
+    ])(
+      "gates $pluginId docs on sdk-api body type support",
+      async ({
+        pluginId,
+        supportedMarker,
+        unsupportedMarker,
+        expectFileRead,
+      }) => {
+        const supported = await resolveIntegrationDocumentation(pluginId, {
+          sdkVersion: "0.0.7",
+        });
+        expect(supported).toContain(supportedMarker);
+        expect(supported).not.toContain(unsupportedMarker);
+        if (expectFileRead) {
+          expect(supported).toContain('readContentsAsync("raw")');
+        }
+
+        const unsupported = await resolveIntegrationDocumentation(pluginId, {
+          sdkVersion: "0.0.6",
+        });
+        expect(unsupported).toContain(unsupportedMarker);
+        expect(unsupported).not.toContain("bodyType");
+
+        const unversioned = await resolveIntegrationDocumentation(pluginId);
+        expect(unversioned).not.toContain("bodyType");
+        expect(unversioned).not.toContain(unsupportedMarker);
+
+        for (const docs of [supported, unsupported, unversioned]) {
+          expect(docs).not.toContain("body: fileContent");
+          expect(docs).not.toContain("file: fileContent");
+          expect(docs).not.toContain('"Content-Type": "multipart/form-data"');
+          expect(docs).not.toContain('body: "File content here"');
+        }
+      },
+    );
+
+    it.each([
+      { pluginId: "box", host: "upload.box.com/api/2.0" },
+      { pluginId: "googledrive", host: "googleapis.com/upload/drive/v3" },
+    ])(
+      "tells $pluginId callers uploads are unavailable at every sdk-api version",
+      async ({ pluginId, host }) => {
+        for (const options of [
+          { sdkVersion: "0.0.7" as const },
+          { sdkVersion: "0.0.6" as const },
+          undefined,
+        ]) {
+          const docs = await resolveIntegrationDocumentation(pluginId, options);
+          expect(docs).toContain("Uploads Are Not Available");
+          expect(docs).toContain(host);
+          expect(docs).not.toContain("bodyType");
+          expect(docs).not.toContain('readContentsAsync("raw")');
+          expect(docs).not.toContain("file: fileContent");
+          expect(docs).not.toContain('body: "File content here"');
+          expect(docs).not.toContain('path: "/upload/drive/v3/files"');
+        }
+      },
+    );
+  });
+
   it("blocks overlay paths outside the plugin directory", async () => {
     const integrationsDirectory = createPluginDocsFixture("dropbox", {
       "README.md": "base",

package/src/integrations/documentation.test.ts

@@ -118,3 +118,15 @@ describe("SQL integration documentation", () => {
     },
   );
 });
+
+describe("Anthropic integration documentation", () => {
+  it("uses claude-sonnet-5-20250715 instead of Claude 3.5 snapshot IDs", () => {
+    const readme = readIntegrationFile("anthropic", "README.md");
+    const typeDocs = readIntegrationFile("anthropic", "types.ts");
+
+    expect(readme).toContain("claude-sonnet-5-20250715");
+    expect(typeDocs).toContain("claude-sonnet-5-20250715");
+    expect(readme).not.toMatch(/claude-3-5-sonnet-\d{8}/);
+    expect(typeDocs).not.toMatch(/claude-3-5-sonnet-\d{8}/);
+  });
+});

package/src/integrations/dropbox/README.md

@@ -123,41 +123,6 @@ const result = await ctx.integrations.dropbox.apiRequest(
 );
 ```
 
-### Upload a File
-
-```typescript
-const UploadResponseSchema = z.object({
-  name: z.string(),
-  path_lower: z.string(),
-  path_display: z.string(),
-  id: z.string(),
-  client_modified: z.string(),
-  server_modified: z.string(),
-  size: z.number(),
-  content_hash: z.string(),
-});
-
-const result = await ctx.integrations.dropbox.apiRequest(
-  {
-    method: "POST",
-    path: "/2/files/upload",
-    headers: {
-      "Dropbox-API-Arg": JSON.stringify({
-        path: "/Documents/new-file.txt",
-        mode: "add", // add, overwrite, or update
-        autorename: true,
-        mute: false,
-      }),
-      "Content-Type": "application/octet-stream",
-    },
-    body: "File content here",
-  },
-  { response: UploadResponseSchema },
-);
-
-console.log(`Uploaded: ${result.path_display}`);
-```
-
 ### Create a Folder
 
 ```typescript
@@ -369,27 +334,9 @@ const path = "/Documents/file.txt";
 const path = "";
 ```
 
-### Upload Headers
-
-File uploads require special headers:
-
-```typescript
-// Upload requires Dropbox-API-Arg header
-const headers = {
-  "Dropbox-API-Arg": JSON.stringify({
-    path: "/path/to/file.txt",
-    mode: "add",
-  }),
-  "Content-Type": "application/octet-stream",
-};
-
-// The body is raw file content, not JSON
-const body = "Raw file content";
-```
-
 ### Download Headers
 
-Downloads also use special headers:
+Downloads use special headers, not the body, to carry parameters:
 
 ```typescript
 // Download parameters go in header, not body
@@ -453,23 +400,6 @@ async function listAllFiles(dropbox: DropboxClient, path: string) {
 }
 ```
 
-### Write Conflict Modes
-
-Choose the right mode for uploads:
-
-```typescript
-const modes = {
-  add: "Never overwrite, fail if file exists",
-  overwrite: "Always overwrite existing file",
-  update: "Update only if rev matches (optimistic locking)",
-};
-
-const body = {
-  path: "/file.txt",
-  mode: "add", // or { ".tag": "update", "update": revisionId }
-};
-```
-
 ### Case Sensitivity
 
 Dropbox paths are case-insensitive but preserve case:

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

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

package/src/integrations/dropbox/overlays/upload-unsupported.md

@@ -0,0 +1,3 @@
+## Upload a File
+
+This agent's sdk-api cannot upload files to Dropbox through `apiRequest()` because it serializes every body as JSON, and `/2/files/upload` expects the raw file bytes. Do not generate upload code until the agent is upgraded. Listing, metadata, download, folder, and sharing calls work as documented above.

package/src/integrations/dropbox/overlays/upload.md

@@ -0,0 +1,89 @@
+## Upload a File
+
+`/2/files/upload` takes the file bytes as the request body and the upload parameters in the `Dropbox-API-Arg` header. Pass `bodyType: "binary"` with the `Uint8Array` returned by `await file.readContentsAsync("raw")`. The SDK adds `Content-Type: application/octet-stream`, which Dropbox requires. `Dropbox-API-Arg` must be ASCII-only, so escape non-ASCII filenames before building it (Dropbox rejects a raw UTF-8 header).
+
+```typescript
+const UploadResponseSchema = z.object({
+  name: z.string(),
+  path_lower: z.string(),
+  path_display: z.string(),
+  id: z.string(),
+  client_modified: z.string(),
+  server_modified: z.string(),
+  size: z.number(),
+  content_hash: z.string(),
+});
+
+const file = input.upload.files[0];
+
+// Dropbox-API-Arg is an HTTP header value, which must be ASCII-only.
+// Escape any non-ASCII character (e.g. accented letters) as \uXXXX.
+function toDropboxApiArg(value: unknown): string {
+  return JSON.stringify(value).replace(
+    /[\u0080-\uffff]/g,
+    (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+}
+
+const result = await ctx.integrations.dropbox.apiRequest(
+  {
+    method: "POST",
+    path: "/2/files/upload",
+    headers: {
+      "Dropbox-API-Arg": toDropboxApiArg({
+        path: `/Documents/${file.name}`,
+        mode: "add", // add, overwrite, or update
+        autorename: true,
+        mute: false,
+      }),
+    },
+    bodyType: "binary",
+    body: await file.readContentsAsync("raw"),
+  },
+  { response: UploadResponseSchema },
+);
+
+console.log(`Uploaded: ${result.path_display}`);
+```
+
+For text generated in the API rather than an uploaded file, use `bodyType: "raw"` with a string body and set `Content-Type: application/octet-stream` yourself, since raw mode adds no headers:
+
+```typescript
+const notesText = ["# Meeting notes", "", ...input.notes].join("\n");
+
+await ctx.integrations.dropbox.apiRequest(
+  {
+    method: "POST",
+    path: "/2/files/upload",
+    headers: {
+      "Dropbox-API-Arg": JSON.stringify({
+        path: "/Documents/notes.txt",
+        mode: "overwrite",
+      }),
+      "Content-Type": "application/octet-stream",
+    },
+    bodyType: "raw",
+    body: notesText,
+  },
+  { response: UploadResponseSchema },
+);
+```
+
+Do not send the file as a JSON body. Without `bodyType`, `apiRequest()` rejects a `Uint8Array`/`Buffer` body outright, and JSON-encodes a string body instead of sending it raw, so Dropbox would store the quoted JSON text instead of the file content. `readContentsAsync("binary")` returns base64 text, not bytes; use `readContentsAsync("raw")` for uploads.
+
+### Write Conflict Modes
+
+Choose the right `mode` for uploads:
+
+```typescript
+const modes = {
+  add: "Never overwrite, fail if file exists",
+  overwrite: "Always overwrite existing file",
+  update: "Update only if rev matches (optimistic locking)",
+};
+
+const dropboxApiArg = {
+  path: "/file.txt",
+  mode: "add", // or { ".tag": "update", "update": revisionId }
+};
+```

package/src/integrations/dynamodb/client.ts

@@ -8,7 +8,10 @@
 
 import type { z } from "zod";
 
-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";
@@ -85,12 +88,10 @@ export class DynamoDBClientImpl
     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/elasticsearch/README.md

@@ -226,70 +226,6 @@ const result = await ctx.integrations.es.apiRequest(
 );
 ```
 
-### Bulk Operations
-
-```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",
-    },
-    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}`);
-    }
-  });
-}
-```
-
 ### Aggregations
 
 ```typescript
@@ -493,22 +429,6 @@ const body = {
 };
 ```
 
-### Bulk Format
-
-Bulk operations require NDJSON format:
-
-```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";
-```
-
 ### Total Hits Accuracy
 
 For large result sets, total is approximate by default:

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

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

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,
       );
     }