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

package/src/integrations/restapiintegration/client.test.ts

@@ -227,50 +227,55 @@ describe("RestApiIntegrationPluginClientImpl", () => {
       expect(executeQuery).toHaveBeenCalled();
     });
 
-    it("accepts response schemas that transform bytes to bytes", async () => {
+    it("returns decoded bytes and ignores a response schema passed at runtime", async () => {
+      // Models sandboxed API code: its Uint8Array is a different constructor,
+      // so a caller's z.instanceof(Uint8Array) rejects every SDK-decoded body.
+      const crossRealmInstanceof = z.custom<Uint8Array>(() => false);
       const { client } = createClient(workerBufferPayload(PDF_BYTES));
 
-      const result = await client.apiRequest(
+      const result = await callApiRequest(
+        client,
         { method: "GET", path: "/file.pdf", responseType: "binary" },
-        {
-          response: z
-            .instanceof(Uint8Array)
-            .refine((bytes) => bytes[0] === 0x25)
-            .transform((bytes) => bytes.slice(1)),
-        },
+        { response: crossRealmInstanceof },
       );
 
-      expect(Array.from(result)).toEqual(PDF_BYTES.slice(1));
+      expect(result).toBeInstanceOf(Uint8Array);
+      expect(result instanceof Uint8Array && Array.from(result)).toEqual(
+        PDF_BYTES,
+      );
     });
 
-    it("throws RestApiValidationError when the schema rejects normalized bytes", async () => {
-      const { client } = createClient(workerBufferPayload(PDF_BYTES));
+    it("still validates the request body for binary responses", async () => {
+      const { client, executeQuery } = createClient(
+        workerBufferPayload(PDF_BYTES),
+      );
+
+      const dynamicBody: unknown = JSON.parse('{"pages":"many"}');
 
       await expect(
         client.apiRequest(
-          { method: "GET", path: "/file.pdf", responseType: "binary" },
           {
-            response: z
-              .instanceof(Uint8Array)
-              .refine((bytes) => bytes.byteLength > 64),
+            method: "POST",
+            path: "/render.pdf",
+            body: dynamicBody,
+            responseType: "binary",
           },
+          { body: z.object({ pages: z.number() }) },
         ),
       ).rejects.toThrow(RestApiValidationError);
+      expect(executeQuery).not.toHaveBeenCalled();
     });
 
-    it("redacts binary data from response validation errors", async () => {
-      const bytes = Array.from({ length: 4096 }, () => 0);
+    it("redacts binary data from malformed-body errors", async () => {
+      const bytes = [...Array.from({ length: 4096 }, () => 0), 256];
       const { client } = createClient(workerBufferPayload(bytes));
 
       try {
-        await client.apiRequest(
-          { method: "GET", path: "/file.pdf", responseType: "binary" },
-          {
-            response: z
-              .instanceof(Uint8Array)
-              .refine((value) => value.byteLength < 1024),
-          },
-        );
+        await client.apiRequest({
+          method: "GET",
+          path: "/file.pdf",
+          responseType: "binary",
+        });
       } catch (error) {
         expect(error).toBeInstanceOf(RestApiValidationError);
         if (!(error instanceof RestApiValidationError)) {
@@ -282,7 +287,30 @@ describe("RestApiIntegrationPluginClientImpl", () => {
         });
         return;
       }
-      throw new Error("Expected binary response validation to fail");
+      throw new Error("Expected malformed binary decoding to fail");
+    });
+
+    it("keeps binary bytes out of the thrown message, not just details.zodError", async () => {
+      const bytes = [137, 80, 78, 71, 256];
+      const { client } = createClient(workerBufferPayload(bytes));
+
+      let caught: unknown;
+      try {
+        await client.apiRequest({
+          method: "GET",
+          path: "/file.png",
+          responseType: "binary",
+        });
+      } 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",
+      );
     });
   });
 
@@ -438,24 +466,32 @@ describe("RestApiIntegrationPluginClientImpl", () => {
       await wrongBinary;
     });
 
-    it("rejects binary response schemas that transform bytes to another type", () => {
+    it("rejects response schemas on binary requests but accepts body schemas", async () => {
       const { client: binaryClient } = createClient(
         workerBufferPayload(PDF_BYTES),
       );
 
-      // @ts-expect-error binary response schemas must output Uint8Array
-      binaryClient.apiRequest(
+      // @ts-expect-error binary responses do not take a response schema
+      const withResponse = binaryClient.apiRequest(
         {
           method: "GET",
           path: "/file.pdf",
           responseType: "binary",
         },
+        { response: z.instanceof(Uint8Array) },
+      );
+      await withResponse;
+
+      const withBody: Promise<Uint8Array> = binaryClient.apiRequest(
         {
-          response: z
-            .instanceof(Uint8Array)
-            .transform((bytes) => bytes.byteLength),
+          method: "POST",
+          path: "/render.pdf",
+          body: { pages: 1 },
+          responseType: "binary",
         },
+        { body: z.object({ pages: z.number() }) },
       );
+      expect(Array.from(await withBody)).toEqual(PDF_BYTES);
     });
 
     it("rejects response types outside the public SDK contract", async () => {

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.

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

@@ -0,0 +1,115 @@
+## Request Body Types
+
+`apiRequest()` serializes request bodies as JSON by default. For endpoints that expect another encoding, pass `bodyType`:
+
+- `"json"` for JSON payloads. This is the default.
+- `"raw"` for caller-encoded string bodies such as XML, CSV, or plain text.
+- `"formUrlencoded"` for `application/x-www-form-urlencoded` payloads.
+- `"multipartForm"` for multipart fields and file parts.
+- `"binary"` for byte payloads. Pass bytes such as a `Uint8Array`, `ArrayBuffer`, `DataView`, or `Buffer`.
+
+### Form URL-Encoded Requests
+
+Use `bodyType: "formUrlencoded"` for OAuth token exchanges and other APIs that expect HTML form encoding. Arrays repeat the key, so `tags: ["a", "b"]` encodes as `tags=a&tags=b`. APIs that expect bracket keys need the brackets in the key, and nested fields must be flattened with bracket notation:
+
+```typescript
+const token = await ctx.integrations.authApi.apiRequest(
+  {
+    method: "POST",
+    path: "/oauth/token",
+    bodyType: "formUrlencoded",
+    body: {
+      grant_type: "client_credentials",
+      client_id: input.clientId,
+      scope: "read:orders write:orders",
+    },
+  },
+  { response: TokenResponseSchema },
+);
+
+const order = await ctx.integrations.ordersApi.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/orders",
+    bodyType: "formUrlencoded",
+    body: {
+      amount: 2000,
+      currency: "usd",
+      "metadata[order_id]": "6735",
+    },
+  },
+  { response: OrderResponseSchema },
+);
+```
+
+The SDK adds `Content-Type: application/x-www-form-urlencoded` unless you already provided a `Content-Type` header.
+Fields whose value is `undefined` are omitted. Empty arrays are omitted. The body must encode at least one field.
+
+### Binary Uploads
+
+Use `bodyType: "binary"` for APIs that accept the request body as bytes, such as SharePoint-style upload endpoints. For an uploaded file, pass the `Uint8Array` returned by `await file.readContentsAsync("raw")` directly as the body:
+
+```typescript
+const file = input.upload.files[0];
+
+await ctx.integrations.sharepoint.apiRequest(
+  {
+    method: "PUT",
+    path: `/sites/${siteId}/drive/root:/reports/${file.name}:/content`,
+    bodyType: "binary",
+    body: await file.readContentsAsync("raw"),
+    headers: { "Content-Type": file.type || "application/octet-stream" },
+  },
+  { response: UploadResponseSchema },
+);
+```
+
+For bytes that do not come from an uploaded file, pass a byte container supported by the SDK, such as `Uint8Array`, `ArrayBuffer`, `DataView`, or `Buffer`. Do not convert file bytes to a string. `readContentsAsync("binary")` returns base64 text, not bytes. Never send that text as a file body. Use `readContentsAsync("raw")` instead. If only base64 text is available, decode it with `Buffer.from(text, "base64")` and send the result with `bodyType: "binary"`.
+
+The SDK sends the exact byte window of a byte view, so `bytes.subarray(start, end)` uploads a slice. It adds `Content-Type: application/octet-stream` unless you already provided a `Content-Type` header such as `application/pdf`.
+
+Binary request bodies must be non-empty; a zero-length body throws a validation error.
+
+### Multipart Uploads
+
+Use `bodyType: "multipartForm"` for endpoints that expect fields plus file parts. File parts must be wrapped as `{ value, filename }`; a bare binary value without that wrapper is rejected with a message naming the required `{ value, filename }` shape. A file part `value` is a string or bytes such as the `Uint8Array` returned by `await file.readContentsAsync("raw")`. `readContentsAsync("binary")` returns base64 text, not bytes; never pass that text as a file part value, it will be UTF-8 encoded a second time and silently corrupt the upload. Use `readContentsAsync("raw")` for file part bytes.
+
+```typescript
+const invoice = input.upload.files[0];
+
+const upload = await ctx.integrations.filesApi.apiRequest(
+  {
+    method: "POST",
+    path: "/files",
+    bodyType: "multipartForm",
+    body: {
+      folder: "invoices",
+      invoice: {
+        value: await invoice.readContentsAsync("raw"),
+        filename: invoice.name,
+      },
+    },
+  },
+  { response: UploadResponseSchema },
+);
+```
+
+Do not set `Content-Type` for multipart requests. The worker generates the multipart boundary during execution.
+Do not set per-part `contentType`. Arrays repeat the key, so `files: [partA, partB]` sends two `files` parts. Fields whose value is `undefined` are omitted. Empty file parts are allowed.
+
+### Raw String Bodies
+
+Use `bodyType: "raw"` for pre-encoded text bodies. The SDK does not add a `Content-Type` header in raw mode, so provide the header expected by the API. Prefer `"json"`, `"formUrlencoded"`, `"multipartForm"`, or `"binary"` when the target API fits one of those shapes; reach for `"raw"` only when the API needs a pre-encoded format none of the typed body types cover, such as SOAP/XML or a signed payload:
+
+```typescript
+await ctx.integrations.legacyApi.apiRequest(
+  {
+    method: "POST",
+    path: "/soap",
+    bodyType: "raw",
+    body: `<Envelope><Body>${payload}</Body></Envelope>`,
+    headers: { "Content-Type": "text/xml" },
+  },
+  { response: SoapResponseSchema },
+);
+```

package/src/integrations/restapiintegration/overlays/response-types-binary.md

@@ -5,7 +5,7 @@
 - `"binary"` for PDFs and other byte payloads. The result is a `Uint8Array`
 - `"text"` for XML, CSV, HTML, and other decoded strings
 
-With `responseType: "text"` or `responseType: "binary"` the response schema may be omitted. Text returns the raw string typed `unknown`. Binary returns a `Uint8Array`:
+With `responseType: "text"` the response schema may be omitted, and the raw string is returned typed `unknown`. With `responseType: "binary"` never pass a response schema. The SDK decodes and validates the bytes and returns a `Uint8Array`:
 
 ```typescript
 const xml = await ctx.integrations.legacyApi.apiRequest({
@@ -23,7 +23,7 @@ const pdf = await ctx.integrations.legacyApi.apiRequest({
 // pdf is a Uint8Array
 ```
 
-To validate after decoding, pass a schema that matches the decoded value:
+To validate a text response after decoding, pass a schema that matches the decoded string:
 
 ```typescript
 const xml = await ctx.integrations.legacyApi.apiRequest(
@@ -31,14 +31,10 @@ const xml = await ctx.integrations.legacyApi.apiRequest(
   { response: z.string() },
 );
 // xml is typed string
-
-const pdf = await ctx.integrations.legacyApi.apiRequest(
-  { method: "GET", path: "/file.pdf", responseType: "binary" },
-  { response: z.instanceof(Uint8Array) },
-);
-// pdf is typed Uint8Array
 ```
 
+Do not use `z.instanceof(Uint8Array)` anywhere in an API, including the response or output schema. API code runs in a sandbox where the bytes the SDK returns are not instances of the API code's `Uint8Array`, so that check always fails. Check binary content directly in `run()` instead, for example `if (pdf.byteLength === 0) throw new Error("Empty PDF")`.
+
 Convert binary data to a JSON-safe representation before returning it from an SDK API:
 
 ```typescript

package/src/integrations/s3/client.ts

@@ -9,7 +9,10 @@ import type { z } from "zod";
 
 import type { Plugin as S3Plugin } from "@superblocksteam/types/dist/src/plugins/s3/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 S3ClientImpl implements S3Client, 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/salesforce/client.ts

@@ -7,7 +7,11 @@
 
 import type { z } from "zod";
 
-import { QueryValidationError, RestApiValidationError } from "../../errors.js";
+import {
+  QueryValidationError,
+  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";
@@ -205,12 +209,10 @@ export class SalesforceClientImpl
 
     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/slack/client.test.ts

@@ -307,6 +307,36 @@ describe("SlackClientImpl", () => {
       expect(request.params).toEqual([{ key: "unfurl_links", value: "false" }]);
     });
 
+    it("sends formUrlencoded bodies through the shared request builder", async () => {
+      const { client, executeQuery } = createClient({
+        ok: true,
+        channel: "C123",
+        ts: "1234567890.123456",
+      });
+
+      await client.apiRequest(
+        {
+          method: "POST",
+          path: "/chat.postMessage",
+          body: { channel: "#alerts", text: "hello" },
+          bodyType: "formUrlencoded",
+        },
+        { response: PostMessageSchema },
+      );
+
+      expect(executeQuery).toHaveBeenCalledWith(
+        expect.objectContaining({
+          body: expect.any(String),
+          bodyType: "rawBody",
+          headers: [
+            { key: "Content-Type", value: "application/x-www-form-urlencoded" },
+          ],
+        }),
+        undefined,
+        undefined,
+      );
+    });
+
     it("passes trace metadata to executeQuery", async () => {
       const { client, executeQuery } = createClient({
         ok: true,

package/src/integrations/slack/client.ts

@@ -8,7 +8,7 @@
 
 import type { z } from "zod";
 
-import { RestApiValidationError } from "../../errors.js";
+import { restApiValidationErrorFromZodError } from "../../errors.js";
 import { RestApiClientBase } from "../base/rest-api-client-base.js";
 import type { ApiRequestOptions } from "../base/types.js";
 import type { TraceMetadata } from "../registry.js";
@@ -51,24 +51,20 @@ export class SlackClientImpl extends RestApiClientBase implements SlackClient {
       "ok" in result &&
       (result as Record<string, unknown>).ok === false
     ) {
-      throw new RestApiValidationError(
-        `Slack returned ok: false but the response did not match the expected error shape: ${errorResult.error.message}`,
-        {
-          zodError: errorResult.error,
-          data: result,
-        },
+      throw restApiValidationErrorFromZodError(
+        "Slack returned ok: false but the response did not match the expected error shape",
+        errorResult.error,
+        result,
       );
     }
 
     // Success responses must carry the Slack envelope discriminant.
     const successEnvelopeResult = SlackSuccessEnvelopeSchema.safeParse(result);
     if (!successEnvelopeResult.success) {
-      throw new RestApiValidationError(
-        `Slack success response is missing the expected ok: true envelope: ${successEnvelopeResult.error.message}`,
-        {
-          zodError: successEnvelopeResult.error,
-          data: result,
-        },
+      throw restApiValidationErrorFromZodError(
+        "Slack success response is missing the expected ok: true envelope",
+        successEnvelopeResult.error,
+        result,
       );
     }
 
@@ -81,12 +77,10 @@ export class SlackClientImpl extends RestApiClientBase implements SlackClient {
 
     const payloadResult = schema.response.safeParse(payloadCandidate);
     if (!payloadResult.success) {
-      throw new RestApiValidationError(
-        `Response validation failed: ${payloadResult.error.message}`,
-        {
-          zodError: payloadResult.error,
-          data: result,
-        },
+      throw restApiValidationErrorFromZodError(
+        "Response validation failed",
+        payloadResult.error,
+        result,
       );
     }
 

package/src/integrations/snowflakepostgres/README.md

@@ -137,9 +137,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/stabilityai/README.md

@@ -79,84 +79,6 @@ export default api({
 });
 ```
 
-### Image-to-Image (Transform Existing Image)
-
-```typescript
-const result = await ctx.integrations.stability.apiRequest(
-  {
-    method: "POST",
-    path: "/v1/generation/stable-diffusion-xl-1024-v1-0/image-to-image",
-    headers: {
-      "Content-Type": "multipart/form-data",
-    },
-    body: {
-      init_image: sourceImageBase64,
-      text_prompts: [{ text: "A vibrant oil painting style", weight: 1 }],
-      image_strength: 0.35, // How much to modify (0-1)
-      cfg_scale: 7,
-      samples: 1,
-      steps: 30,
-    },
-  },
-  { response: GenerationResponseSchema },
-);
-```
-
-### Upscale an Image
-
-```typescript
-const UpscaleResponseSchema = z.object({
-  artifacts: z.array(
-    z.object({
-      base64: z.string(),
-      finishReason: z.string(),
-      seed: z.number(),
-    }),
-  ),
-});
-
-const result = await ctx.integrations.stability.apiRequest(
-  {
-    method: "POST",
-    path: "/v1/generation/esrgan-v1-x2plus/image-to-image/upscale",
-    headers: {
-      "Content-Type": "multipart/form-data",
-    },
-    body: {
-      image: sourceImageBase64,
-      width: 2048, // Target width (optional)
-    },
-  },
-  { response: UpscaleResponseSchema },
-);
-
-const upscaledImage = result.artifacts[0].base64;
-```
-
-### Inpainting (Edit Parts of an Image)
-
-```typescript
-const result = await ctx.integrations.stability.apiRequest(
-  {
-    method: "POST",
-    path: "/v1/generation/stable-diffusion-xl-1024-v1-0/image-to-image/masking",
-    headers: {
-      "Content-Type": "multipart/form-data",
-    },
-    body: {
-      init_image: sourceImageBase64,
-      mask_image: maskImageBase64, // White areas will be regenerated
-      mask_source: "MASK_IMAGE_WHITE",
-      text_prompts: [{ text: "A golden retriever sitting", weight: 1 }],
-      cfg_scale: 7,
-      samples: 1,
-      steps: 30,
-    },
-  },
-  { response: GenerationResponseSchema },
-);
-```
-
 ### Generate with Specific Style
 
 ```typescript
@@ -263,12 +185,6 @@ The engine/model ID is part of the URL path:
 // Text-to-image with SDXL 1.0
 const path = "/v1/generation/stable-diffusion-xl-1024-v1-0/text-to-image";
 
-// Image-to-image
-const path = "/v1/generation/stable-diffusion-xl-1024-v1-0/image-to-image";
-
-// Upscaling
-const path = "/v1/generation/esrgan-v1-x2plus/image-to-image/upscale";
-
 // Available engines:
 // - stable-diffusion-xl-1024-v1-0 (SDXL 1.0)
 // - stable-diffusion-v1-6
@@ -402,9 +318,6 @@ const imageBase64 = result.artifacts[0].base64;
 
 // To save or display, you may need to add data URL prefix
 const dataUrl = `data:image/png;base64,${imageBase64}`;
-
-// For input images (image-to-image), provide raw base64 without prefix
-const inputImage = rawBase64WithoutPrefix;
 ```
 
 ### Seed for Reproducibility

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

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

package/src/integrations/stabilityai/overlays/image-uploads-unsupported.md

@@ -0,0 +1,3 @@
+## Image-to-Image, Upscale, and Inpainting
+
+The `/image-to-image`, `/image-to-image/upscale`, and `/image-to-image/masking` endpoints require `multipart/form-data`. This agent's sdk-api cannot upload images to them through `apiRequest()` because it serializes every body as JSON. Do not generate image-to-image, upscale, or inpainting code until the agent is upgraded. Text-to-image, account balance, and engine listing work as documented above.