store changes and source, subject, billingref

masl2 · masl2 · commit 2a92c2ffd0d4 · 2025-12-24T10:27:07.000Z
diff --git a/internal/datastore/src/__test__/letter-repository.test.ts b/internal/datastore/src/__test__/letter-repository.test.ts
@@ -27,6 +27,7 @@ function createLetter(
     updatedAt: now,
     source: "/data-plane/letter-rendering/pdf",
     subject: `client/1/letter-request/${letterId}`,
+    billingRef: "specification1",
   };
 }
 
@@ -112,6 +113,7 @@ describe("LetterRepository", () => {
     expect(letter.reasonCode).toBeUndefined();
     expect(letter.reasonText).toBeUndefined();
     expect(letter.subject).toBe(`client/1/letter-request/${letterId}`);
+    expect(letter.billingRef).toBe("specification1");
     assertTtl(letter.ttl, before, after);
   });
 
diff --git a/internal/datastore/src/types.ts b/internal/datastore/src/types.ts
@@ -50,6 +50,7 @@ export const LetterSchema = LetterSchemaBase.extend({
   ttl: z.int(),
   source: z.string(),
   subject: z.string(),
+  billingRef: z.string(),
 }).describe("Letter");
 
 /**
diff --git a/internal/events/package.json b/internal/events/package.json
@@ -50,5 +50,5 @@
     "typecheck": "tsc --noEmit"
   },
   "types": "dist/index.d.ts",
-  "version": "1.0.5"
+  "version": "1.0.6"
 }
diff --git a/internal/events/schemas/examples/letter.ACCEPTED.json b/internal/events/schemas/examples/letter.ACCEPTED.json
@@ -1,5 +1,6 @@
 {
   "data": {
+    "billingRef": "1y3q9v1zzzz",
     "domainId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
     "groupId": "client_template",
     "origin": {
diff --git a/internal/events/schemas/examples/letter.FORWARDED.json b/internal/events/schemas/examples/letter.FORWARDED.json
@@ -1,5 +1,6 @@
 {
   "data": {
+    "billingRef": "1y3q9v1zzzz",
     "domainId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
     "groupId": "client_template",
     "origin": {
diff --git a/internal/events/schemas/examples/letter.RETURNED.json b/internal/events/schemas/examples/letter.RETURNED.json
@@ -1,5 +1,6 @@
 {
   "data": {
+    "billingRef": "1y3q9v1zzzz",
     "domainId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
     "groupId": "client_template",
     "origin": {
diff --git a/internal/events/src/domain/letter.ts b/internal/events/src/domain/letter.ts
@@ -76,6 +76,13 @@ The identifier will be included as the origin domain in the subject of any corre
       examples: ["1y3q9v1zzzz"],
     }),
 
+    billingRef: z.string().meta({
+      title: "Billing Reference",
+      description:
+        "A billing reference determined for this letter based on its specification",
+      examples: ["1y3q9v1zzzz"],
+    }),
+
     supplierId: z.string().meta({
       title: "Supplier ID",
       description: "Supplier ID allocated to the letter during creation.",
diff --git a/internal/events/src/events/__tests__/letter-status-change-events.test.ts b/internal/events/src/events/__tests__/letter-status-change-events.test.ts
@@ -37,6 +37,7 @@ describe("LetterStatus event validations", () => {
             }),
             domainId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
             specificationId: "1y3q9v1zzzz",
+            billingRef: "1y3q9v1zzzz",
             groupId: "client_template",
             status,
           }),
diff --git a/internal/events/src/events/__tests__/testData/letter.ACCEPTED-with-invalid-major-version.json b/internal/events/src/events/__tests__/testData/letter.ACCEPTED-with-invalid-major-version.json
@@ -1,5 +1,6 @@
 {
   "data": {
+    "billingRef": "1y3q9v1zzzz",
     "domainId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
     "groupId": "client_template",
     "origin": {
diff --git a/internal/events/src/events/__tests__/testData/letter.ACCEPTED-with-missing-fields.json b/internal/events/src/events/__tests__/testData/letter.ACCEPTED-with-missing-fields.json
@@ -1,5 +1,6 @@
 {
   "data": {
+    "billingRef": "1y3q9v1zzzz",
     "domainId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
     "groupId": "client_template",
     "origin": {
diff --git a/internal/events/src/events/__tests__/testData/letter.ACCEPTED.json b/internal/events/src/events/__tests__/testData/letter.ACCEPTED.json
@@ -1,5 +1,6 @@
 {
   "data": {
+    "billingRef": "1y3q9v1zzzz",
     "domainId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
     "groupId": "client_template",
     "origin": {
diff --git a/internal/events/src/events/__tests__/testData/letter.FORWARDED.json b/internal/events/src/events/__tests__/testData/letter.FORWARDED.json
@@ -1,5 +1,6 @@
 {
   "data": {
+    "billingRef": "1y3q9v1zzzz",
     "domainId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
     "groupId": "client_template",
     "origin": {
diff --git a/internal/events/src/events/__tests__/testData/letter.RETURNED.json b/internal/events/src/events/__tests__/testData/letter.RETURNED.json
@@ -1,5 +1,6 @@
 {
   "data": {
+    "billingRef": "1y3q9v1zzzz",
     "domainId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
     "groupId": "client_template",
     "origin": {
diff --git a/lambdas/api-handler/src/mappers/__tests__/letter-mapper.test.ts b/lambdas/api-handler/src/mappers/__tests__/letter-mapper.test.ts
@@ -18,6 +18,7 @@ describe("letter-mapper", () => {
       status: "PENDING",
       supplierId: "supplier1",
       specificationId: "spec123",
+      billingRef: "spec123",
       groupId: "group123",
       url: "https://example.com/letter/abc123",
       createdAt: date,
@@ -26,6 +27,7 @@ describe("letter-mapper", () => {
       supplierStatusSk: date,
       ttl: 123,
       source: "/data-plane/letter-rendering/pdf",
+      subject: "letter-rendering/source/letter/letter-id",
     };
 
     const result: PatchLetterResponse = mapToPatchLetterResponse(letter);
@@ -50,6 +52,7 @@ describe("letter-mapper", () => {
       status: "PENDING",
       supplierId: "supplier1",
       specificationId: "spec123",
+      billingRef: "spec123",
       groupId: "group123",
       url: "https://example.com/letter/abc123",
       createdAt: date,
@@ -60,6 +63,7 @@ describe("letter-mapper", () => {
       reasonCode: "R01",
       reasonText: "Reason text",
       source: "/data-plane/letter-rendering/pdf",
+      subject: "letter-rendering/source/letter/letter-id",
     };
 
     const result: PatchLetterResponse = mapToPatchLetterResponse(letter);
@@ -86,6 +90,7 @@ describe("letter-mapper", () => {
       status: "PENDING",
       supplierId: "supplier1",
       specificationId: "spec123",
+      billingRef: "spec123",
       groupId: "group123",
       url: "https://example.com/letter/abc123",
       createdAt: date,
@@ -94,6 +99,7 @@ describe("letter-mapper", () => {
       supplierStatusSk: date,
       ttl: 123,
       source: "/data-plane/letter-rendering/pdf",
+      subject: "letter-rendering/source/letter/letter-id",
     };
 
     const result: GetLetterResponse = mapToGetLetterResponse(letter);
@@ -118,6 +124,7 @@ describe("letter-mapper", () => {
       status: "PENDING",
       supplierId: "supplier1",
       specificationId: "spec123",
+      billingRef: "spec123",
       groupId: "group123",
       url: "https://example.com/letter/abc123",
       createdAt: date,
@@ -128,6 +135,7 @@ describe("letter-mapper", () => {
       reasonCode: "R01",
       reasonText: "Reason text",
       source: "/data-plane/letter-rendering/pdf",
+      subject: "letter-rendering/source/letter/letter-id",
     };
 
     const result: GetLetterResponse = mapToGetLetterResponse(letter);
@@ -154,6 +162,7 @@ describe("letter-mapper", () => {
       status: "PENDING",
       supplierId: "supplier1",
       specificationId: "spec123",
+      billingRef: "spec123",
       groupId: "group123",
       url: "https://example.com/letter/abc123",
       createdAt: date,
@@ -164,6 +173,7 @@ describe("letter-mapper", () => {
       reasonCode: "R01",
       reasonText: "Reason text",
       source: "/data-plane/letter-rendering/pdf",
+      subject: "letter-rendering/source/letter/letter-id",
     };
 
     const result: GetLettersResponse = mapToGetLettersResponse([
diff --git a/lambdas/api-handler/src/services/__tests__/letter-operations.test.ts b/lambdas/api-handler/src/services/__tests__/letter-operations.test.ts
@@ -29,6 +29,7 @@ function makeLetter(id: string, status: Letter["status"]): Letter {
     status,
     supplierId: "supplier1",
     specificationId: "spec123",
+    billingRef: "spec123",
     groupId: "group123",
     url: `s3://letterDataBucket/${id}.pdf`,
     createdAt: new Date().toISOString(),
@@ -39,6 +40,7 @@ function makeLetter(id: string, status: Letter["status"]): Letter {
     reasonCode: "R01",
     reasonText: "Reason text",
     source: "/data-plane/letter-rendering/pdf",
+    subject: "letter-rendering/source/letter/letter-id",
   };
 }
 
diff --git a/lambdas/letter-updates-transformer/src/__tests__/letter-updates-transformer.test.ts b/lambdas/letter-updates-transformer/src/__tests__/letter-updates-transformer.test.ts
@@ -257,9 +257,14 @@ function generateLetter(status: LetterStatus, id?: string): LetterForEventPub {
     id: id || "1",
     status,
     specificationId: "spec1",
+    billingRef: "spec1",
     supplierId: "supplier1",
     groupId: "group1",
+    createdAt: "2025-12-10T11:12:54Z",
     updatedAt: "2025-12-10T11:13:54Z",
+    url: "https://example.com/letter.pdf",
+    source: "test-source",
+    subject: "test-source/subject-id",
   };
 }
 
diff --git a/lambdas/letter-updates-transformer/src/mappers/__tests__/letter-mapper.test.ts b/lambdas/letter-updates-transformer/src/mappers/__tests__/letter-mapper.test.ts
@@ -7,12 +7,15 @@ describe("letter-mapper", () => {
     const letter = {
       id: "id1",
       specificationId: "spec1",
+      billingRef: "spec1",
       supplierId: "supplier1",
       groupId: "group1",
       status: "PRINTED",
       reasonCode: "R02",
       reasonText: "Reason text",
       updatedAt: "2025-11-24T15:55:18.000Z",
+      source: "letter-rendering/source/test",
+      subject: "letter-rendering/source/letter/letter-id",
     } as Letter;
     const event = mapLetterToCloudEvent(letter);
 
@@ -22,22 +25,23 @@ describe("letter-mapper", () => {
     expect(event.dataschema).toBe(
       `https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.PRINTED.${event.dataschemaversion}.schema.json`,
     );
-    expect(event.dataschemaversion).toBe("1.0.5");
+    expect(event.dataschemaversion).toBe("1.0.6");
     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",
+      billingRef: "spec1",
       supplierId: "supplier1",
       groupId: "group1",
       reasonCode: "R02",
       reasonText: "Reason text",
       origin: {
         domain: "supplier-api",
-        source: "/data-plane/supplier-api/letters",
-        subject: "letter-origin/supplier-api/letter/id1",
+        source: "letter-rendering/source/test",
+        subject: "letter-rendering/source/letter/letter-id",
         event: event.id,
       },
     });
diff --git a/lambdas/letter-updates-transformer/src/mappers/letter-mapper.ts b/lambdas/letter-updates-transformer/src/mappers/letter-mapper.ts
@@ -22,14 +22,15 @@ export default function mapLetterToCloudEvent(
       domainId: letter.id as LetterEvent["data"]["domainId"],
       status: letter.status,
       specificationId: letter.specificationId,
+      billingRef: letter.billingRef,
       supplierId: letter.supplierId,
       groupId: letter.groupId,
       reasonCode: letter.reasonCode,
       reasonText: letter.reasonText,
       origin: {
         domain: "supplier-api",
-        source: "/data-plane/supplier-api/letters",
-        subject: `letter-origin/supplier-api/letter/${letter.id}`,
+        source: letter.source,
+        subject: letter.subject,
         event: eventId,
       },
     },
diff --git a/lambdas/letter-updates-transformer/src/types.ts b/lambdas/letter-updates-transformer/src/types.ts
@@ -1,10 +1,10 @@
-import { LetterSchemaBase, SupplierSchema } from "@internal/datastore";
-import { idRef } from "@internal/helpers";
+import { LetterSchema } from "@internal/datastore";
 import { z } from "zod";
 
-export const LetterSchemaForEventPub = LetterSchemaBase.extend({
-  supplierId: idRef(SupplierSchema, "id"),
-  updatedAt: z.string(),
+export const LetterSchemaForEventPub = LetterSchema.omit({
+  supplierStatus: true,
+  supplierStatusSk: true,
+  ttl: true,
 });
 
 export type LetterForEventPub = z.infer<typeof LetterSchemaForEventPub>;
diff --git a/lambdas/upsert-letter/src/handler/__tests__/upsert-handler.test.ts b/lambdas/upsert-letter/src/handler/__tests__/upsert-handler.test.ts
@@ -122,6 +122,7 @@ function createSupplierStatusChangeEvent(
       reasonCode: "R07",
       reasonText: "No such address",
       specificationId: "1y3q9v1zzzz",
+      billingRef: "1y3q9v1zzzz",
       status: "RETURNED",
       supplierId: "supplier1",
     },
diff --git a/lambdas/upsert-letter/src/handler/upsert-handler.ts b/lambdas/upsert-letter/src/handler/upsert-handler.ts
@@ -47,6 +47,7 @@ function getOperationFromType(type: string): UpsertOperation {
           preparedRequest,
           supplierSpec.supplierId,
           supplierSpec.specId,
+          supplierSpec.specId, //use specId for now
         );
         await deps.letterRepo.putLetter(letterToInsert);
       },
@@ -68,6 +69,7 @@ function mapToInsertLetter(
   upsertRequest: PreparedEvents,
   supplier: string,
   spec: string,
+  billingRef: string,
 ): InsertLetter {
   const now = new Date().toISOString();
   return {
@@ -84,6 +86,7 @@ function mapToInsertLetter(
     subject: upsertRequest.subject,
     createdAt: now,
     updatedAt: now,
+    billingRef: billingRef,
   };
 }
 
diff --git a/scripts/utilities/letter-test-data/src/__test__/helpers/create_letter_helpers.test.ts b/scripts/utilities/letter-test-data/src/__test__/helpers/create_letter_helpers.test.ts
@@ -55,6 +55,8 @@ describe("Create letter helpers", () => {
       updatedAt: "2020-02-01T00:00:00.000Z",
       url: "s3://bucketName/supplierId/targetFilename",
       source: "/data-plane/letter-rendering/letter-test-data",
+      subject: "supplier-api/letter-test-data/letterId",
+      billingRef: "specificationId"
     });
   });
 
@@ -83,6 +85,8 @@ describe("Create letter helpers", () => {
       createdAt: "2020-02-01T00:00:00.000Z",
       updatedAt: "2020-02-01T00:00:00.000Z",
       source: "/data-plane/letter-rendering/letter-test-data",
+      subject: "supplier-api/letter-test-data/testLetterId",
+      billingRef: "testSpecId"
     });
   });
 });
diff --git a/scripts/utilities/letter-test-data/src/helpers/create_letter_helpers.ts b/scripts/utilities/letter-test-data/src/helpers/create_letter_helpers.ts
@@ -43,6 +43,8 @@ export async function createLetter(params: {
     createdAt: new Date().toISOString(),
     updatedAt: new Date().toISOString(),
     source: "/data-plane/letter-rendering/letter-test-data",
+    subject: `supplier-api/letter-test-data/${letterId}`,
+    billingRef: specificationId
   };
 
   const letterRecord = await letterRepository.putLetter(letter);
@@ -76,6 +78,8 @@ export function createLetterDto(params: {
     createdAt: new Date().toISOString(),
     updatedAt: new Date().toISOString(),
     source: "/data-plane/letter-rendering/letter-test-data",
+    subject: `supplier-api/letter-test-data/${letterId}`,
+    billingRef: specificationId
   };
 
   return letter;

Original file line number	Diff line number	Diff line change
`@@ -50,5 +50,5 @@`
`50`	`50`	`"typecheck": "tsc --noEmit"`
`51`	`51`	`},`
`52`	`52`	`"types": "dist/index.d.ts",`
`53`		`- "version": "1.0.5"`
	`53`	`+ "version": "1.0.6"`
`54`	`54`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"data": {`
	`3`	`+ "billingRef": "1y3q9v1zzzz",`
`3`	`4`	`"domainId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",`
`4`	`5`	`"groupId": "client_template",`
`5`	`6`	`"origin": {`