@superblocksteam/sdk-api 0.0.12 → 0.0.13

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

@@ -0,0 +1,323 @@
+import { describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+
+import {
+  REDACTED_BINARY_RESPONSE_DATA,
+  RestApiValidationError,
+} from "../../errors.js";
+import type { IntegrationConfig } from "../types.js";
+import { RestApiIntegrationPluginClientImpl } from "./client.js";
+
+const TEST_CONFIG: IntegrationConfig = {
+  id: "restapi-test-id",
+  name: "Test REST API",
+  pluginId: "restapiintegration",
+  configuration: {},
+};
+
+const JsonResponseSchema = z.object({ ok: z.boolean() });
+
+function createClient() {
+  const executeQuery = vi.fn().mockResolvedValue({ ok: true });
+  const client = new RestApiIntegrationPluginClientImpl(
+    TEST_CONFIG,
+    executeQuery,
+  );
+  return { client, executeQuery };
+}
+
+function callApiRequest(
+  client: RestApiIntegrationPluginClientImpl,
+  ...args: unknown[]
+): Promise<unknown> {
+  return Reflect.apply(client.apiRequest, client, args);
+}
+
+describe("RestApiIntegrationPluginClientImpl request body types", () => {
+  it("preserves omitted and explicit JSON body wire behavior", async () => {
+    for (const bodyType of [undefined, "json"] as const) {
+      const { client, executeQuery } = createClient();
+      await client.apiRequest(
+        { method: "POST", path: "/payments", body: { amount: 42 }, bodyType },
+        { response: JsonResponseSchema },
+      );
+      expect(executeQuery).toHaveBeenCalledWith(
+        expect.objectContaining({
+          body: JSON.stringify({ amount: 42 }),
+          bodyType: "jsonBody",
+        }),
+        undefined,
+        undefined,
+      );
+    }
+  });
+
+  it("sends raw string bodies as rawBody", async () => {
+    const { client, executeQuery } = createClient();
+    await client.apiRequest(
+      {
+        method: "POST",
+        path: "/xml",
+        body: "<note>hello</note>",
+        bodyType: "raw",
+      },
+      { response: JsonResponseSchema },
+    );
+    expect(executeQuery).toHaveBeenCalledWith(
+      expect.objectContaining({
+        body: "<note>hello</note>",
+        bodyType: "rawBody",
+      }),
+      undefined,
+      undefined,
+    );
+  });
+
+  it("sends formUrlencoded bodies as rawBody with injected Content-Type", async () => {
+    const { client, executeQuery } = createClient();
+    await client.apiRequest(
+      {
+        method: "POST",
+        path: "/charges",
+        body: { amount: 2000, currency: "usd", "metadata[order_id]": "6735" },
+        bodyType: "formUrlencoded",
+      },
+      { response: JsonResponseSchema },
+    );
+    expect(executeQuery).toHaveBeenCalledWith(
+      expect.objectContaining({
+        body: "amount=2000&currency=usd&metadata%5Border_id%5D=6735",
+        bodyType: "rawBody",
+        headers: [
+          { key: "Content-Type", value: "application/x-www-form-urlencoded" },
+        ],
+      }),
+      undefined,
+      undefined,
+    );
+  });
+
+  it("appends the injected Content-Type after caller headers", async () => {
+    const { client, executeQuery } = createClient();
+    await client.apiRequest(
+      {
+        method: "POST",
+        path: "/charges",
+        headers: { Authorization: "Bearer x" },
+        body: { amount: 2000 },
+        bodyType: "formUrlencoded",
+      },
+      { response: JsonResponseSchema },
+    );
+    expect(executeQuery).toHaveBeenCalledWith(
+      expect.objectContaining({
+        headers: [
+          { key: "Authorization", value: "Bearer x" },
+          { key: "Content-Type", value: "application/x-www-form-urlencoded" },
+        ],
+      }),
+      undefined,
+      undefined,
+    );
+  });
+
+  it("keeps a caller Content-Type of any case and injects nothing", async () => {
+    const { client, executeQuery } = createClient();
+    await client.apiRequest(
+      {
+        method: "POST",
+        path: "/charges",
+        headers: {
+          "content-type": "application/x-www-form-urlencoded; charset=utf-8",
+        },
+        body: { amount: 2000 },
+        bodyType: "formUrlencoded",
+      },
+      { response: JsonResponseSchema },
+    );
+    expect(executeQuery).toHaveBeenCalledWith(
+      expect.objectContaining({
+        headers: [
+          {
+            key: "content-type",
+            value: "application/x-www-form-urlencoded; charset=utf-8",
+          },
+        ],
+      }),
+      undefined,
+      undefined,
+    );
+  });
+
+  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",
+          file: { value: "contents", filename: "note.txt" },
+          image: { value: bytes, filename: "b.png" },
+        },
+        bodyType: "multipartForm",
+      },
+      { response: JsonResponseSchema },
+    );
+    expect(executeQuery).toHaveBeenCalledWith(
+      expect.objectContaining({
+        bodyType: "formDataBase64",
+        formData: [
+          { key: "note", value: "mixed" },
+          expect.objectContaining({
+            key: "file",
+            file: { filename: "note.txt" },
+          }),
+          expect.objectContaining({
+            key: "image",
+            file: { filename: "b.png" },
+          }),
+        ],
+      }),
+      undefined,
+      undefined,
+    );
+    expect(executeQuery.mock.calls[0][0]).not.toHaveProperty("body");
+  });
+
+  it("rejects invalid bodyType and invalid bodies before executeQuery", async () => {
+    for (const bodyType of [
+      "form",
+      "jsonBody",
+      "rawBody",
+      "formData",
+      "fileForm",
+      "binaryBody",
+      "formDataBase64",
+    ]) {
+      const { client, executeQuery } = createClient();
+      await expect(
+        callApiRequest(
+          client,
+          { method: "POST", path: "/bad", body: {}, bodyType },
+          { response: JsonResponseSchema },
+        ),
+      ).rejects.toThrow(RestApiValidationError);
+      expect(executeQuery).not.toHaveBeenCalled();
+    }
+
+    const invalidCases = [
+      { method: "POST", path: "/bad", body: Uint8Array.from([1]) },
+      { method: "POST", path: "/bad", bodyType: "raw" },
+      { method: "POST", path: "/bad", bodyType: "formUrlencoded" },
+      { method: "POST", path: "/bad", bodyType: "multipartForm" },
+      { method: "POST", path: "/bad", bodyType: "binary" },
+    ];
+    for (const options of invalidCases) {
+      const { client, executeQuery } = createClient();
+      await expect(
+        callApiRequest(client, options, { response: JsonResponseSchema }),
+      ).rejects.toThrow(RestApiValidationError);
+      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

@@ -13,6 +13,14 @@
     {
       "file": "overlays/response-types-unsupported.md",
       "sdkVersionRange": "<0.0.3"
+    },
+    {
+      "file": "overlays/request-body-types.md",
+      "sdkVersionRange": ">=0.0.7"
+    },
+    {
+      "file": "overlays/request-body-types-unsupported.md",
+      "sdkVersionRange": "<0.0.7"
     }
   ]
 }

package/src/integrations/restapiintegration/overlays/request-body-types-unsupported.md

@@ -0,0 +1,7 @@
+## Request Body Types
+
+This organization's agent does not support the `bodyType` option on `apiRequest()` yet. Its worker runs an sdk-api version that always serializes request bodies as JSON, so raw strings, binary uploads, multipart/form-data, and application/x-www-form-urlencoded payloads cannot be sent from SDK APIs until the agent is upgraded.
+
+Do not generate code that passes a `bodyType` value before that upgrade. It may typecheck against a newer local copy of the SDK but fail at runtime on this agent.
+
+When the user needs a non-JSON request body, tell them the required action: an administrator must upgrade this organization's Superblocks agent (On-Premise Agent / OPA) to a newer version that supports the `bodyType` option. Until that upgrade happens, there is no code-level workaround.