@superblocksteam/sdk-api 0.0.4

package/src/integrations/dynamodb/types.ts

@@ -0,0 +1,257 @@
+/**
+ * DynamoDB client types.
+ *
+ * All operations use DynamoDB's native AttributeValue format for typed values.
+ * Parameters are serialized as JSON and passed directly to the AWS SDK.
+ */
+
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
+
+/**
+ * DynamoDB AttributeValue type descriptor.
+ *
+ * Values in DynamoDB require explicit type annotations using single-key objects:
+ * - `{ S: "hello" }` - String
+ * - `{ N: "42" }` - Number (always a string in the wire format)
+ * - `{ BOOL: true }` - Boolean
+ * - `{ NULL: true }` - Null
+ * - `{ L: [...] }` - List
+ * - `{ M: {...} }` - Map
+ * - `{ B: "base64..." }` - Binary
+ * - `{ SS: ["a", "b"] }` - String Set
+ * - `{ NS: ["1", "2"] }` - Number Set
+ * - `{ BS: ["base64..."] }` - Binary Set
+ */
+export type DynamoDBAttributeValue =
+  | { S: string }
+  | { N: string }
+  | { BOOL: boolean }
+  | { NULL: true }
+  | { L: DynamoDBAttributeValue[] }
+  | { M: Record<string, DynamoDBAttributeValue> }
+  | { B: string }
+  | { SS: string[] }
+  | { NS: string[] }
+  | { BS: string[] };
+
+/**
+ * DynamoDB client for database operations.
+ *
+ * All operations pass parameters directly to the AWS SDK via JSON body.
+ * Values use DynamoDB's AttributeValue format with type descriptors.
+ *
+ * @example
+ * ```typescript
+ * // Declare in api(): integrations: { db: dynamodb(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.db
+ *
+ * // PartiQL query with typed parameters
+ * const users = await ctx.integrations.db.query(
+ *   'SELECT * FROM users WHERE status = ?',
+ *   z.array(z.object({ id: z.string(), name: z.string() })),
+ *   [{ S: 'active' }]
+ * );
+ *
+ * // Get item by key
+ * const user = await ctx.integrations.db.getItem('users', { id: { S: '123' } }, UserSchema);
+ *
+ * // Put item
+ * await ctx.integrations.db.putItem('users', {
+ *   id: { S: '123' },
+ *   name: { S: 'Alice' },
+ *   age: { N: '30' },
+ * });
+ *
+ * // Update item
+ * await ctx.integrations.db.updateItem(
+ *   'users',
+ *   { id: { S: '123' } },
+ *   'SET #n = :name',
+ *   { ':name': { S: 'Bob' } },
+ *   { '#n': 'name' }
+ * );
+ *
+ * // Delete item
+ * await ctx.integrations.db.deleteItem('users', { id: { S: '123' } });
+ *
+ * // Scan with filter
+ * const active = await ctx.integrations.db.scan(
+ *   'users',
+ *   UsersSchema,
+ *   'status = :s',
+ *   { ':s': { S: 'active' } }
+ * );
+ * ```
+ */
+export interface DynamoDBClient extends BaseIntegrationClient {
+  /**
+   * Execute a PartiQL statement against DynamoDB.
+   *
+   * Uses the `executeStatement` action. The `?` placeholders in the
+   * statement are bound server-side using the Parameters array.
+   *
+   * @param statement - The PartiQL statement with `?` placeholders
+   * @param schema - Zod schema for validating the result
+   * @param params - Optional array of DynamoDB AttributeValue parameters
+   * @returns The validated result
+   */
+  query<T>(
+    statement: string,
+    schema: z.ZodSchema<T>,
+    params?: DynamoDBAttributeValue[],
+    metadata?: TraceMetadata,
+  ): Promise<T>;
+
+  /**
+   * Get an item from a DynamoDB table by key.
+   *
+   * @param table - The table name
+   * @param key - The primary key as AttributeValue map
+   * @param schema - Zod schema for validating the result
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The validated result
+   */
+  getItem<T>(
+    table: string,
+    key: Record<string, DynamoDBAttributeValue>,
+    schema: z.ZodSchema<T>,
+    metadata?: TraceMetadata,
+  ): Promise<T>;
+
+  /**
+   * Scan a DynamoDB table with optional filter.
+   *
+   * @param table - The table name
+   * @param schema - Zod schema for validating the result
+   * @param filterExpression - Optional filter expression (e.g., 'status = :s')
+   * @param expressionAttributeValues - Values for expression placeholders
+   * @param expressionAttributeNames - Name aliases for reserved words. **Note:** since both
+   *   this param and `metadata` accept plain objects, pass `undefined` when you only need metadata.
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The validated result
+   */
+  scan<T>(
+    table: string,
+    schema: z.ZodSchema<T>,
+    filterExpression?: string,
+    expressionAttributeValues?: Record<string, DynamoDBAttributeValue>,
+    expressionAttributeNames?: Record<string, string>,
+    metadata?: TraceMetadata,
+  ): Promise<T>;
+
+  /**
+   * Query a DynamoDB table or index using key conditions.
+   *
+   * @param table - The table name
+   * @param keyConditionExpression - Key condition (e.g., 'pk = :pk')
+   * @param expressionAttributeValues - Values for expression placeholders
+   * @param schema - Zod schema for validating the result
+   * @param expressionAttributeNames - Optional name aliases for reserved words. **Note:** since both
+   *   this param and `metadata` accept plain objects, pass `undefined` when you only need metadata.
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The validated result
+   */
+  queryTable<T>(
+    table: string,
+    keyConditionExpression: string,
+    expressionAttributeValues: Record<string, DynamoDBAttributeValue>,
+    schema: z.ZodSchema<T>,
+    expressionAttributeNames?: Record<string, string>,
+    metadata?: TraceMetadata,
+  ): Promise<T>;
+
+  /**
+   * Put (insert or replace) an item in a DynamoDB table.
+   *
+   * @param table - The table name
+   * @param item - The item as an AttributeValue map
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The raw result from DynamoDB
+   */
+  putItem(
+    table: string,
+    item: Record<string, DynamoDBAttributeValue>,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
+
+  /**
+   * Update an existing item in a DynamoDB table.
+   *
+   * @param table - The table name
+   * @param key - The primary key as AttributeValue map
+   * @param updateExpression - Update expression (e.g., 'SET #n = :name, age = :age')
+   * @param expressionAttributeValues - Values for expression placeholders
+   * @param expressionAttributeNames - Optional name aliases for reserved words. **Note:** since both
+   *   this param and `metadata` accept plain objects, pass `undefined` when you only need metadata.
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The raw result from DynamoDB
+   */
+  updateItem(
+    table: string,
+    key: Record<string, DynamoDBAttributeValue>,
+    updateExpression: string,
+    expressionAttributeValues: Record<string, DynamoDBAttributeValue>,
+    expressionAttributeNames?: Record<string, string>,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
+
+  /**
+   * Delete an item from a DynamoDB table by key.
+   *
+   * @param table - The table name
+   * @param key - The primary key as AttributeValue map
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The raw result from DynamoDB
+   */
+  deleteItem(
+    table: string,
+    key: Record<string, DynamoDBAttributeValue>,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
+
+  /**
+   * Write multiple items in a single batch.
+   *
+   * @param requestItems - Map of table names to write request arrays
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The raw result from DynamoDB
+   */
+  batchWriteItem(
+    requestItems: Record<string, Array<Record<string, unknown>>>,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
+
+  /**
+   * List all DynamoDB tables.
+   *
+   * @param schema - Zod schema for validating the result
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The validated table list
+   */
+  listTables<T>(schema: z.ZodSchema<T>, metadata?: TraceMetadata): Promise<T>;
+
+  /**
+   * Describe a DynamoDB table's structure and metadata.
+   *
+   * @param table - The table name
+   * @param schema - Zod schema for validating the result
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The validated table description
+   */
+  describeTable<T>(
+    table: string,
+    schema: z.ZodSchema<T>,
+    metadata?: TraceMetadata,
+  ): Promise<T>;
+
+  /**
+   * Delete a DynamoDB table.
+   *
+   * @param table - The table name to delete
+   * @param metadata - Optional trace metadata for diagnostics
+   * @returns The raw result from DynamoDB
+   */
+  deleteTable(table: string, metadata?: TraceMetadata): Promise<unknown>;
+}