Merge branch 'main' into dependabotCombined

Author: masl2

infrastructure/terraform/components/api/ddb_table_letter_queue.tf

@@ -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       = "queueTimestamp"
     projection_type = "ALL"
   }
 

infrastructure/terraform/components/api/module_lambda_update_letter_queue.tf

@@ -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/*"
     ]
   }
 

internal/datastore/src/__test__/db.ts

@@ -129,7 +129,7 @@ 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

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

@@ -1,3 +1,4 @@
+import { GetCommand } from "@aws-sdk/lib-dynamodb";
 import { Logger } from "pino";
 import {
   DBContext,
@@ -7,8 +8,9 @@ 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 {
   return {
@@ -51,32 +53,19 @@ 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();
+      jest.useFakeTimers().setSystemTime(new Date("2026-03-04T13:15:45.000Z"));
 
       const pendingLetter =
         await letterQueueRepository.putLetter(createLetter());
 
-      const after = Date.now();
-
-      const timestampInMillis = new Date(
-        pendingLetter.queueTimestamp,
-      ).valueOf();
-      expect(timestampInMillis).toBeGreaterThanOrEqual(before);
-      expect(timestampInMillis).toBeLessThanOrEqual(after);
-      assertTtl(pendingLetter.ttl, before, after);
+      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(await letterExists(db, "supplier1", "letter1")).toBe(true);
     });
 
     it("throws LetterAlreadyExistsError when creating a letter which already exists", async () => {
@@ -101,4 +90,48 @@ 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 letterExists(
+  db: DBContext,
+  supplierId: string,
+  letterId: string,
+): Promise<boolean> {
+  const result = await db.docClient.send(
+    new GetCommand({
+      TableName: db.config.letterQueueTableName,
+      Key: { supplierId, letterId },
+    }),
+  );
+  return result.Item !== undefined;
+}

internal/datastore/src/index.ts

@@ -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";

internal/datastore/src/errors.ts …store/src/letter-already-exists-error.tsinternal/datastore/src/errors.ts renamed to internal/datastore/src/letter-already-exists-error.ts internal/datastore/src/errors.ts renamed to internal/datastore/src/letter-already-exists-error.ts

@@ -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";
+  }
+}

internal/datastore/src/letter-does-not-exist-error.ts

@@ -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;
@@ -22,10 +27,13 @@ export default class LetterQueueRepository {
   async putLetter(
     insertPendingLetter: InsertPendingLetter,
   ): Promise<PendingLetter> {
+    // needs to be an ISO timestamp as Db sorts alphabetically
+    const now = new Date().toISOString();
+
     const pendingLetter: PendingLetter = {
       ...insertPendingLetter,
-      // needs to be an ISO timestamp as Db sorts alphabetically
-      queueTimestamp: new Date().toISOString(),
+      queueTimestamp: now,
+      visibilityTimestamp: now,
       ttl: Math.floor(
         Date.now() / 1000 + 60 * 60 * this.config.letterQueueTtlHours,
       ),
@@ -52,4 +60,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;
+    }
+  }
 }

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

@@ -80,14 +80,18 @@ export const PendingLetterSchema = z.object({
   supplierId: idRef(SupplierSchema, "id"),
   letterId: idRef(LetterSchema, "id"),
   queueTimestamp: z.string().describe("Secondary index SK"),
+  visibilityTimestamp: z.string(),
   specificationId: z.string(),
   groupId: z.string(),
   ttl: z.int(),
 });
 
 export type PendingLetter = z.infer<typeof PendingLetterSchema>;
 
-export type InsertPendingLetter = Omit<PendingLetter, "ttl" | "queueTimestamp">;
+export type InsertPendingLetter = Omit<
+  PendingLetter,
+  "ttl" | "queueTimestamp" | "visibilityTimestamp"
+>;
 
 export const MISchemaBase = z.object({
   id: z.string(),