@superblocksteam/sdk-api 0.0.11 → 0.0.12-body-types

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

@@ -0,0 +1,548 @@
+import type { PartialMessage } from "@bufbuild/protobuf";
+import { z } from "zod";
+
+import type { Property } from "@superblocksteam/types/dist/src/common/v1/plugin_pb";
+
+import { RestApiValidationError } from "../../errors.js";
+import { REST_API_BODY_TYPES } from "./types.js";
+import type { BinaryBody } from "./types.js";
+
+export const MAX_BINARY_BODY_BYTES = 20 * 1024 * 1024;
+
+const REQUEST_BODY_SIZE_ERROR_MESSAGE =
+  "request bodies must be 20 MiB or smaller because agent requests have a 28 MiB serialized size cap";
+
+type RequestBodyWireType =
+  | "jsonBody"
+  | "rawBody"
+  | "formData"
+  | "formDataBase64"
+  | "binaryBody";
+type InjectedHeader = { readonly key: string; readonly value: string };
+
+export type RequestBodyWirePatch = {
+  readonly body?: string;
+  readonly formData?: readonly PartialMessage<Property>[];
+  readonly bodyType?: RequestBodyWireType;
+  readonly injectedHeaders: readonly InjectedHeader[];
+};
+
+type MultipartPart =
+  | {
+      readonly kind: "field";
+      readonly key: string;
+      readonly value: string;
+      readonly byteLength: number;
+    }
+  | {
+      readonly kind: "file";
+      readonly key: string;
+      readonly value: string | BinaryBody;
+      readonly filename: string;
+      readonly byteLength: number;
+    };
+
+const requestBodyTypeSchema = z.enum(REST_API_BODY_TYPES);
+
+export function encodeRequestBody(input: {
+  body: unknown;
+  bodyType?: unknown;
+  headers?: Record<string, string>;
+}): RequestBodyWirePatch {
+  const bodyTypeResult = requestBodyTypeSchema.safeParse(
+    input.bodyType ?? "json",
+  );
+  if (!bodyTypeResult.success) {
+    throw new RestApiValidationError(
+      `Unsupported bodyType ${JSON.stringify(input.bodyType)} - expected one of: ${REST_API_BODY_TYPES.join(", ")}`,
+      { data: input.bodyType, zodError: bodyTypeResult.error },
+    );
+  }
+
+  const bodyType = bodyTypeResult.data;
+  if (input.body === undefined) {
+    if (bodyType === "json") return { injectedHeaders: [] };
+    throw validationError(
+      `bodyType "${bodyType}" requires a request body`,
+      input.body,
+      ["body"],
+    );
+  }
+
+  switch (bodyType) {
+    case "json":
+      return encodeJsonBody(input.body);
+    case "raw":
+      return encodeRawBody(input.body);
+    case "formUrlencoded":
+      return encodeFormUrlencodedBody(input.body, input.headers);
+    case "multipartForm":
+      return encodeMultipartFormBody(input.body, input.headers);
+    case "binary":
+      return encodeBinaryBody(input.body, input.headers);
+    default: {
+      const _exhaustive: never = bodyType;
+      return _exhaustive;
+    }
+  }
+}
+
+function encodeJsonBody(body: unknown): RequestBodyWirePatch {
+  if (isBinaryBody(body)) {
+    throw validationError(
+      'Binary request bodies require bodyType: "binary"',
+      body,
+      ["body"],
+    );
+  }
+  let serialized: string | undefined;
+  try {
+    serialized = JSON.stringify(body);
+  } catch (error) {
+    throw validationError(
+      `JSON request body could not be serialized: ${errorMessage(error)}`,
+      body,
+      ["body"],
+    );
+  }
+  if (serialized === undefined) {
+    throw validationError(
+      "JSON request body must serialize to a JSON value",
+      body,
+      ["body"],
+    );
+  }
+  validateRequestByteLength(utf8ByteLength(serialized), ["body"]);
+  return { body: serialized, bodyType: "jsonBody", injectedHeaders: [] };
+}
+
+function encodeRawBody(body: unknown): RequestBodyWirePatch {
+  if (typeof body !== "string" || body.length === 0) {
+    throw validationError(
+      'bodyType "raw" requires a non-empty string request body',
+      body,
+      ["body"],
+    );
+  }
+  validateRequestByteLength(utf8ByteLength(body), ["body"]);
+  return { body, bodyType: "rawBody", injectedHeaders: [] };
+}
+
+function encodeFormUrlencodedBody(
+  body: unknown,
+  headers: Record<string, string> | undefined,
+): RequestBodyWirePatch {
+  if (!isPlainRecord(body)) {
+    throw validationError(
+      'bodyType "formUrlencoded" requires a plain object request body',
+      body,
+      ["body"],
+    );
+  }
+  const params = new URLSearchParams();
+  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,
+        ["body", key],
+      );
+    }
+    appendFormUrlencodedValue(params, key, value);
+  }
+  const encodedBody = params.toString();
+  if (encodedBody.length === 0) {
+    throw validationError(
+      "formUrlencoded body must encode at least one field",
+      body,
+      ["body"],
+    );
+  }
+  validateRequestByteLength(utf8ByteLength(encodedBody), ["body"]);
+  return {
+    body: encodedBody,
+    bodyType: "rawBody",
+    injectedHeaders: contentTypeHeaderIfMissing(
+      headers,
+      "application/x-www-form-urlencoded",
+    ),
+  };
+}
+
+function appendFormUrlencodedValue(
+  params: URLSearchParams,
+  key: string,
+  value: unknown,
+): void {
+  if (Array.isArray(value)) {
+    for (const item of value)
+      params.append(key, formUrlencodedPrimitiveToString(key, item));
+    return;
+  }
+  params.append(key, formUrlencodedPrimitiveToString(key, value));
+}
+
+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 "${key}" is nested; flatten it using bracket notation such as "metadata[order_id]"`,
+      value,
+      ["body", key],
+    );
+  }
+  throw validationError(
+    `formUrlencoded field "${key}" must be a string, finite number, boolean, or array of those values`,
+    value,
+    ["body", key],
+  );
+}
+
+function encodeBinaryBody(
+  body: unknown,
+  headers: Record<string, string> | undefined,
+): RequestBodyWirePatch {
+  if (!isBinaryBody(body)) {
+    throw validationError(
+      'bodyType "binary" requires an ArrayBuffer or ArrayBufferView request body',
+      body,
+      ["body"],
+    );
+  }
+  const bytes = binaryBodyToBytes(body);
+  validateBinaryBodyByteLength(bytes.byteLength, body, ["body"]);
+  return {
+    body: base64Encode(bytes),
+    bodyType: "binaryBody",
+    injectedHeaders: contentTypeHeaderIfMissing(
+      headers,
+      "application/octet-stream",
+    ),
+  };
+}
+
+function encodeMultipartFormBody(
+  body: unknown,
+  headers: Record<string, string> | undefined,
+): RequestBodyWirePatch {
+  if (hasHeader(headers, "content-type")) {
+    throw validationError(
+      "multipartForm bodies cannot provide Content-Type because the multipart boundary is generated at execution time",
+      body,
+      ["headers", "Content-Type"],
+    );
+  }
+  if (!isPlainRecord(body) || Object.keys(body).length === 0) {
+    throw validationError(
+      'bodyType "multipartForm" requires a plain non-empty object request body',
+      body,
+      ["body"],
+    );
+  }
+  const parts = Object.entries(body)
+    .filter(([_key, value]) => value !== undefined)
+    .map(([key, value]) => parseMultipartPart(key, value));
+  if (parts.length === 0) {
+    throw validationError(
+      "multipartForm body must encode at least one field",
+      body,
+      ["body"],
+    );
+  }
+  validateRequestByteLength(totalMultipartPartBytes(parts), ["body"]);
+  const hasBinaryFile = parts.some(
+    (part) => part.kind === "file" && isBinaryBody(part.value),
+  );
+  return {
+    bodyType: hasBinaryFile ? "formDataBase64" : "formData",
+    formData: parts.map((part) => multipartPartToWire(part, hasBinaryFile)),
+    injectedHeaders: [],
+  };
+}
+
+function parseMultipartPart(key: string, value: unknown): MultipartPart {
+  if (key.length === 0)
+    throw validationError(
+      "multipartForm body keys must be non-empty strings",
+      value,
+      ["body", key],
+    );
+  if (
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    const stringValue = String(value);
+    return {
+      kind: "field",
+      key,
+      value: stringValue,
+      byteLength: utf8ByteLength(stringValue),
+    };
+  }
+  if (isBinaryBody(value)) {
+    throw validationError(
+      `multipartForm binary field "${key}" must be wrapped as { value, filename }`,
+      value,
+      ["body", key],
+    );
+  }
+  if (!isPlainRecord(value)) {
+    throw validationError(
+      `multipartForm field "${key}" must be a primitive value or { value, filename } file part`,
+      value,
+      ["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 "${key}" is missing required ${pluralize("key", missingKeys)}: ${missingKeys.join(", ")}`,
+      value,
+      ["body", key],
+    );
+  }
+  const unexpectedKeys = keys.filter(
+    (partKey) => partKey !== "value" && partKey !== "filename",
+  );
+  if (unexpectedKeys.length > 0) {
+    throw validationError(
+      `multipartForm file part "${key}" has unexpected ${pluralize("key", unexpectedKeys)}: ${unexpectedKeys.join(", ")}`,
+      value,
+      ["body", key],
+    );
+  }
+  if (typeof value.filename !== "string" || value.filename.length === 0) {
+    throw validationError(
+      `multipartForm file part "${key}" requires a non-empty filename`,
+      value,
+      ["body", key, "filename"],
+    );
+  }
+  if (typeof value.value !== "string" && !isBinaryBody(value.value)) {
+    throw validationError(
+      `multipartForm file part "${key}" value must be a string or binary body`,
+      value,
+      ["body", key, "value"],
+    );
+  }
+  const byteLength = isBinaryBody(value.value)
+    ? binaryBodyToBytes(value.value).byteLength
+    : utf8ByteLength(value.value);
+  validateMultipartFilePartByteLength(byteLength, value.value, [
+    "body",
+    key,
+    "value",
+  ]);
+  return {
+    kind: "file",
+    key,
+    value: value.value,
+    filename: value.filename,
+    byteLength,
+  };
+}
+
+function totalMultipartPartBytes(parts: MultipartPart[]): number {
+  return parts.reduce((total, part) => total + part.byteLength, 0);
+}
+
+function multipartPartToWire(
+  part: MultipartPart,
+  encodeFilePartsAsBase64: boolean,
+): PartialMessage<Property> {
+  if (part.kind === "field") return { key: part.key, value: part.value };
+  if (!encodeFilePartsAsBase64) {
+    if (typeof part.value !== "string") {
+      throw validationError(
+        "multipartForm binary file parts require formDataBase64 encoding",
+        part.value,
+        ["body", part.key, "value"],
+      );
+    }
+    return {
+      key: part.key,
+      value: part.value,
+      file: { filename: part.filename },
+    };
+  }
+  const bytes = isBinaryBody(part.value)
+    ? binaryBodyToBytes(part.value)
+    : textToUtf8Bytes(part.value);
+  return {
+    key: part.key,
+    value: base64Encode(bytes),
+    file: { filename: part.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 isBinaryBody(value: unknown): value is BinaryBody {
+  return value instanceof ArrayBuffer || ArrayBuffer.isView(value);
+}
+
+function binaryBodyToBytes(value: BinaryBody): Uint8Array {
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+}
+
+function validateBinaryBodyByteLength(
+  byteLength: number,
+  data: unknown,
+  path: (string | number)[],
+): void {
+  if (byteLength === 0)
+    throw validationError(
+      "binary request bodies must be non-empty",
+      data,
+      path,
+    );
+  validateRequestByteLength(byteLength, path, data);
+}
+
+function validateMultipartFilePartByteLength(
+  byteLength: number,
+  data: string | BinaryBody,
+  path: (string | number)[],
+): void {
+  if (byteLength <= MAX_BINARY_BODY_BYTES) return;
+  throw validationError(
+    REQUEST_BODY_SIZE_ERROR_MESSAGE,
+    isBinaryBody(data) ? data : { byteLength },
+    path,
+  );
+}
+
+function validateRequestByteLength(
+  byteLength: number,
+  path: (string | number)[],
+  data: unknown = { byteLength },
+): void {
+  if (byteLength <= MAX_BINARY_BODY_BYTES) return;
+  throw validationError(REQUEST_BODY_SIZE_ERROR_MESSAGE, data, path);
+}
+
+function contentTypeHeaderIfMissing(
+  headers: Record<string, string> | undefined,
+  value: string,
+): readonly InjectedHeader[] {
+  return hasHeader(headers, "content-type")
+    ? []
+    : [{ key: "Content-Type", value }];
+}
+
+function hasHeader(
+  headers: Record<string, string> | undefined,
+  headerName: string,
+): boolean {
+  return (
+    !!headers &&
+    Object.keys(headers).some(
+      (key) => key.toLowerCase() === headerName.toLowerCase(),
+    )
+  );
+}
+
+function base64Encode(bytes: Uint8Array): string {
+  if (typeof Buffer !== "undefined")
+    return Buffer.from(
+      bytes.buffer,
+      bytes.byteOffset,
+      bytes.byteLength,
+    ).toString("base64");
+  const alphabet =
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  let output = "";
+  for (let index = 0; index < bytes.length; index += 3) {
+    const first = bytes[index];
+    const second = bytes[index + 1];
+    const third = bytes[index + 2];
+    output += alphabet[first >> 2];
+    output += alphabet[((first & 0x03) << 4) | ((second ?? 0) >> 4)];
+    output +=
+      second === undefined
+        ? "="
+        : alphabet[((second & 0x0f) << 2) | ((third ?? 0) >> 6)];
+    output += third === undefined ? "=" : alphabet[third & 0x3f];
+  }
+  return output;
+}
+
+function textToUtf8Bytes(value: string): Uint8Array {
+  if (typeof TextEncoder !== "undefined")
+    return new TextEncoder().encode(value);
+  const bytes: number[] = [];
+  for (let index = 0; index < value.length; index += 1) {
+    const codePoint = value.codePointAt(index);
+    if (codePoint === undefined) continue;
+    if (codePoint > 0xffff) index += 1;
+    appendCodePointAsUtf8(bytes, codePoint);
+  }
+  return Uint8Array.from(bytes);
+}
+
+function utf8ByteLength(value: string): number {
+  let byteLength = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    const codePoint = value.codePointAt(index);
+    if (codePoint === undefined) continue;
+    if (codePoint > 0xffff) index += 1;
+    if (codePoint <= 0x7f) byteLength += 1;
+    else if (codePoint <= 0x7ff) byteLength += 2;
+    else if (codePoint <= 0xffff) byteLength += 3;
+    else byteLength += 4;
+  }
+  return byteLength;
+}
+
+function pluralize(word: string, values: readonly unknown[]): string {
+  return values.length === 1 ? word : `${word}s`;
+}
+
+function appendCodePointAsUtf8(bytes: number[], codePoint: number): void {
+  if (codePoint <= 0x7f) bytes.push(codePoint);
+  else if (codePoint <= 0x7ff)
+    bytes.push(0xc0 | (codePoint >> 6), 0x80 | (codePoint & 0x3f));
+  else if (codePoint <= 0xffff)
+    bytes.push(
+      0xe0 | (codePoint >> 12),
+      0x80 | ((codePoint >> 6) & 0x3f),
+      0x80 | (codePoint & 0x3f),
+    );
+  else
+    bytes.push(
+      0xf0 | (codePoint >> 18),
+      0x80 | ((codePoint >> 12) & 0x3f),
+      0x80 | ((codePoint >> 6) & 0x3f),
+      0x80 | (codePoint & 0x3f),
+    );
+}
+
+function validationError(
+  message: string,
+  data: unknown,
+  path: (string | number)[],
+): RestApiValidationError {
+  return new RestApiValidationError(message, {
+    data,
+    zodError: new z.ZodError([{ code: z.ZodIssueCode.custom, message, path }]),
+  });
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

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

@@ -8,6 +8,7 @@ import { RestApiValidationError } from "../../errors.js";
 import type { QueryExecutor, TraceMetadata } from "../registry.js";
 import type { IntegrationConfig, IntegrationClientImpl } from "../types.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";
 
@@ -92,12 +93,25 @@ export abstract class RestApiClientBase implements IntegrationClientImpl {
       responseType,
     };
 
-    if (options.body !== undefined) {
-      request.body = JSON.stringify(options.body);
-      request.bodyType = "jsonBody";
+    const bodyPatch = encodeRequestBody({
+      body: options.body,
+      bodyType: options.bodyType,
+      headers: options.headers,
+    });
+    if (bodyPatch.body !== undefined) {
+      request.body = bodyPatch.body;
+    }
+    if (bodyPatch.formData !== undefined) {
+      request.formData = [...bodyPatch.formData];
+    }
+    if (bodyPatch.bodyType !== undefined) {
+      request.bodyType = bodyPatch.bodyType;
+    }
+    for (const { key, value } of bodyPatch.injectedHeaders) {
+      headers.push(this.createParam(key, value));
     }
 
-    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/types.ts

@@ -8,6 +8,34 @@ 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 type BinaryBody = ArrayBuffer | ArrayBufferView;
+
+export type MultipartFormValue =
+  | string
+  | number
+  | boolean
+  | { value: string | BinaryBody; filename: string };
+
+export type MultipartFormBody = Record<string, MultipartFormValue>;
+
+export type FormUrlencodedValue =
+  | string
+  | number
+  | boolean
+  | readonly (string | number | boolean)[];
+
+export type FormUrlencodedBody = Record<string, FormUrlencodedValue>;
+
 export interface ApiRequestOptions<TBody = unknown> {
   /**
    * HTTP method for the request.
@@ -25,6 +53,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 +104,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 +145,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>(