@felloh-org/lambda-wrapper 1.11.192 → 1.11.194

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