Address re-review comments

Author: stevebux

internal/events/src/domain/letter.ts

@@ -76,6 +76,12 @@ The identifier will be included as the origin domain in the subject of any corre
       examples: ["1y3q9v1zzzz"],
     }),
 
+    supplierId: z.string().meta({
+      title: "Supplier ID",
+      description: "Supplier ID allocated to the letter during creation.",
+      examples: ["supplier-1"],
+    }),
+
     groupId: z.string().meta({
       title: "Group ID",
       description:

internal/events/src/events/__tests__/testData/letter.ACCEPTED-with-invalid-major-version.json

@@ -9,7 +9,8 @@
       "subject": "client/00f3b388-bbe9-41c9-9e76-052d37ee8988/letter-request/0o5Fs0EELR0fUjHjbCnEtdUwQe4_0o5Fs0EELR0fUjHjbCnEtdUwQe5"
     },
     "specificationId": "1y3q9v1zzzz",
-    "status": "ACCEPTED"
+    "status": "ACCEPTED",
+    "supplierId": "supplier1"
   },
   "datacontenttype": "application/json",
   "dataschema": "https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.ACCEPTED.0.1.0.schema.json",

internal/events/src/events/__tests__/testData/letter.ACCEPTED-with-missing-fields.json

@@ -8,7 +8,8 @@
       "source": "/data-plane/letter-rendering/prod/render-pdf"
     },
     "specificationId": "1y3q9v1zzzz",
-    "status": "ACCEPTED"
+    "status": "ACCEPTED",
+    "supplierId": "supplier1"
   },
   "datacontenttype": "application/json",
   "dataschema": "https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.ACCEPTED.1.0.0.schema.json",

internal/events/src/events/__tests__/testData/letter.ACCEPTED.json

@@ -9,7 +9,8 @@
       "subject": "client/00f3b388-bbe9-41c9-9e76-052d37ee8988/letter-request/0o5Fs0EELR0fUjHjbCnEtdUwQe4_0o5Fs0EELR0fUjHjbCnEtdUwQe5"
     },
     "specificationId": "1y3q9v1zzzz",
-    "status": "ACCEPTED"
+    "status": "ACCEPTED",
+    "supplierId": "supplier1"
   },
   "datacontenttype": "application/json",
   "dataschema": "https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.ACCEPTED.1.0.0.schema.json",

internal/events/src/events/__tests__/testData/letter.FORWARDED.json

@@ -11,7 +11,8 @@
     "reasonCode": "RNIB",
     "reasonText": "RNIB",
     "specificationId": "1y3q9v1zzzz",
-    "status": "FORWARDED"
+    "status": "FORWARDED",
+    "supplierId": "supplier1"
   },
   "datacontenttype": "application/json",
   "dataschema": "https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.FORWARDED.1.0.0.schema.json",

internal/events/src/events/__tests__/testData/letter.RETURNED.json

@@ -11,7 +11,8 @@
     "reasonCode": "R07",
     "reasonText": "No such address",
     "specificationId": "1y3q9v1zzzz",
-    "status": "RETURNED"
+    "status": "RETURNED",
+    "supplierId": "supplier1"
   },
   "datacontenttype": "application/json",
   "dataschema": "https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.RETURNED.1.0.0.schema.json",

lambdas/letter-updates-transformer/package.json

@@ -3,10 +3,12 @@
     "@aws-sdk/client-sns": "^3.943.0",
     "@aws-sdk/util-dynamodb": "^3.943.0",
     "@internal/datastore": "^0.1.0",
+    "@internal/helpers": "^0.1.0",
     "@nhsdigital/nhs-notify-event-schemas-supplier-api": "*",
     "aws-lambda": "^1.0.7",
     "esbuild": "^0.24.0",
