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

package/src/integrations/restapiintegration/client.body-types.test.ts

@@ -1,214 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { z } from "zod";
-
-import { RestApiValidationError } from "../../errors.js";
-import type { IntegrationConfig } from "../types.js";
-import { RestApiIntegrationPluginClientImpl } from "./client.js";
-
-const TEST_CONFIG: IntegrationConfig = {
-  id: "restapi-test-id",
-  name: "Test REST API",
-  pluginId: "restapiintegration",
-  configuration: {},
-};
-
-const JsonResponseSchema = z.object({ ok: z.boolean() });
-
-function createClient() {
-  const executeQuery = vi.fn().mockResolvedValue({ ok: true });
-  const client = new RestApiIntegrationPluginClientImpl(
-    TEST_CONFIG,
-    executeQuery,
-  );
-  return { client, executeQuery };
-}
-
-function callApiRequest(
-  client: RestApiIntegrationPluginClientImpl,
-  ...args: unknown[]
-): Promise<unknown> {
-  return Reflect.apply(client.apiRequest, client, args);
-}
-
-describe("RestApiIntegrationPluginClientImpl request body types", () => {
-  it("preserves omitted and explicit JSON body wire behavior", async () => {
-    for (const bodyType of [undefined, "json"] as const) {
-      const { client, executeQuery } = createClient();
-      await client.apiRequest(
-        { method: "POST", path: "/payments", body: { amount: 42 }, bodyType },
-        { response: JsonResponseSchema },
-      );
-      expect(executeQuery).toHaveBeenCalledWith(
-        expect.objectContaining({
-          body: JSON.stringify({ amount: 42 }),
-          bodyType: "jsonBody",
-        }),
-        undefined,
-        undefined,
-      );
-    }
-  });
-
-  it("sends raw string bodies as rawBody", async () => {
-    const { client, executeQuery } = createClient();
-    await client.apiRequest(
-      {
-        method: "POST",
-        path: "/xml",
-        body: "<note>hello</note>",
-        bodyType: "raw",
-      },
-      { response: JsonResponseSchema },
-    );
-    expect(executeQuery).toHaveBeenCalledWith(
-      expect.objectContaining({
-        body: "<note>hello</note>",
-        bodyType: "rawBody",
-      }),
-      undefined,
-      undefined,
-    );
-  });
-
-  it("sends formUrlencoded bodies as rawBody with injected Content-Type", async () => {
-    const { client, executeQuery } = createClient();
-    await client.apiRequest(
-      {
-        method: "POST",
-        path: "/charges",
-        body: { amount: 2000, currency: "usd", "metadata[order_id]": "6735" },
-        bodyType: "formUrlencoded",
-      },
-      { response: JsonResponseSchema },
-    );
-    expect(executeQuery).toHaveBeenCalledWith(
-      expect.objectContaining({
-        body: "amount=2000&currency=usd&metadata%5Border_id%5D=6735",
-        bodyType: "rawBody",
-        headers: [
-          { key: "Content-Type", value: "application/x-www-form-urlencoded" },
-        ],
-      }),
-      undefined,
-      undefined,
-    );
-  });
-
-  it("sends binary bodies as base64 binaryBody with default Content-Type", async () => {
-    const bytes = Uint8Array.from([137, 80, 78, 71]);
-    const { client, executeQuery } = createClient();
-    await client.apiRequest(
-      {
-        method: "PUT",
-        path: "/files/report.png",
-        body: bytes,
-        bodyType: "binary",
-      },
-      { response: JsonResponseSchema },
-    );
-    expect(executeQuery).toHaveBeenCalledWith(
-      expect.objectContaining({
-        body: Buffer.from(bytes).toString("base64"),
-        bodyType: "binaryBody",
-        headers: [{ key: "Content-Type", value: "application/octet-stream" }],
-      }),
-      undefined,
-      undefined,
-    );
-  });
-
-  it("sends text multipart file parts as formData", async () => {
-    const { client, executeQuery } = createClient();
-    await client.apiRequest(
-      {
-        method: "POST",
-        path: "/upload",
-        body: {
-          note: "hello",
-          file: { value: "contents", filename: "note.txt" },
-        },
-        bodyType: "multipartForm",
-      },
-      { response: JsonResponseSchema },
-    );
-    expect(executeQuery).toHaveBeenCalledWith(
-      expect.objectContaining({
-        bodyType: "formData",
-        formData: [
-          { key: "note", value: "hello" },
-          { key: "file", value: "contents", file: { filename: "note.txt" } },
-        ],
-      }),
-      undefined,
-      undefined,
-    );
-  });
-
-  it("sends mixed multipart file parts as formDataBase64 with no top-level body", async () => {
-    const bytes = Uint8Array.from([137, 80, 78, 71]);
-    const { client, executeQuery } = createClient();
-    await client.apiRequest(
-      {
-        method: "POST",
-        path: "/upload",
-        body: { note: "mixed", image: { value: bytes, filename: "b.png" } },
-        bodyType: "multipartForm",
-      },
-      { response: JsonResponseSchema },
-    );
-    expect(executeQuery).toHaveBeenCalledWith(
-      expect.objectContaining({
-        bodyType: "formDataBase64",
-        formData: [
-          { key: "note", value: "mixed" },
-          {
-            key: "image",
-            value: Buffer.from(bytes).toString("base64"),
-            file: { filename: "b.png" },
-          },
-        ],
-      }),
-      undefined,
-      undefined,
-    );
-    expect(executeQuery.mock.calls[0][0]).not.toHaveProperty("body");
-  });
-
-  it("rejects invalid bodyType and invalid bodies before executeQuery", async () => {
-    for (const bodyType of [
-      "form",
-      "jsonBody",
-      "rawBody",
-      "formData",
-      "fileForm",
-      "binaryBody",
-      "formDataBase64",
-    ]) {
-      const { client, executeQuery } = createClient();
-      await expect(
-        callApiRequest(
-          client,
-          { method: "POST", path: "/bad", body: {}, bodyType },
-          { response: JsonResponseSchema },
-        ),
-      ).rejects.toThrow(RestApiValidationError);
-      expect(executeQuery).not.toHaveBeenCalled();
-    }
-
-    const invalidCases = [
-      { method: "POST", path: "/bad", body: Uint8Array.from([1]) },
-      { method: "POST", path: "/bad", body: () => undefined },
-      { method: "POST", path: "/bad", bodyType: "raw" },
-      { method: "POST", path: "/bad", bodyType: "formUrlencoded" },
-      { method: "POST", path: "/bad", bodyType: "multipartForm" },
-      { method: "POST", path: "/bad", bodyType: "binary" },
-    ];
-    for (const options of invalidCases) {
-      const { client, executeQuery } = createClient();
-      await expect(
-        callApiRequest(client, options, { response: JsonResponseSchema }),
-      ).rejects.toThrow(RestApiValidationError);
-      expect(executeQuery).not.toHaveBeenCalled();
-    }
-  });
-});

