@superblocksteam/sdk-api 0.0.13 → 0.0.14

package/src/integrations/base/decode-worker-binary-response.ts

@@ -7,6 +7,18 @@ import {
 
 export { REDACTED_BINARY_RESPONSE_DATA };
 
+// Node's decoder accepts missing and misplaced padding. A worker payload is
+// a canonical padded string, so reject anything else before decoding.
+const BASE64 =
+  /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+
+function decodeBase64(data: string): Uint8Array | undefined {
+  if (!BASE64.test(data)) {
+    return undefined;
+  }
+  return new Uint8Array(Buffer.from(data, "base64"));
+}
+
 const workerBinaryResponseSchema = z.union([
   z.instanceof(Uint8Array).transform((value) => new Uint8Array(value)),
   z
@@ -15,10 +27,23 @@ const workerBinaryResponseSchema = z.union([
       type: z.literal("Buffer"),
     })
     .transform((value, context) => {
+      if (typeof value.data === "string") {
+        const bytes = decodeBase64(value.data);
+        if (!bytes) {
+          context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "data must be base64",
+            path: ["data"],
+          });
+          return z.NEVER;
+        }
+        return bytes;
+      }
+
       if (!Array.isArray(value.data)) {
         context.addIssue({
           code: z.ZodIssueCode.custom,
-          message: "data must be an array of bytes",
+          message: "data must be an array of bytes or a base64 string",
           path: ["data"],
         });
         return z.NEVER;

package/src/integrations/base/index.ts

@@ -10,6 +10,7 @@ export { REST_API_BODY_TYPES } from "./types.js";
 export type {
   ApiRequestOptions,
   ApiRequestSchema,
+  BinaryApiRequestSchema,
   RestApiBodyType,
   RestApiResponseType,
   SupportsApiRequest,

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

@@ -9,6 +9,7 @@ import { RestApiClientBase } from "./rest-api-client-base.js";
 import type {
   ApiRequestOptions,
   ApiRequestSchema,
+  BinaryApiRequestSchema,
   RestApiResponseType,
   SupportsApiRequest,
 } from "./types.js";
@@ -30,7 +31,7 @@ export abstract class RestApiIntegrationClient
     options: ApiRequestOptions<TBody> & {
       responseType: "binary";
     },
-    schema?: ApiRequestSchema<TBody, Uint8Array>,
+    schema?: BinaryApiRequestSchema<TBody>,
     metadata?: TraceMetadata,
   ): Promise<Uint8Array>;
   async apiRequest<TBody>(
@@ -42,7 +43,7 @@ export abstract class RestApiIntegrationClient
   ): Promise<unknown>;
   async apiRequest<TBody, TResponse>(
     options: ApiRequestOptions<TBody>,
-    schema?: ApiRequestSchema<TBody, TResponse>,
+    schema?: ApiRequestSchema<TBody, TResponse> | BinaryApiRequestSchema<TBody>,
     metadata?: TraceMetadata,
   ): Promise<TResponse | Uint8Array | unknown> {
     if ((options.responseType ?? "json") === "json" && !schema?.response) {
@@ -67,7 +68,9 @@ export abstract class RestApiIntegrationClient
       metadata,
     );
 
-    if (!schema?.response) {
+    // Binary bodies are validated while decoding. A caller's schema cannot
+    // check them: the sandbox's Uint8Array is not the SDK's constructor.
+    if (options.responseType === "binary" || !schema?.response) {
       return result;
     }
 

package/src/integrations/base/types.ts

@@ -61,10 +61,10 @@ export interface ApiRequestOptions<TBody = unknown> {
    * How the response body should be decoded. Defaults to `"json"`.
    *
    * Use `"text"` for endpoints that return non-JSON payloads such as
-   * XML. Use `"binary"` for PDFs and other byte payloads. When
-   * requesting a text or binary response, omit the response schema (or
-   * use one matching the decoded value, e.g. `z.string()` or
-   * `z.instanceof(Uint8Array)`).
+   * XML. Use `"binary"` for PDFs and other byte payloads. Text responses
+   * may omit the response schema or use one matching the decoded value,
+   * e.g. `z.string()`. Binary responses never take a response schema; the
+   * decoded `Uint8Array` is already validated.
    */
   responseType?: RestApiResponseType;
 }
@@ -83,6 +83,24 @@ export interface ApiRequestSchema<TBody = unknown, TResponse = unknown> {
   response?: z.ZodSchema<TResponse>;
 }
 
+/**
+ * Schemas accepted by `apiRequest()` with `responseType: "binary"`.
+ *
+ * There is no response schema: the SDK decodes and validates the bytes
+ * itself. API code runs in a sandbox whose `Uint8Array` is a different
+ * constructor from the SDK's, so `z.instanceof(Uint8Array)` would reject
+ * every binary response. A `response` passed at runtime is ignored.
+ */
+export interface BinaryApiRequestSchema<TBody = unknown> {
+  /**
+   * Optional Zod schema for request body validation.
+   * When omitted, `options.body` is sent without validation.
+   */
+  body?: z.ZodSchema<TBody>;
+
+  response?: never;
+}
+
 /**
  * Interface for integration clients that support generic API requests.
  *
@@ -153,7 +171,8 @@ export interface SupportsApiRequest {
    * Execute a generic API request that returns binary data.
    *
    * @param options - Request configuration; `responseType` must be "binary"
-   * @param schema - Optional Zod schemas for request body and decoded response validation
+   * @param schema - Optional Zod schema for request body validation. Binary
+   * responses do not take a response schema.
    * @param metadata - Optional trace metadata for observability (label, description)
    * @returns The decoded body as a `Uint8Array`
    *
@@ -171,7 +190,7 @@ export interface SupportsApiRequest {
     options: ApiRequestOptions<TBody> & {
       responseType: "binary";
     },
-    schema?: ApiRequestSchema<TBody, Uint8Array>,
+    schema?: BinaryApiRequestSchema<TBody>,
     metadata?: TraceMetadata,
   ): Promise<Uint8Array>;
 

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/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.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,20 +287,20 @@ 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];
+      const bytes = [137, 80, 78, 71, 256];
       const { client } = createClient(workerBufferPayload(bytes));
 
       let caught: unknown;
       try {
-        await callApiRequest(
-          client,
-          { method: "GET", path: "/file.png", responseType: "binary" },
-          { response: z.literal("unexpected") },
-        );
+        await client.apiRequest({
+          method: "GET",
+          path: "/file.png",
+          responseType: "binary",
+        });
       } catch (error) {
         caught = error;
       }
@@ -461,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/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/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