CCM-16553: Utility tool

Author: nhsd-angel-pastor

Makefile

@@ -60,6 +60,9 @@ config:: _install-dependencies version dependencies # Configure development envi
 serve-docs:
 	$(MAKE) -C docs s
 
+perf-test:
+	npm run start:nft --workspace=nft-event-generator
+
 version:
 	rm -f .version
 	make version-create-effective-file dir=.

package-lock.json

@@ -83,6 +83,7 @@
     "src/digital-letters-events",
     "src/python-schema-generator",
     "src/typescript-schema-generator",
+    "scripts/nft-event-generator",
     "tests/playwright",
     "tests/pact-tests"
   ]

package.json

@@ -101,6 +101,7 @@
       { "name": "ttl-handle-expiry-lambda", "rootPath": "lambdas/ttl-handle-expiry-lambda" },
       { "name": "ttl-poll-lambda", "rootPath": "lambdas/ttl-poll-lambda" },
       { "name": "utils", "rootPath": "utils/utils" },
+      { "name": "event-generator", "rootPath": "scripts/nft-event-generator" },
     ],
     "testing.defaultGutterClickAction": "runWithCoverage",
   },

project.code-workspace

@@ -87,6 +87,7 @@ service_sorted
 setCachedSchema
 Someobject
 src
+[Ss]ubcommand
 stderr
 Syft
 temp_dir

scripts/config/vale/styles/config/vocabularies/words/accept.txt

