@chaim-tools/cdk-lib 0.1.0

package/README.md

@@ -0,0 +1,238 @@
+# @chaim-tools/cdk-lib
+
+AWS CDK L2 constructs for binding DynamoDB tables to Chaim schemas.
+
+## Installation
+
+```bash
+npm install @chaim-tools/cdk-lib
+# or
+pnpm add @chaim-tools/cdk-lib
+```
+
+## Development
+
+### Build
+
+```bash
+pnpm install
+pnpm build
+```
+
+### Test
+
+```bash
+pnpm test              # Run tests
+pnpm test:watch        # Watch mode
+pnpm test:coverage     # With coverage
+```
+
+### Clean
+
+```bash
+pnpm clean
+```
+
+## Quick Start
+
+```typescript
+import { ChaimDynamoDBBinder, ChaimCredentials, TableBindingConfig } from '@chaim-tools/cdk-lib';
+import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
+
+// Create a DynamoDB table
+const usersTable = new dynamodb.Table(this, 'Users', {
+  partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
+  billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
+});
+
+// Create binding configuration
+const config = new TableBindingConfig(
+  'my-app',
+  ChaimCredentials.fromSecretsManager('chaim/api-credentials')
+);
+
+// Bind schema to table
+new ChaimDynamoDBBinder(this, 'UsersBinding', {
+  schemaPath: './schemas/users.bprint',
+  table: usersTable,
+  config,
+});
+```
+
+## API Reference
+
+### `ChaimDynamoDBBinder`
+
+Construct that binds a DynamoDB table to a Chaim schema.
+
+#### Props
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `schemaPath` | string | Yes | Path to `.bprint` schema file |
+| `table` | `ITable` | Yes | DynamoDB table to bind |
+| `config` | `TableBindingConfig` | Yes | Binding configuration (appId, credentials, failureMode) |
+
+### `TableBindingConfig`
+
+Configuration for entity bindings. For single-table design, create one config and share across all entity bindings.
+
+```typescript
+// Create config with Secrets Manager (recommended for production)
+const config = new TableBindingConfig(
+  'my-app',
+  ChaimCredentials.fromSecretsManager('chaim/api-credentials')
+);
+
+// Or with direct API keys (for development)
+const config = new TableBindingConfig(
+  'my-app',
+  ChaimCredentials.fromApiKeys(apiKey, apiSecret),
+  FailureMode.STRICT  // Optional - defaults to BEST_EFFORT
+);
+```
+
+**Constructor Parameters:**
+- `appId` (string) - Application ID for the Chaim platform
+- `credentials` (IChaimCredentials) - API credentials
+- `failureMode` (FailureMode) - Optional, defaults to BEST_EFFORT
+
+### `ChaimCredentials`
+
+Factory class for creating Chaim API credentials.
+
+```typescript
+// Using AWS Secrets Manager (recommended for production)
+const credentials = ChaimCredentials.fromSecretsManager('chaim/api-credentials');
+
+// Using direct API keys (for development/testing)
+const credentials = ChaimCredentials.fromApiKeys(apiKey, apiSecret);
+```
+
+### `FailureMode`
+
+| Mode | Behavior |
+|------|----------|
+| `BEST_EFFORT` (default) | Log errors, return SUCCESS to CloudFormation |
+| `STRICT` | Return FAILED to CloudFormation on any ingestion error |
+
+## Single-Table Design (Multiple Entities)
+
+For single-table design where multiple entity types share one DynamoDB table, create **one** `TableBindingConfig` and share it across all entity bindings:
+
+```typescript
+import { ChaimDynamoDBBinder, ChaimCredentials, TableBindingConfig } from '@chaim-tools/cdk-lib';
+
+const singleTable = new dynamodb.Table(this, 'SingleTable', {
+  partitionKey: { name: 'PK', type: dynamodb.AttributeType.STRING },
+  sortKey: { name: 'SK', type: dynamodb.AttributeType.STRING },
+});
+
+// Create config ONCE for the table
+const tableConfig = new TableBindingConfig(
+  'my-app',
+  ChaimCredentials.fromSecretsManager('chaim/api-credentials')
+);
+
+// Share config across all entities in the table
+new ChaimDynamoDBBinder(this, 'UserBinding', {
+  schemaPath: './schemas/user.bprint',
+  table: singleTable,
+  config: tableConfig,
+});
+
+new ChaimDynamoDBBinder(this, 'OrderBinding', {
+  schemaPath: './schemas/order.bprint',
+  table: singleTable,
+  config: tableConfig, // Same config!
+});
+
+new ChaimDynamoDBBinder(this, 'ProductBinding', {
+  schemaPath: './schemas/product.bprint',
+  table: singleTable,
+  config: tableConfig, // Same config!
+});
+```
+
+**Why this pattern?**
+
+All entities in the same DynamoDB table must belong to the same application (`appId`) with the same credentials. `TableBindingConfig` enforces this by design:
+
+- Sharing the same config object makes consistency automatic
+- Validation catches accidental misconfigurations (different appIds)
+- Clear intent in your CDK code
+- DRY - define credentials once
+
+**Result:**
+- 3 separate snapshots (one per entity)
+- 3 separate resourceIds: `SingleTable__User`, `SingleTable__Order`, `SingleTable__Product`
+- All with the same `appId` and `credentials`
+- Each entity can be independently created, updated, or deleted
+
+## How It Works
+
+1. At **synth time**: The construct reads your `.bprint` file, validates it, and writes a snapshot to the CDK asset directory
+2. During **deploy**: CloudFormation invokes the ingestion Lambda in your account
+3. The Lambda:
+   - Reads the bundled snapshot from `./snapshot.json`
+   - Generates `eventId` (UUID v4), `nonce` (UUID v4), and `contentHash` (SHA-256)
+   - Requests presigned URL: `POST /ingest/presign` with HMAC authentication
+   - Uploads snapshot: `PUT <presignedUrl>`
+
+## Ingestion Flow
+
+```
+Create/Update:
+  1. POST /ingest/presign with HMAC signature → get presigned S3 URL
+     Request includes: appId, eventId, contentHash, timestamp, nonce
+  2. PUT snapshot bytes to presigned S3 URL
+  
+Delete:
+  1. Build DELETE snapshot (action: 'DELETE', schema: null)
+  2. POST /ingest/presign with HMAC signature → get presigned S3 URL
+  3. PUT DELETE snapshot bytes to presigned S3 URL
+```
+
+## Snapshot Payload
+
+The snapshot payload includes:
+
+**Schema & Identity:**
+- `schemaVersion` - Payload version for backward compatibility (current: 1.0)
+- `.bprint` schema content (entity definitions, field types, constraints)
+- Application ID and resource identifiers
+
+**Infrastructure Metadata:**
+- AWS account ID, region, stack information
+- DynamoDB table configuration (keys, indexes, TTL, streams)
+- CloudFormation context
+
+**Versioning Strategy:**
+- **Minor bump** (1.0 → 1.1): Additive or optional field changes
+- **Major bump** (1.x → 2.0): Breaking changes (removed/renamed/required fields)
+
+## Configuration
+
+### Environment Configuration
+
+The API defaults to production: `https://api.chaim.co`
+
+Override for different environments via CDK context:
+
+```bash
+# Production (default - no context needed)
+cdk deploy
+
+# Development
+cdk deploy --context chaimApiBaseUrl=https://api.dev.chaim.co
+
+# Beta
+cdk deploy --context chaimApiBaseUrl=https://api.beta.chaim.co
+```
+
+You can also set a custom API URL via environment variable in the Lambda:
+- `CHAIM_API_BASE_URL` - Overrides the default at runtime
+
+## License
+
+Apache-2.0

