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

package/src/integrations/documentation-resolver.test.ts

@@ -859,6 +859,28 @@ 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.5",
+      });
+
+      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("notes bodyType non-support before sdk-api request body support", async () => {
+      const docs = await resolveIntegrationDocumentation("restapiintegration", {
+        sdkVersion: "0.0.4",
+      });
+
+      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 +891,11 @@ 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");
     });
   });
 

package/src/integrations/dynamodb/README.md

@@ -12,7 +12,6 @@ Execute operations against Amazon DynamoDB with full type safety and runtime val
 | `updateItem(table, key, expr, values, names?, metadata?)`       | Update an existing item      |
 | `deleteItem(table, key, metadata?)`                             | Delete an item by key        |
 | `scan(table, schema, filter?, values?, names?, metadata?)`      | Scan a table                 |
-| `scan(table, schema, options, metadata?)`                       | Scan with pagination options |
 | `queryTable(table, keyExpr, values, schema, names?, metadata?)` | Query by key condition       |
 | `batchWriteItem(requestItems, metadata?)`                       | Batch write multiple items   |
 | `listTables(schema, metadata?)`                                 | List all tables              |
@@ -134,41 +133,21 @@ await ctx.integrations.dynamodb.deleteItem("users", { id: { S: "user-123" } });
 ### Scan Table
 
 ```typescript
-// DynamoDB Scan returns raw AttributeValue maps.
-// import type { DynamoDBAttributeValue } from "@superblocksteam/sdk-api";
-const AttributeValueSchema = z.custom<DynamoDBAttributeValue>();
-const ItemSchema = z.record(AttributeValueSchema);
-const ScanPageSchema = z.object({
-  Items: z.array(ItemSchema).optional(),
-  LastEvaluatedKey: z.record(AttributeValueSchema).optional(),
-});
+// Full scan
+const allUsers = await ctx.integrations.dynamodb.scan(
+  "users",
+  z.array(z.object({ id: z.string(), name: z.string() })),
+);
 
-// Paginate past DynamoDB's 1 MB per-Scan limit. Bound the number of
-// requests so throttling or an unexpectedly large table cannot consume
-// the entire API execution timeout.
-const MAX_PAGES = 100;
-let exclusiveStartKey: Record<string, DynamoDBAttributeValue> | undefined;
-const allItems: Array<Record<string, DynamoDBAttributeValue>> = [];
-for (let pageNumber = 0; pageNumber < MAX_PAGES; pageNumber += 1) {
-  const page = await ctx.integrations.dynamodb.scan("users", ScanPageSchema, {
-    exclusiveStartKey,
-    filterExpression: "status = :s",
-    expressionAttributeValues: { ":s": { S: "active" } },
-  });
-  allItems.push(...(page.Items ?? []));
-  exclusiveStartKey = page.LastEvaluatedKey;
-  if (!exclusiveStartKey) {
-    break;
-  }
-  if (pageNumber === MAX_PAGES - 1) {
-    throw new Error(`Scan exceeded the ${MAX_PAGES}-page safety limit`);
-  }
-}
+// With filter expression
+const activeUsers = await ctx.integrations.dynamodb.scan(
+  "users",
+  z.array(z.object({ id: z.string(), name: z.string() })),
+  "status = :s",
+  { ":s": { S: "active" } },
+);
 ```
 