-    "pino": "^10.1.0"
+    "pino": "^10.1.0",
+    "zod": "^4.1.13"
   },
   "devDependencies": {
     "@tsconfig/node22": "^22.0.2",

lambdas/letter-updates-transformer/src/__tests__/letter-updates-transformer.test.ts

@@ -13,6 +13,7 @@ import { Deps } from "../deps";
 import { EnvVars } from "../env";
 import mapLetterToCloudEvent from "../mappers/letter-mapper";
 import { LetterStatus } from "../../../api-handler/src/contracts/letters";
+import { LetterWithSupplierId } from "../types";
 
 // Make crypto return consistent values, since we"re calling it in both prod and test code and comparing the values
 const realCrypto = jest.requireActual("crypto");
@@ -147,7 +148,7 @@ describe("letter-updates-transformer Lambda", () => {
     it("does not publish invalid letter data", async () => {
       const handler = createHandler(mockedDeps);
       const oldLetter = generateLetter("ACCEPTED");
-      const newLetter = { id: oldLetter.id } as LetterBase;
+      const newLetter = { id: oldLetter.id } as LetterWithSupplierId;
 
       const testData = generateKinesisEvent([
         generateModifyRecord(oldLetter, newLetter),
@@ -252,27 +253,28 @@ describe("letter-updates-transformer Lambda", () => {
 });
 
 
-function generateLetter(status: LetterStatus, id?: string): LetterBase {
+function generateLetter(status: LetterStatus, id?: string): LetterWithSupplierId {
   return {
     id: id || "1",
     status,
     specificationId: "spec1",
+    supplierId: "supplier1",
     groupId: "group1",
   };
 }
 
 function generateLetters(
   numLetters: number,
   status: LetterStatus,
-): LetterBase[] {
+): LetterWithSupplierId[] {
   return [...new Array(numLetters).keys()].map((i) =>
     generateLetter(status, String(i + 1)),
   );
 }
 
 function generateModifyRecord(
-  oldLetter: LetterBase,
-  newLetter: LetterBase,
+  oldLetter: LetterWithSupplierId,
+  newLetter: LetterWithSupplierId,
 ): DynamoDBRecord {
   const oldImage = Object.fromEntries(
     Object.entries(oldLetter).map(([key, value]) => [key, { S: value }]),

lambdas/letter-updates-transformer/src/letter-updates-transformer.ts

@@ -10,9 +10,9 @@ import {
   PublishBatchRequestEntry,
 } from "@aws-sdk/client-sns";
 import { LetterEvent } from "@nhsdigital/nhs-notify-event-schemas-supplier-api/src";
-import { LetterBase, LetterSchemaBase } from "@internal/datastore";
 import mapLetterToCloudEvent from "./mappers/letter-mapper";
 import { Deps } from "./deps";
+import { LetterSchemaWithSupplierId, LetterWithSupplierId } from "./types";
 
 // SNS PublishBatchCommand supports up to 10 messages per batch
 const BATCH_SIZE = 10;
@@ -62,9 +62,9 @@ function isChanged(record: DynamoDBRecord, property: string): boolean {
   return oldValue?.S !== newValue?.S;
 }
 
-function extractNewLetter(record: DynamoDBRecord): LetterBase {
+function extractNewLetter(record: DynamoDBRecord): LetterWithSupplierId {
   const newImage = record.dynamodb?.NewImage!;
-  return LetterSchemaBase.parse(unmarshall(newImage as any));
+  return LetterSchemaWithSupplierId.parse(unmarshall(newImage as any));
 }
 
 function* generateBatches(events: LetterEvent[]) {

lambdas/letter-updates-transformer/src/mappers/__tests__/letter-mapper.test.ts

@@ -1,17 +1,18 @@
 import { $LetterEvent } from "@nhsdigital/nhs-notify-event-schemas-supplier-api/src";
-import { LetterBase } from "@internal/datastore";
+import { Letter } from "@internal/datastore";
 import mapLetterToCloudEvent from "../letter-mapper";
 
 describe("letter-mapper", () => {
   it("maps a letter to a letter event", async () => {
-    const letter: LetterBase = {
+    const letter = {
       id: "id1",
       specificationId: "spec1",
+      supplierId: "supplier1",
       groupId: "group1",
       status: "PRINTED",
       reasonCode: "R02",
       reasonText: "Reason text",
-    };
+    } as Letter;
     jest.useFakeTimers().setSystemTime(new Date("2025-11-24T15:55:18Z"));
 
     const event = mapLetterToCloudEvent(letter);
@@ -20,16 +21,17 @@ describe("letter-mapper", () => {
     $LetterEvent.parse(event);
     expect(event.type).toBe("uk.nhs.notify.supplier-api.letter.printed.v1");
     expect(event.dataschema).toBe(
-      "https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.printed.1.1.5.schema.json",
+      `https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.printed.${event.dataschemaversion}.schema.json`,
     );
-    expect(event.dataschemaversion).toBe("1.1.5");
+    expect(event.dataschemaversion).toBe("1.0.4");
     expect(event.subject).toBe("letter-origin/supplier-api/letter/id1");
     expect(event.time).toBe("2025-11-24T15:55:18.000Z");
     expect(event.recordedtime).toBe("2025-11-24T15:55:18.000Z");
     expect(event.data).toEqual({
       domainId: "id1",
       status: "PRINTED",
       specificationId: "spec1",
+      supplierId: "supplier1",
       groupId: "group1",
       reasonCode: "R02",
       reasonText: "Reason text",