CCM-12352: Bootstrap internal/events package

Author: m-houston

internal/datastore/package.json

@@ -2,6 +2,7 @@
   "dependencies": {
     "@aws-sdk/client-dynamodb": "^3.858.0",
     "@aws-sdk/lib-dynamodb": "^3.858.0",
+    "@internal/helpers": "*",
     "pino": "^9.7.0",
     "zod": "^4.0.14"
   },
@@ -18,12 +19,11 @@
     "testcontainers": "^11.4.0",
     "ts-jest": "^29.4.0",
     "ts-node": "^10.9.2",
-    "typescript": "^5.8.2",
-    "zod-mermaid": "^1.0.9"
+    "typescript": "^5.8.2"
   },
   "license": "MIT",
   "main": "src/index.ts",
-  "name": "datastore",
+  "name": "@internal/datastore",
   "private": true,
   "scripts": {
     "diagrams": "ts-node src/cli/diagrams.ts",

internal/datastore/src/cli/diagrams.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { idRef } from 'zod-mermaid';
+import { idRef } from '@internal/helpers';
 
 export const SupplerStatus = z.enum(['ENABLED', 'DISABLED']);
 

internal/datastore/src/types.md

@@ -1,6 +1,12 @@
 {
   "compilerOptions": {
-    "isolatedModules": true
+    "baseUrl": ".",
+    "isolatedModules": true,
+    "paths": {
+      "@internal/helpers": [
+        "../helpers/src"
+      ]
+    }
   },
   "extends": "@tsconfig/node22/tsconfig.json",
   "include": [

internal/datastore/src/types.ts

@@ -0,0 +1,51 @@
+# NHS Notify Schemas (Supplier API)
+
+This package contains schema definitions and type interfaces for the NHS Notify Supplier API event system.
+
+## Installation
+
+```bash
+npm install --save nhs-notify-schemas-supplier-api
+```
+
+## Usage
+
+```typescript
+import { LetterStatusSchema, LetterStatusType } from 'nhs-notify-schemas-supplier-api';
+
+// Validate an incoming event
+const result = LetterStatusSchema.safeParse(incomingData);
+if (!result.success) {
+  console.error('Invalid letter status event:', result.error);
+  return;
+}
+
+// Use the validated data with full type safety
+const letterEvent: LetterStatusType = result.data;
+console.log(`Letter ${letterEvent.letterId} status: ${letterEvent.status}`);
+```
+
+## Available Schemas
+
+- `LetterStatusSchema`: For letter status update events
+- `LetterCreatedSchema`: For letter creation events
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+npm test
+```
+
+### Generating Schema Diagrams
+
+```bash
+npm run generate-diagrams
+```

internal/datastore/tsconfig.json

@@ -0,0 +1,35 @@
+{
+  "dependencies": {
+    "@internal/helpers": "*",
+    "zod": "^4.0.14"
+  },
+  "description": "Schemas for NHS Notify Supplier API events",
+  "devDependencies": {
+    "@stylistic/eslint-plugin": "^3.1.0",
+    "@tsconfig/node22": "^22.0.2",
+    "@types/jest": "^29.5.14",
+    "@typescript-eslint/eslint-plugin": "^8.27.0",
+    "@typescript-eslint/parser": "^8.27.0",
+    "eslint": "^9.27.0",
+    "eslint-plugin-jest": "^29.0.1",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.2",
+    "zod-mermaid": "^1.0.9"
+  },
+  "license": "MIT",
+  "main": "dist/index.js",
+  "name": "nhs-notify-schemas-supplier-api",
+  "private": true,
+  "scripts": {
+    "build": "tsc",
+    "generate-diagrams": "ts-node src/cli/generateDiagrams.ts",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "jest",
+    "typecheck": "tsc --noEmit"
+  },
+  "types": "dist/index.d.ts",
+  "version": "0.1.0"
+}

internal/events/README.md

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+
+/**
+ * Status values for letters in the NHS Notify system
+ */
+export const LetterStatus = z.enum([
+  'PENDING',      // Letter is waiting to be processed
+  'PROCESSING',   // Letter is being processed
+  'PRINTED',      // Letter has been printed
+  'DISPATCHED',   // Letter has been dispatched to delivery service
+  'DELIVERED',    // Letter has been delivered
+  'FAILED',       // Letter processing failed
+]);
+
+export type LetterStatusEnum = z.infer<typeof LetterStatus>;
+
+/**
+ * Schema for letter status update events
+ */
+export const LetterStatusSchema = z.object({
+  eventType: z.literal('LETTER_STATUS_UPDATE'),
+  timestamp: z.string().datetime(),
+  letterId: z.string().uuid(),
+  groupId: z.string().optional(),
+  specificationId: z.string().optional(),
+  supplierId: z.string(),
+  status: LetterStatus,
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type LetterStatusType = z.infer<typeof LetterStatusSchema>;
+
+/**
+ * Schema for letter creation events
+ */
+export const LetterCreatedSchema = z.object({
+  eventType: z.literal('LETTER_CREATED'),
+  timestamp: z.string().datetime(),
+  letterId: z.string().uuid(),
+  groupId: z.string().optional(),
+  specificationId: z.string().optional(),
+  supplierId: z.string(),
+  contentReference: z.string(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type LetterCreatedType = z.infer<typeof LetterCreatedSchema>;

internal/events/package.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "declaration": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "outDir": "dist",
+    "paths": {
+      "@internal/helpers": [
+        "../helpers/src"
+      ]
+    },
+    "skipLibCheck": true,
+    "strict": true
+  },
+  "exclude": [
+    "node_modules",
+    "dist"
+  ],
+  "extends": "@tsconfig/node22/tsconfig.json",
+  "include": [
+    "src/**/*",
+    "jest.config.ts"
+  ]
+}

internal/events/src/schemas/letter.ts

@@ -0,0 +1,24 @@
+# Dependency directories
+node_modules/
+
+# Built output
+dist/
+
+# Coverage directory used by tools like istanbul
+coverage/
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Editor directories and files
+.idea/
+.vscode/
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?