@superblocksteam/sdk-api 2.0.165-next.0 → 2.0.166-next.0

package/src/integrations/box/README.md

@@ -1,6 +1,6 @@
 # Box Client
 
-Upload, download, and manage files in Box.
+Download and manage files in Box. File uploads are not available through this integration; see [File Uploads Are Not Available](#file-uploads-are-not-available).
 
 ## Methods
 
@@ -163,37 +163,6 @@ const content = await ctx.integrations.box.apiRequest(
 );
 ```
 
-### Upload a File
-
-```typescript
-const UploadResponseSchema = z.object({
-  entries: z.array(FileInfoSchema),
-  total_count: z.number(),
-});
-
-// For files < 50MB, use direct upload
-const result = await ctx.integrations.box.apiRequest(
-  {
-    method: "POST",
-    path: "/files/content",
-    headers: {
-      "Content-Type": "multipart/form-data",
-    },
-    body: {
-      attributes: JSON.stringify({
-        name: "new-file.txt",
-        parent: { id: folderId },
-      }),
-      file: fileContent,
-    },
-  },
-  { response: UploadResponseSchema },
-);
-
-const uploadedFile = result.entries[0];
-console.log(`Uploaded: ${uploadedFile.name} (${uploadedFile.id})`);
-```
-
 ### Create a Folder
 
 ```typescript
@@ -399,7 +368,7 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 ```typescript
 // WRONG - These methods do not exist
 await box.listFiles({ ... });
-await box.uploadFile({ ... });
+await box.createFolder({ ... });
 
 // CORRECT - Use apiRequest
 await ctx.integrations.box.apiRequest(
@@ -457,20 +426,9 @@ const result = await ctx.integrations.box.apiRequest(
 );
 ```
 
-### Upload Returns Array
-
-File uploads return an array in `entries`:
+### File Uploads Are Not Available
 
-```typescript
-// Response structure
-const schema = z.object({
-  entries: z.array(FileInfoSchema), // Array even for single file
-  total_count: z.number(),
-});
-
-// Access the uploaded file
-const uploadedFile = result.entries[0];
-```
+Box serves every upload endpoint (`/files/content`, `/files/upload_sessions`) from `https://upload.box.com/api/2.0`. This integration's base URL is fixed by the Box integration template to `https://api.box.com/2.0` and `apiRequest` cannot target another host, so uploads through `ctx.integrations.box` fail. Do not generate upload code for this integration. If an app must upload to Box, ask the user to configure a REST API integration with base URL `https://upload.box.com/api/2.0` using the same OAuth client, then call it through that integration.
 
 ### If-Match Header for Updates
 
@@ -521,20 +479,6 @@ async function getAllItems(box: BoxClient, folderId: string) {
 }
 ```
 
-### File Size Limits
-
-Different upload methods for different file sizes:
-
-```typescript
-// < 50MB - Use /files/content (simple upload)
-// > 50MB - Use chunked upload session
-
-// Chunked upload for large files:
-// 1. POST /files/upload_sessions - Create session
-// 2. PUT /files/upload_sessions/:id - Upload parts
-// 3. POST /files/upload_sessions/:id/commit - Finalize
-```
-
 ### Shared Link Access Levels
 
 ```typescript

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/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.