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

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/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/lakebase/README.md

@@ -162,9 +162,7 @@ The `query()` method requires a Zod schema for runtime validation:
 // WRONG - Missing schema parameter
 const users = await ctx.integrations.db.query(
   "SELECT * FROM users",
-  [
-    /* params */
-  ], // This is wrong - params are 3rd argument
+  [/* params */], // This is wrong - params are 3rd argument
 );
 
 // CORRECT - Schema is the second parameter

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/postgres/README.md

@@ -292,9 +292,7 @@ The `query()` method requires a Zod schema for runtime validation. This is by de
 // WRONG - Missing schema parameter
 const users = await ctx.integrations.db.query(
   "SELECT * FROM users",
-  [
-    /* params */
-  ], // This is wrong - params are 3rd argument
+  [/* params */], // This is wrong - params are 3rd argument
 );
 
 // CORRECT - Schema is the second parameter

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");
+  });
+});