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

package/src/integrations/base/rest-api-client-base.ts

@@ -4,9 +4,13 @@ import { z } from "zod";
 import type { Property } from "@superblocksteam/types/dist/src/common/v1/plugin_pb";
 import type { Plugin as RestApiIntegrationPlugin } from "@superblocksteam/types/dist/src/plugins/restapiintegration/v1/plugin_pb";
 
-import { RestApiValidationError } from "../../errors.js";
+import {
+  RestApiValidationError,
+  restApiValidationErrorFromZodError,
+} from "../../errors.js";
 import type { QueryExecutor, TraceMetadata } from "../registry.js";
 import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import { describeOptionValue, validationError } from "../utils.js";
 import { decodeWorkerBinaryResponse } from "./decode-worker-binary-response.js";
 import { encodeRequestBody } from "./request-body.js";
 import { REST_API_RESPONSE_TYPES } from "./types.js";
@@ -46,12 +50,10 @@ export abstract class RestApiClientBase implements IntegrationClientImpl {
     if (options.body !== undefined && bodySchema) {
       const bodyParseResult = bodySchema.safeParse(options.body);
       if (!bodyParseResult.success) {
-        throw new RestApiValidationError(
-          `Request body validation failed: ${bodyParseResult.error.message}`,
-          {
-            zodError: bodyParseResult.error,
-            data: options.body,
-          },
+        throw restApiValidationErrorFromZodError(
+          "Request body validation failed",
+          bodyParseResult.error,
+          options.body,
         );
       }
     }
@@ -74,16 +76,22 @@ export abstract class RestApiClientBase implements IntegrationClientImpl {
       .enum(REST_API_RESPONSE_TYPES)
       .safeParse(options.responseType ?? "json");
     if (!responseTypeResult.success) {
-      throw new RestApiValidationError(
-        `Unsupported responseType ${JSON.stringify(options.responseType)} - expected one of: ${REST_API_RESPONSE_TYPES.join(", ")}`,
-        {
-          zodError: responseTypeResult.error,
-          data: options.responseType,
-        },
+      throw validationError(
+        `Unsupported responseType ${describeOptionValue(options.responseType)} - expected one of: ${REST_API_RESPONSE_TYPES.join(", ")}`,
+        ["responseType"],
       );
     }
     const responseType = responseTypeResult.data;
 
+    const { wire: bodyWire, contentType } = encodeRequestBody({
+      body: options.body,
+      bodyType: options.bodyType,
+      headers: options.headers,
+    });
+    if (contentType !== undefined) {
+      headers.push(this.createParam("Content-Type", contentType));
+    }
+
     const request: RestApiRequest = {
       openApiAction: "genericHttpRequest",
       httpMethod: options.method.toUpperCase(),
@@ -91,26 +99,9 @@ export abstract class RestApiClientBase implements IntegrationClientImpl {
       headers,
       params,
       responseType,
+      ...bodyWire,
     };
 
-    const bodyPatch = encodeRequestBody({
-      body: options.body,
-      bodyType: options.bodyType,
-      headers: options.headers,
-    });
-    if (bodyPatch.body !== undefined) {
-      request.body = bodyPatch.body;
-    }
-    if (bodyPatch.formData !== undefined) {
-      request.formData = [...bodyPatch.formData];
-    }
-    if (bodyPatch.bodyType !== undefined) {
-      request.bodyType = bodyPatch.bodyType;
-    }
-    for (const { key, value } of bodyPatch.injectedHeaders) {
-      headers.push(this.createParam(key, value));
-    }
-
     const result = await this.executeQuery(request, undefined, metadata);
 
     if (result === null || result === undefined) {

package/src/integrations/base/rest-api-integration-client.ts

@@ -1,6 +1,9 @@
 import { z } from "zod";
 
-import { RestApiValidationError } from "../../errors.js";
+import {
+  RestApiValidationError,
+  restApiValidationErrorFromZodError,
+} from "../../errors.js";
 import type { TraceMetadata } from "../registry.js";
 import { RestApiClientBase } from "./rest-api-client-base.js";
 import type {
@@ -71,12 +74,10 @@ export abstract class RestApiIntegrationClient
     const responseParseResult = schema.response.safeParse(result);
 
     if (!responseParseResult.success) {
-      throw new RestApiValidationError(
-        `Response validation failed: ${responseParseResult.error.message}`,
-        {
-          data: result,
-          zodError: responseParseResult.error,
-        },
+      throw restApiValidationErrorFromZodError(
+        "Response validation failed",
+        responseParseResult.error,
+        result,
       );
     }
 

package/src/integrations/base/types.ts

@@ -18,24 +18,6 @@ export const REST_API_BODY_TYPES = [
 
 export type RestApiBodyType = (typeof REST_API_BODY_TYPES)[number];
 
-export type BinaryBody = ArrayBuffer | ArrayBufferView;
-
-export type MultipartFormValue =
-  | string
-  | number
-  | boolean
-  | { value: string | BinaryBody; filename: string };
-
-export type MultipartFormBody = Record<string, MultipartFormValue>;
-
-export type FormUrlencodedValue =
-  | string
-  | number
-  | boolean
-  | readonly (string | number | boolean)[];
-
-export type FormUrlencodedBody = Record<string, FormUrlencodedValue>;
-
 export interface ApiRequestOptions<TBody = unknown> {
   /**
    * HTTP method for the request.

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

@@ -861,7 +861,7 @@ describe("resolveIntegrationDocumentation", () => {
 
     it("documents request bodyType only for agents whose sdk-api supports it", async () => {
       const docs = await resolveIntegrationDocumentation("restapiintegration", {
-        sdkVersion: "0.0.5",
+        sdkVersion: "0.0.7",
       });
 
       expect(docs).toContain('responseType: "binary"');
@@ -871,9 +871,23 @@ describe("resolveIntegrationDocumentation", () => {
       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.4",
+        sdkVersion: "0.0.6",
       });
 
       expect(docs).toContain('responseType: "binary"');
@@ -899,6 +913,98 @@ describe("resolveIntegrationDocumentation", () => {
     });
   });
 
+  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 }
+};
+```