@felloh-org/lambda-wrapper 1.11.192 → 1.11.193

package/README.md

@@ -1,4 +1,231 @@
-# Lambda Wrapper [![release](https://github.com/felloh-org/lambda-wrapper/actions/workflows/release.yml/badge.svg)](https://github.com/felloh-org/lambda-wrapper/actions/workflows/release.yml)
+# Lambda Wrapper
 
-A function wrapper to wrap all of our lambdas and provide core functionality, monitoring and logging + time saving tooling to all of our serverless services.
+[![release](https://github.com/felloh-org/lambda-wrapper/actions/workflows/release.yml/badge.svg)](https://github.com/felloh-org/lambda-wrapper/actions/workflows/release.yml)
 
+A shared library for Felloh serverless projects that provides core functionality including dependency injection, logging, request handling, database entities, and response models for AWS Lambda functions.
+
+## Installation
+
+```bash
+npm install @felloh-org/lambda-wrapper
+# or
+yarn add @felloh-org/lambda-wrapper
+```
+
+## Quick Start
+
+```javascript
+import { LambdaWrapper, DEFINITIONS, ResponseModel } from '@felloh-org/lambda-wrapper';
+
+const configuration = {
+  SERVICE_NAME: 'my-service',
+};
+
+export const handler = LambdaWrapper(configuration, async (di, request) => {
+  const logger = di.get(DEFINITIONS.LOGGER);
+  const warehouse = di.get(DEFINITIONS.WAREHOUSE);
+
+  logger.info('Processing request');
+
+  // Your handler logic here
+
+  return new ResponseModel({ message: 'Success' }, 200).generate();
+});
+```
+
+## Features
+
+### Lambda Wrapper
+
+The core wrapper provides:
+
+- **Dependency Injection** - Access services via `di.get(DEFINITIONS.SERVICE_NAME)`
+- **Automatic Error Handling** - Catches and formats errors consistently
+- **Request Parsing** - Parses body, query params, path params, and headers
+- **Logging & Metrics** - Built-in logging with automatic metric collection
+- **Warm-up Support** - Handles `serverless-plugin-warmup` events automatically
+
+### Built-in Services
+
+Access these via `di.get(DEFINITIONS.SERVICE_NAME)`:
+
+| Service | Definition | Description |
+|---------|------------|-------------|
+| Logger | `DEFINITIONS.LOGGER` | Structured logging with metric support |
+| Request | `DEFINITIONS.REQUEST` | Parsed request data (body, params, headers) |
+| Warehouse | `DEFINITIONS.WAREHOUSE` | TypeORM database connection manager |
+| Authentication | `DEFINITIONS.AUTHENTICATION` | JWT authentication and user context |
+| EventBridge | `DEFINITIONS.EVENT_BRIDGE` | AWS EventBridge event publishing |
+| Secrets | `DEFINITIONS.SECRETS` | AWS Secrets Manager integration |
+| HTTP | `DEFINITIONS.HTTP` | HTTP client for external requests |
+| Webhook | `DEFINITIONS.WEBHOOK` | Webhook dispatch service |
+| User | `DEFINITIONS.USER` | User service utilities |
+| AuditLogger | `DEFINITIONS.AUDIT_LOGGER` | Audit trail logging |
+
+### Response Model
+
+All Lambda responses are standardised:
+
+```javascript
+import { ResponseModel } from '@felloh-org/lambda-wrapper';
+
+// Success response
+return new ResponseModel({ users: [...] }, 200).generate();
+
+// Error response
+return new ResponseModel({}, 400)
+  .setErrors([{ field: 'email', message: 'Invalid email' }])
+  .generate();
+```
+
+Response format:
+
+```json
+{
+  "statusCode": 200,
+  "headers": {
+    "Content-Type": "application/json",
+    "Access-Control-Allow-Origin": "*"
+  },
+  "body": {
+    "data": { ... },
+    "errors": [],
+    "meta": {
+      "code": 200,
+      "reason": "OK",
+      "message": "Success",
+      "request_id": "uuid"
+    }
+  }
+}
+```
+
+### Database Entities (TypeORM)
+
+The library includes TypeORM entities organised by domain:
+
+| Domain | Description |
+|--------|-------------|
+| `payment` | Transactions, refunds, chargebacks, payment links, providers |
+| `user` | Users, organisations, roles, features, webhooks |
+| `bank` | Accounts, ledgers, settlements, disbursals |
+| `agent-data` | Bookings, components, suppliers |
+| `acquirer` | BIN data, batches, adjustments |
+| `aisp` | Open banking transactions and connections |
+| `nuapay` | Nuapay integration entities |
+| `nuvei` | Nuvei payment processor entities |
+| `trust-payments` | Trust Payments integration |
+| `total-processing` | Total Processing integration |
+| `planet` | Planet payment processor entities |
+| `saltedge` | Saltedge banking integration |
+| `basis-theory` | Tokenisation entities |
+| `go-cardless` | GoCardless Direct Debit |
+| `marketing` | Marketing contacts and ESUs |
+
+### EventBridge Events
+
+Publish events to AWS EventBridge:
+
+```javascript
+import { LambdaWrapper, DEFINITIONS, TransactionCustomerReceipt } from '@felloh-org/lambda-wrapper';
+
+export const handler = LambdaWrapper(configuration, async (di, request) => {
+  const eventBridge = di.get(DEFINITIONS.EVENT_BRIDGE);
+
+  const event = new TransactionCustomerReceipt();
+  event.setCustomerEmail('customer@example.com');
+  event.setOrgName('Acme Travel');
+  event.setAmount(150000);
+  event.setCurrencyMajorUnit('GBP');
+  event.setId('txn_123');
+
+  await eventBridge.send(event);
+});
+```
+
+See [Event Documentation](./docs/events/README.md) for all available events.
+
+### Dependency Injection
+
+Create custom services by extending `DependencyAwareClass`:
+
+```javascript
+import { DependencyAwareClass, DEFINITIONS } from '@felloh-org/lambda-wrapper';
+
+class MyCustomService extends DependencyAwareClass {
+  async doSomething() {
+    const logger = this.di.get(DEFINITIONS.LOGGER);
+    const warehouse = this.di.get(DEFINITIONS.WAREHOUSE);
+
+    // Your service logic
+  }
+}
+
+// Register in configuration
+const configuration = {
+  DEPENDENCIES: {
+    MY_SERVICE: MyCustomService,
+  },
+};
+```
+
+## Development
+
+### Commands
+
+```bash
+# Build for production (webpack)
+yarn build
+
+# Build for TypeORM migrations (babel)
+yarn build:orm
+
+# Run linter
+yarn lint
+
+# Run tests with coverage
+yarn test
+
+# Run database migrations
+yarn orm:migration:run
+
+# Generate a new migration
+yarn orm:migration:generate <name>
+
+# Revert last migration
+yarn orm:revert
+
+# Create database schemas
+yarn orm:schema:create
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SERVICE_NAME` | Service identifier for logging and events |
+| `EVENT_BRIDGE_ARN` | AWS EventBridge bus ARN |
+| `DB_HOST` | Database host |
+| `DB_PORT` | Database port |
+| `DB_USERNAME` | Database username |
+| `DB_PASSWORD` | Database password |
+| `DB_DATABASE` | Database name |
+
+### Project Structure
+
+```
+src/
+├── config/          # Dependency definitions
+├── dependency-injection/  # DI implementation
+├── entity/          # TypeORM entities by domain
+├── event/           # EventBridge event classes
+├── migration/       # Database migrations by schema
+├── model/           # Response and data models
+├── service/         # Core services
+├── util/            # Utility functions
+└── wrapper/         # Lambda wrapper implementation
+```
+
+## License
+
+MIT

package/docs/events/README.md

@@ -0,0 +1,50 @@
+# EventBridge Events
+
+This directory contains documentation for all EventBridge events available in the lambda-wrapper.
+
+## Available Events
+
+| Event | Detail Type | Description |
+|-------|-------------|-------------|
+| [TransactionCustomerReceipt](./transaction-customer-receipt.md) | `transaction:customer:receipt` | Sends payment confirmation email to customer |
+| [TransactionCompleteEmailEvent](./transaction-complete-email.md) | `transaction:complete:email` | Triggers transaction completion notification |
+| [UserRegistration](./user-registration.md) | `user:registration` | Triggered when a new user registers |
+| [UserPasswordChanged](./user-password-changed.md) | `user:password:changed` | Triggered when a user changes their password |
+| [CSVEmail](./csv-export-link.md) | `csv:export-link` | Sends CSV export download link via email |
+| [POSCRequestEmail](./posc-request.md) | `posc:request` | Sends POSC request notification |
+| [BaseEvent](./base-event.md) | Custom | Base class for creating custom events |
+
+## Quick Start
+
+```javascript
+import { LambdaWrapper, DEFINITIONS, TransactionCustomerReceipt } from '@felloh-org/lambda-wrapper';
+
+export const handler = LambdaWrapper(configuration, async (di, request) => {
+  const eventBridge = di.get(DEFINITIONS.EVENT_BRIDGE);
+
+  const event = new TransactionCustomerReceipt();
+  event.setCustomerEmail('customer@example.com');
+  event.setOrgName('Acme Travel Ltd');
+  event.setAmount(150000);
+  event.setCurrencyMajorUnit('GBP');
+  event.setId('txn_abc123xyz');
+
+  await eventBridge.send(event);
+});
+```
+
+## Creating Custom Events
+
+For events not covered by the built-in classes, use `BaseEvent`:
+
+```javascript
+import { BaseEvent } from '@felloh-org/lambda-wrapper';
+
+const event = new BaseEvent('custom:event:type');
+event.setDetailParam('data', { foo: 'bar' });
+event.setUserBy({ id: 'usr_123', email: 'user@example.com' });
+
+await eventBridge.send(event);
+```
+
+See [BaseEvent documentation](./base-event.md) for more details.

package/docs/events/base-event.md

@@ -0,0 +1,107 @@
+# BaseEvent Class
+
+The `BaseEvent` class is the foundation for all EventBridge events in the lambda-wrapper. Use it to create custom events or extend it for reusable event types.
+
+## Event Structure
+
+All events follow this base structure:
+
+```json
+{
+  "Source": "your-service-name",
+  "EventBusName": "your-event-bus-arn",
+  "DetailType": "your:event:type",
+  "Time": "2024-01-15T10:30:00.000Z",
+  "Detail": {
+    "your": "data",
+    "userBy": {
+      "id": "usr_abc123xyz",
+      "email": "user@example.com"
+    }
+  }
+}
+```
+
+## Base Methods
+
+| Method | Description |
+|--------|-------------|
+| `getBase()` | Returns the complete event payload with stringified Detail |
+| `setDetailType(type)` | Sets the event type (e.g., `user:registration`) |
+| `setDetailParam(key, value)` | Sets a key-value pair in the Detail object |
+| `setDetail(detail)` | Replaces the entire Detail object |
+| `setUserBy(user)` | Sets the user who initiated the action |
+
+## Creating a Custom Event
+
+```javascript
+import { BaseEvent } from '@felloh-org/lambda-wrapper';
+
+// Option 1: Use BaseEvent directly
+const event = new BaseEvent('custom:event:type');
+event.setDetailParam('data', {
+  field1: 'value1',
+  field2: 'value2'
+});
+event.setUserBy({ id: 'usr_123', email: 'user@example.com' });
+
+const payload = event.getBase();
+```
+
+## Extending BaseEvent
+
+For reusable event types, create a custom class:
+
+```javascript
+import { BaseEvent } from '@felloh-org/lambda-wrapper';
+
+class MyCustomEvent extends BaseEvent {
+  constructor() {
+    super();
+    this.setDetailType('my:custom:event');
+    this.setDetailParam('data', {});
+  }
+
+  setCustomField(value) {
+    this.base.Detail.data.custom_field = value;
+  }
+
+  setAnotherField(value) {
+    this.base.Detail.data.another_field = value;
+  }
+}
+
+export default MyCustomEvent;
+```
+
+## Sending Events
+
+All events are dispatched via the `EventBridgeService`:
+
+```javascript
+import { LambdaWrapper, DEFINITIONS, BaseEvent } from '@felloh-org/lambda-wrapper';
+
+export const handler = LambdaWrapper(configuration, async (di, request) => {
+  const eventBridge = di.get(DEFINITIONS.EVENT_BRIDGE);
+
+  const event = new BaseEvent('custom:event:type');
+  event.setDetailParam('data', { foo: 'bar' });
+
+  await eventBridge.send(event);
+});
+```
+
+## Environment Variables
+
+The BaseEvent class uses these environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `SERVICE_NAME` | Used as the event `Source` |
+| `EVENT_BRIDGE_ARN` | Used as the `EventBusName` |
+
+## Notes
+
+- The `Detail` object is automatically stringified when calling `getBase()`
+- The `Time` field is automatically set to the current timestamp on construction
+- Use specific event classes (e.g., `TransactionCustomerReceipt`) when available for better type safety and validation

package/docs/events/csv-export-link.md

@@ -0,0 +1,91 @@
+# csv:export-link Event Specification
+
+This event triggers an email containing a link to download a CSV export file.
+
+## Event Structure
+
+```json
+{
+  "source": "your-service-name",
+  "detail-type": "csv:export-link",
+  "detail": {
+    "data": {
+      "email": "user@example.com",
+      "download_url": "https://example.com/exports/file.csv",
+      "export_type": "transactions",
+      "organisation_name": "Acme Travel Ltd",
+      "file_name": "transactions-2024-01.csv"
+    },
+    "userBy": {
+      "id": "usr_abc123xyz",
+      "email": "user@example.com"
+    }
+  }
+}
+```
+
+## Field Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `data` | object | **Yes** | The export data for the email |
+| `data.email` | string | **Yes** | Recipient email address |
+| `data.download_url` | string | **Yes** | URL to download the CSV file |
+| `data.export_type` | string | No | Type of export (e.g., `transactions`, `payments`, `settlements`) |
+| `data.organisation_name` | string | No | Organisation name for the email |
+| `data.file_name` | string | No | Name of the exported file |
+| `userBy` | object | No | The user who requested the export |
+
+## Usage Example
+
+```javascript
+import { CSVEmail } from '@felloh-org/lambda-wrapper';
+
+const event = new CSVEmail();
+
+// Set the export data
+event.setDetailParam('data', {
+  email: 'user@example.com',
+  download_url: 'https://example.com/exports/file.csv',
+  export_type: 'transactions',
+  organisation_name: 'Acme Travel Ltd',
+  file_name: 'transactions-2024-01.csv'
+});
+
+// Set who requested the export
+event.setUserBy({
+  id: 'usr_abc123xyz',
+  email: 'user@example.com'
+});
+
+// Get the event payload for EventBridge
+const payload = event.getBase();
+```
+
+## Sending the Event
+
+To dispatch this event via EventBridge, use the `EventBridgeService`:
+
+```javascript
+import { LambdaWrapper, DEFINITIONS, CSVEmail } from '@felloh-org/lambda-wrapper';
+
+export const handler = LambdaWrapper(configuration, async (di, request) => {
+  const eventBridge = di.get(DEFINITIONS.EVENT_BRIDGE);
+
+  const event = new CSVEmail();
+  event.setDetailParam('data', {
+    email: 'user@example.com',
+    download_url: 'https://example.com/exports/file.csv',
+    export_type: 'transactions',
+    organisation_name: 'Acme Travel Ltd',
+    file_name: 'transactions-2024-01.csv'
+  });
+
+  await eventBridge.send(event);
+});
+```
+
+## Notes
+
+- The download URL should be a pre-signed URL or a secure link with appropriate expiration
+- The `data` object can include additional context fields as needed by the email template

package/docs/events/posc-request.md

@@ -0,0 +1,99 @@
+# posc:request Event Specification
+
+This event triggers a POSC (Payment on Statement of Credit) request notification email.
+
+## Event Structure
+
+```json
+{
+  "source": "your-service-name",
+  "detail-type": "posc:request",
+  "detail": {
+    "data": {
+      "email": "recipient@example.com",
+      "organisation_name": "Acme Travel Ltd",
+      "request_id": "posc_abc123xyz",
+      "amount": 150000,
+      "currency": "GBP",
+      "customer_name": "John Doe",
+      "booking_reference": "BOOK-12345"
+    },
+    "userBy": {
+      "id": "usr_abc123xyz",
+      "email": "agent@example.com"
+    }
+  }
+}
+```
+
+## Field Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `data` | object | **Yes** | The POSC request data |
+| `data.email` | string | **Yes** | Recipient email address |
+| `data.organisation_name` | string | **Yes** | Organisation name |
+| `data.request_id` | string | **Yes** | Unique identifier for the POSC request |
+| `data.amount` | integer | **Yes** | Request amount in minor units (e.g., pence/cents) |
+| `data.currency` | string | **Yes** | ISO 4217 currency code |
+| `data.customer_name` | string | No | Name of the customer |
+| `data.booking_reference` | string | No | Associated booking reference |
+| `userBy` | object | No | The user who initiated the request |
+
+## Usage Example
+
+```javascript
+import { POSCRequestEmail } from '@felloh-org/lambda-wrapper';
+
+const event = new POSCRequestEmail();
+
+// Set the POSC request data
+event.setDetailParam('data', {
+  email: 'recipient@example.com',
+  organisation_name: 'Acme Travel Ltd',
+  request_id: 'posc_abc123xyz',
+  amount: 150000,
+  currency: 'GBP',
+  customer_name: 'John Doe',
+  booking_reference: 'BOOK-12345'
+});
+
+// Set who initiated the request
+event.setUserBy({
+  id: 'usr_abc123xyz',
+  email: 'agent@example.com'
+});
+
+// Get the event payload for EventBridge
+const payload = event.getBase();
+```
+
+## Sending the Event
+
+To dispatch this event via EventBridge, use the `EventBridgeService`:
+
+```javascript
+import { LambdaWrapper, DEFINITIONS, POSCRequestEmail } from '@felloh-org/lambda-wrapper';
+
+export const handler = LambdaWrapper(configuration, async (di, request) => {
+  const eventBridge = di.get(DEFINITIONS.EVENT_BRIDGE);
+
+  const event = new POSCRequestEmail();
+  event.setDetailParam('data', {
+    email: 'recipient@example.com',
+    organisation_name: 'Acme Travel Ltd',
+    request_id: 'posc_abc123xyz',
+    amount: 150000,
+    currency: 'GBP',
+    customer_name: 'John Doe',
+    booking_reference: 'BOOK-12345'
+  });
+
+  await eventBridge.send(event);
+});
+```
+
+## Notes
+
+- The `amount` field should be in **minor units** (e.g., £1,500.00 = `150000` pence)
+- POSC requests are typically used for payment reminders or follow-up notifications

package/docs/events/transaction-complete-email.md

@@ -0,0 +1,91 @@
+# transaction:complete:email Event Specification
+
+This event triggers an email notification when a transaction is completed.
+
+## Event Structure
+
+```json
+{
+  "source": "your-service-name",
+  "detail-type": "transaction:complete:email",
+  "detail": {
+    "data": {
+      "transaction_id": "txn_abc123xyz",
+      "amount": 150000,
+      "currency": "GBP",
+      "customer_email": "customer@example.com",
+      "organisation_name": "Acme Travel Ltd"
+    },
+    "userBy": {
+      "id": "usr_abc123xyz",
+      "email": "agent@example.com"
+    }
+  }
+}
+```
+
+## Field Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `data` | object | **Yes** | The transaction data for the email |
+| `data.transaction_id` | string | **Yes** | Unique identifier for the transaction |
+| `data.amount` | integer | **Yes** | Transaction amount in minor units (e.g., pence/cents) |
+| `data.currency` | string | **Yes** | ISO 4217 currency code |
+| `data.customer_email` | string | **Yes** | Recipient email address |
+| `data.organisation_name` | string | **Yes** | Organisation name for the email |
+| `userBy` | object | No | The user who initiated the action |
+
+## Usage Example
+
+```javascript
+import { TransactionCompleteEmailEvent } from '@felloh-org/lambda-wrapper';
+
+const event = new TransactionCompleteEmailEvent();
+
+// Set the transaction data
+event.setDetailParam('data', {
+  transaction_id: 'txn_abc123xyz',
+  amount: 150000,
+  currency: 'GBP',
+  customer_email: 'customer@example.com',
+  organisation_name: 'Acme Travel Ltd'
+});
+
+// Optionally set who initiated the action
+event.setUserBy({
+  id: 'usr_abc123xyz',
+  email: 'agent@example.com'
+});
+
+// Get the event payload for EventBridge
+const payload = event.getBase();
+```
+
+## Sending the Event
+
+To dispatch this event via EventBridge, use the `EventBridgeService`:
+
+```javascript
+import { LambdaWrapper, DEFINITIONS, TransactionCompleteEmailEvent } from '@felloh-org/lambda-wrapper';
+
+export const handler = LambdaWrapper(configuration, async (di, request) => {
+  const eventBridge = di.get(DEFINITIONS.EVENT_BRIDGE);
+
+  const event = new TransactionCompleteEmailEvent();
+  event.setDetailParam('data', {
+    transaction_id: 'txn_abc123xyz',
+    amount: 150000,
+    currency: 'GBP',
+    customer_email: 'customer@example.com',
+    organisation_name: 'Acme Travel Ltd'
+  });
+
+  await eventBridge.send(event);
+});
+```
+
+## Notes
+
+- The `amount` field should be in **minor units** (e.g., £1,500.00 = `150000` pence)
+- The `data` object structure can be extended with additional fields as needed by the email template

package/docs/events/transaction-customer-receipt.md

@@ -0,0 +1,110 @@
+# transaction:customer:receipt Event Specification
+
+This event triggers a payment confirmation email to be sent to a customer after a successful transaction.
+
+## Event Structure
+
+```json
+{
+  "source": "your-service-name",
+  "detail-type": "transaction:customer:receipt",
+  "detail": {
+    "data": {
+      "customer_email": "customer@example.com",
+      "org_name": "Acme Travel Ltd",
+      "amount": 150000,
+      "currency_major_unit": "GBP",
+      "id": "txn_abc123xyz",
+      "method": "Card",
+      "booking_reference": "BOOK-12345",
+      "logo_url": "https://example.com/your-logo.png"
+    }
+  }
+}
+```
+
+## Field Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `customer_email` | string | **Yes** | Recipient email address |
+| `org_name` | string | **Yes** | Organisation name displayed in the email |
+| `amount` | integer | **Yes** | Transaction amount in minor units (e.g., pence/cents) |
+| `currency_major_unit` | string | **Yes** | ISO 4217 currency code (e.g., `GBP`, `EUR`, `USD`) |
+| `id` | string | **Yes** | Transaction ID displayed to the customer |
+| `method` | string | No | Payment method (e.g., `Card`, `Bank Transfer`). Omit to hide this field. |
+| `booking_reference` | string | No | Booking reference. Omit to hide this field. |
+| `logo_url` | string | No | Custom logo URL. Defaults to Felloh logo if not provided. |
+
+## Usage Example
+
+```javascript
+import { TransactionCustomerReceipt } from '@felloh-org/lambda-wrapper';
+
+const event = new TransactionCustomerReceipt();
+
+// Required fields
+event.setCustomerEmail('customer@example.com');
+event.setOrgName('Acme Travel Ltd');
+event.setAmount(150000);  // £1,500.00 in pence
+event.setCurrencyMajorUnit('GBP');
+event.setId('txn_abc123xyz');
+
+// Optional fields
+event.setMethod('Card');
+event.setBookingReference('BOOK-12345');
+event.setLogoUrl('https://example.com/your-logo.png');
+
+// Get the event payload for EventBridge
+const payload = event.getBase();
+```
+
+## Sending the Event
+
+To dispatch this event via EventBridge, use the `EventBridgeService`:
+
+```javascript
+import { LambdaWrapper, DEFINITIONS, TransactionCustomerReceipt } from '@felloh-org/lambda-wrapper';
+
+export const handler = LambdaWrapper(configuration, async (di, request) => {
+  const eventBridge = di.get(DEFINITIONS.EVENT_BRIDGE);
+
+  const event = new TransactionCustomerReceipt();
+  event.setCustomerEmail('customer@example.com');
+  event.setOrgName('Acme Travel Ltd');
+  event.setAmount(150000);
+  event.setCurrencyMajorUnit('GBP');
+  event.setId('txn_abc123xyz');
+
+  await eventBridge.send(event);
+});
+```
+
+## Usage Example
+
+```javascript
+import { TransactionCustomerReceipt } from '@felloh-org/lambda-wrapper';
+
+const event = new TransactionCustomerReceipt();
+
+// Required fields
+event.setCustomerEmail('customer@example.com');
+event.setOrgName('Acme Travel Ltd');
+event.setAmount(150000);  // £1,500.00 in pence
+event.setCurrencyMajorUnit('GBP');
+event.setId('txn_abc123xyz');
+
+// Optional fields
+event.setMethod('Card');
+event.setBookingReference('BOOK-12345');
+event.setLogoUrl('https://example.com/your-logo.png');
+
+// Get the event payload for EventBridge
+const payload = event.getBase();
+```
+
+## Notes
+
+- The `amount` field should be in **minor units** (e.g., £1,500.00 = `150000` pence)
+- The logo image should ideally be 40px in height for optimal display
+- Optional fields (`method`, `booking_reference`, `logo_url`) can be omitted entirely from the payload

package/docs/events/user-password-changed.md

@@ -0,0 +1,83 @@
+# user:password:changed Event Specification
+
+This event is triggered when a user successfully changes their password.
+
+## Event Structure
+
+```json
+{
+  "source": "your-service-name",
+  "detail-type": "user:password:changed",
+  "detail": {
+    "user": {
+      "id": "usr_abc123xyz",
+      "email": "user@example.com"
+    },
+    "userBy": {
+      "id": "usr_abc123xyz",
+      "email": "user@example.com"
+    }
+  }
+}
+```
+
+## Field Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `user` | object | **Yes** | The user whose password was changed |
+| `user.id` | string | **Yes** | Unique identifier for the user |
+| `user.email` | string | **Yes** | Email address of the user |
+| `userBy` | object | No | The user who initiated the password change |
+
+## Usage Example
+
+```javascript
+import { UserPasswordChanged } from '@felloh-org/lambda-wrapper';
+
+const event = new UserPasswordChanged();
+
+// Set the user whose password was changed
+event.setDetailParam('user', {
+  id: 'usr_abc123xyz',
+  email: 'user@example.com'
+});
+
+// Set who initiated the change (could be the user themselves or an admin)
+event.setUserBy({
+  id: 'usr_abc123xyz',
+  email: 'user@example.com'
+});
+
+// Get the event payload for EventBridge
+const payload = event.getBase();
+```
+
+## Sending the Event
+
+To dispatch this event via EventBridge, use the `EventBridgeService`:
+
+```javascript
+import { LambdaWrapper, DEFINITIONS, UserPasswordChanged } from '@felloh-org/lambda-wrapper';
+
+export const handler = LambdaWrapper(configuration, async (di, request) => {
+  const eventBridge = di.get(DEFINITIONS.EVENT_BRIDGE);
+
+  const event = new UserPasswordChanged();
+  event.setDetailParam('user', {
+    id: 'usr_abc123xyz',
+    email: 'user@example.com'
+  });
+  event.setUserBy({
+    id: 'usr_abc123xyz',
+    email: 'user@example.com'
+  });
+
+  await eventBridge.send(event);
+});
+```
+
+## Notes
+
+- This event is typically used to trigger confirmation emails or audit logging
+- The `userBy` field helps distinguish between self-service password changes and admin-initiated changes

package/docs/events/user-registration.md

@@ -0,0 +1,87 @@
+# user:registration Event Specification
+
+This event is triggered when a new user registers in the system.
+
+## Event Structure
+
+```json
+{
+  "source": "your-service-name",
+  "detail-type": "user:registration",
+  "detail": {
+    "user": {
+      "id": "usr_abc123xyz",
+      "email": "newuser@example.com",
+      "first_name": "John",
+      "last_name": "Doe"
+    },
+    "userBy": {
+      "id": "usr_admin123",
+      "email": "admin@example.com"
+    }
+  }
+}
+```
+
+## Field Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `user` | object | **Yes** | The user object containing registration details |
+| `user.id` | string | **Yes** | Unique identifier for the new user |
+| `user.email` | string | **Yes** | Email address of the new user |
+| `user.first_name` | string | No | First name of the user |
+| `user.last_name` | string | No | Last name of the user |
+| `userBy` | object | No | The user who initiated the registration (if applicable) |
+
+## Usage Example
+
+```javascript
+import { UserRegistration } from '@felloh-org/lambda-wrapper';
+
+const event = new UserRegistration();
+
+// Set the user details
+event.setDetailParam('user', {
+  id: 'usr_abc123xyz',
+  email: 'newuser@example.com',
+  first_name: 'John',
+  last_name: 'Doe'
+});
+
+// Optionally set who initiated the registration
+event.setUserBy({
+  id: 'usr_admin123',
+  email: 'admin@example.com'
+});
+
+// Get the event payload for EventBridge
+const payload = event.getBase();
+```
+
+## Sending the Event
+
+To dispatch this event via EventBridge, use the `EventBridgeService`:
+
+```javascript
+import { LambdaWrapper, DEFINITIONS, UserRegistration } from '@felloh-org/lambda-wrapper';
+
+export const handler = LambdaWrapper(configuration, async (di, request) => {
+  const eventBridge = di.get(DEFINITIONS.EVENT_BRIDGE);
+
+  const event = new UserRegistration();
+  event.setDetailParam('user', {
+    id: 'usr_abc123xyz',
+    email: 'newuser@example.com',
+    first_name: 'John',
+    last_name: 'Doe'
+  });
+
+  await eventBridge.send(event);
+});
+```
+
+## Notes
+
+- The `user` object structure can be extended with additional fields as needed
+- Use `setUserBy()` to track which user (e.g., admin) initiated the registration if applicable

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@felloh-org/lambda-wrapper",
-  "version": "1.11.192",
+  "version": "1.11.193",
   "description": "Lambda wrapper for all Felloh Serverless Projects",
   "main": "dist/index.js",
   "engines": {