-Choose a page cap appropriate for the API timeout and provisioned read
-capacity. For very large tables, process and persist pages incrementally.
-
 ### Query Table by Key Condition
 
 ```typescript

package/src/integrations/dynamodb/client.ts

@@ -12,23 +12,7 @@ import { RestApiValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
 import type { QueryExecutor, TraceMetadata } from "../registry.js";
 import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type {
-  DynamoDBClient,
-  DynamoDBAttributeValue,
-  DynamoDBScanOptions,
-} from "./types.js";
-
-const DYNAMODB_SCAN_OPTION_KEYS = new Set<string>([
-  "filterExpression",
-  "expressionAttributeValues",
-  "expressionAttributeNames",
-  "exclusiveStartKey",
-  "limit",
-  "projectionExpression",
-  "indexName",
-  "segment",
-  "totalSegments",
-]);
+import type { DynamoDBClient, DynamoDBAttributeValue } from "./types.js";
 
 /**
  * Internal implementation of DynamoDBClient.
@@ -205,120 +189,33 @@ export class DynamoDBClientImpl
     return this.executeWithErrorHandling(request, "deleteItem", metadata);
   }
 
-  /** Copy optional AWS Scan fields onto the request body. */
-  private applyScanParams(
-    params: Record<string, unknown>,
-    options: DynamoDBScanOptions,
-  ): void {
-    if (options.filterExpression) {
-      params.FilterExpression = options.filterExpression;
-    }
-    if (
-      options.expressionAttributeValues &&
-      Object.keys(options.expressionAttributeValues).length > 0
-    ) {
-      params.ExpressionAttributeValues = options.expressionAttributeValues;
-    }
-    if (
-      options.expressionAttributeNames &&
-      Object.keys(options.expressionAttributeNames).length > 0
-    ) {
-      params.ExpressionAttributeNames = options.expressionAttributeNames;
-    }
-    if (options.exclusiveStartKey) {
-      params.ExclusiveStartKey = options.exclusiveStartKey;
-    }
-    if (options.limit !== undefined) {
-      params.Limit = options.limit;
-    }
-    if (options.projectionExpression) {
-      params.ProjectionExpression = options.projectionExpression;
-    }
-    if (options.indexName) {
-      params.IndexName = options.indexName;
-    }
-    if (options.segment !== undefined) {
-      params.Segment = options.segment;
-    }
-    if (options.totalSegments !== undefined) {
-      params.TotalSegments = options.totalSegments;
-    }
-  }
-
-  private isScanOptions(value: unknown): value is DynamoDBScanOptions {
-    return (
-      typeof value === "object" &&
-      value !== null &&
-      Object.keys(value).every((key) => DYNAMODB_SCAN_OPTION_KEYS.has(key))
-    );
-  }
-
-  private isTraceMetadata(value: unknown): value is TraceMetadata {
-    return (
-      typeof value === "object" &&
-      value !== null &&
-      Object.keys(value).every(
-        (key) => key === "label" || key === "description",
-      ) &&
-      Object.values(value).every(
-        (entry) => entry === undefined || typeof entry === "string",
-      )
-    );
-  }
-
   async scan<T>(
     table: string,
     schema: z.ZodSchema<T>,
-    filterExpressionOrOptions?: string | DynamoDBScanOptions,
-    expressionAttributeValuesOrMetadata?:
-      | Record<string, DynamoDBAttributeValue>
-      | TraceMetadata,
+    filterExpression?: string,
+    expressionAttributeValues?: Record<string, DynamoDBAttributeValue>,
     expressionAttributeNames?: Record<string, string>,
     metadata?: TraceMetadata,
   ): Promise<T> {
     const params: Record<string, unknown> = { TableName: table };
-    let resolvedMetadata = metadata;
-
-    if (
-      typeof filterExpressionOrOptions === "object" &&
-      filterExpressionOrOptions !== null
-    ) {
-      if (!this.isScanOptions(filterExpressionOrOptions)) {
-        throw new Error(
-          `Invalid DynamoDB scan options: ${Object.keys(filterExpressionOrOptions).join(", ")}`,
-        );
-      }
-      this.applyScanParams(params, filterExpressionOrOptions);
 
-      if (expressionAttributeValuesOrMetadata !== undefined) {
-        if (!this.isTraceMetadata(expressionAttributeValuesOrMetadata)) {
-          throw new Error("Invalid DynamoDB scan trace metadata");
-        }
-        resolvedMetadata = expressionAttributeValuesOrMetadata;
-      }
-    } else {
-      if (filterExpressionOrOptions) {
-        params.FilterExpression = filterExpressionOrOptions;
-      }
-      if (
-        expressionAttributeValuesOrMetadata &&
-        Object.keys(expressionAttributeValuesOrMetadata).length > 0
-      ) {
-        params.ExpressionAttributeValues = expressionAttributeValuesOrMetadata;
-      }
-      if (
-        expressionAttributeNames &&
-        Object.keys(expressionAttributeNames).length > 0
-      ) {
-        params.ExpressionAttributeNames = expressionAttributeNames;
-      }
+    if (filterExpression) {
+      params.FilterExpression = filterExpression;
+    }
+
+    if (expressionAttributeValues) {
+      params.ExpressionAttributeValues = expressionAttributeValues;
+    }
+
+    if (expressionAttributeNames) {
+      params.ExpressionAttributeNames = expressionAttributeNames;
     }
 
     const request = this.buildRequest("scan", params);
     const result = await this.executeWithErrorHandling(
       request,
       "scan",
-      resolvedMetadata,
+      metadata,
     );
     return this.validateResult(result, schema, "scan");
   }
@@ -336,10 +233,8 @@ export class DynamoDBClientImpl
       KeyConditionExpression: keyConditionExpression,
       ExpressionAttributeValues: expressionAttributeValues,
     };
-    if (
-      expressionAttributeNames &&
-      Object.keys(expressionAttributeNames).length > 0
-    ) {
+
+    if (expressionAttributeNames) {
       params.ExpressionAttributeNames = expressionAttributeNames;
     }
 

package/src/integrations/dynamodb/index.ts

@@ -4,9 +4,5 @@
  * @module
  */
 
-export type {
-  DynamoDBClient,
-  DynamoDBAttributeValue,
-  DynamoDBScanOptions,
-} from "./types.js";
+export type { DynamoDBClient, DynamoDBAttributeValue } from "./types.js";
 export { DynamoDBClientImpl } from "./client.js";

package/src/integrations/dynamodb/types.ts

@@ -37,24 +37,6 @@ export type DynamoDBAttributeValue =
   | { NS: string[] }
   | { BS: string[] };
 
-/**
- * Optional Scan parameters forwarded to the AWS SDK.
- *
- * Use `exclusiveStartKey` with `LastEvaluatedKey` from a previous page to
- * continue past DynamoDB's 1 MB per-Scan limit.
- */
-export interface DynamoDBScanOptions {
-  filterExpression?: string;
-  expressionAttributeValues?: Record<string, DynamoDBAttributeValue>;
-  expressionAttributeNames?: Record<string, string>;
-  exclusiveStartKey?: Record<string, DynamoDBAttributeValue>;
-  limit?: number;
-  projectionExpression?: string;
-  indexName?: string;
-  segment?: number;
-  totalSegments?: number;
-}
-
 /**
  * DynamoDB client for database operations.
  *
@@ -102,11 +84,6 @@ export interface DynamoDBScanOptions {
  *   'status = :s',
  *   { ':s': { S: 'active' } }
  * );
- *
- * // Paginate past the 1 MB Scan limit
- * const page = await ctx.integrations.db.scan('users', UsersSchema, {
- *   exclusiveStartKey: lastEvaluatedKey,
- * });
  * ```
  */
 export interface DynamoDBClient extends BaseIntegrationClient {
@@ -145,10 +122,7 @@ export interface DynamoDBClient extends BaseIntegrationClient {
   ): Promise<T>;
 
   /**
-   * Scan a DynamoDB table.
-   *
-   * Prefer the options-object form when paginating (`exclusiveStartKey`) or
-   * when you need `limit`, `indexName`, or parallel scan segments.
+   * Scan a DynamoDB table with optional filter.
    *
    * @param table - The table name
    * @param schema - Zod schema for validating the result
@@ -159,12 +133,6 @@ export interface DynamoDBClient extends BaseIntegrationClient {
    * @param metadata - Optional trace metadata for diagnostics
    * @returns The validated result
    */
-  scan<T>(
-    table: string,
-    schema: z.ZodSchema<T>,
-    options: DynamoDBScanOptions,
-    metadata?: TraceMetadata,
-  ): Promise<T>;
   scan<T>(
     table: string,
     schema: z.ZodSchema<T>,

package/src/integrations/index.ts

@@ -363,7 +363,6 @@ export { MongoDBClientImpl } from "./mongodb/index.js";
 export type {
   DynamoDBClient,
   DynamoDBAttributeValue,
-  DynamoDBScanOptions,
 } from "./dynamodb/index.js";
 export { DynamoDBClientImpl } from "./dynamodb/index.js";
 

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

@@ -0,0 +1,214 @@
+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/docs.manifest.json

@@ -13,6 +13,14 @@
     {
       "file": "overlays/response-types-unsupported.md",
       "sdkVersionRange": "<0.0.3"
+    },
+    {
+      "file": "overlays/request-body-types.md",
+      "sdkVersionRange": ">=0.0.5"
+    },
+    {
+      "file": "overlays/request-body-types-unsupported.md",
+      "sdkVersionRange": "<0.0.5"
     }
   ]
 }

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

@@ -0,0 +1,7 @@
+## 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.