@superblocksteam/sdk-api 0.0.9 → 0.0.11

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

package/src/integrations/s3/README.md

@@ -25,6 +25,7 @@ import { api, z, s3 } from "@superblocksteam/sdk-api";
 const PROD_S3 = "a1b2c3d4-5678-90ab-cdef-s300000001";
 
 export default api({
+  name: "ListBucketObjects",
   integrations: {
     storage: s3(PROD_S3),
   },

package/src/integrations/snowflakecortex/README.md

@@ -108,6 +108,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. Always set
+`stream: false` in Cortex request bodies (as the examples do) — a streaming
+response fails 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 Snowflake Cortex client only provides `apiRequest()`. There are no other specialized methods:

package/src/integrations/stabilityai/README.md

@@ -234,6 +234,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/runtime/context.ts

@@ -57,6 +57,13 @@ export interface CreateContextOptions {
   /** Environment variables */
   env: Record<string, string>;
 
+  /**
+   * Server-resolved data tag key.
+   *
+   * Optional for compatibility with execution wrappers from older agents.
+   */
+  dataTag?: string;
+
   /** User information from JWT */
   user: ApiUser;
 
@@ -101,6 +108,7 @@ export function createApiContext(
     executeQuery,
     executionId,
     env,
+    dataTag,
     user,
     logger,
   } = options;
@@ -172,6 +180,7 @@ export function createApiContext(
     >["integrations"],
     log,
     env: Object.freeze({ ...env }),
+    dataTag,
     user,
   };
 }

package/src/runtime/executor.ts

@@ -36,6 +36,13 @@ export interface ExecuteApiRequest {
   /** Environment variables available to the API */
   env: Record<string, string>;
 
+  /**
+   * Server-resolved data tag key for this execution.
+   *
+   * Optional on the low-level request for compatibility with older runtimes.
+   */
+  dataTag?: string;
+
   /** User information extracted from the Superblocks JWT */
   user: ApiUser;
 
@@ -162,6 +169,7 @@ export async function executeApi<TInput = unknown, TOutput = unknown>(
       executeQuery: request.executeQuery,
       executionId: request.executionId,
       env: request.env,
+      dataTag: request.dataTag,
       user: request.user,
     });
 

package/src/types.ts

@@ -182,6 +182,17 @@ export interface ApiContext<
   /** Access to environment variables */
   readonly env: Readonly<Record<string, string>>;
 
+  /**
+   * Canonical key of the requested data tag validated for this execution.
+   *
+   * This identifies the integration configuration in use, not a user's
+   * environment entitlement. It is supplied by the Superblocks runtime and
+   * cannot be selected through API input. It is undefined when no data tag was
+   * resolved or on runtimes that predate data-tag context support;
+   * authorization checks must deny access in those cases.
+   */
+  readonly dataTag?: string;
+
   /** User information from the Superblocks JWT */
   readonly user: ApiUser;
 }