add to cloudevents

Author: nhsd-david-wass

internal/events/package.json

@@ -37,5 +37,5 @@
     "typecheck": "tsc --noEmit"
   },
   "types": "dist/index.d.ts",
-  "version": "1.0.13"
+  "version": "1.0.14"
 }

internal/events/src/domain/letter.ts

@@ -83,6 +83,13 @@ The identifier will be included as the origin domain in the subject of any corre
       examples: ["1y3q9v1zzzz"],
     }),
 
+    specificationBillingId: z.string().meta({
+      title: "Specification Billing ID",
+      description:
+        "The billing ID from the letter specification which was used to produce a letter pack for this request.",
+      examples: ["1y3q9v1zzzz"],
+    }),
+
     supplierId: z.string().meta({
       title: "Supplier ID",
       description: "Supplier ID allocated to the letter during creation.",

internal/events/src/events/__tests__/letter-mapper.test.ts

@@ -16,6 +16,7 @@ describe("letter-mapper", () => {
       updatedAt: "2025-11-24T15:55:18.000Z",
       source: "letter-rendering/source/test",
       subject: "letter-rendering/source/letter/letter-id",
+      specificationBillingId: "billing123",
     } as Letter;
     const source = "/data-plane/supplier-api/nhs-supplier-api-dev/main/letters";
     const event = mapLetterToCloudEvent(letter, source);
@@ -35,6 +36,7 @@ describe("letter-mapper", () => {
       status: "PRINTED",
       specificationId: "spec1",
       billingRef: "spec1",
+      specificationBillingId: "billing123",
       supplierId: "supplier1",
       groupId: "group1",
       reasonCode: "R02",

internal/events/src/events/__tests__/letter-status-change-events.test.ts

@@ -40,6 +40,7 @@ describe("LetterStatus event validations", () => {
             billingRef: "1y3q9v1zzzz",
             groupId: "client_template",
             status,
+            specificationBillingId: "billing123",
           }),
         }),
       );

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

@@ -9,6 +9,7 @@
       "source": "/data-plane/letter-rendering/prod/render-pdf",
       "subject": "client/00f3b388-bbe9-41c9-9e76-052d37ee8988/letter-request/0o5Fs0EELR0fUjHjbCnEtdUwQe4_0o5Fs0EELR0fUjHjbCnEtdUwQe5"
     },
+    "specificationBillingId": "billing123",
     "specificationId": "1y3q9v1zzzz",
     "status": "ACCEPTED",
     "supplierId": "supplier1"

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

@@ -8,6 +8,7 @@
       "event": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
       "source": "/data-plane/letter-rendering/prod/render-pdf"
     },
+    "specificationBillingId": "billing123",
     "specificationId": "1y3q9v1zzzz",
     "status": "ACCEPTED",
     "supplierId": "supplier1"

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

@@ -9,6 +9,7 @@
       "source": "/data-plane/letter-rendering/prod/render-pdf",
       "subject": "client/00f3b388-bbe9-41c9-9e76-052d37ee8988/letter-request/0o5Fs0EELR0fUjHjbCnEtdUwQe4_0o5Fs0EELR0fUjHjbCnEtdUwQe5"
     },
+    "specificationBillingId": "billing123",
     "specificationId": "1y3q9v1zzzz",
     "status": "ACCEPTED",
     "supplierId": "supplier1"

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

@@ -11,6 +11,7 @@
     },
     "reasonCode": "RNIB",
     "reasonText": "RNIB",
+    "specificationBillingId": "billing123",
     "specificationId": "1y3q9v1zzzz",
     "status": "FORWARDED",
     "supplierId": "supplier1"

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

@@ -11,6 +11,7 @@
     },
     "reasonCode": "R07",
     "reasonText": "No such address",
+    "specificationBillingId": "billing123",
     "specificationId": "1y3q9v1zzzz",
     "status": "RETURNED",
     "supplierId": "supplier1"

internal/events/src/events/letter-mapper.ts

@@ -25,6 +25,7 @@ export function mapLetterToCloudEvent(
       status: letter.status,
       specificationId: letter.specificationId,
       billingRef: letter.billingRef,
+      specificationBillingId: letter.specificationBillingId,
       supplierId: letter.supplierId,
       groupId: letter.groupId,
       reasonCode: letter.reasonCode,