@superblocksteam/sdk-api 0.0.12 → 2.0.0-SNAPSHOT.1d540461e97d05b4

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

@@ -0,0 +1,368 @@
+import type { PartialMessage } from "@bufbuild/protobuf";
+import { z } from "zod";
+
+import type { Property } from "@superblocksteam/types/dist/src/common/v1/plugin_pb";
+
+import { 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",
+    ]);
+  }
+  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/cosmosdb/client.ts

@@ -11,7 +11,10 @@ import type { z } from "zod";
 
 import type { Plugin as CosmosDBPlugin } from "@superblocksteam/types/dist/src/plugins/cosmosdb/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";
@@ -80,12 +83,10 @@ export class CosmosDBClientImpl
     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/documentation-resolver.test.ts

@@ -859,6 +859,42 @@ describe("resolveIntegrationDocumentation", () => {
       expect(docs).not.toContain("does not support the `responseType`");
     });
 
+    it("documents request bodyType only for agents whose sdk-api supports it", async () => {
+      const docs = await resolveIntegrationDocumentation("restapiintegration", {
+        sdkVersion: "0.0.7",
+      });
+
+      expect(docs).toContain('responseType: "binary"');
+      expect(docs).toContain('bodyType: "formUrlencoded"');
+      expect(docs).toContain('bodyType: "multipartForm"');
+      expect(docs).toContain('bodyType: "binary"');
+      expect(docs).not.toContain("does not support the `bodyType`");
+    });
+
+    it("documents binary request bodies with direct raw file bytes", async () => {
+      const docs = await resolveIntegrationDocumentation("restapiintegration", {
+        sdkVersion: "0.0.7",
+      });
+
+      expect(docs).not.toContain("Buffer.from(raw");
+      expect(docs).not.toContain("Buffer.isBuffer(raw");
+      expect(docs).toContain(
+        'pass the `Uint8Array` returned by `await file.readContentsAsync("raw")` directly as the body',
+      );
+      expect(docs).toContain('bodyType: "binary"');
+      expect(docs).toContain('body: await file.readContentsAsync("raw")');
+    });
+
+    it("notes bodyType non-support before sdk-api request body support", async () => {
+      const docs = await resolveIntegrationDocumentation("restapiintegration", {
+        sdkVersion: "0.0.6",
+      });
+
+      expect(docs).toContain('responseType: "binary"');
+      expect(docs).toContain("does not support the `bodyType` option");
+      expect(docs).not.toContain('bodyType: "formUrlencoded"');
+    });
+
     it("notes non-support instead of documenting responseType on older agents", async () => {
       const docs = await resolveIntegrationDocumentation("restapiintegration", {
         sdkVersion: "0.0.2",
@@ -869,10 +905,38 @@ describe("resolveIntegrationDocumentation", () => {
       expect(docs).not.toContain('responseType: "binary"');
     });
 
-    it("stays silent about responseType when the agent reports no sdk-api version", async () => {
+    it("stays silent about responseType and request bodyType when the agent reports no sdk-api version", async () => {
       const docs = await resolveIntegrationDocumentation("restapiintegration");
 
       expect(docs).not.toContain("responseType");
+      expect(docs).not.toContain("bodyType");
+    });
+  });
+
+  describe("jira attachment gating (real docs)", () => {
+    it("gates jira upload docs on sdk-api multipart support", async () => {
+      const supported = await resolveIntegrationDocumentation("jira", {
+        sdkVersion: "0.0.7",
+      });
+      expect(supported).toContain('bodyType: "multipartForm"');
+      expect(supported).toContain('readContentsAsync("raw")');
+      expect(supported).not.toContain("cannot upload");
+
+      const unsupported = await resolveIntegrationDocumentation("jira", {
+        sdkVersion: "0.0.6",
+      });
+      expect(unsupported).toContain("cannot upload");
+      expect(unsupported).not.toContain("bodyType");
+
+      const unversioned = await resolveIntegrationDocumentation("jira");
+      expect(unversioned).not.toContain("bodyType");
+      expect(unversioned).not.toContain("cannot upload");
+
+      for (const docs of [supported, unsupported, unversioned]) {
+        expect(docs).not.toContain("body: fileContent");
+        expect(docs).not.toContain("file: fileContent");
+        expect(docs).not.toContain('"Content-Type": "multipart/form-data"');
+      }
     });
   });
 

package/src/integrations/documentation.test.ts

@@ -118,3 +118,15 @@ describe("SQL integration documentation", () => {
     },
   );
 });
+
+describe("Anthropic integration documentation", () => {
+  it("uses claude-sonnet-5-20250715 instead of Claude 3.5 snapshot IDs", () => {
+    const readme = readIntegrationFile("anthropic", "README.md");
+    const typeDocs = readIntegrationFile("anthropic", "types.ts");
+
+    expect(readme).toContain("claude-sonnet-5-20250715");
+    expect(typeDocs).toContain("claude-sonnet-5-20250715");
+    expect(readme).not.toMatch(/claude-3-5-sonnet-\d{8}/);
+    expect(typeDocs).not.toMatch(/claude-3-5-sonnet-\d{8}/);
+  });
+});