NHSDigital · stevebux · Mar 3, 2026 · Mar 5, 2026 · Mar 10, 2026 · Mar 11, 2026
@@ -30,7 +30,7 @@ No requirements.
 | <a name="input_group"></a> [group](#input\_group) | The group variables are being inherited from (often synonmous with account short-name) | `string` | n/a | yes |
 | <a name="input_kms_deletion_window"></a> [kms\_deletion\_window](#input\_kms\_deletion\_window) | When a kms key is deleted, how long should it wait in the pending deletion state? | `string` | `"30"` | no |
 | <a name="input_letter_table_ttl_hours"></a> [letter\_table\_ttl\_hours](#input\_letter\_table\_ttl\_hours) | Number of hours to set as TTL on letters table | `number` | `24` | no |
-| <a name="input_letter_variant_map"></a> [letter\_variant\_map](#input\_letter\_variant\_map) | n/a | `map(object({ supplierId = string, specId = string }))` | <pre>{<br/>  "lv1": {<br/>    "specId": "spec1",<br/>    "supplierId": "supplier1"<br/>  },<br/>  "lv2": {<br/>    "specId": "spec2",<br/>    "supplierId": "supplier1"<br/>  },<br/>  "lv3": {<br/>    "specId": "spec3",<br/>    "supplierId": "supplier2"<br/>  }<br/>}</pre> | no |
+| <a name="input_letter_variant_map"></a> [letter\_variant\_map](#input\_letter\_variant\_map) | n/a | `map(object({ supplierId = string, specId = string, priority = number }))` | <pre>{<br/>  "lv1": {<br/>    "priority": 10,<br/>    "specId": "spec1",<br/>    "supplierId": "supplier1"<br/>  },<br/>  "lv2": {<br/>    "priority": 10,<br/>    "specId": "spec2",<br/>    "supplierId": "supplier1"<br/>  },<br/>  "lv3": {<br/>    "priority": 10,<br/>    "specId": "spec3",<br/>    "supplierId": "supplier2"<br/>  }<br/>}</pre> | no |
 | <a name="input_log_level"></a> [log\_level](#input\_log\_level) | The log level to be used in lambda functions within the component. Any log with a lower severity than the configured value will not be logged: https://docs.python.org/3/library/logging.html#levels | `string` | `"INFO"` | no |
 | <a name="input_log_retention_in_days"></a> [log\_retention\_in\_days](#input\_log\_retention\_in\_days) | The retention period in days for the Cloudwatch Logs events to be retained, default of 0 is indefinite | `number` | `0` | no |
 | <a name="input_manually_configure_mtls_truststore"></a> [manually\_configure\_mtls\_truststore](#input\_manually\_configure\_mtls\_truststore) | Manually manage the truststore used for API Gateway mTLS (e.g. for prod environment) | `bool` | `false` | no |
@@ -45,7 +45,7 @@ No requirements.
 | Name | Source | Version |
 |------|--------|---------|
 | <a name="module_amendment_event_transformer"></a> [amendment\_event\_transformer](#module\_amendment\_event\_transformer) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
-| <a name="module_amendments_queue"></a> [amendments\_queue](#module\_amendments\_queue) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.24/terraform-sqs.zip | n/a |
+| <a name="module_amendments_queue"></a> [amendments\_queue](#module\_amendments\_queue) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/3.0.5/terraform-sqs.zip | n/a |
 | <a name="module_authorizer_lambda"></a> [authorizer\_lambda](#module\_authorizer\_lambda) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_ddb_alarms_letter_queue"></a> [ddb\_alarms\_letter\_queue](#module\_ddb\_alarms\_letter\_queue) | ../../modules/alarms-ddb | n/a |
 | <a name="module_ddb_alarms_letters"></a> [ddb\_alarms\_letters](#module\_ddb\_alarms\_letters) | ../../modules/alarms-ddb | n/a |
@@ -60,16 +60,16 @@ No requirements.
 | <a name="module_get_status"></a> [get\_status](#module\_get\_status) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_kms"></a> [kms](#module\_kms) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.26/terraform-kms.zip | n/a |
 | <a name="module_lambda_alarms"></a> [lambda\_alarms](#module\_lambda\_alarms) | ../../modules/alarms-lambda | n/a |
-| <a name="module_letter_status_updates_queue"></a> [letter\_status\_updates\_queue](#module\_letter\_status\_updates\_queue) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.24/terraform-sqs.zip | n/a |
+| <a name="module_letter_status_updates_queue"></a> [letter\_status\_updates\_queue](#module\_letter\_status\_updates\_queue) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/3.0.5/terraform-sqs.zip | n/a |
 | <a name="module_letter_updates_transformer"></a> [letter\_updates\_transformer](#module\_letter\_updates\_transformer) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_mi_updates_transformer"></a> [mi\_updates\_transformer](#module\_mi\_updates\_transformer) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.26/terraform-lambda.zip | n/a |
 | <a name="module_patch_letter"></a> [patch\_letter](#module\_patch\_letter) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_post_letters"></a> [post\_letters](#module\_post\_letters) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_post_mi"></a> [post\_mi](#module\_post\_mi) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_s3bucket_test_letters"></a> [s3bucket\_test\_letters](#module\_s3bucket\_test\_letters) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.26/terraform-s3bucket.zip | n/a |
 | <a name="module_sqs_alarms"></a> [sqs\_alarms](#module\_sqs\_alarms) | ../../modules/alarms-sqs | n/a |
-| <a name="module_sqs_letter_updates"></a> [sqs\_letter\_updates](#module\_sqs\_letter\_updates) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.26/terraform-sqs.zip | n/a |
-| <a name="module_sqs_supplier_allocator"></a> [sqs\_supplier\_allocator](#module\_sqs\_supplier\_allocator) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.26/terraform-sqs.zip | n/a |
+| <a name="module_sqs_letter_updates"></a> [sqs\_letter\_updates](#module\_sqs\_letter\_updates) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/3.0.5/terraform-sqs.zip | n/a |
+| <a name="module_sqs_supplier_allocator"></a> [sqs\_supplier\_allocator](#module\_sqs\_supplier\_allocator) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/3.0.5/terraform-sqs.zip | n/a |
 | <a name="module_supplier_allocator"></a> [supplier\_allocator](#module\_supplier\_allocator) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_supplier_ssl"></a> [supplier\_ssl](#module\_supplier\_ssl) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.26/terraform-ssl.zip | n/a |
 | <a name="module_update_letter_queue"></a> [update\_letter\_queue](#module\_update\_letter\_queue) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |

@@ -3,16 +3,16 @@ resource "aws_dynamodb_table" "letter_queue" {
   billing_mode = "PAY_PER_REQUEST"
 
   hash_key  = "supplierId"
-  range_key = "queueTimestamp"
+  range_key = "letterId"
 
   ttl {
     attribute_name = "ttl"
     enabled        = true
   }
 
   local_secondary_index {
-    name            = "letterId-index"
-    range_key       = "letterId"
+    name            = "queueSortOrder-index"
+    range_key       = "queueSortOrderSk"
     projection_type = "ALL"
   }
 
@@ -27,7 +27,7 @@ resource "aws_dynamodb_table" "letter_queue" {
   }
 
   attribute {
-    name = "queueTimestamp"
+    name = "queueSortOrderSk"
     type = "S"
   }
 

@@ -35,7 +35,7 @@ module "update_letter_queue" {
   log_subscription_role_arn = local.acct.log_subscription_role_arn
 
   lambda_env_vars = merge(local.common_lambda_env_vars, {
-    LETTER_QUEUE_TABLE_NAME = aws_dynamodb_table.letter_queue.name,
+    LETTER_QUEUE_TABLE_NAME = "${local.csi}-letter-queue",
     LETTER_QUEUE_TTL_HOURS  = 168 # 7 days
   })
 }
@@ -47,11 +47,12 @@ data "aws_iam_policy_document" "update_letter_queue_lambda" {
 
     actions = [
       "dynamodb:PutItem",
+      "dynamodb:DeleteItem",
     ]
 
     resources = [
-      aws_dynamodb_table.letter_queue.arn,
-      "${aws_dynamodb_table.letter_queue.arn}/index/*"
+      "arn:aws:dynamodb:${var.region}:${var.aws_account_id}:table/${local.csi}-letter-queue",
+      "arn:aws:dynamodb:${var.region}:${var.aws_account_id}:table/${local.csi}-letter-queue/index/*"
     ]
   }
 

@@ -136,11 +136,11 @@ variable "eventpub_control_plane_bus_arn" {
 }
 
 variable "letter_variant_map" {
-  type = map(object({ supplierId = string, specId = string }))
+  type = map(object({ supplierId = string, specId = string, priority = number }))
   default = {
-    "lv1" = { supplierId = "supplier1", specId = "spec1" },
-    "lv2" = { supplierId = "supplier1", specId = "spec2" },
-    "lv3" = { supplierId = "supplier2", specId = "spec3" }
+    "lv1" = { supplierId = "supplier1", specId = "spec1", priority = 10 },
+    "lv2" = { supplierId = "supplier1", specId = "spec2", priority = 10 },
+    "lv3" = { supplierId = "supplier2", specId = "spec3", priority = 10 }
   }
 }
 

@@ -22,6 +22,7 @@ export async function setupDynamoDBContainer() {
       accessKeyId: "fakeMyKeyId",
       secretAccessKey: "fakeSecretAccessKey",
     },
+    maxAttempts: 1,
   });
 
   const docClient = DynamoDBDocumentClient.from(ddbClient);
@@ -129,10 +130,10 @@ const createLetterQueueTableCommand = new CreateTableCommand({
   ],
   LocalSecondaryIndexes: [
     {
-      IndexName: "timestamp-index",
+      IndexName: "queueSortOrder-index",
       KeySchema: [
         { AttributeName: "supplierId", KeyType: "HASH" }, // Partition key for LSI
-        { AttributeName: "queueTimestamp", KeyType: "RANGE" }, // Sort key for LSI
+        { AttributeName: "queueSortOrderSk", KeyType: "RANGE" }, // Sort key for LSI
       ],
       Projection: {
         ProjectionType: "ALL",
@@ -142,7 +143,7 @@ const createLetterQueueTableCommand = new CreateTableCommand({
   AttributeDefinitions: [
     { AttributeName: "supplierId", AttributeType: "S" },
     { AttributeName: "letterId", AttributeType: "S" },
-    { AttributeName: "queueTimestamp", AttributeType: "S" },
+    { AttributeName: "queueSortOrderSk", AttributeType: "S" },
   ],
 });
 

@@ -1,3 +1,4 @@
+import { GetCommand } from "@aws-sdk/lib-dynamodb";
 import { Logger } from "pino";
 import {
   DBContext,
@@ -7,15 +8,20 @@ import {
 } from "./db";
 import LetterQueueRepository from "../letter-queue-repository";
 import { InsertPendingLetter } from "../types";
-import { LetterAlreadyExistsError } from "../errors";
+import { LetterAlreadyExistsError } from "../letter-already-exists-error";
 import { createTestLogger } from "./logs";
+import { LetterDoesNotExistError } from "../letter-does-not-exist-error";
 
-function createLetter(letterId = "letter1"): InsertPendingLetter {
+function createLetter(
+  overrides: Partial<InsertPendingLetter> = {},
+): InsertPendingLetter {
   return {
-    letterId,
+    letterId: "letter1",
     supplierId: "supplier1",
     specificationId: "specification1",
     groupId: "group1",
+    priority: 10,
+    ...overrides,
   };
 }
 
@@ -51,32 +57,44 @@ describe("LetterQueueRepository", () => {
     await db.container.stop();
   });
 
-  function assertTtl(ttl: number, before: number, after: number) {
-    const expectedLower = Math.floor(
-      before / 1000 + 60 * 60 * db.config.letterQueueTtlHours,
-    );
-    const expectedUpper = Math.floor(
-      after / 1000 + 60 * 60 * db.config.lettersTtlHours,
-    );
-    expect(ttl).toBeGreaterThanOrEqual(expectedLower);
-    expect(ttl).toBeLessThanOrEqual(expectedUpper);
-  }
-
   describe("putLetter", () => {
-    it("adds a letter to the database", async () => {
-      const before = Date.now();
+    beforeEach(() => {
+      jest.useFakeTimers().setSystemTime(new Date("2026-03-04T13:15:45.000Z"));
+    });
 
+    it("adds a letter to the database", async () => {
       const pendingLetter =
         await letterQueueRepository.putLetter(createLetter());
 
-      const after = Date.now();
+      expect(pendingLetter.queueTimestamp).toBe("2026-03-04T13:15:45.000Z");
+      expect(pendingLetter.visibilityTimestamp).toBe(
+        "2026-03-04T13:15:45.000Z",
+      );
+      expect(pendingLetter.ttl).toBe(1_772_633_745);
+      expect(pendingLetter.queueSortOrderSk).toBe(
+        "10-2026-03-04T13:15:45.000Z",
+      );
+      expect(await letterExists(db, "supplier1", "letter1")).toBe(true);
+    });
+
+    it("left-pads the priority with zeros in the sort key", async () => {
+      const pendingLetter = await letterQueueRepository.putLetter(
+        createLetter({ priority: 5 }),
+      );
 
-      const timestampInMillis = new Date(
-        pendingLetter.queueTimestamp,
-      ).valueOf();
-      expect(timestampInMillis).toBeGreaterThanOrEqual(before);
-      expect(timestampInMillis).toBeLessThanOrEqual(after);
-      assertTtl(pendingLetter.ttl, before, after);
+      expect(pendingLetter.queueSortOrderSk).toBe(
+        "05-2026-03-04T13:15:45.000Z",
+      );
+    });
+
+    it("defaults a missing priority to 10 in the sort key", async () => {
+      const pendingLetter = await letterQueueRepository.putLetter(
+        createLetter({ priority: undefined }),
+      );
+
+      expect(pendingLetter.queueSortOrderSk).toBe(
+        "10-2026-03-04T13:15:45.000Z",
+      );
     });
 
     it("throws LetterAlreadyExistsError when creating a letter which already exists", async () => {
@@ -101,4 +119,53 @@ describe("LetterQueueRepository", () => {
       ).rejects.toThrow("Cannot do operations on a non-existent table");
     });
   });
+
+  describe("deleteLetter", () => {
+    it("deletes a letter from the database", async () => {
+      await letterQueueRepository.putLetter(createLetter());
+
+      await letterQueueRepository.deleteLetter("supplier1", "letter1");
+
+      expect(await letterExists(db, "supplier1", "letter1")).toBe(false);
+    });
+
+    it("throws an error when the letter does not exist", async () => {
+      await expect(
+        letterQueueRepository.deleteLetter("supplier1", "letter1"),
+      ).rejects.toThrow(LetterDoesNotExistError);
+    });
+
+    it("rethrows errors from DynamoDB when deleting a letter", async () => {
+      const misconfiguredRepository = new LetterQueueRepository(
+        db.docClient,
+        logger,
+        {
+          ...db.config,
+          letterQueueTableName: "nonexistent-table",
+        },
+      );
+      await expect(
+        misconfiguredRepository.deleteLetter("supplier1", "letter1"),
+      ).rejects.toThrow("Cannot do operations on a non-existent table");
+    });
+  });
 });
+
+async function getLetter(db: DBContext, supplierId: string, letterId: string) {
+  const result = await db.docClient.send(
+    new GetCommand({
+      TableName: db.config.letterQueueTableName,
+      Key: { supplierId, letterId },
+    }),
+  );
+  return result.Item;
+}
+
+async function letterExists(
+  db: DBContext,
+  supplierId: string,
+  letterId: string,
+): Promise<boolean> {
+  const letter = await getLetter(db, supplierId, letterId);
+  return letter !== undefined;
+}
@@ -1,5 +1,6 @@
 export * from "./types";
-export * from "./errors";
+export * from "./letter-already-exists-error";
+export * from "./letter-does-not-exist-error";
 export * from "./mi-repository";
 export * from "./letter-repository";
 export * from "./supplier-repository";

@@ -0,0 +1,15 @@
+/**
+ * Error thrown when attempting to delete a letter that does not exist in the database.
+ */
+// eslint-disable-next-line import-x/prefer-default-export
+export class LetterDoesNotExistError extends Error {
+  constructor(
+    public readonly supplierId: string,
+    public readonly letterId: string,
+  ) {
+    super(
+      `Letter does not exist: supplierId=${supplierId}, letterId=${letterId}`,
+    );
+    this.name = "LetterDoesNotExistError";
+  }
+}
@@ -1,11 +1,16 @@
-import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
+import {
+  DeleteCommand,
+  DynamoDBDocumentClient,
+  PutCommand,
+} from "@aws-sdk/lib-dynamodb";
 import { Logger } from "pino";
 import {
   InsertPendingLetter,
   PendingLetter,
   PendingLetterSchema,
 } from "./types";
-import { LetterAlreadyExistsError } from "./errors";
+import { LetterAlreadyExistsError } from "./letter-already-exists-error";
+import { LetterDoesNotExistError } from "./letter-does-not-exist-error";
 
 type LetterQueueRepositoryConfig = {
   letterQueueTableName: string;
@@ -19,13 +24,22 @@ export default class LetterQueueRepository {
     readonly config: LetterQueueRepositoryConfig,
   ) {}
 
+  private readonly defaultPriority = 10;
+
   async putLetter(
     insertPendingLetter: InsertPendingLetter,
   ): Promise<PendingLetter> {
+    // needs to be an ISO timestamp as Db sorts alphabetically
+    const now = new Date().toISOString();
+    const priority = String(
+      insertPendingLetter.priority ?? this.defaultPriority,
+    );
+    const queueSortOrderSk = `${priority.padStart(2, "0")}-${now}`;
     const pendingLetter: PendingLetter = {
       ...insertPendingLetter,
-      // needs to be an ISO timestamp as Db sorts alphabetically
-      queueTimestamp: new Date().toISOString(),
+      queueTimestamp: now,
+      visibilityTimestamp: now,
+      queueSortOrderSk,
       ttl: Math.floor(
         Date.now() / 1000 + 60 * 60 * this.config.letterQueueTtlHours,
       ),
@@ -52,4 +66,24 @@ export default class LetterQueueRepository {
     }
     return PendingLetterSchema.parse(pendingLetter);
   }
+
+  async deleteLetter(supplierId: string, letterId: string): Promise<void> {
+    try {
+      await this.ddbClient.send(
+        new DeleteCommand({
+          TableName: this.config.letterQueueTableName,
+          Key: { supplierId, letterId },
+          ConditionExpression: "attribute_exists(letterId)",
+        }),
+      );
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        error.name === "ConditionalCheckFailedException"
+      ) {
+        throw new LetterDoesNotExistError(supplierId, letterId);
+      }
+      throw error;
+    }
+  }
 }