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

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/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/utils.ts

@@ -1,7 +1,23 @@
+import { z } from "zod";
+
+import { isBinaryData, RestApiValidationError } from "../errors.js";
+
+const MAX_OPTION_VALUE_CHARS = 64;
+
 /**
  * Integration utility functions.
  */
 
+/**
+ * Truncates a string to at most `max` characters, appending "..." when it
+ * was cut. The single place that defines how caller-supplied strings are
+ * bounded for display (`describeType`, `describeOptionValue`) and for the
+ * Zod issue `path` (`boundedPathSegment`).
+ */
+function truncate(value: string, max = MAX_OPTION_VALUE_CHARS): string {
+  return value.length > max ? `${value.slice(0, max)}...` : value;
+}
+
 /**
  * Produces a safe, human-readable description of a value's type
  * without exposing potentially sensitive data.
@@ -18,8 +34,42 @@ export function describeType(value: unknown): string {
   if (t === "object") {
     const keys = Object.keys(value as Record<string, unknown>);
     if (keys.length === 0) return "empty object";
-    return `object with keys [${keys.slice(0, 5).join(", ")}${keys.length > 5 ? ", ..." : ""}]`;
+    const shown = keys.slice(0, 5).map((k) => truncate(k));
+    return `object with keys [${shown.join(", ")}${keys.length > 5 ? ", ..." : ""}]`;
   }
 
   return t;
 }
+
+/**
+ * Describes a caller-supplied option value for an error message with bounded
+ * length. Strings are quoted and truncated; everything else is described by type
+ * so arbitrary payloads never land in the message.
+ */
+export function describeOptionValue(value: unknown): string {
+  if (isBinaryData(value)) {
+    return `binary data (${value.byteLength} bytes)`;
+  }
+  if (typeof value !== "string") return describeType(value);
+  return JSON.stringify(truncate(value));
+}
+
+function boundedPathSegment(segment: string | number): string | number {
+  return typeof segment === "string" ? truncate(segment) : segment;
+}
+
+export function validationError(
+  message: string,
+  path: (string | number)[],
+): RestApiValidationError {
+  return new RestApiValidationError(message, {
+    data: undefined,
+    zodError: new z.ZodError([
+      {
+        code: z.ZodIssueCode.custom,
+        message,
+        path: path.map(boundedPathSegment),
+      },
+    ]),
+  });
+}