CCM-13906 Urgent Letter Priority

Author: stevebux

internal/datastore/src/__test__/letter-queue-repository.test.ts

@@ -12,12 +12,16 @@ import { LetterAlreadyExistsError } from "../letter-already-exists-error";
 import { createTestLogger } from "./logs";
 import { LetterDoesNotExistError } from "../letter-does-not-exist-error";
 
-function createLetter(letterId = "letter1"): PendingLetterBase {
+function createLetter(
+  overrides: Partial<PendingLetterBase> = {},
+): PendingLetterBase {
   return {
-    letterId,
+    letterId: "letter1",
     supplierId: "supplier1",
     specificationId: "specification1",
     groupId: "group1",
+    priority: 10,
+    ...overrides,
   };
 }
 
@@ -55,17 +59,42 @@ describe("LetterQueueRepository", () => {
   });
 
   describe("putLetter", () => {
-    it("adds a letter to the database", async () => {
+    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());
 
       expect(pendingLetter.queueTimestamp).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 }),
+      );
+
+      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 () => {
       await letterQueueRepository.putLetter(createLetter());
 
@@ -139,11 +168,21 @@ describe("LetterQueueRepository", () => {
     });
 
     it("returns letters in timestamp order", async () => {
-      await letterQueueRepository.putLetter(createLetter("first-letter"));
-      await letterQueueRepository.putLetter(createLetter("second-letter"));
-      await letterQueueRepository.putLetter(createLetter("third-letter"));
-      await letterQueueRepository.putLetter(createLetter("fourth-letter"));
-      await letterQueueRepository.putLetter(createLetter("fifth-letter"));
+      await letterQueueRepository.putLetter(
+        createLetter({ letterId: "first-letter" }),
+      );
+      await letterQueueRepository.putLetter(
+        createLetter({ letterId: "second-letter" }),
+      );
+      await letterQueueRepository.putLetter(
+        createLetter({ letterId: "third-letter" }),
+      );
+      await letterQueueRepository.putLetter(
+        createLetter({ letterId: "fourth-letter" }),
+      );
+      await letterQueueRepository.putLetter(
+        createLetter({ letterId: "fifth-letter" }),
+      );
 
       const letters = await letterQueueRepository.getLetters("supplier1", 5);
 
@@ -155,10 +194,18 @@ describe("LetterQueueRepository", () => {
     });
 
     it("limits results to the supplied number", async () => {
-      await letterQueueRepository.putLetter(createLetter("first-letter"));
-      await letterQueueRepository.putLetter(createLetter("second-letter"));
-      await letterQueueRepository.putLetter(createLetter("third-letter"));
-      await letterQueueRepository.putLetter(createLetter("fourth-letter"));
+      await letterQueueRepository.putLetter(
+        createLetter({ letterId: "first-letter" }),
+      );
+      await letterQueueRepository.putLetter(
+        createLetter({ letterId: "second-letter" }),
+      );
+      await letterQueueRepository.putLetter(
+        createLetter({ letterId: "third-letter" }),
+      );
+      await letterQueueRepository.putLetter(
+        createLetter({ letterId: "fourth-letter" }),
+      );
 
       const letters = await letterQueueRepository.getLetters("supplier1", 3);
 
@@ -179,6 +226,7 @@ describe("LetterQueueRepository", () => {
 
       const letter = await getLetter(db, "supplier1", "letter1");
       expect(letter?.queueTimestamp).toBe("2026-03-04T13:15:45.000Z");
+      expect(letter?.queueSortOrderSk).toBe("10-2026-03-04T13:15:45.000Z");
     });
 
     it("does nothing when the letter does not exist", async () => {

internal/datastore/src/letter-queue-repository.ts

@@ -23,13 +23,19 @@ export default class LetterQueueRepository {
     readonly config: LetterQueueRepositoryConfig,
   ) {}
 
+  private readonly defaultPriority = 10;
+
   async putLetter(
     insertPendingLetter: PendingLetterBase,
   ): Promise<PendingLetter> {
+    const priority = String(insertPendingLetter.priority ?? 10);
+    // needs to be an ISO timestamp as Db sorts alphabetically
+    const queueTimestamp = new Date().toISOString();
+    const queueSortOrderSk = `${priority.padStart(2, "0")}-${queueTimestamp}`;
     const pendingLetter: PendingLetter = {
       ...insertPendingLetter,
-      // needs to be an ISO timestamp as Db sorts alphabetically
-      queueTimestamp: new Date().toISOString(),
+      queueTimestamp,
+      queueSortOrderSk,
       ttl: Math.floor(
         Date.now() / 1000 + 60 * 60 * this.config.letterQueueTtlHours,
       ),
@@ -102,6 +108,9 @@ export default class LetterQueueRepository {
     pendingLetter: PendingLetterBase,
     timestamp: Date,
   ): Promise<void> {
+    const priority = String(pendingLetter.priority ?? this.defaultPriority);
+    const isoTimestamp = timestamp.toISOString();
+    const queueSortOrderSk = `${priority.padStart(2, "0")}-${isoTimestamp}`;
     try {
       await this.ddbClient.send(
         new UpdateCommand({
@@ -110,10 +119,12 @@ export default class LetterQueueRepository {
             supplierId: pendingLetter.supplierId,
             letterId: pendingLetter.letterId,
           },
-          UpdateExpression: "SET queueTimestamp = :ts",
+          UpdateExpression:
+            "SET queueTimestamp = :ts, queueSortOrderSk = :sortOrder",
           ConditionExpression: "attribute_exists(letterId)",
           ExpressionAttributeValues: {
-            ":ts": timestamp.toISOString(),
+            ":ts": isoTimestamp,
+            ":sortOrder": queueSortOrderSk,
           },
         }),
       );

internal/datastore/src/types.ts

@@ -43,6 +43,7 @@ export const LetterSchemaBase = z.object({
 export const LetterSchema = LetterSchemaBase.extend({
   supplierId: idRef(SupplierSchema, "id"),
   eventId: z.string().optional(),
+  priority: z.int().min(0).max(99).optional(), // A lower number represents a higher priority
   url: z.url(),
   createdAt: z.string(),
   updatedAt: z.string(),
@@ -81,12 +82,14 @@ export const PendingLetterSchemaBase = z.object({
   letterId: idRef(LetterSchema, "id"),
   specificationId: z.string(),
   groupId: z.string(),
+  priority: z.int().min(0).max(99).optional(),
 });
 
 export const PendingLetterSchema = z.object({
   supplierId: idRef(SupplierSchema, "id"),
   letterId: idRef(LetterSchema, "id"),
-  queueTimestamp: z.string().describe("Secondary index SK"),
+  queueTimestamp: z.string(),
+  queueSortOrderSk: z.string().describe("Secondary index SK"),
   specificationId: z.string(),
   groupId: z.string(),
   ttl: z.int(),