CCM-13752 Added specificationBillingId

nhsd-david-wass · nhsd-david-wass · commit ae7cacef938c · 2026-03-11T13:42:50.000Z
diff --git a/internal/datastore/src/__test__/letter-repository.test.ts b/internal/datastore/src/__test__/letter-repository.test.ts
@@ -30,6 +30,7 @@ function createLetter(
     source: "/data-plane/letter-rendering/pdf",
     subject: `client/1/letter-request/${letterId}`,
     billingRef: "specification1",
+    specificationBillingId: "specification1",
   };
 }
 
diff --git a/internal/datastore/src/types.ts b/internal/datastore/src/types.ts
@@ -53,6 +53,7 @@ export const LetterSchema = LetterSchemaBase.extend({
   source: z.string(),
   subject: z.string(),
   billingRef: z.string(),
+  specificationBillingId: z.string(),
 }).describe("Letter");
 
 /**
diff --git a/lambdas/api-handler/src/mappers/__tests__/letter-mapper.test.ts b/lambdas/api-handler/src/mappers/__tests__/letter-mapper.test.ts
@@ -28,6 +28,7 @@ describe("letter-mapper", () => {
       ttl: 123,
       source: "/data-plane/letter-rendering/pdf",
       subject: "letter-rendering/source/letter/letter-id",
+      specificationBillingId: "billing123",
     };
 
     const result: PatchLetterResponse = mapToPatchLetterResponse(letter);
@@ -64,6 +65,7 @@ describe("letter-mapper", () => {
       reasonText: "Reason text",
       source: "/data-plane/letter-rendering/pdf",
       subject: "letter-rendering/source/letter/letter-id",
+      specificationBillingId: "billing123",
     };
 
     const result: PatchLetterResponse = mapToPatchLetterResponse(letter);
@@ -100,6 +102,7 @@ describe("letter-mapper", () => {
       ttl: 123,
       source: "/data-plane/letter-rendering/pdf",
       subject: "letter-rendering/source/letter/letter-id",
+      specificationBillingId: "billing123",
     };
 
     const result: GetLetterResponse = mapToGetLetterResponse(letter);
@@ -136,6 +139,7 @@ describe("letter-mapper", () => {
       reasonText: "Reason text",
       source: "/data-plane/letter-rendering/pdf",
       subject: "letter-rendering/source/letter/letter-id",
+      specificationBillingId: "billing123",
     };
 
     const result: GetLetterResponse = mapToGetLetterResponse(letter);
@@ -174,6 +178,7 @@ describe("letter-mapper", () => {
       reasonText: "Reason text",
       source: "/data-plane/letter-rendering/pdf",
       subject: "letter-rendering/source/letter/letter-id",
+      specificationBillingId: "billing123",
     };
 
     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
@@ -41,6 +41,7 @@ function makeLetter(id: string, status: Letter["status"]): Letter {
     reasonText: "Reason text",
     source: "/data-plane/letter-rendering/pdf",
     subject: "letter-rendering/source/letter/letter-id",
+    specificationBillingId: "billing123",
   };
 }
 
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
@@ -339,6 +339,7 @@ function generateLetter(status: LetterStatus, id?: string): Letter {
     supplierStatus: `supplier1#${status}`,
     supplierStatusSk: "2025-12-10T11:12:54Z#1",
     ttl: 1_234_567_890,
+    specificationBillingId: "billing1",
   };
 }
 
diff --git a/lambdas/supplier-allocator/src/config/__tests__/env.test.ts b/lambdas/supplier-allocator/src/config/__tests__/env.test.ts
@@ -19,7 +19,8 @@ describe("lambdaEnv", () => {
     process.env.VARIANT_MAP = `{
       "lv1": {
         "supplierId": "supplier1",
-        "specId": "spec1"
+        "specId": "spec1",
+        "billingId": "billing1"
       }
     }`;
 
@@ -31,6 +32,7 @@ describe("lambdaEnv", () => {
         lv1: {
           supplierId: "supplier1",
           specId: "spec1",
+          billingId: "billing1",
         },
       },
     });
diff --git a/lambdas/supplier-allocator/src/config/env.ts b/lambdas/supplier-allocator/src/config/env.ts
@@ -5,6 +5,7 @@ const LetterVariantSchema = z.record(
   z.object({
     supplierId: z.string(),
     specId: z.string(),
+    billingId: z.string(),
   }),
 );
 export type LetterVariant = z.infer<typeof LetterVariantSchema>;
diff --git a/lambdas/supplier-allocator/src/handler/__tests__/allocate-handler.test.ts b/lambdas/supplier-allocator/src/handler/__tests__/allocate-handler.test.ts
@@ -26,8 +26,16 @@ function makeDeps(overrides: Partial<Deps> = {}): Deps {
 
   const env = {
     VARIANT_MAP: {
-      "variant-1": { supplierId: "supplier-1", specId: "spec-1" },
-      "variant-2": { supplierId: "supplier-2", specId: "spec-2" },
+      "variant-1": {
+        supplierId: "supplier-1",
+        specId: "spec-1",
+        billingId: "billing-1",
+      },
+      "variant-2": {
+        supplierId: "supplier-2",
+        specId: "spec-2",
+        billingId: "billing-2",
+      },
     },
   };
 
@@ -87,6 +95,7 @@ function setupDefaultMocks() {
   (supplierConfig.getSupplierDetails as jest.Mock).mockResolvedValue({
     supplierId: "supplier-1",
     specId: "spec-1",
+    billingId: "billing-1",
   });
 }
 
diff --git a/lambdas/supplier-allocator/src/handler/allocate-handler.ts b/lambdas/supplier-allocator/src/handler/allocate-handler.ts
@@ -17,7 +17,7 @@ import {
 } from "../services/supplier-config";
 import { Deps } from "../config/deps";
 
-type SupplierSpec = { supplierId: string; specId: string };
+type SupplierSpec = { supplierId: string; specId: string; billingId: string };
 type PreparedEvents = LetterRequestPreparedEventV2 | LetterRequestPreparedEvent;
 
 // small envelope that must exist in all inputs
diff --git a/lambdas/update-letter-queue/src/__tests__/update-letter-queue.test.ts b/lambdas/update-letter-queue/src/__tests__/update-letter-queue.test.ts
@@ -46,6 +46,7 @@ function generateLetter(status: LetterStatus, id?: string): Letter {
     source: "test-source",
     subject: "test-subject",
     billingRef: "billing-ref-1",
+    specificationBillingId: "billing1",
   };
 }
 
diff --git a/lambdas/upsert-letter/src/handler/__tests__/upsert-handler.test.ts b/lambdas/upsert-letter/src/handler/__tests__/upsert-handler.test.ts
@@ -97,6 +97,7 @@ function createSupplierStatusChangeEventWithoutSupplier(
       billingRef: "1y3q9v1zzzz",
       status: "RETURNED",
       supplierId: "",
+      specificationBillingId: "billing1",
     },
     datacontenttype: "application/json",
     dataschema:
@@ -151,6 +152,7 @@ function createSupplierStatusChangeEvent(
       billingRef: "1y3q9v1zzzz",
       status: "RETURNED",
       supplierId: "supplier1",
+      specificationBillingId: "billing1",
     },
     datacontenttype: "application/json",
     dataschema:
@@ -211,11 +213,19 @@ describe("createUpsertLetterHandler", () => {
   test("processes all records successfully and returns no batch failures", async () => {
     const v2message = {
       letterEvent: createPreparedV2Event(),
-      supplierSpec: { supplierId: "supplier1", specId: "spec1" },
+      supplierSpec: {
+        supplierId: "supplier1",
+        specId: "spec1",
+        billingId: "billing1",
+      },
     };
     const v1message = {
       letterEvent: createPreparedV1Event(),
-      supplierSpec: { supplierId: "supplier1", specId: "spec1" },
+      supplierSpec: {
+        supplierId: "supplier1",
+        specId: "spec1",
+        billingId: "billing1",
+      },
     };
 
     const evt: SQSEvent = createSQSEvent([
@@ -249,6 +259,7 @@ describe("createUpsertLetterHandler", () => {
     expect(insertedV2Letter.status).toBe("PENDING");
     expect(insertedV2Letter.groupId).toBe("client1campaign1template1");
     expect(insertedV2Letter.source).toBe("/data-plane/letter-rendering/test");
+    expect(insertedV2Letter.specificationBillingId).toBe("billing1");
 
     const insertedV1Letter = (mockedDeps.letterRepo.putLetter as jest.Mock).mock
       .calls[1][0];
@@ -260,6 +271,7 @@ describe("createUpsertLetterHandler", () => {
     expect(insertedV1Letter.status).toBe("PENDING");
     expect(insertedV1Letter.groupId).toBe("client1campaign1template1");
     expect(insertedV1Letter.source).toBe("/data-plane/letter-rendering/test");
+    expect(insertedV1Letter.specificationBillingId).toBe("billing1");
 
     const updatedLetter = (
       mockedDeps.letterRepo.updateLetterStatus as jest.Mock
@@ -472,14 +484,22 @@ describe("createUpsertLetterHandler", () => {
         id: "7b9a03ca-342a-4150-b56b-989109c45615",
         domainId: "ok",
       }),
-      supplierSpec: { supplierId: "supplier1", specId: "spec1" },
+      supplierSpec: {
+        supplierId: "supplier1",
+        specId: "spec1",
+        billingId: "billing1",
+      },
     };
     const message2 = {
       letterEvent: createPreparedV2Event({
         id: "7b9a03ca-342a-4150-b56b-989109c45616",
         domainId: "fail",
       }),
-      supplierSpec: { supplierId: "supplier1", specId: "spec1" },
+      supplierSpec: {
+        supplierId: "supplier1",
+        specId: "spec1",
+        billingId: "billing1",
+      },
     };
     const evt: SQSEvent = createSQSEvent([
       createSqsRecord("ok-msg", JSON.stringify(message1)),
diff --git a/lambdas/upsert-letter/src/handler/upsert-handler.ts b/lambdas/upsert-letter/src/handler/upsert-handler.ts
@@ -16,12 +16,13 @@ import z from "zod";
 import { MetricsLogger, Unit, metricScope } from "aws-embedded-metrics";
 import { Deps } from "../config/deps";
 
-type SupplierSpec = { supplierId: string; specId: string };
+type SupplierSpec = { supplierId: string; specId: string; billingId: string };
 type PreparedEvents = LetterRequestPreparedEventV2 | LetterRequestPreparedEvent;
 
 const SupplierSpecSchema = z.object({
   supplierId: z.string().min(1),
   specId: z.string().min(1),
+  billingId: z.string().min(1),
 });
 
 const PreparedEventUnionSchema = z.discriminatedUnion("type", [
@@ -62,7 +63,8 @@ function getOperationFromType(type: string): UpsertOperation {
           preparedRequest,
           supplierSpec.supplierId,
           supplierSpec.specId,
-          supplierSpec.specId, // use specId for now
+          supplierSpec.specId,
+          supplierSpec.billingId, // use specId for now
         );
         await deps.letterRepo.putLetter(letterToInsert);
 
@@ -99,6 +101,7 @@ function mapToInsertLetter(
   supplier: string,
   spec: string,
   billingRef: string,
+  billingId: string,
 ): InsertLetter {
   const now = new Date().toISOString();
   return {
@@ -117,6 +120,7 @@ function mapToInsertLetter(
     createdAt: now,
     updatedAt: now,
     billingRef,
+    specificationBillingId: billingId,
   };
 }
 
@@ -235,7 +239,11 @@ export default function createUpsertLetterHandler(deps: Deps): SQSHandler {
           await runUpsert(
             operation,
             letterEvent,
-            supplierSpec ?? { supplierId: "unknown", specId: "unknown" },
+            supplierSpec ?? {
+              supplierId: "unknown",
+              specId: "unknown",
+              billingId: "unknown",
+            },
             deps,
           );
 
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
@@ -62,6 +62,7 @@ describe("Create letter helpers", () => {
       source: "/data-plane/letter-rendering/letter-test-data",
       subject: "supplier-api/letter-test-data/letterId",
       billingRef: "specificationId",
+      specificationBillingId: "specificationId",
     });
   });
 
@@ -110,6 +111,7 @@ describe("Create letter helpers", () => {
       billingRef: "specificationId",
       source: "/data-plane/letter-rendering/letter-test-data",
       subject: "supplier-api/letter-test-data/letterId",
+      specificationBillingId: "specificationId",
     });
   });
 
@@ -140,6 +142,7 @@ describe("Create letter helpers", () => {
       source: "/data-plane/letter-rendering/letter-test-data",
       subject: "supplier-api/letter-test-data/testLetterId",
       billingRef: "testSpecId",
+      specificationBillingId: "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
@@ -49,6 +49,7 @@ export async function createLetter(params: {
     source: "/data-plane/letter-rendering/letter-test-data",
     subject: `supplier-api/letter-test-data/${letterId}`,
     billingRef: specificationId,
+    specificationBillingId: specificationId,
   };
 
   const letterRecord = await letterRepository.putLetter(letter);
@@ -78,6 +79,7 @@ export function createLetterDto(params: {
     source: "/data-plane/letter-rendering/letter-test-data",
     subject: `supplier-api/letter-test-data/${letterId}`,
     billingRef: specificationId,
+    specificationBillingId: specificationId,
   };
 
   return letter;

Original file line number	Diff line number	Diff line change
`@@ -30,6 +30,7 @@ function createLetter(`
`30`	`30`	`source: "/data-plane/letter-rendering/pdf",`
`31`	`31`	subject: `client/1/letter-request/${letterId}`,
`32`	`32`	`billingRef: "specification1",`
	`33`	`+ specificationBillingId: "specification1",`
`33`	`34`	`};`
`34`	`35`	`}`
`35`	`36`
Original file line number	Diff line number	Diff line change
`@@ -41,6 +41,7 @@ function makeLetter(id: string, status: Letter["status"]): Letter {`
`41`	`41`	`reasonText: "Reason text",`
`42`	`42`	`source: "/data-plane/letter-rendering/pdf",`
`43`	`43`	`subject: "letter-rendering/source/letter/letter-id",`
	`44`	`+ specificationBillingId: "billing123",`
`44`	`45`	`};`
`45`	`46`	`}`
`46`	`47`
Original file line number	Diff line number	Diff line change
`@@ -339,6 +339,7 @@ function generateLetter(status: LetterStatus, id?: string): Letter {`
`339`	`339`	supplierStatus: `supplier1#${status}`,
`340`	`340`	`supplierStatusSk: "2025-12-10T11:12:54Z#1",`
`341`	`341`	`ttl: 1_234_567_890,`
	`342`	`+ specificationBillingId: "billing1",`
`342`	`343`	`};`
`343`	`344`	`}`
`344`	`345`
Original file line number	Diff line number	Diff line change
`@@ -46,6 +46,7 @@ function generateLetter(status: LetterStatus, id?: string): Letter {`
`46`	`46`	`source: "test-source",`
`47`	`47`	`subject: "test-subject",`
`48`	`48`	`billingRef: "billing-ref-1",`
	`49`	`+ specificationBillingId: "billing1",`
`49`	`50`	`};`
`50`	`51`	`}`
`51`	`52`