Merge remote-tracking branch 'origin/main' into feature/CCM-14318

francisco-videira-nhs · francisco-videira-nhs · commit c727ab481ff9 · 2026-03-29T23:29:47.000Z
diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-1.1.5-${yyyy}${mm}${dd}.${HH}${MM}${SS}+${hash}
+1.1.6-${yyyy}${mm}${dd}.${HH}${MM}${SS}+${hash}
diff --git a/internal/datastore/src/__test__/letter-repository.test.ts b/internal/datastore/src/__test__/letter-repository.test.ts
@@ -9,6 +9,7 @@ import {
 import { LetterRepository } from "../letter-repository";
 import { InsertLetter, Letter, UpdateLetter } from "../types";
 import { LogStream, createTestLogger } from "./logs";
+import { LetterAlreadyExistsError } from "../letter-already-exists-error";
 
 function createLetter(
   supplierId: string,
@@ -149,9 +150,7 @@ describe("LetterRepository", () => {
     await letterRepository.putLetter(createLetter("supplier1", "letter1"));
     await expect(
       letterRepository.putLetter(createLetter("supplier1", "letter1")),
-    ).rejects.toThrow(
-      "Letter with id letter1 already exists for supplier supplier1",
-    );
+    ).rejects.toThrow(LetterAlreadyExistsError);
   });
 
   test("rethrows errors from DynamoDB when creating a letter", async () => {
diff --git a/internal/datastore/src/letter-repository.ts b/internal/datastore/src/letter-repository.ts
@@ -19,6 +19,7 @@ import {
   UpdateLetter,
 } from "./types";
 import LetterNotFoundError from "./errors/letter-not-found-error";
+import LetterAlreadyExistsError from "./errors/letter-already-exists-error";
 
 export type PagingOptions = Partial<{
   exclusiveStartKey: Record<string, any>;
@@ -63,9 +64,7 @@ export class LetterRepository {
         error instanceof Error &&
         error.name === "ConditionalCheckFailedException"
       ) {
-        throw new Error(
-          `Letter with id ${letter.id} already exists for supplier ${letter.supplierId}`,
-        );
+        throw new LetterAlreadyExistsError(letter.supplierId, letter.id);
       }
       throw error;
     }
diff --git a/internal/event-builders/README.md b/internal/event-builders/README.md
@@ -0,0 +1,7 @@
+# @internal/event-builders
+
+Helper utilities to produce supplier api event types.
+
+This package contains functions for constructing CloudEvent-compliant event payloads and related helpers.
+
+Independent package to allow for type imports across the project without circular dependencies.
diff --git a/internal/event-builders/jest.config.ts b/internal/event-builders/jest.config.ts
@@ -0,0 +1,14 @@
+export default {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  testMatch: [
+    "**/src/__tests__/**/*.ts?(x)",
+    "**/src/?(*.)+(spec|test).ts?(x)",
+  ],
+  collectCoverageFrom: ["src/**/*.ts"],
+  coveragePathIgnorePatterns: ["/node_modules/", "__tests__"],
+  testPathIgnorePatterns: ["/node_modules/", "/dist/"],
+  transform: {
+    "^.+\\.tsx?$": ["ts-jest", {}],
+  },
+};
diff --git a/internal/event-builders/package.json b/internal/event-builders/package.json
@@ -0,0 +1,19 @@
+{
+  "dependencies": {
+    "@internal/datastore": "*",
+    "@nhsdigital/nhs-notify-event-schemas-supplier-api": "*"
+  },
+  "devDependencies": {},
+  "main": "dist/index.js",
+  "name": "@internal/event-builders",
+  "private": true,
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test:unit": "jest",
+    "typecheck": "tsc --noEmit"
+  },
+  "types": "dist/index.d.ts",
+  "version": "1.0.0"
+}
diff --git a/internal/event-builders/src/__tests__/letter-mapper.test.ts b/internal/event-builders/src/__tests__/letter-mapper.test.ts
@@ -1,6 +1,6 @@
 import { $LetterEvent } from "@nhsdigital/nhs-notify-event-schemas-supplier-api/src";
 import { Letter } from "@internal/datastore";
-import { mapLetterToCloudEvent } from "@nhsdigital/nhs-notify-event-schemas-supplier-api/src/events/letter-mapper";
+import { mapLetterToCloudEvent } from "../letter-mapper";
 
 describe("letter-mapper", () => {
   it("maps a letter to a letter event", async () => {
diff --git a/internal/event-builders/src/index.ts b/internal/event-builders/src/index.ts
@@ -0,0 +1,2 @@
+// Export event builder utilities
+export * from "./letter-mapper";
diff --git a/internal/event-builders/src/letter-mapper.ts b/internal/event-builders/src/letter-mapper.ts
@@ -1,7 +1,7 @@
 import { randomBytes, randomUUID } from "node:crypto";
 import eventSchemaPackage from "@nhsdigital/nhs-notify-event-schemas-supplier-api/package.json";
 import { Letter } from "@internal/datastore";
-import { LetterEvent } from "./letter-events";
+import { LetterEvent } from "@nhsdigital/nhs-notify-event-schemas-supplier-api/src/events/letter-events";
 
 // eslint-disable-next-line import-x/prefer-default-export
 export function mapLetterToCloudEvent(
diff --git a/internal/event-builders/tsconfig.json b/internal/event-builders/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "declaration": true
+  },
+  "exclude": [
+    "node_modules",
+    "dist"
+  ],
+  "extends": "../../tsconfig.base.json",
+  "include": [
+    "src/**/*",
+    "jest.config.ts"
+  ]
+}
diff --git a/internal/events/package.json b/internal/events/package.json
@@ -1,7 +1,6 @@
 {
   "dependencies": {
     "@asyncapi/bundler": "^0.6.4",
-    "@internal/datastore": "*",
     "zod": "^4.1.11"
   },
   "description": "Schemas for NHS Notify Supplier API events",
@@ -37,5 +36,5 @@
     "typecheck": "tsc --noEmit"
   },
   "types": "dist/index.d.ts",
-  "version": "1.0.16"
+  "version": "1.0.17"
 }
diff --git a/internal/events/src/index.ts b/internal/events/src/index.ts
@@ -4,5 +4,4 @@ export { default as DomainBase } from "./domain/domain-base";
 export * from "./events/event-envelope";
 export * from "./events/letter-events";
 export * from "./events/mi-events";
-export * from "./events/letter-mapper";
 export * from "./version";
diff --git a/internal/helpers/package.json b/internal/helpers/package.json
@@ -1,5 +1,6 @@
 {
   "dependencies": {
+    "@nhsdigital/nhs-notify-event-schemas-supplier-api": "*",
     "aws-embedded-metrics": "^4.2.1",
     "pino": "^10.3.0",
     "zod": "^4.1.11"
diff --git a/lambdas/api-handler/package.json b/lambdas/api-handler/package.json
@@ -7,6 +7,7 @@
     "@aws-sdk/lib-dynamodb": "^3.1008.0",
     "@aws-sdk/s3-request-presigner": "^3.925.0",
     "@internal/datastore": "*",
+    "@internal/event-builders": "*",
     "@internal/helpers": "*",
     "@nhsdigital/nhs-notify-event-schemas-supplier-api": "*",
     "aws-embedded-metrics": "^4.2.1",
diff --git a/lambdas/api-handler/src/handlers/__tests__/amendment-event-transformer.test.ts b/lambdas/api-handler/src/handlers/__tests__/amendment-event-transformer.test.ts
@@ -2,7 +2,7 @@ import { Context, SQSEvent, SQSRecord } from "aws-lambda";
 import { mockDeep } from "jest-mock-extended";
 import pino from "pino";
 import { SNSClient } from "@aws-sdk/client-sns";
-import { mapLetterToCloudEvent } from "@nhsdigital/nhs-notify-event-schemas-supplier-api/src/events/letter-mapper";
+import { mapLetterToCloudEvent } from "@internal/event-builders/src";
 import { Letter, LetterRepository } from "@internal/datastore/src";
 import { UpdateLetterCommand } from "../../contracts/letters";
 import { EnvVars } from "../../config/env";
diff --git a/lambdas/api-handler/src/handlers/amendment-event-transformer.ts b/lambdas/api-handler/src/handlers/amendment-event-transformer.ts
@@ -1,10 +1,10 @@
 import { SQSBatchItemFailure, SQSEvent, SQSHandler } from "aws-lambda";
 import { PublishCommand } from "@aws-sdk/client-sns";
 import { LetterEvent } from "@nhsdigital/nhs-notify-event-schemas-supplier-api/src/events/letter-events";
-import { mapLetterToCloudEvent } from "@nhsdigital/nhs-notify-event-schemas-supplier-api/src/events/letter-mapper";
+import { MetricEntry, MetricStatus, buildEMFObject } from "@internal/helpers";
+import { mapLetterToCloudEvent } from "@internal/event-builders/src";
 import { Unit } from "aws-embedded-metrics";
 import pino from "pino";
-import { MetricEntry, MetricStatus, buildEMFObject } from "@internal/helpers";
 import {
   UpdateLetterCommand,
   UpdateLetterCommandSchema,
diff --git a/lambdas/letter-updates-transformer/package.json b/lambdas/letter-updates-transformer/package.json
@@ -3,6 +3,7 @@
     "@aws-sdk/client-sns": "^3.943.0",
     "@aws-sdk/util-dynamodb": "^3.943.0",
     "@internal/datastore": "^0.1.0",
+    "@internal/event-builders": "*",
     "@internal/helpers": "^0.1.0",
     "@nhsdigital/nhs-notify-event-schemas-supplier-api": "*",
     "aws-embedded-metrics": "^4.2.1",
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
@@ -8,7 +8,7 @@ import {
 } from "aws-lambda";
 import { mockDeep } from "jest-mock-extended";
 import { Letter } from "@internal/datastore";
-import { mapLetterToCloudEvent } from "@nhsdigital/nhs-notify-event-schemas-supplier-api/src/events/letter-mapper";
+import { mapLetterToCloudEvent } from "@internal/event-builders/src";
 import createHandler from "../letter-updates-transformer";
 import { Deps } from "../deps";
 import { EnvVars } from "../env";
diff --git a/lambdas/letter-updates-transformer/src/letter-updates-transformer.ts b/lambdas/letter-updates-transformer/src/letter-updates-transformer.ts
@@ -10,11 +10,11 @@ import {
   PublishBatchRequestEntry,
 } from "@aws-sdk/client-sns";
 import { LetterEvent } from "@nhsdigital/nhs-notify-event-schemas-supplier-api/src";
-import { mapLetterToCloudEvent } from "@nhsdigital/nhs-notify-event-schemas-supplier-api/src/events/letter-mapper";
+import { MetricEntry, buildEMFObject } from "@internal/helpers";
 import { Letter, LetterSchema } from "@internal/datastore";
+import { mapLetterToCloudEvent } from "@internal/event-builders/src";
 import { Unit } from "aws-embedded-metrics";
 import pino from "pino";
-import { MetricEntry, buildEMFObject } from "@internal/helpers";
 import { Deps } from "./deps";
 
 // SNS PublishBatchCommand supports up to 10 messages per batch
diff --git a/lambdas/upsert-letter/jest.config.ts b/lambdas/upsert-letter/jest.config.ts
@@ -9,6 +9,9 @@ export const baseJestConfig = {
       },
     ],
   },
+  transformIgnorePatterns: [
+    "node_modules/(?!(@nhsdigital/nhs-notify-event-schemas-supplier-config)/)",
+  ],
 
   // Automatically clear mock calls, instances, contexts and results before every test
   clearMocks: true,
diff --git a/lambdas/upsert-letter/src/handler/__tests__/upsert-handler.test.ts b/lambdas/upsert-letter/src/handler/__tests__/upsert-handler.test.ts
@@ -1,6 +1,9 @@
 import { SQSEvent, SQSRecord } from "aws-lambda";
 import pino from "pino";
-import { LetterRepository } from "internal/datastore/src";
+import {
+  LetterAlreadyExistsError,
+  LetterRepository,
+} from "@internal/datastore";
 import { LetterRequestPreparedEventV2 } from "@nhsdigital/nhs-notify-event-schemas-letter-rendering";
 import { LetterRequestPreparedEvent } from "@nhsdigital/nhs-notify-event-schemas-letter-rendering-v1";
 import {
@@ -199,7 +202,11 @@ describe("createUpsertLetterHandler", () => {
       putLetter: jest.fn(),
       updateLetterStatus: jest.fn(),
     } as unknown as LetterRepository,
-    logger: { error: jest.fn(), info: jest.fn() } as unknown as pino.Logger,
+    logger: {
+      error: jest.fn(),
+      warn: jest.fn(),
+      info: jest.fn(),
+    } as unknown as pino.Logger,
     env: {
       LETTERS_TABLE_NAME: "LETTERS_TABLE_NAME",
       LETTER_TTL_HOURS: 12_960,
@@ -301,6 +308,31 @@ describe("createUpsertLetterHandler", () => {
     );
   });
 
+  it("does not treat a replayed insert as a failure", async () => {
+    const v1message = {
+      letterEvent: createPreparedV1Event(),
+      supplierSpec: {
+        supplierId: "supplier1",
+        specId: "spec1",
+        priority: 10,
+        billingId: "billing1",
+      },
+    };
+    const evt: SQSEvent = createSQSEvent([
+      createSqsRecord("msg2", JSON.stringify(v1message)),
+    ]);
+    (mockedDeps.letterRepo.putLetter as jest.Mock).mockRejectedValue(
+      new LetterAlreadyExistsError("supplier1", "letter1"),
+    );
+
+    const result = await createUpsertLetterHandler(mockedDeps)(
+      evt,
+      {} as any,
+      {} as any,
+    );
+    expect(result!.batchItemFailures).toEqual([]);
+  });
+
   test("unknown supplier has metric emitted with 'unknown' supplier dimension", async () => {
     const letterEvent = createSupplierStatusChangeEventWithoutSupplier();
 
diff --git a/lambdas/upsert-letter/src/handler/upsert-handler.ts b/lambdas/upsert-letter/src/handler/upsert-handler.ts
@@ -1,5 +1,9 @@
 import { SQSBatchItemFailure, SQSEvent, SQSHandler } from "aws-lambda";
-import { InsertLetter, UpdateLetter } from "@internal/datastore";
+import {
+  InsertLetter,
+  LetterAlreadyExistsError,
+  UpdateLetter,
+} from "@internal/datastore";
 import {
   $LetterRequestPreparedEvent,
   LetterRequestPreparedEvent,
@@ -69,14 +73,26 @@ function getOperationFromType(type: string): UpsertOperation {
           supplierSpec.priority,
           supplierSpec.billingId, // use billingId for now
         );
-        await deps.letterRepo.putLetter(letterToInsert);
+        try {
+          await deps.letterRepo.putLetter(letterToInsert);
 
-        deps.logger.info({
-          description: "Inserted letter",
-          eventId: preparedRequest.id,
-          letterId: letterToInsert.id,
-          supplierId: letterToInsert.supplierId,
-        });
+          deps.logger.info({
+            description: "Inserted letter",
+            eventId: preparedRequest.id,
+            letterId: letterToInsert.id,
+            supplierId: letterToInsert.supplierId,
+          });
+        } catch (error) {
+          if (error instanceof LetterAlreadyExistsError) {
+            deps.logger.warn({
+              description: "Letter already exists",
+              supplierId: letterToInsert.supplierId,
+              letterId: letterToInsert.id,
+            });
+          } else {
+            throw error;
+          }
+        }
       },
     };
   }
diff --git a/package-lock.json b/package-lock.json
diff --git a/scripts/utilities/letter-test-data/src/cli/index.ts b/scripts/utilities/letter-test-data/src/cli/index.ts
@@ -76,6 +76,7 @@ async function main() {
           choices: [
             "test-letter-large",
             "test-letter-standard",
+            "test-letter-smoke",
             "none", // none exists to specify letter without pdf for error testing scenarios
           ],
         },
diff --git a/scripts/utilities/letter-test-data/src/test-letters/test-letter-smoke.pdf b/scripts/utilities/letter-test-data/src/test-letters/test-letter-smoke.pdf
diff --git a/tests/component-tests/events-tests/event-subscription.spec.ts b/tests/component-tests/events-tests/event-subscription.spec.ts
@@ -9,6 +9,7 @@ import { SUPPLIER_LETTERS, envName } from "tests/constants/api-constants";
 import {
   pollSupplierAllocatorLogForResolvedSpec,
   pollUpsertLetterLogForError,
+  pollUpsertLetterLogForWarning,
 } from "tests/helpers/aws-cloudwatch-helper";
 import { supplierDataSetup } from "tests/helpers/suppliers-setup-helper";
 import { pollForLetterStatus } from "tests/helpers/poll-for-letters-helper";
@@ -133,8 +134,6 @@ test.describe("Event Subscription SNS Tests", () => {
     expect(duplicateResponse.MessageId).toBeTruthy();
 
     // poll supplier upsert to check if duplicate event was processed
-    await pollUpsertLetterLogForError(
-      `Letter with id ${domainId} already exists for supplier ${supplierId}"`,
-    );
+    await pollUpsertLetterLogForWarning("Letter already exists", domainId);
   });
 });
diff --git a/tests/component-tests/letterQueue-tests/queue-operations.spec.ts b/tests/component-tests/letterQueue-tests/queue-operations.spec.ts
diff --git a/tests/helpers/aws-cloudwatch-helper.ts b/tests/helpers/aws-cloudwatch-helper.ts

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-1.1.5-${yyyy}${mm}${dd}.${HH}${MM}${SS}+${hash}`
	`1`	`+1.1.6-${yyyy}${mm}${dd}.${HH}${MM}${SS}+${hash}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+// Export event builder utilities`
	`2`	`+export * from "./letter-mapper";`