@superblocksteam/sdk-api 2.0.89-next.0

package/src/integrations/dynamodb/README.md

@@ -0,0 +1,244 @@
+# DynamoDB Client
+
+Execute operations against Amazon DynamoDB with full type safety and runtime validation. All parameters are passed directly to the AWS SDK as JSON.
+
+## Methods
+
+| Method | Description |
+| ------ | ----------- |
+| `query(statement, schema, params?)` | Execute a PartiQL statement |
+| `getItem(table, key, schema)` | Get an item by key |
+| `putItem(table, item)` | Insert or replace an item |
+| `updateItem(table, key, expr, values, names?)` | Update an existing item |
+| `deleteItem(table, key)` | Delete an item by key |
+| `scan(table, schema, filter?, values?, names?)` | Scan a table |
+| `queryTable(table, keyExpr, values, schema, names?)` | Query by key condition |
+| `batchWriteItem(requestItems)` | Batch write multiple items |
+| `listTables(schema)` | List all tables |
+| `describeTable(table, schema)` | Describe a table's structure |
+| `deleteTable(table)` | Delete a table |
+
+## DynamoDB AttributeValue Format
+
+All values use DynamoDB's native type descriptors:
+
+```typescript
+{ S: "hello" }       // String
+{ N: "42" }          // Number (always a string)
+{ BOOL: true }       // Boolean
+{ NULL: true }       // Null
+{ L: [{ S: "a" }] } // List
+{ M: { k: { S: "v" } } } // Map
+```
+
+## Usage
+
+### PartiQL Query
+
+```typescript
+import { api, z } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_DYNAMODB = "a1b2c3d4-5678-90ab-cdef-dynamodb0001";
+
+const UserSchema = z.array(z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string(),
+}));
+
+export default api({
+  name: "DynamoDBExample",
+  input: z.object({
+    status: z.string(),
+  }),
+  output: z.object({
+    users: UserSchema,
+  }),
+  async run(ctx, { status }) {
+    const dynamodb = ctx.dynamodb(PROD_DYNAMODB);
+
+    const users = await dynamodb.query(
+      "SELECT * FROM users WHERE status = ?",
+      UserSchema,
+      [{ S: status }]
+    );
+
+    return { users };
+  },
+});
+```
+
+### Get Item by Key
+
+```typescript
+const user = await dynamodb.getItem(
+  "users",
+  { id: { S: "user-123" } },
+  z.object({ id: z.string(), name: z.string(), email: z.string() })
+);
+```
+
+### Put Item
+
+```typescript
+await dynamodb.putItem("users", {
+  id: { S: "user-456" },
+  name: { S: "John Doe" },
+  email: { S: "john@example.com" },
+  age: { N: "30" },
+});
+```
+
+### Update Item
+
+```typescript
+await dynamodb.updateItem(
+  "users",
+  { id: { S: "user-123" } },
+  "SET #n = :name, email = :email",
+  {
+    ":name": { S: "Jane Doe" },
+    ":email": { S: "jane@example.com" },
+  },
+  { "#n": "name" }  // name is a reserved word in DynamoDB
+);
+```
+
+### Delete Item
+
+```typescript
+await dynamodb.deleteItem("users", { id: { S: "user-123" } });
+```
+
+### Scan Table
+
+```typescript
+// Full scan
+const allUsers = await dynamodb.scan(
+  "users",
+  z.array(z.object({ id: z.string(), name: z.string() }))
+);
+
+// With filter expression
+const activeUsers = await dynamodb.scan(
+  "users",
+  z.array(z.object({ id: z.string(), name: z.string() })),
+  "status = :s",
+  { ":s": { S: "active" } }
+);
+```
+
+### Query Table by Key Condition
+
+```typescript
+const userOrders = await dynamodb.queryTable(
+  "orders",
+  "userId = :uid",
+  { ":uid": { S: "user-123" } },
+  z.array(z.object({ orderId: z.string(), total: z.number() }))
+);
+```
+
+### Batch Write Items
+
+```typescript
+await dynamodb.batchWriteItem({
+  users: [
+    { PutRequest: { Item: { id: { S: "user-1" }, name: { S: "Alice" } } } },
+    { PutRequest: { Item: { id: { S: "user-2" }, name: { S: "Bob" } } } },
+    { DeleteRequest: { Key: { id: { S: "user-3" } } } },
+  ],
+});
+```
+
+### List Tables
+
+```typescript
+const tables = await dynamodb.listTables(
+  z.object({ TableNames: z.array(z.string()) })
+);
+```
+
+### Describe Table
+
+```typescript
+const description = await dynamodb.describeTable(
+  "users",
+  z.object({
+    Table: z.object({
+      TableName: z.string(),
+      KeySchema: z.array(z.object({
+        AttributeName: z.string(),
+        KeyType: z.string(),
+      })),
+      ItemCount: z.number(),
+    }),
+  })
+);
+```
+
+### Delete Table
+
+```typescript
+await dynamodb.deleteTable("temp-table");
+```
+
+## Common Pitfalls
+
+### Use Parameterized PartiQL Queries
+
+Always use `?` placeholders with typed parameters:
+
+```typescript
+// CORRECT - parameterized with AttributeValue types
+await dynamodb.query(
+  "SELECT * FROM users WHERE id = ?",
+  schema,
+  [{ S: userId }]
+);
+
+// AVOID - string interpolation (potential injection)
+await dynamodb.query(
+  `SELECT * FROM users WHERE id = '${userId}'`,
+  schema
+);
+```
+
+### Numbers Are Always Strings in DynamoDB
+
+DynamoDB represents numbers as strings in the wire format:
+
+```typescript
+// CORRECT
+{ age: { N: "30" } }
+
+// WRONG - N must be a string
+{ age: { N: 30 } }
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError, IntegrationError } from "@superblocksteam/sdk-api";
+
+try {
+  const users = await dynamodb.query(
+    "SELECT * FROM users WHERE status = ?",
+    UserSchema,
+    [{ S: "active" }]
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  } else if (error instanceof IntegrationError) {
+    console.error("DynamoDB error:", error.message);
+  }
+}
+```
+
+## API Reference
+
+- [PartiQL for DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.html)
+- [DynamoDB Developer Guide](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/)
+- [AttributeValue Reference](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_AttributeValue.html)

