npm package: @lewinnovation/dynamo-eventbridge-pipe-construct
Description: A TypeScript AWS CDK construct that creates an EventBridge Pipe from a DynamoDB table stream to an EventBridge event bus. This construct automatically handles IAM permissions for reading from DynamoDB streams and publishing to EventBridge.
Latest version: 0.3.1

# DynamoDB EventBridge Pipe Construct

A TypeScript AWS CDK construct that creates an EventBridge Pipe from a DynamoDB table stream to an EventBridge event bus. This construct automatically handles IAM permissions for reading from DynamoDB streams and publishing to EventBridge.

## Prerequisites

- The DynamoDB table **must have streams enabled** for the pipe to work
- AWS CDK v2
- Node.js 18+ and TypeScript

## Installation

```bash
npm install @lewinnovation/dynamo-eventbridge-pipe-construct
```

## Usage

### Basic Usage

```typescript
import { DynamoEventbridgePipeConstruct } from '@lewinnovation/dynamo-eventbridge-pipe-construct';
import { Table, StreamViewType } from 'aws-cdk-lib/aws-dynamodb';
import { EventBus } from 'aws-cdk-lib/aws-events';

// Create a table with streams enabled
const table = new Table(this, 'MyTable', {
  partitionKey: { name: 'id', type: AttributeType.STRING },
  stream: StreamViewType.NEW_AND_OLD_IMAGES, // Required!
});

// Create an event bus
const bus = new EventBus(this, 'MyEventBus');

// Create the pipe construct
const pipe = new DynamoEventbridgePipeConstruct(this, 'MyPipe', {
  table,
  bus,
  entityName: 'User',
  sourceName: 'myapp.users'
});
```

### Advanced Usage with Custom Names

```typescript
const pipe = new DynamoEventbridgePipeConstruct(this, 'MyPipe', {
  table,
  bus,
  entityName: 'User',
  sourceName: 'myapp.users',
  pipeName: 'custom-pipe-name',     // Optional: custom pipe name
  roleName: 'custom-role-name'      // Optional: custom IAM role name
});
```

## API Reference

### DynamoEventbridgePipeConstructProps

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `table` | `ITable` | ✅ | DynamoDB table with streams enabled |
| `bus` | `IEventBus` | ✅ | EventBridge event bus to send events to |
| `entityName` | `string` | ✅ | Entity name used for the detail type in EventBridge events |
| `sourceName` | `string` | ✅ | Source name for EventBridge events |
| `pipeName` | `string` | ❌ | Name for the EventBridge pipe (auto-generated if not provided) |
| `roleName` | `string` | ❌ | IAM role name for the pipe (auto-generated if not provided) |

### Public Properties

| Property | Type | Description |
|----------|------|-------------|
| `bus` | `IEventBus` | The EventBridge event bus that events are sent to |
| `pipe` | `Pipe` | The EventBridge pipe that connects DynamoDB stream to EventBridge |

## Security and Best Practices

This construct includes **cdk-nag** integration for security best practices validation. The construct automatically applies appropriate suppressions for:

- **IAM5**: Wildcard permissions required for DynamoDB stream access and EventBridge publishing
- **IAM4**: Inline policies used for specific DynamoDB stream and EventBridge permissions  
- **Pipes-1**: Pipe uses DynamoDB stream as source which requires specific permissions

### Using cdk-nag with this construct

```typescript
import { AwsSolutionsChecks } from 'cdk-nag';

// Apply cdk-nag checks to your stack
AwsSolutionsChecks.quiet = false; // Set to true to suppress output

// Your stack will automatically pass cdk-nag validation
```

## Important Notes

- **Role Name Uniqueness**: If you provide a custom `roleName`, it must be globally unique within your AWS account. Consider using auto-generated names for multiple deployments.
- **Stream Requirements**: The DynamoDB table must have streams enabled. The construct will throw an error if streams are not configured.
- **Input Validation**: The construct validates that `entityName` and `sourceName` are non-empty strings.
- **Security**: The construct includes cdk-nag suppressions for legitimate security patterns specific to EventBridge Pipes and DynamoDB streams.

## Development

### Useful Commands

* `npm run build`   compile typescript to js
* `npm run watch`   watch for changes and compile
* `npm run test`    perform the jest unit tests

### Running Tests

```bash
npm test
```

## License

This project is licensed under the MIT License.