package/src/integrations/restapiintegration/overlays/request-body-types-unsupported.md

@@ -1,7 +0,0 @@
-## Request Body Types
-
-This organization's agent does not support the `bodyType` option on `apiRequest()` yet. Its worker runs an sdk-api version that always serializes request bodies as JSON, so raw strings, binary uploads, multipart/form-data, and application/x-www-form-urlencoded payloads cannot be sent from SDK APIs until the agent is upgraded.
-
-Do not generate code that passes a `bodyType` value before that upgrade. It may typecheck against a newer local copy of the SDK but fail at runtime on this agent.
-
-When the user needs a non-JSON request body, tell them the required action: an administrator must upgrade this organization's Superblocks agent (On-Premise Agent / OPA) to a newer version that supports the `bodyType` option. Until that upgrade happens, there is no code-level workaround.

package/src/integrations/restapiintegration/overlays/request-body-types.md

@@ -1,106 +0,0 @@
-## 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 such as `Uint8Array`, `ArrayBuffer`, `DataView`, or `Buffer`.
-
-### Form URL-Encoded Requests
-
-Use `bodyType: "formUrlencoded"` for Stripe, OAuth token exchanges, and APIs that expect HTML form encoding. Arrays repeat the key in order, and nested fields should 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 charge = await ctx.integrations.stripe.apiRequest(
-  {
-    method: "POST",
-    path: "/v1/charges",
-    bodyType: "formUrlencoded",
-    body: {
-      amount: 2000,
-      currency: "usd",
-      "metadata[order_id]": "6735",
-    },
-  },
-  { response: ChargeResponseSchema },
-);
-```
-
-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:
-
-```typescript
-await ctx.integrations.sharepoint.apiRequest(
-  {
-    method: "PUT",
-    path: `/sites/${siteId}/drive/root:/reports/monthly.pdf:/content`,
-    bodyType: "binary",
-    body: pdfBytes,
-  },
-  { response: UploadResponseSchema },
-);
-```
-
-The SDK sends the exact byte window for views such as `Uint8Array.subarray()` and `DataView`. It adds `Content-Type: application/octet-stream` unless you already provided a `Content-Type` header such as `application/pdf`.
-Request bodies are limited to 20 MiB before serialization so the agent request stays under its 28 MiB serialized size cap.
-
-### Multipart Uploads
-
-Use `bodyType: "multipartForm"` for endpoints that expect fields plus file parts. File parts must be wrapped as `{ value, filename }`:
-
-```typescript
-const upload = await ctx.integrations.filesApi.apiRequest(
-  {
-    method: "POST",
-    path: "/files",
-    bodyType: "multipartForm",
-    body: {
-      folder: "invoices",
-      invoice: { value: invoicePdfBytes, filename: "invoice.pdf" },
-    },
-  },
-  { response: UploadResponseSchema },
-);
-```
-
-Do not set `Content-Type` for multipart requests. The worker generates the multipart boundary during execution.
-Do not set per-part `contentType`. Fields whose value is `undefined` are omitted. Empty file parts are allowed. The total multipart field and file-part content is limited to 20 MiB before serialization.
-
-### 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:
-
-```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 },
-);
-```
-
-Raw string bodies are limited to 20 MiB.