package/lib/binders/base-chaim-binder.d.ts

@@ -0,0 +1,144 @@
+import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
+import { Construct } from 'constructs';
+import { SchemaData } from '@chaim-tools/chaim-bprint-spec';
+import { BaseBinderProps } from '../types/base-binder-props';
+import { DataStoreMetadata } from '../types/data-store-metadata';
+import { TableBindingConfig } from '../types/table-binding-config';
+/**
+ * Abstract base class for all Chaim data store binders.
+ *
+ * Provides shared infrastructure:
+ * - Schema loading and validation
+ * - Snapshot payload construction
+ * - LOCAL snapshot writing during CDK synth (to OS cache)
+ * - Lambda-backed custom resource for S3 presigned upload + snapshot-ref
+ *
+ * Subclasses implement `extractMetadata()` for store-specific metadata extraction
+ * and optionally override `getTable()` for DynamoDB-like resources.
+ */
+export declare abstract class BaseChaimBinder extends Construct {
+    /** Validated schema data */
+    readonly schemaData: SchemaData;
+    /** Extracted data store metadata */
+    readonly dataStoreMetadata: DataStoreMetadata;
+    /** Generated resource ID ({resourceName}__{entityName}[__N]) */
+    readonly resourceId: string;
+    /** Binding configuration */
+    readonly config: TableBindingConfig;
+    /** Base props (for internal use) */
+    protected readonly baseProps: BaseBinderProps;
+    constructor(scope: Construct, id: string, props: BaseBinderProps);
+    /**
+     * Validate that all bindings to the same table use the same config.
+     *
+     * This is a safety check - sharing the same TableBindingConfig object
+     * already ensures consistency, but this catches cases where users
+     * create separate configs with identical values.
+     */
+    private validateTableConsistency;
+    /**
+     * Abstract method - subclasses implement store-specific metadata extraction.
+     */
+    protected abstract extractMetadata(): DataStoreMetadata;
+    /**
+     * Override in subclasses to provide the table construct for stable identity.
+     * Default returns undefined (will fall back to construct path).
+     */
+    protected getTable(): dynamodb.ITable | undefined;
+    /**
+     * Get the resource name for display and filenames.
+     * For DynamoDB, this is the user label (not necessarily the physical table name).
+     *
+     * Subclasses can override this to provide a more meaningful name
+     * (e.g., construct node ID instead of physical resource name which may contain tokens).
+     */
+    protected getResourceName(): string;
+    /**
+     * Get the entity name from schema.
+     */
+    private getEntityName;
+    /**
+     * Read package version from package.json.
+     * Used to populate producer metadata in snapshots.
+     */
+    private getPackageVersion;
+    /**
+     * Build a LOCAL snapshot payload for CLI consumption.
+     * Does not include eventId or contentHash - those are generated at deploy-time.
+     */
+    private buildLocalSnapshot;
+    /**
+     * Build resource metadata from dataStore metadata.
+     */
+    private buildResourceMetadata;
+    /**
+     * Detect if metadata contains unresolved CDK tokens.
+     */
+    private detectUnresolvedTokens;
+    /**
+     * Generate a UUID v4 for operation tracking.
+     */
+    private generateUuid;
+    /**
+     * Apply snapshot cache policy based on CDK context.
+     *
+     * Checks the `chaimSnapshotCachePolicy` context value:
+     * - NONE (default): No cleanup
+     * - PRUNE_STACK: Delete existing stack snapshots before writing new ones
+     *
+     * This runs once per stack (tracked by static flag) to avoid
+     * multiple cleanup attempts when binding multiple entities.
+     */
+    private applySnapshotCachePolicy;
+    /**
+     * Parse snapshot cache policy from context value.
+     */
+    private parseSnapshotCachePolicy;
+    /**
+     * Extract stack name from stableResourceKey.
+     * Format: dynamodb:path:StackName/ResourceName
+     */
+    private extractStackNameFromResourceKey;
+    /**
+     * Write LOCAL snapshot to OS cache for chaim-cli consumption.
+     * Uses hierarchical path: aws/{accountId}/{region}/{stackName}/{datastoreType}/{resourceId}.json
+     *
+     * @param snapshot - The snapshot payload to write
+     * @returns The path where snapshot was written
+     */
+    private writeLocalSnapshotToDisk;
+    /**
+     * Find the CDK project root by walking up from current module.
+     */
+    private findCdkProjectRoot;
+    /**
+     * Write snapshot and Lambda handler to isolated CDK asset directory for Lambda bundling.
+     *
+     * Asset directory is per {stackName}/{resourceId} and MUST NOT be shared.
+     * The Lambda reads ./snapshot.json from its bundle, NOT from env vars or OS cache.
+     *
+     * The handler is copied from the canonical handler file (src/lambda-handler/handler.js)
+     * rather than being generated inline - this ensures a single source of truth.
+     *
+     * @returns The asset directory path
+     */
+    private writeSnapshotAsset;
+    /**
+     * Deploy Lambda function and custom resource for ingestion.
+     */
+    private deployIngestionResources;
+    /**
+     * Create Lambda function for ingestion workflow.
+     * Lambda reads snapshot from its bundled asset directory.
+     */
+    private createIngestionLambda;
+    /**
+     * Build Lambda environment variables.
+     * Note: Snapshot is NOT passed via env - Lambda reads from bundled asset.
+     */
+    private buildLambdaEnvironment;
+    /**
+     * Create CloudFormation custom resource.
+     */
+    private createCustomResource;
+}