@superblocksteam/sdk-api 0.0.4

package/src/integrations/dynamodb/README.md

@@ -0,0 +1,280 @@
+# 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?, metadata?)`                  | Execute a PartiQL statement  |
+| `getItem(table, key, schema, metadata?)`                        | Get an item by key           |
+| `putItem(table, item, metadata?)`                               | Insert or replace an item    |
+| `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                 |
+| `queryTable(table, keyExpr, values, schema, names?, metadata?)` | Query by key condition       |
+| `batchWriteItem(requestItems, metadata?)`                       | Batch write multiple items   |
+| `listTables(schema, metadata?)`                                 | List all tables              |
+| `describeTable(table, schema, metadata?)`                       | Describe a table's structure |
+| `deleteTable(table, metadata?)`                                 | 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, dynamodb } 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",
+  integrations: {
+    dynamodb: dynamodb(PROD_DYNAMODB),
+  },
+  input: z.object({
+    status: z.string(),
+  }),
+  output: z.object({
+    users: UserSchema,
+  }),
+  async run(ctx, { status }) {
+    const users = await ctx.integrations.dynamodb.query(
+      "SELECT * FROM users WHERE status = ?",
+      UserSchema,
+      [{ S: status }],
+    );
+
+    return { users };
+  },
+});
+```
+
+### Get Item by Key
+
+```typescript
+const user = await ctx.integrations.dynamodb.getItem(
+  "users",
+  { id: { S: "user-123" } },
+  z.object({ id: z.string(), name: z.string(), email: z.string() }),
+);
+```
+
+### Put Item
+
+```typescript
+await ctx.integrations.dynamodb.putItem("users", {
+  id: { S: "user-456" },
+  name: { S: "John Doe" },
+  email: { S: "john@example.com" },
+  age: { N: "30" },
+});
+```
+
+### Update Item
+
+```typescript
+await ctx.integrations.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 ctx.integrations.dynamodb.deleteItem("users", { id: { S: "user-123" } });
+```
+
+### Scan Table
+
+```typescript
+// Full scan
+const allUsers = await ctx.integrations.dynamodb.scan(
+  "users",
+  z.array(z.object({ id: z.string(), name: z.string() })),
+);
+
+// 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" } },
+);
+```
+
+### Query Table by Key Condition
+
+```typescript
+const userOrders = await ctx.integrations.dynamodb.queryTable(
+  "orders",
+  "userId = :uid",
+  { ":uid": { S: "user-123" } },
+  z.array(z.object({ orderId: z.string(), total: z.number() })),
+);
+```
+
+### Batch Write Items
+
+```typescript
+await ctx.integrations.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 ctx.integrations.dynamodb.listTables(
+  z.object({ TableNames: z.array(z.string()) }),
+);
+```
+
+### Describe Table
+
+```typescript
+const description = await ctx.integrations.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 ctx.integrations.dynamodb.deleteTable("temp-table");
+```
+
+## Trace Metadata
+
+All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling. See the [root SDK README](../../../README.md#trace-metadata) for details.
+
+## Common Pitfalls
+
+### Use Parameterized PartiQL Queries
+
+Always use `?` placeholders with typed parameters:
+
+```typescript
+// CORRECT - parameterized with AttributeValue types
+await ctx.integrations.dynamodb.query(
+  "SELECT * FROM users WHERE id = ?",
+  schema,
+  [{ S: userId }],
+);
+
+// AVOID - string interpolation (potential injection)
+await ctx.integrations.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 ctx.integrations.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,294 @@
+/**
+ * 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, TraceMetadata } 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,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
+    try {
+      return await this.executeQuery(request, undefined, metadata);
+    } 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[],
+    metadata?: TraceMetadata,
+  ): 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",
+      metadata,
+    );
+    return this.validateResult(result, schema, "query");
+  }
+
+  async getItem<T>(
+    table: string,
+    key: Record<string, DynamoDBAttributeValue>,
+    schema: z.ZodSchema<T>,
+    metadata?: TraceMetadata,
+  ): Promise<T> {
+    const request = this.buildRequest("getItem", {
+      TableName: table,
+      Key: key,
+    });
+    const result = await this.executeWithErrorHandling(
+      request,
+      "getItem",
+      metadata,
+    );
+    return this.validateResult(result, schema, "getItem");
+  }
+
+  async putItem(
+    table: string,
+    item: Record<string, DynamoDBAttributeValue>,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
+    const request = this.buildRequest("putItem", {
+      TableName: table,
+      Item: item,
+    });
+    return this.executeWithErrorHandling(request, "putItem", metadata);
+  }
+
+  async updateItem(
+    table: string,
+    key: Record<string, DynamoDBAttributeValue>,
+    updateExpression: string,
+    expressionAttributeValues: Record<string, DynamoDBAttributeValue>,
+    expressionAttributeNames?: Record<string, string>,
+    metadata?: TraceMetadata,
+  ): 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", metadata);
+  }
+
+  async deleteItem(
+    table: string,
+    key: Record<string, DynamoDBAttributeValue>,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
+    const request = this.buildRequest("deleteItem", {
+      TableName: table,
+      Key: key,
+    });
+    return this.executeWithErrorHandling(request, "deleteItem", metadata);
+  }
+
+  async scan<T>(
+    table: string,
+    schema: z.ZodSchema<T>,
+    filterExpression?: string,
+    expressionAttributeValues?: Record<string, DynamoDBAttributeValue>,
+    expressionAttributeNames?: Record<string, string>,
+    metadata?: TraceMetadata,
+  ): 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",
+      metadata,
+    );
+    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>,
+    metadata?: TraceMetadata,
+  ): 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",
+      metadata,
+    );
+    return this.validateResult(result, schema, "queryTable");
+  }
+
+  async batchWriteItem(
+    requestItems: Record<string, Array<Record<string, unknown>>>,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
+    const request = this.buildRequest("batchWriteItem", {
+      RequestItems: requestItems,
+    });
+    return this.executeWithErrorHandling(request, "batchWriteItem", metadata);
+  }
+
+  async listTables<T>(
+    schema: z.ZodSchema<T>,
+    metadata?: TraceMetadata,
+  ): Promise<T> {
+    const request = this.buildRequest("listTables", {});
+    const result = await this.executeWithErrorHandling(
+      request,
+      "listTables",
+      metadata,
+    );
+    return this.validateResult(result, schema, "listTables");
+  }
+
+  async describeTable<T>(
+    table: string,
+    schema: z.ZodSchema<T>,
+    metadata?: TraceMetadata,
+  ): Promise<T> {
+    const request = this.buildRequest("describeTable", {
+      TableName: table,
+    });
+    const result = await this.executeWithErrorHandling(
+      request,
+      "describeTable",
+      metadata,
+    );
+    return this.validateResult(result, schema, "describeTable");
+  }
+
+  async deleteTable(table: string, metadata?: TraceMetadata): Promise<unknown> {
+    const request = this.buildRequest("deleteTable", {
+      TableName: table,
+    });
+    return this.executeWithErrorHandling(request, "deleteTable", metadata);
+  }
+}

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";