package/src/integrations/dynamodb/client.ts

@@ -0,0 +1,248 @@
+/**
+ * DynamoDB client implementation.
+ *
+ * Uses the native DynamoDB plugin type from @superblocksteam/types.
+ * All operations pass parameters as a JSON string in the `body` field,
+ * which the orchestrator parses and forwards directly to the AWS SDK.
+ */
+
+import type { z } from 'zod';
+import type { IntegrationConfig, IntegrationClientImpl } from '../types.js';
+import type { QueryExecutor } from '../registry.js';
+import { RestApiValidationError } from '../../errors.js';
+import { IntegrationError } from '../../runtime/errors.js';
+import type { DynamoDBClient, DynamoDBAttributeValue } from './types.js';
+
+/**
+ * Internal implementation of DynamoDBClient.
+ *
+ * The orchestrator's DynamoDB handler only uses two fields from the proto:
+ * - `action`: which AWS SDK command to execute
+ * - `body`: JSON string of parameters passed directly to that command
+ *
+ * All other proto fields (table, filterBy, newValues, etc.) are ignored.
+ */
+export class DynamoDBClientImpl implements DynamoDBClient, IntegrationClientImpl {
+  readonly config: IntegrationConfig;
+  private readonly executeQuery: QueryExecutor;
+
+  constructor(config: IntegrationConfig, executeQuery: QueryExecutor) {
+    this.config = config;
+    this.executeQuery = executeQuery;
+  }
+
+  get name(): string {
+    return this.config.name;
+  }
+
+  get pluginId(): string {
+    return this.config.pluginId;
+  }
+
+  /**
+   * Build a request with action and JSON body.
+   *
+   * @param action - AWS SDK command name (e.g., 'executeStatement', 'getItem')
+   * @param params - Parameters to serialize as JSON body
+   */
+  private buildRequest(
+    action: string,
+    params: Record<string, unknown>,
+  ): Record<string, unknown> {
+    return {
+      action,
+      body: JSON.stringify(params),
+    };
+  }
+
+  /**
+   * Validate a result against a schema.
+   */
+  private validateResult<T>(result: unknown, schema: z.ZodSchema<T>, operation: string): T {
+    const parseResult = schema.safeParse(result);
+
+    if (!parseResult.success) {
+      throw new RestApiValidationError(
+        `Result validation failed: ${parseResult.error.message}`,
+        {
+          zodError: parseResult.error,
+          data: result,
+        },
+      );
+    }
+
+    return parseResult.data;
+  }
+
+  /**
+   * Execute a request and wrap errors.
+   */
+  private async executeWithErrorHandling(
+    request: Record<string, unknown>,
+    operation: string,
+  ): Promise<unknown> {
+    try {
+      return await this.executeQuery(request);
+    } catch (error) {
+      if (
+        error instanceof RestApiValidationError ||
+        error instanceof IntegrationError
+      ) {
+        throw error;
+      }
+
+      throw new IntegrationError(this.config.name, operation, error);
+    }
+  }
+
+  async query<T>(
+    statement: string,
+    schema: z.ZodSchema<T>,
+    params?: DynamoDBAttributeValue[],
+  ): Promise<T> {
+    const body: Record<string, unknown> = { Statement: statement };
+
+    if (params && params.length > 0) {
+      body.Parameters = params;
+    }
+
+    const request = this.buildRequest('executeStatement', body);
+    const result = await this.executeWithErrorHandling(request, 'query');
+    return this.validateResult(result, schema, 'query');
+  }
+
+  async getItem<T>(
+    table: string,
+    key: Record<string, DynamoDBAttributeValue>,
+    schema: z.ZodSchema<T>,
+  ): Promise<T> {
+    const request = this.buildRequest('getItem', {
+      TableName: table,
+      Key: key,
+    });
+    const result = await this.executeWithErrorHandling(request, 'getItem');
+    return this.validateResult(result, schema, 'getItem');
+  }
+
+  async putItem(
+    table: string,
+    item: Record<string, DynamoDBAttributeValue>,
+  ): Promise<unknown> {
+    const request = this.buildRequest('putItem', {
+      TableName: table,
+      Item: item,
+    });
+    return this.executeWithErrorHandling(request, 'putItem');
+  }
+
+  async updateItem(
+    table: string,
+    key: Record<string, DynamoDBAttributeValue>,
+    updateExpression: string,
+    expressionAttributeValues: Record<string, DynamoDBAttributeValue>,
+    expressionAttributeNames?: Record<string, string>,
+  ): Promise<unknown> {
+    const params: Record<string, unknown> = {
+      TableName: table,
+      Key: key,
+      UpdateExpression: updateExpression,
+      ExpressionAttributeValues: expressionAttributeValues,
+    };
+
+    if (expressionAttributeNames) {
+      params.ExpressionAttributeNames = expressionAttributeNames;
+    }
+
+    const request = this.buildRequest('updateItem', params);
+    return this.executeWithErrorHandling(request, 'updateItem');
+  }
+
+  async deleteItem(
+    table: string,
+    key: Record<string, DynamoDBAttributeValue>,
+  ): Promise<unknown> {
+    const request = this.buildRequest('deleteItem', {
+      TableName: table,
+      Key: key,
+    });
+    return this.executeWithErrorHandling(request, 'deleteItem');
+  }
+
+  async scan<T>(
+    table: string,
+    schema: z.ZodSchema<T>,
+    filterExpression?: string,
+    expressionAttributeValues?: Record<string, DynamoDBAttributeValue>,
+    expressionAttributeNames?: Record<string, string>,
+  ): Promise<T> {
+    const params: Record<string, unknown> = { TableName: table };
+
+    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');
+    return this.validateResult(result, schema, 'scan');
+  }
+
+  async queryTable<T>(
+    table: string,
+    keyConditionExpression: string,
+    expressionAttributeValues: Record<string, DynamoDBAttributeValue>,
+    schema: z.ZodSchema<T>,
+    expressionAttributeNames?: Record<string, string>,
+  ): Promise<T> {
+    const params: Record<string, unknown> = {
+      TableName: table,
+      KeyConditionExpression: keyConditionExpression,
+      ExpressionAttributeValues: expressionAttributeValues,
+    };
+
+    if (expressionAttributeNames) {
+      params.ExpressionAttributeNames = expressionAttributeNames;
+    }
+
+    const request = this.buildRequest('query', params);
+    const result = await this.executeWithErrorHandling(request, 'queryTable');
+    return this.validateResult(result, schema, 'queryTable');
+  }
+
+  async batchWriteItem(
+    requestItems: Record<string, Array<Record<string, unknown>>>,
+  ): Promise<unknown> {
+    const request = this.buildRequest('batchWriteItem', {
+      RequestItems: requestItems,
+    });
+    return this.executeWithErrorHandling(request, 'batchWriteItem');
+  }
+
+  async listTables<T>(schema: z.ZodSchema<T>): Promise<T> {
+    const request = this.buildRequest('listTables', {});
+    const result = await this.executeWithErrorHandling(request, 'listTables');
+    return this.validateResult(result, schema, 'listTables');
+  }
+
+  async describeTable<T>(table: string, schema: z.ZodSchema<T>): Promise<T> {
+    const request = this.buildRequest('describeTable', {
+      TableName: table,
+    });
+    const result = await this.executeWithErrorHandling(request, 'describeTable');
+    return this.validateResult(result, schema, 'describeTable');
+  }
+
+  async deleteTable(table: string): Promise<unknown> {
+    const request = this.buildRequest('deleteTable', {
+      TableName: table,
+    });
+    return this.executeWithErrorHandling(request, 'deleteTable');
+  }
+}

package/src/integrations/dynamodb/index.ts

@@ -0,0 +1,8 @@
+/**
+ * DynamoDB integration client.
+ *
+ * @module
+ */
+
+export type { DynamoDBClient, DynamoDBAttributeValue } from './types.js';
+export { DynamoDBClientImpl } from './client.js';