@superblocksteam/sdk-api 0.0.12 → 0.0.13

package/src/integrations/base/request-body.ts

@@ -0,0 +1,392 @@
+import type { PartialMessage } from "@bufbuild/protobuf";
+import { z } from "zod";
+
+import type { Property } from "@superblocksteam/types/dist/src/common/v1/plugin_pb";
+
+import { findBinaryDataPath, isBinaryData } from "../../errors.js";
+import { describeOptionValue, validationError } from "../utils.js";
+import { REST_API_BODY_TYPES } from "./types.js";
+
+type BinaryBody = ArrayBuffer | ArrayBufferView;
+
+type RequestBodyWireType =
+  | "jsonBody"
+  | "rawBody"
+  | "formDataBase64"
+  | "binaryBody";
+
+/**
+ * Fields safe to spread directly onto the proto `RestApiRequest`. Never
+ * carries `contentType`: that is a header directive, not a wire field, and
+ * lives on `EncodedRequestBody` instead so a caller cannot spread it onto
+ * the wire message by mistake.
+ */
+export type RequestBodyWireFields = {
+  readonly body?: string;
+  readonly formData?: PartialMessage<Property>[];
+  readonly bodyType?: RequestBodyWireType;
+};
+
+/**
+ * The encoder's full result: wire fields plus an optional Content-Type the
+ * caller must push onto request headers itself.
+ */
+export type EncodedRequestBody = {
+  readonly wire: RequestBodyWireFields;
+  readonly contentType?: string;
+};
+
+const requestBodyTypeSchema = z.enum(REST_API_BODY_TYPES);
+
+export function encodeRequestBody(input: {
+  body: unknown;
+  bodyType?: unknown;
+  headers?: Record<string, string>;
+}): EncodedRequestBody {
+  const bodyTypeResult = requestBodyTypeSchema.safeParse(
+    input.bodyType === undefined ? "json" : input.bodyType,
+  );
+  if (!bodyTypeResult.success) {
+    throw validationError(
+      `Unsupported bodyType ${describeOptionValue(input.bodyType)} - expected one of: ${REST_API_BODY_TYPES.join(", ")}`,
+      ["bodyType"],
+    );
+  }
+
+  const bodyType = bodyTypeResult.data;
+  if (input.body === undefined) {
+    if (bodyType === "json") return { wire: {} };
+    throw validationError(`bodyType "${bodyType}" requires a request body`, [
+      "body",
+    ]);
+  }
+
+  switch (bodyType) {
+    case "json":
+      return { wire: encodeJsonBody(input.body) };
+    case "raw":
+      return { wire: encodeRawBody(input.body) };
+    case "formUrlencoded":
+      return encodeFormUrlencodedBody(input.body, input.headers);
+    case "multipartForm":
+      return { wire: encodeMultipartFormBody(input.body, input.headers) };
+    case "binary":
+      return encodeBinaryBody(input.body, input.headers);
+  }
+}
+
+// JSON.stringify's own error text is unbounded: a circular-structure message
+// embeds the caller's full property path and constructor names, and a
+// throwing toJSON()/getter contributes an arbitrary caller-authored string.
+// Every other message in this module goes through describeOptionValue's
+// bounded conventions; classify the failure instead of echoing its text.
+function describeJsonSerializationFailure(error: unknown): string {
+  if (
+    error instanceof TypeError &&
+    /circular (structure|reference)/i.test(error.message)
+  ) {
+    return "the body contains a circular reference";
+  }
+  if (error instanceof TypeError && /BigInt/i.test(error.message)) {
+    return "the body contains a BigInt value";
+  }
+  return "a nested value's toJSON, toString, or getter threw while serializing the body";
+}
+
+function encodeJsonBody(body: unknown): RequestBodyWireFields {
+  if (isBinaryData(body)) {
+    throw validationError('Binary request bodies require bodyType: "binary"', [
+      "body",
+    ]);
+  }
+  // The walk itself only ever throws MAX_BINARY_SCAN_DEPTH's RangeError
+  // (see errors.ts); anything else (a throwing getter, an unusual toJSON)
+  // is left for JSON.stringify to judge below, which reports the same
+  // failure as a serialization error. A depth-capped walk fails closed
+  // instead: treat the body as containing binary at an unknown location
+  // rather than assume none, because JSON.stringify does not throw on a
+  // Uint8Array/Buffer/typed array -- the exact shape this check exists to
+  // catch -- it silently serializes them into digit-keyed garbage.
+  let binaryPath: (string | number)[] | undefined;
+  try {
+    binaryPath = findBinaryDataPath(body, isBinaryData);
+  } catch (error) {
+    binaryPath = error instanceof RangeError ? [] : undefined;
+  }
+  if (binaryPath !== undefined) {
+    const location =
+      binaryPath.length > 0
+        ? ` at ${describeOptionValue(binaryPath.join("."))}`
+        : "";
+    throw validationError(
+      `bodyType "json" request body contains binary data${location}; send file parts with bodyType: "multipartForm" as { value, filename }, or send bytes alone with bodyType: "binary"`,
+      ["body", ...binaryPath],
+    );
+  }
+  let serialized: string | undefined;
+  try {
+    serialized = JSON.stringify(body);
+  } catch (error) {
+    throw validationError(
+      `bodyType "json" request body is not JSON-serializable: ${describeJsonSerializationFailure(error)}`,
+      ["body"],
+    );
+  }
+  if (serialized === undefined) {
+    throw validationError(
+      `bodyType "json" cannot serialize a ${typeof body} request body`,
+      ["body"],
+    );
+  }
+  return { body: serialized, bodyType: "jsonBody" };
+}
+
+function encodeRawBody(body: unknown): RequestBodyWireFields {
+  if (typeof body !== "string" || body.length === 0) {
+    throw validationError(
+      'bodyType "raw" requires a non-empty string request body',
+      ["body"],
+    );
+  }
+  return { body, bodyType: "rawBody" };
+}
+
+// A field's value may be a scalar or an array; either way, undefined items
+// (an explicitly-undefined optional field, or an undefined array element)
+// are omitted rather than encoded, matching JSON.stringify's default-body
+// semantics. Shared by encodeFormUrlencodedBody and encodeMultipartFormBody.
+function definedArrayValues(value: unknown): unknown[] {
+  return (Array.isArray(value) ? value : [value]).filter(
+    (item) => item !== undefined,
+  );
+}
+
+function encodeFormUrlencodedBody(
+  body: unknown,
+  headers: Record<string, string> | undefined,
+): EncodedRequestBody {
+  if (!isPlainRecord(body)) {
+    throw validationError(
+      'bodyType "formUrlencoded" requires a plain object request body',
+      ["body"],
+    );
+  }
+  const pairs: string[] = [];
+  for (const [key, value] of Object.entries(body)) {
+    if (value === undefined) continue;
+    if (key.length === 0) {
+      throw validationError(
+        "formUrlencoded body keys must be non-empty strings",
+        ["body", key],
+      );
+    }
+    const encodedKey = formUrlencode(key, key);
+    for (const item of definedArrayValues(value)) {
+      pairs.push(
+        `${encodedKey}=${formUrlencode(formUrlencodedPrimitiveToString(key, item), key)}`,
+      );
+    }
+  }
+  if (pairs.length === 0) {
+    throw validationError(
+      "formUrlencoded body must encode at least one field",
+      ["body"],
+    );
+  }
+  return {
+    wire: { body: pairs.join("&"), bodyType: "rawBody" },
+    contentType: contentTypeIfMissing(
+      headers,
+      "application/x-www-form-urlencoded",
+    ),
+  };
+}
+
+// The WASM sdk-api sandbox has no URLSearchParams global, so encode by hand.
+// encodeURIComponent's unreserved set leaves `! ' ( ) ~` unescaped, but the
+// WHATWG application/x-www-form-urlencoded safe set (what URLSearchParams
+// produces) escapes those five; only alphanumerics, `* - . _`, and space
+// (as `+`) stay literal.
+function formUrlencode(value: string, key: string): string {
+  try {
+    return encodeURIComponent(value)
+      .replace(/%20/g, "+")
+      .replace(
+        /[!'()~]/g,
+        (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`,
+      );
+  } catch {
+    throw validationError(
+      `formUrlencoded field ${describeOptionValue(key)} contains a lone surrogate and cannot be percent-encoded`,
+      ["body", key],
+    );
+  }
+}
+
+function formUrlencodedPrimitiveToString(key: string, value: unknown): string {
+  if (typeof value === "string" || typeof value === "boolean")
+    return String(value);
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  if (typeof value === "object" && value !== null) {
+    throw validationError(
+      `formUrlencoded field ${describeOptionValue(key)} is nested; flatten it using bracket notation such as "metadata[order_id]"`,
+      ["body", key],
+    );
+  }
+  throw validationError(
+    `formUrlencoded field ${describeOptionValue(key)} must be a string, finite number, boolean, or array of those values`,
+    ["body", key],
+  );
+}
+
+function encodeBinaryBody(
+  body: unknown,
+  headers: Record<string, string> | undefined,
+): EncodedRequestBody {
+  if (!isBinaryData(body)) {
+    throw validationError(
+      'bodyType "binary" requires an ArrayBuffer or ArrayBufferView request body',
+      ["body"],
+    );
+  }
+  if (body.byteLength === 0) {
+    throw validationError("binary request bodies must be non-empty", ["body"]);
+  }
+  return {
+    wire: { body: toBuffer(body).toString("base64"), bodyType: "binaryBody" },
+    contentType: contentTypeIfMissing(headers, "application/octet-stream"),
+  };
+}
+
+function encodeMultipartFormBody(
+  body: unknown,
+  headers: Record<string, string> | undefined,
+): RequestBodyWireFields {
+  if (hasHeader(headers, "content-type")) {
+    throw validationError(
+      "multipartForm bodies cannot provide Content-Type because the multipart boundary is generated at execution time",
+      ["headers", "Content-Type"],
+    );
+  }
+  if (!isPlainRecord(body)) {
+    throw validationError(
+      'bodyType "multipartForm" requires a plain object request body',
+      ["body"],
+    );
+  }
+  const formData = Object.entries(body).flatMap(([key, value]) =>
+    definedArrayValues(value).map((item) => parseMultipartPart(key, item)),
+  );
+  if (formData.length === 0) {
+    throw validationError("multipartForm body must encode at least one field", [
+      "body",
+    ]);
+  }
+  return { bodyType: "formDataBase64", formData };
+}
+
+function parseMultipartPart(
+  key: string,
+  value: unknown,
+): PartialMessage<Property> {
+  if (key.length === 0)
+    throw validationError("multipartForm body keys must be non-empty strings", [
+      "body",
+      key,
+    ]);
+  if (
+    typeof value === "string" ||
+    typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value))
+  ) {
+    return { key, value: String(value) };
+  }
+  if (isBinaryData(value)) {
+    throw validationError(
+      `multipartForm binary field ${describeOptionValue(key)} must be wrapped as { value, filename }`,
+      ["body", key],
+    );
+  }
+  if (!isPlainRecord(value)) {
+    throw validationError(
+      `multipartForm field ${describeOptionValue(key)} must be a primitive value or { value, filename } file part`,
+      ["body", key],
+    );
+  }
+  const keys = Object.keys(value).filter(
+    (partKey) => value[partKey] !== undefined,
+  );
+  const missingKeys = ["value", "filename"].filter(
+    (requiredKey) => !keys.includes(requiredKey),
+  );
+  if (missingKeys.length > 0) {
+    throw validationError(
+      `multipartForm file part ${describeOptionValue(key)} is missing required ${pluralize("key", missingKeys)}: ${missingKeys.join(", ")}`,
+      ["body", key],
+    );
+  }
+  const unexpectedKeys = keys.filter(
+    (partKey) => partKey !== "value" && partKey !== "filename",
+  );
+  if (unexpectedKeys.length > 0) {
+    const shown = unexpectedKeys.slice(0, 5).map(describeOptionValue);
+    const suffix = unexpectedKeys.length > 5 ? ", ..." : "";
+    throw validationError(
+      `multipartForm file part ${describeOptionValue(key)} has unexpected ${pluralize("key", unexpectedKeys)}: ${shown.join(", ")}${suffix}`,
+      ["body", key],
+    );
+  }
+  if (typeof value.filename !== "string" || value.filename.length === 0) {
+    throw validationError(
+      `multipartForm file part ${describeOptionValue(key)} requires a non-empty filename`,
+      ["body", key, "filename"],
+    );
+  }
+  if (typeof value.value !== "string" && !isBinaryData(value.value)) {
+    throw validationError(
+      `multipartForm file part ${describeOptionValue(key)} value must be a string or binary body`,
+      ["body", key, "value"],
+    );
+  }
+  return {
+    key,
+    value: toBuffer(value.value).toString("base64"),
+    file: { filename: value.filename },
+  };
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function toBuffer(value: string | BinaryBody): Buffer {
+  if (typeof value === "string") return Buffer.from(value, "utf8");
+  if (value instanceof ArrayBuffer) return Buffer.from(value);
+  return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+}
+
+function contentTypeIfMissing(
+  headers: Record<string, string> | undefined,
+  value: string,
+): string | undefined {
+  return hasHeader(headers, "content-type") ? undefined : value;
+}
+
+function hasHeader(
+  headers: Record<string, string> | undefined,
+  headerName: string,
+): boolean {
+  return (
+    !!headers &&
+    Object.keys(headers).some(
+      (key) => key.toLowerCase() === headerName.toLowerCase(),
+    )
+  );
+}
+
+function pluralize(word: string, values: readonly unknown[]): string {
+  return values.length === 1 ? word : `${word}s`;
+}

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

@@ -4,10 +4,15 @@ 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";
 import type { ApiRequestOptions } from "./types.js";
 
@@ -45,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,
         );
       }
     }
@@ -73,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(),
@@ -90,14 +99,10 @@ export abstract class RestApiClientBase implements IntegrationClientImpl {
       headers,
       params,
       responseType,
+      ...bodyWire,
     };
 
-    if (options.body !== undefined) {
-      request.body = JSON.stringify(options.body);
-      request.bodyType = "jsonBody";
-    }
-
-    const result = await this.executeQuery({ ...request }, undefined, metadata);
+    const result = await this.executeQuery(request, undefined, metadata);
 
     if (result === null || result === undefined) {
       throw new RestApiValidationError(

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

@@ -8,6 +8,16 @@ export const REST_API_RESPONSE_TYPES = ["binary", "json", "text"] as const;
 
 export type RestApiResponseType = (typeof REST_API_RESPONSE_TYPES)[number];
 
+export const REST_API_BODY_TYPES = [
+  "json",
+  "raw",
+  "formUrlencoded",
+  "multipartForm",
+  "binary",
+] as const;
+
+export type RestApiBodyType = (typeof REST_API_BODY_TYPES)[number];
+
 export interface ApiRequestOptions<TBody = unknown> {
   /**
    * HTTP method for the request.
@@ -25,6 +35,18 @@ export interface ApiRequestOptions<TBody = unknown> {
    */
   body?: TBody;
 
+  /**
+   * How the request body should be encoded. Defaults to `"json"`.
+   *
+   * Use `"raw"` for caller-encoded string bodies, `"formUrlencoded"` for
+   * `application/x-www-form-urlencoded` payloads, `"multipartForm"` for
+   * multipart form fields and file parts, and `"binary"` for byte payloads.
+   * Worker wire values such as `"jsonBody"`, `"rawBody"`, `"formData"`,
+   * `"fileForm"`, `"binaryBody"`, and `"formDataBase64"` are not public SDK
+   * `bodyType` values.
+   */
+  bodyType?: RestApiBodyType;
+
   /**
    * Optional query parameters
    */
@@ -64,16 +86,20 @@ export interface ApiRequestSchema<TBody = unknown, TResponse = unknown> {
 /**
  * Interface for integration clients that support generic API requests.
  *
- * Providing a response schema gives type-safe, validated results. Omitting
- * it returns the decoded response: `Uint8Array` for `responseType: "binary"`,
- * or `unknown` for `responseType: "text"`. JSON still requires a schema.
- * Object schemas only make sense for JSON-shaped results.
+ * Providing a response schema gives type-safe, validated results. Omitting it
+ * returns the decoded response: `Uint8Array` for `responseType: "binary"`, or
+ * `unknown` for `responseType: "text"`. JSON still requires a schema. Object
+ * schemas only make sense for JSON-shaped results.
+ *
+ * Request bodies default to JSON. Set `bodyType` to one of `"json"`, `"raw"`,
+ * `"formUrlencoded"`, `"multipartForm"`, or `"binary"` when the endpoint
+ * expects a different request encoding.
  */
 export interface SupportsApiRequest {
   /**
    * Execute a generic API request with type-safe validation.
    *
-   * @param options - Request configuration including method, path, params, and body
+   * @param options - Request configuration including method, path, params, body, and bodyType
    * @param schema - Zod schemas for request body and response validation
    * @param metadata - Optional trace metadata for observability (label, description)
    * @returns Validated response data
@@ -101,6 +127,16 @@ export interface SupportsApiRequest {
    *   { label: 'slack.postMessage', description: 'Post a message to #alerts' }
    * );
    * // result is typed as { ts: string; channel: string }
+   *
+   * await ctx.integrations.stripe.apiRequest(
+   *   {
+   *     method: 'POST',
+   *     path: '/v1/charges',
+   *     bodyType: 'formUrlencoded',
+   *     body: { amount: 2000, currency: 'usd' },
+   *   },
+   *   { response: StripeChargeSchema }
+   * );
    * ```
    */
   apiRequest<TBody, TResponse>(

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