@@ -0,0 +1,123 @@
+# NFT Event Generator
+
+This script generates events and sends them in batches of 10 to the AWS EventBridge event bus: **`nhs-<environment>-dl`** (where `<environment>` is the environment specified at the command line).
+
+It supports two event types, each invoked as a subcommand:
+
+- **`supplier-api-letter-event`** – generates `SupplierApiLetterEvent` events (mirrors the `LetterEvent` consumed by `print-status-handler`)
+- **`paper-letter-opt-out-event`** – generates `PaperLetterOptedOut` channel status events, reading input from a CSV file
+
+## Common features
+
+- Custom environments (e.g. `pr293`, `main`, `nft`)
+- Controlled delay between batches of maximum 10 messages
+
+---
+
+## Subcommand: `supplier-api-letter-event`
+
+Generates a configurable number of supplier API letter events with dynamic or fixed field values.
+
+### CLI Options
+
+| Option               | Type   | Required | Default       | Description                                                                                                                                                                      |
+|----------------------|--------|----------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--numberOfEvents`   | number | ✅        |               | Total number of events to generate and send                                                                                                                                      |
+| `--environment`      | string | ❌        | `nft`         | Target environment (e.g. `main`, `nft`, `pr283`)                                                                                                                                |
+| `--interval`         | number | ❌        | `1000`        | Delay between batches in milliseconds                                                                                                                                            |
+| `--status`           | string | ❌        | `ACCEPTED`    | Letter status for generated events. One of: `ACCEPTED`, `REJECTED`, `PRINTED`, `DISPATCHED`, `FAILED`, `RETURNED`, `PENDING`, `ENCLOSED`, `CANCELLED`, `FORWARDED`, `DELIVERED` |
+| `--id`               | string | ❌        | *(generated)* | Fixed event `id` (uuid). If omitted, a new uuid is generated per event                                                                                                          |
+| `--time`             | string | ❌        | *(generated)* | Fixed event `time` (ISO 8601). If omitted, the current time is used per event                                                                                                   |
+| `--subject`          | string | ❌        | *(generated)* | Fixed event `subject`. If omitted, a subject is built from `messageReference`                                                                                                   |
+| `--messageReference` | string | ❌        | *(generated)* | Fixed message reference (uuid) embedded in `subject` and `data.origin.subject`. If omitted, a new uuid is generated per event                                                   |
+
+### Examples
+
+Generate 2 events in the `nft` environment with a 2-second interval between batches:
+
+```shell
+npm start -- supplier-api-letter-event --environment nft --numberOfEvents 2 --interval 2000
+```
+
+Generate events with a specific status:
+
+```shell
+npm start -- supplier-api-letter-event --environment pr293 --numberOfEvents 5 --status PRINTED
+```
+
+Generate events with a fixed `messageReference` (useful for targeting a specific letter request):
+
+```shell
+npm start -- supplier-api-letter-event --environment pr293 --numberOfEvents 1 --messageReference aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
+```
+
+---
+
+## Subcommand: `paper-letter-opt-out-event`
+
+Reads a CSV file and generates one `PaperLetterOptedOut` channel status event per row.
+
+### CSV format
+
+The CSV file must have two columns per row (no header):
+
+| Column | Description                     |
+|--------|---------------------------------|
+| 1      | `messageReference` (uuid)       |
+| 2      | `senderId`                      |
+
+Example `opt-outs.csv`:
+
+```csv
+aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee,sender-001
+11111111-2222-3333-4444-555555555555,sender-002
+```
+
+The `messageReference` field in each generated event is built as `<senderId>_<messageReference>`.
+
+### CLI Options
+
+| Option          | Type   | Required | Default       | Description                                        |
+|-----------------|--------|----------|---------------|----------------------------------------------------|
+| `--csvFile`     | string | ✅        |               | Path to the CSV file (`messageReference,senderId`) |
+| `--environment` | string | ❌        | `nft`         | Target environment (e.g. `main`, `nft`, `pr283`)   |
+| `--interval`    | number | ❌        | `1000`        | Delay between batches in milliseconds              |
+
+### Examples
+
+Send opt-out events from a CSV file to the `nft` environment:
+
+```shell
+npm start -- paper-letter-opt-out-event --environment nft --csvFile ./opt-outs.csv
+```
+
+Send to a PR environment with a custom batch interval:
+
+```shell
+npm start -- paper-letter-opt-out-event --environment pr293 --csvFile ./opt-outs.csv --interval 500
+```
+
+---
+
+## Running via Make
+
+To run this script from anywhere in the repository:
+
+```shell
+make perf-test
+```
+
+The make command runs the following script (configured in `package.json`):
+
+```shell
+"start:nft": "npm start -- supplier-api-letter-event --environment nft --numberOfEvents 2 --interval 2000"
+```
+
+## Help
+
+To see all available options for a subcommand:
+
+```shell
+npm start -- supplier-api-letter-event --help
+npm start -- paper-letter-opt-out-event --help
+```

scripts/nft-event-generator/README.md

@@ -0,0 +1,55 @@
+import type { Config } from 'jest';
+
+const config: Config = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>'],
+  testMatch: ['**/__tests__/**/*.test.ts', '**/?(*.)+(spec|test).ts'],
+  transform: {
+    '^.+\\.ts$': [
+      'ts-jest',
+      {
+        tsconfig: {
+          esModuleInterop: true,
+          allowSyntheticDefaultImports: true,
+          allowImportingTsExtensions: true,
+          module: 'commonjs',
+          target: 'ES2020',
+          moduleResolution: 'node',
+          noEmit: true,
+          typeRoots: ['../../node_modules/@types'],
+        },
+        diagnostics: {
+          ignoreCodes: [1343], // Ignore TS1343: import.meta errors
+        },
+      },
+    ],
+  },
+  modulePaths: ['<rootDir>/src'],
+  collectCoverageFrom: [
+    'src/**/*.{ts,js}',
+    '!src/**/*.d.ts',
+    '!src/**/__tests__/**',
+    '!src/**/*.test.ts',
+    '!src/**/*.spec.ts',
+    '!src/cli.ts',
+  ],
+  coverageDirectory: 'coverage',
+  coveragePathIgnorePatterns: ['/node_modules/', '/__tests__/'],
+  coverageThreshold: {
+    global: {
+      branches: 60,
+      functions: 60,
+      lines: 60,
+      statements: 60,
+    },
+  },
+  moduleFileExtensions: ['ts', 'js', 'json'],
+  moduleNameMapper: {
+    '^(.*)\\.ts$': '$1',
+  },
+  setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
+  testTimeout: 10_000,
+};
+
+export default config;

scripts/nft-event-generator/jest.config.ts

@@ -0,0 +1,5 @@
+// Suppress console output
+console.log = jest.fn();
+console.warn = jest.fn();
+console.error = jest.fn();
+console.group = jest.fn();

scripts/nft-event-generator/jest.setup.ts

@@ -0,0 +1,42 @@
+{
+  "author": "",
+  "dependencies": {
+    "@aws-sdk/client-eventbridge": "^3.914.0",
+    "@nhsdigital/nhs-notify-event-schemas-status-published": "^1.0.1",
+    "csv-parse": "^6.1.0",
+    "digital-letters-events": "^0.0.1",
+    "tsx": "^4.20.6",
+    "yargs": "^17.7.2"
+  },
+  "description": "This script generates events such LetterEvent from Supplier API and sends them to the AWS event bus: **`nhs-main-nudge-inbound-event-queue`**",
+  "devDependencies": {
+    "@jest/diff-sequences": "^30.0.1",
+    "@tsconfig/node22": "^22.0.5",
+    "@types/csv-parse": "^1.1.12",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.5.2",
+    "@types/yargs": "^17.0.33",
+    "eslint": "^9.37.0",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "exit-x": "^0.2.2",
+    "jest": "^30.2.0",
+    "jest-html-reporter": "^4.3.0",
+    "jest-mock-extended": "^4.0.0",
+    "ts-jest": "^29.4.5",
+    "typescript": "^5.9.3"
+  },
+  "keywords": [],
+  "license": "ISC",
+  "main": "index.js",
+  "name": "nft-event-generator",
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "start": "tsx src/cli.ts",
+    "start:nft": "npm start -- --environment nft --numberOfEvents 2 --interval 2000",
+    "test:unit": "jest",
+    "typecheck": "tsc --noEmit"
+  },
+  "type": "commonjs",
+  "version": "1.0.0"
+}

scripts/nft-event-generator/package.json

@@ -0,0 +1,90 @@
+import {
+  PutEventsCommand,
+  PutEventsResultEntry,
+} from '@aws-sdk/client-eventbridge';
+import { sampleSupplierApiLetterEvent } from '__tests__/fixtures/sample-supplier-api-letter-event';
+import { PublishableEvent } from 'destinations/destination-client';
+import { mock } from 'jest-mock-extended';
+import { sendEventsToEventBus } from 'destinations/send-events-to-event-bus';
+
+const environment = 'dev';
+
+const mockEventBridgeClient = { send: jest.fn() };
+jest.mock('@aws-sdk/client-eventbridge', () => {
+  const originalModule = jest.requireActual('@aws-sdk/client-eventbridge');
+
+  return {
+    __esModule: true,
+    ...originalModule,
+    EventBridgeClient: jest.fn(() => mockEventBridgeClient),
+  };
+});
+
+const successEntry = mock<PutEventsResultEntry>({ ErrorCode: undefined });
+const successfulSendResponse = { Entries: [successEntry] };
+
+describe('sendEventsToEventBus', () => {
+  beforeEach(() => {
+    mockEventBridgeClient.send.mockReset();
+  });
+
+  it('should send the expected request to EventBridge', async () => {
+    mockEventBridgeClient.send.mockResolvedValue(successfulSendResponse);
+
+    await sendEventsToEventBus(environment, [sampleSupplierApiLetterEvent], 5);
+
+    expect(mockEventBridgeClient.send).toHaveBeenCalled();
+    const putEventsCommand: PutEventsCommand =
+      mockEventBridgeClient.send.mock.calls[0][0];
+
+    expect(putEventsCommand.input.Entries).toHaveLength(1);
+    const entry = putEventsCommand.input.Entries![0];
+    expect(entry.EventBusName).toBe(`nhs-${environment}-dl`);
+    expect(entry.Source).toBe(sampleSupplierApiLetterEvent.source);
+    expect(entry.DetailType).toBe(sampleSupplierApiLetterEvent.type);
+    expect(entry.Detail).toBe(JSON.stringify(sampleSupplierApiLetterEvent));
+  });
+
+  it('should send a request for each batch of messages', async () => {
+    const events: PublishableEvent[] = Array.from(
+      { length: 52 },
+      () => sampleSupplierApiLetterEvent,
+    );
+    mockEventBridgeClient.send.mockResolvedValue(successfulSendResponse);
+
+    await sendEventsToEventBus(environment, events, 5);
+
+    // Batch size is 10, so 52 events = 6 batches.
+    expect(mockEventBridgeClient.send).toHaveBeenCalledTimes(6);
+  });
+
+  it('should continue sending batches if an error is raised', async () => {
+    mockEventBridgeClient.send.mockRejectedValueOnce(
+      new Error('Something went wrong!'),
+    );
+    mockEventBridgeClient.send.mockResolvedValue(successfulSendResponse);
+
+    const events: PublishableEvent[] = Array.from(
+      { length: 30 },
+      () => sampleSupplierApiLetterEvent,
+    );
+
+    await sendEventsToEventBus(environment, events, 5);
+
+    // Batch size is 10, so 30 events = 3 batches.
+    expect(mockEventBridgeClient.send).toHaveBeenCalledTimes(3);
+  });
+
+  it('should warn when some events fail to publish', async () => {
+    const failedEntry = mock<PutEventsResultEntry>({
+      ErrorCode: 'InternalFailure',
+    });
+    mockEventBridgeClient.send.mockResolvedValue({
+      Entries: [failedEntry],
+    });
+
+    await sendEventsToEventBus(environment, [sampleSupplierApiLetterEvent], 5);
+
+    expect(console.warn).toHaveBeenCalled();
+  });
+});