@superblocksteam/sdk-api 0.0.8 → 0.0.10

package/src/integrations/dynamodb/client.test.ts

@@ -0,0 +1,254 @@
+/**
+ * Unit tests for DynamoDB client request bodies.
+ *
+ * The orchestrator forwards `action` + JSON `body` to the AWS SDK, so these
+ * tests lock the wire params - especially ExclusiveStartKey pagination.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { z } from "zod";
+
+import type { IntegrationConfig } from "../types.js";
+import { DynamoDBClientImpl } from "./client.js";
+
+const TEST_CONFIG: IntegrationConfig = {
+  id: "dynamodb-test-id",
+  name: "Test DynamoDB",
+  pluginId: "dynamodb",
+  configuration: {},
+};
+
+const ItemsSchema = z.object({ Items: z.array(z.unknown()).optional() });
+
+function createClient(mockResult: unknown = { Items: [] }) {
+  const executeQuery = vi.fn().mockResolvedValue(mockResult);
+  const client = new DynamoDBClientImpl(TEST_CONFIG, executeQuery);
+  return { client, executeQuery };
+}
+
+function parsedBody(executeQuery: ReturnType<typeof vi.fn>, callIndex = 0) {
+  const request = z
+    .object({ action: z.string(), body: z.string() })
+    .parse(executeQuery.mock.calls[callIndex]?.[0]);
+  return { action: request.action, body: JSON.parse(request.body) };
+}
+
+describe("DynamoDBClientImpl", () => {
+  describe("scan", () => {
+    it("omits ExclusiveStartKey on a positional scan", async () => {
+      const { client, executeQuery } = createClient();
+
+      await client.scan("retailers", ItemsSchema, "status = :s", {
+        ":s": { S: "active" },
+      });
+
+      expect(parsedBody(executeQuery)).toEqual({
+        action: "scan",
+        body: {
+          TableName: "retailers",
+          FilterExpression: "status = :s",
+          ExpressionAttributeValues: { ":s": { S: "active" } },
+        },
+      });
+    });
+
+    it("forwards ExclusiveStartKey from the options object", async () => {
+      const { client, executeQuery } = createClient();
+      const exclusiveStartKey = { id: { S: "retailer-18" } };
+
+      await client.scan("retailers", ItemsSchema, { exclusiveStartKey });
+
+      expect(parsedBody(executeQuery)).toEqual({
+        action: "scan",
+        body: {
+          TableName: "retailers",
+          ExclusiveStartKey: exclusiveStartKey,
+        },
+      });
+    });
+
+    it("treats an empty object as empty scan options", async () => {
+      const { client, executeQuery } = createClient();
+
+      await client.scan("retailers", ItemsSchema, {});
+
+      expect(parsedBody(executeQuery)).toEqual({
+        action: "scan",
+        body: { TableName: "retailers" },
+      });
+    });
+
+    it("rejects objects with unknown scan option keys", async () => {
+      const { client, executeQuery } = createClient();
+
+      await expect(
+        Reflect.apply(client.scan, client, [
+          "retailers",
+          ItemsSchema,
+          { label: "not scan options" },
+        ]),
+      ).rejects.toThrow("Invalid DynamoDB scan options: label");
+      expect(executeQuery).not.toHaveBeenCalled();
+    });
+
+    it("forwards pagination and parallel-scan options", async () => {
+      const { client, executeQuery } = createClient();
+
+      await client.scan(
+        "retailers",
+        ItemsSchema,
+        {
+          exclusiveStartKey: { id: { S: "page-2" } },
+          limit: 25,
+          projectionExpression: "id, name",
+          indexName: "gsi1",
+          segment: 0,
+          totalSegments: 4,
+          filterExpression: "#s = :s",
+          expressionAttributeNames: { "#s": "status" },
+          expressionAttributeValues: { ":s": { S: "active" } },
+        },
+        { label: "page retailers" },
+      );
+
+      expect(parsedBody(executeQuery)).toEqual({
+        action: "scan",
+        body: {
+          TableName: "retailers",
+          ExclusiveStartKey: { id: { S: "page-2" } },
+          Limit: 25,
+          ProjectionExpression: "id, name",
+          IndexName: "gsi1",
+          Segment: 0,
+          TotalSegments: 4,
+          FilterExpression: "#s = :s",
+          ExpressionAttributeNames: { "#s": "status" },
+          ExpressionAttributeValues: { ":s": { S: "active" } },
+        },
+      });
+      expect(executeQuery).toHaveBeenCalledWith(expect.anything(), undefined, {
+        label: "page retailers",
+      });
+    });
+
+    it("keeps positional names and metadata working together", async () => {
+      const { client, executeQuery } = createClient();
+
+      await client.scan(
+        "retailers",
+        ItemsSchema,
+        "#s = :s",
+        { ":s": { S: "active" } },
+        { "#s": "status" },
+        { label: "filtered scan" },
+      );
+
+      expect(parsedBody(executeQuery).body).toEqual({
+        TableName: "retailers",
+        FilterExpression: "#s = :s",
+        ExpressionAttributeValues: { ":s": { S: "active" } },
+        ExpressionAttributeNames: { "#s": "status" },
+      });
+      expect(executeQuery.mock.calls[0][2]).toEqual({ label: "filtered scan" });
+    });
+
+    it("keeps schemas that strip pagination cursors backward compatible", async () => {
+      const lastEvaluatedKey = {
+        id: { S: "retailer-18" },
+        version: { N: "2" },
+      };
+      const { client } = createClient({
+        Items: [{ id: { S: "retailer-1" } }],
+        LastEvaluatedKey: lastEvaluatedKey,
+      });
+
+      await expect(
+        client.scan("retailers", ItemsSchema, { limit: 25 }),
+      ).resolves.toEqual({
+        Items: [{ id: { S: "retailer-1" } }],
+      });
+    });
+
+    it("preserves mixed AttributeValue pagination cursors", async () => {
+      const lastEvaluatedKey = {
+        id: { S: "retailer-18" },
+        version: { N: "2" },
+      };
+      const PageSchema = z.object({
+        Items: z.array(z.unknown()).optional(),
+        LastEvaluatedKey: z.record(z.unknown()).optional(),
+      });
+      const { client } = createClient({
+        Items: [],
+        LastEvaluatedKey: lastEvaluatedKey,
+      });
+
+      const page = await client.scan("retailers", PageSchema, {});
+
+      expect(page.LastEvaluatedKey).toEqual(lastEvaluatedKey);
+    });
+
+    it("threads each returned pagination cursor into the next request", async () => {
+      const LastEvaluatedKeySchema = z.object({
+        id: z.object({ S: z.string() }),
+      });
+      const PageSchema = z.object({
+        Items: z.array(z.string()),
+        LastEvaluatedKey: LastEvaluatedKeySchema.optional(),
+      });
+      const lastEvaluatedKey = { id: { S: "retailer-1" } };
+      const executeQuery = vi
+        .fn()
+        .mockResolvedValueOnce({
+          Items: ["retailer-1"],
+          LastEvaluatedKey: lastEvaluatedKey,
+        })
+        .mockResolvedValueOnce({ Items: ["retailer-2"] });
+      const client = new DynamoDBClientImpl(TEST_CONFIG, executeQuery);
+
+      const items: string[] = [];
+      let exclusiveStartKey: z.infer<typeof LastEvaluatedKeySchema> | undefined;
+      do {
+        const page = await client.scan("retailers", PageSchema, {
+          exclusiveStartKey,
+        });
+        items.push(...page.Items);
+        exclusiveStartKey = page.LastEvaluatedKey;
+      } while (exclusiveStartKey);
+
+      expect(items).toEqual(["retailer-1", "retailer-2"]);
+      expect(executeQuery).toHaveBeenCalledTimes(2);
+      expect(parsedBody(executeQuery, 0).body).toEqual({
+        TableName: "retailers",
+      });
+      expect(parsedBody(executeQuery, 1).body).toEqual({
+        TableName: "retailers",
+        ExclusiveStartKey: lastEvaluatedKey,
+      });
+    });
+  });
+
+  describe("queryTable", () => {
+    it("treats a plain names map as ExpressionAttributeNames", async () => {
+      const { client, executeQuery } = createClient();
+
+      await client.queryTable(
+        "orders",
+        "#uid = :uid",
+        { ":uid": { S: "user-123" } },
+        ItemsSchema,
+        { "#uid": "userId" },
+      );
+
+      expect(parsedBody(executeQuery)).toEqual({
+        action: "query",
+        body: {
+          TableName: "orders",
+          KeyConditionExpression: "#uid = :uid",
+          ExpressionAttributeValues: { ":uid": { S: "user-123" } },
+          ExpressionAttributeNames: { "#uid": "userId" },
+        },
+      });
+    });
+  });
+});

package/src/integrations/dynamodb/client.ts

@@ -12,7 +12,23 @@ 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 } 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",
+]);
 
 /**
  * Internal implementation of DynamoDBClient.
@@ -189,33 +205,120 @@ 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>,
-    filterExpression?: string,
-    expressionAttributeValues?: Record<string, DynamoDBAttributeValue>,
+    filterExpressionOrOptions?: string | DynamoDBScanOptions,
+    expressionAttributeValuesOrMetadata?:
+      | Record<string, DynamoDBAttributeValue>
+      | TraceMetadata,
     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 (filterExpression) {
-      params.FilterExpression = filterExpression;
-    }
-
-    if (expressionAttributeValues) {
-      params.ExpressionAttributeValues = expressionAttributeValues;
-    }
-
-    if (expressionAttributeNames) {
-      params.ExpressionAttributeNames = expressionAttributeNames;
+      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;
+      }
     }
 
     const request = this.buildRequest("scan", params);
     const result = await this.executeWithErrorHandling(
       request,
       "scan",
-      metadata,
+      resolvedMetadata,
     );
     return this.validateResult(result, schema, "scan");
   }
@@ -233,8 +336,10 @@ export class DynamoDBClientImpl
       KeyConditionExpression: keyConditionExpression,
       ExpressionAttributeValues: expressionAttributeValues,
     };
-
-    if (expressionAttributeNames) {
+    if (
+      expressionAttributeNames &&
+      Object.keys(expressionAttributeNames).length > 0
+    ) {
       params.ExpressionAttributeNames = expressionAttributeNames;
     }
 

package/src/integrations/dynamodb/index.ts

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

package/src/integrations/dynamodb/types.ts

@@ -37,6 +37,24 @@ 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.
  *
@@ -84,6 +102,11 @@ export type DynamoDBAttributeValue =
  *   '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 {
@@ -122,7 +145,10 @@ export interface DynamoDBClient extends BaseIntegrationClient {
   ): Promise<T>;
 
   /**
-   * Scan a DynamoDB table with optional filter.
+   * Scan a DynamoDB table.
+   *
+   * Prefer the options-object form when paginating (`exclusiveStartKey`) or
+   * when you need `limit`, `indexName`, or parallel scan segments.
    *
    * @param table - The table name
    * @param schema - Zod schema for validating the result
@@ -133,6 +159,12 @@ 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/fireworks/README.md

@@ -293,6 +293,13 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 
 ## Common Pitfalls
 
+### Streaming Is Not Supported
+
+`apiRequest()` does not support streaming or Server-Sent Events. Do not set
+`stream: true` — streaming responses fail schema validation. Every call
+returns the complete response; if a UI needs real-time token streaming,
+handle it at the frontend layer, not through the SDK.
+
 ### No Specialized Methods
 
 ```typescript

package/src/integrations/gemini/README.md

@@ -265,6 +265,14 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 
 ## Common Pitfalls
 
+### Streaming Is Not Supported
+
+`apiRequest()` does not support streaming or Server-Sent Events. Use
+`:generateContent`, never `:streamGenerateContent` or `alt=sse` — streaming
+responses fail schema validation. Every call returns the complete response;
+if a UI needs real-time token streaming, handle it at the frontend layer,
+not through the SDK.
+
 ### No Specialized Methods
 
 ```typescript

package/src/integrations/groq/README.md

@@ -251,6 +251,13 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 
 ## Common Pitfalls
 
+### Streaming Is Not Supported
+
+`apiRequest()` does not support streaming or Server-Sent Events. Do not set
+`stream: true` — streaming responses fail schema validation. Every call
+returns the complete response; if a UI needs real-time token streaming,
+handle it at the frontend layer, not through the SDK.
+
 ### No Specialized Methods
 
 ```typescript

package/src/integrations/index.ts

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

package/src/integrations/mistral/README.md

@@ -277,6 +277,13 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 
 ## Common Pitfalls
 
+### Streaming Is Not Supported
+
+`apiRequest()` does not support streaming or Server-Sent Events. Do not set
+`stream: true` — streaming responses fail schema validation. Every call
+returns the complete response; if a UI needs real-time token streaming,
+handle it at the frontend layer, not through the SDK.
+
 ### No Specialized Methods
 
 ```typescript

package/src/integrations/openai_v2/README.md

@@ -257,6 +257,13 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 
 ## Common Pitfalls
 
+### Streaming Is Not Supported
+
+`apiRequest()` does not support streaming or Server-Sent Events. Do not set
+`stream: true` — streaming responses fail schema validation. Every call
+returns the complete response; if a UI needs real-time token streaming,
+handle it at the frontend layer, not through the SDK.
+
 ### No Specialized Methods
 
 The OpenAI client only provides `apiRequest()`. There are no other specialized methods:

package/src/integrations/perplexity/README.md

@@ -189,6 +189,13 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 
 ## Common Pitfalls
 
+### Streaming Is Not Supported
+
+`apiRequest()` does not support streaming or Server-Sent Events. Do not set
+`stream: true` — streaming responses fail schema validation. Every call
+returns the complete response; if a UI needs real-time token streaming,
+handle it at the frontend layer, not through the SDK.
+
 ### No Specialized Methods
 
 ```typescript