Add upsert lambda

Author: francisco-videira-nhs

infrastructure/terraform/components/api/module_lambda_upsert_letter.tf

@@ -22,7 +22,7 @@ module "upsert_letter" {
   function_code_base_path = local.aws_lambda_functions_dir_path
   function_code_dir       = "upsert-letter/dist"
   function_include_common = true
-  handler_function_name   = "handler"
+  handler_function_name   = "upsertLetterHandler"
   runtime                 = "nodejs22.x"
   memory                  = 128
   timeout                 = 5

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

@@ -7,15 +7,14 @@ import {
   setupDynamoDBContainer,
 } from "./db";
 import { LetterRepository } from "../letter-repository";
-import { Letter } from "../types";
+import { InsertLetter, Letter, UpdateLetter, UpsertLetter } from "../types";
 import { LogStream, createTestLogger } from "./logs";
-import { LetterDto } from "../../../../lambdas/api-handler/src/contracts/letters";
 
 function createLetter(
   supplierId: string,
   letterId: string,
   status: Letter["status"] = "PENDING",
-): Omit<Letter, "ttl" | "supplierStatus" | "supplierStatusSk"> {
+): InsertLetter {
   return {
     id: letterId,
     supplierId,
@@ -126,14 +125,14 @@ describe("LetterRepository", () => {
     await letterRepository.putLetter(letter);
     await checkLetterStatus("supplier1", "letter1", "PENDING");
 
-    const letterDto: LetterDto = {
+    const updateLetter: UpdateLetter = {
       id: "letter1",
       supplierId: "supplier1",
       status: "REJECTED",
       reasonCode: "R01",
       reasonText: "Reason text",
     };
-    await letterRepository.updateLetterStatus(letterDto);
+    await letterRepository.updateLetterStatus(updateLetter);
 
     const updatedLetter = await letterRepository.getLetterById(
       "supplier1",
@@ -159,7 +158,7 @@ describe("LetterRepository", () => {
     // Month is zero-indexed in JavaScript Date
     // Day is one-indexed
     jest.setSystemTime(new Date(2020, 1, 2));
-    const letterDto: LetterDto = {
+    const letterDto: UpdateLetter = {
       id: "letter1",
       supplierId: "supplier1",
       status: "DELIVERED",
@@ -175,13 +174,13 @@ describe("LetterRepository", () => {
   });
 
   test("can't update a letter that does not exist", async () => {
-    const letterDto: LetterDto = {
+    const updateLetter: UpdateLetter = {
       id: "letter1",
       supplierId: "supplier1",
       status: "DELIVERED",
     };
     await expect(
-      letterRepository.updateLetterStatus(letterDto),
+      letterRepository.updateLetterStatus(updateLetter),
     ).rejects.toThrow(
       "Letter with id letter1 not found for supplier supplier1",
     );
@@ -193,13 +192,13 @@ describe("LetterRepository", () => {
       lettersTableName: "nonexistent-table",
     });
 
-    const letterDto: LetterDto = {
+    const updateLetter: UpdateLetter = {
       id: "letter1",
       supplierId: "supplier1",
       status: "DELIVERED",
     };
     await expect(
-      misconfiguredRepository.updateLetterStatus(letterDto),
+      misconfiguredRepository.updateLetterStatus(updateLetter),
     ).rejects.toThrow("Cannot do operations on a non-existent table");
   });
 
@@ -238,12 +237,12 @@ describe("LetterRepository", () => {
     );
     expect(pendingLetters.letters).toHaveLength(2);
 
-    const letterDto: LetterDto = {
+    const updateLetter: UpdateLetter = {
       id: "letter1",
       supplierId: "supplier1",
       status: "DELIVERED",
     };
-    await letterRepository.updateLetterStatus(letterDto);
+    await letterRepository.updateLetterStatus(updateLetter);
     const remainingLetters = await letterRepository.getLettersByStatus(
       "supplier1",
       "PENDING",
@@ -457,4 +456,119 @@ describe("LetterRepository", () => {
       ]),
     ).rejects.toThrow("Cannot do operations on a non-existent table");
   });
+
+  test("successful upsert (update status) returns updated letter", async () => {
+    const insertLetter: InsertLetter = createLetter("supplier1", "letter1");
+
+    const existingLetter = await letterRepository.putLetter(insertLetter);
+
+    const result = await letterRepository.upsertLetter({
+      id: "letter1",
+      supplierId: "supplier1",
+      status: "REJECTED",
+      reasonCode: "R01",
+      reasonText: "R01 text",
+    });
+
+    expect(result).toEqual(
+      expect.objectContaining({
+        id: "letter1",
+        status: "REJECTED",
+        specificationId: "specification1",
+        groupId: "group1",
+        reasonCode: "R01",
+        reasonText: "R01 text",
+        supplierId: "supplier1",
+        url: "s3://bucket/letter1.pdf",
+        supplierStatus: "supplier1#REJECTED",
+      }),
+    );
+    expect(Date.parse(result.updatedAt)).toBeGreaterThan(
+      Date.parse(existingLetter.updatedAt),
+    );
+    expect(Date.parse(result.updatedAt)).toBeLessThan(Date.now());
+    expect(result.createdAt).toBe(existingLetter.createdAt);
+    expect(result.createdAt).toBe(result.supplierStatusSk);
+    expect(result.ttl).toBe(existingLetter.ttl);
+  });
+
+  test("successful upsert (insert) returns created letter", async () => {
+    const upsertLetter: UpsertLetter = {
+      id: "letter1",
+      status: "PENDING",
+      specificationId: "specification1",
+      groupId: "group1",
+      supplierId: "supplier1",
+      url: "s3://bucket/letter1.pdf",
+    };
+
+    const beforeInsert = Date.now() - 1; // widen window
+
+    const result = await letterRepository.upsertLetter(upsertLetter);
+
+    expect(result).toEqual(
+      expect.objectContaining({
+        id: "letter1",
+        status: "PENDING",
+        specificationId: "specification1",
+        groupId: "group1",
+        supplierId: "supplier1",
+        url: "s3://bucket/letter1.pdf",
+      }),
+    );
+
+    expect(Date.parse(result.updatedAt)).toBeGreaterThan(beforeInsert);
+    expect(Date.parse(result.updatedAt)).toBeLessThan(Date.now());
+    expect(result.createdAt).toBe(result.updatedAt);
+    expect(result.supplierStatusSk).toBe(result.createdAt);
+  });
+
+  test("unsuccessful upsert should throw error", async () => {
+    const mockSend = jest.fn().mockResolvedValue({ Items: null });
+    const mockDdbClient = { send: mockSend } as any;
+    const repo = new LetterRepository(
+      mockDdbClient,
+      { debug: jest.fn() } as any,
+      { lettersTableName: "letters", lettersTtlHours: 1 },
+    );
+
+    await expect(
+      repo.upsertLetter({
+        id: "letter1",
+        status: "PENDING",
+        supplierId: "supplier1",
+      }),
+    ).rejects.toThrow("upsertLetter: no attributes returned");
+  });
+
+  test("successful upsert without status", async () => {
+    const insertLetter: InsertLetter = createLetter("supplier1", "letter1");
+
+    const existingLetter = await letterRepository.putLetter(insertLetter);
+
+    const result = await letterRepository.upsertLetter({
+      id: "letter1",
+      supplierId: "supplier1",
+      url: "s3://updatedBucket/letter1.pdf",
+    });
+
+    expect(result).toEqual(
+      expect.objectContaining({
+        id: "letter1",
+        status: "PENDING",
+        specificationId: "specification1",
+        groupId: "group1",
+        supplierId: "supplier1",
+        url: "s3://updatedBucket/letter1.pdf",
+        supplierStatus: "supplier1#PENDING",
+      }),
+    );
+    expect(Date.parse(result.updatedAt)).toBeGreaterThan(
+      Date.parse(existingLetter.updatedAt),
+    );
+    expect(Date.parse(result.updatedAt)).toBeLessThan(Date.now());
+    expect(result.createdAt).toBe(existingLetter.createdAt);
+    expect(result.createdAt).toBe(result.supplierStatusSk);
+    expect(result.ttl).toBe(existingLetter.ttl);
+  });
 });

internal/datastore/src/letter-repository.ts

@@ -9,8 +9,15 @@ import {
 } from "@aws-sdk/lib-dynamodb";
 import { Logger } from "pino";
 import { z } from "zod";
-import { Letter, LetterBase, LetterSchema, LetterSchemaBase } from "./types";
-import { LetterDto } from "../../../lambdas/api-handler/src/contracts/letters";
+import {
+  InsertLetter,
+  Letter,
+  LetterBase,
+  LetterSchema,
+  LetterSchemaBase,
+  UpdateLetter,
+  UpsertLetter,
+} from "./types";
 
 export type PagingOptions = Partial<{
   exclusiveStartKey: Record<string, any>;
@@ -33,9 +40,7 @@ export class LetterRepository {
     readonly config: LetterRepositoryConfig,
   ) {}
 
-  async putLetter(
-    letter: Omit<Letter, "ttl" | "supplierStatus" | "supplierStatusSk">,
-  ): Promise<Letter> {
+  async putLetter(letter: InsertLetter): Promise<Letter> {
     const letterDb: Letter = {
       ...letter,
       supplierStatus: `${letter.supplierId}#${letter.status}`,
@@ -66,9 +71,7 @@ export class LetterRepository {
     return LetterSchema.parse(letterDb);
   }
 
-  async putLetterBatch(
-    letters: Omit<Letter, "ttl" | "supplierStatus" | "supplierStatusSk">[],
-  ): Promise<void> {
+  async putLetterBatch(letters: InsertLetter[]): Promise<void> {
     let lettersDb: Letter[] = [];
     for (let i = 0; i < letters.length; i++) {
       const letter = letters[i];
@@ -161,7 +164,7 @@ export class LetterRepository {
     };
   }
 
-  async updateLetterStatus(letterToUpdate: LetterDto): Promise<Letter> {
+  async updateLetterStatus(letterToUpdate: UpdateLetter): Promise<Letter> {
     this.log.debug(
       `Updating letter ${letterToUpdate.id} to status ${letterToUpdate.status}`,
     );
@@ -247,4 +250,92 @@ export class LetterRepository {
     );
     return z.array(LetterSchemaBase).parse(result.Items ?? []);
   }
+
+  async upsertLetter(upsert: UpsertLetter): Promise<Letter> {
+    const now = new Date();
+    const ttl = Math.floor(
+      now.valueOf() / 1000 + 60 * 60 * this.config.lettersTtlHours,
+    );
+
+    const setParts: string[] = [];
+    const exprAttrNames: Record<string, string> = {};
+    const exprAttrValues: Record<string, any> = {};
+
+    // updateAt is always updated
+    setParts.push("updatedAt = :updatedAt");
+    exprAttrValues[":updatedAt"] = now.toISOString();
+
+    // ttl is always updated
+    setParts.push("#ttl = :ttl");
+    exprAttrNames["#ttl"] = "ttl";
+    exprAttrValues[":ttl"] = ttl;
+
+    // createdAt only if first time
+    setParts.push("createdAt = if_not_exists(createdAt, :createdAt)");
+    exprAttrValues[":createdAt"] = now.toISOString();
+
+    // status and related supplierStatus if provided
+    if (upsert.status !== undefined) {
+      exprAttrNames["#status"] = "status";
+      setParts.push("#status = :status");
+      exprAttrValues[":status"] = upsert.status;
+
+      setParts.push("supplierStatus = :supplierStatus");
+      exprAttrValues[":supplierStatus"] =
+        `${upsert.supplierId}#${upsert.status}`;
+
+      // supplierStatusSk should replicate createdAt
+      setParts.push(
+        "supplierStatusSk = if_not_exists(supplierStatusSk, :supplierStatusSk)",
+      );
+      exprAttrValues[":supplierStatusSk"] = now.toISOString();
+    }
+
+    // fields that could be updated
+
+    if (upsert.specificationId !== undefined) {
+      setParts.push("specificationId = :specificationId");
+      exprAttrValues[":specificationId"] = upsert.specificationId;
+    }
+
+    if (upsert.url !== undefined) {
+      setParts.push("#url = :url");
+      exprAttrNames["#url"] = "url";
+      exprAttrValues[":url"] = upsert.url;
+    }
+
+    if (upsert.groupId !== undefined) {
+      setParts.push("groupId = :groupId");
+      exprAttrValues[":groupId"] = upsert.groupId;
+    }
+
+    if (upsert.reasonCode !== undefined) {
+      setParts.push("reasonCode = :reasonCode");
+      exprAttrValues[":reasonCode"] = upsert.reasonCode;
+    }
+    if (upsert.reasonText !== undefined) {
+      setParts.push("reasonText = :reasonText");
+      exprAttrValues[":reasonText"] = upsert.reasonText;
+    }
+
+    const updateExpression = `SET ${setParts.join(", ")}`;
+
+    const command = new UpdateCommand({
+      TableName: this.config.lettersTableName,
+      Key: { supplierId: upsert.supplierId, id: upsert.id },
+      UpdateExpression: updateExpression,
+      ExpressionAttributeNames: exprAttrNames,
+      ExpressionAttributeValues: exprAttrValues,
+      ReturnValues: "ALL_NEW",
+    });
+
+    const result = await this.ddbClient.send(command);
+
+    if (!result.Attributes) {
+      throw new Error("upsertLetter: no attributes returned");
+    }
+
+    this.log.debug({ exprAttrValues }, `Upsert to letter=${upsert.id}`);
+    return LetterSchema.parse(result.Attributes);
+  }
 }

internal/datastore/src/types.ts

@@ -58,6 +58,29 @@ export const LetterSchema = LetterSchemaBase.extend({
 export type Letter = z.infer<typeof LetterSchema>;
 export type LetterBase = z.infer<typeof LetterSchemaBase>;
 
+export type InsertLetter = Omit<
+  Letter,
+  "ttl" | "supplierStatus" | "supplierStatusSk"
+>;
+export type UpdateLetter = {
+  id: string;
+  supplierId: string;
+  status: Letter["status"];
+  reasonCode?: string;
+  reasonText?: string;
+};
+export type UpsertLetter = {
+  id: string;
+  supplierId: string;
+  // fields that might set/overwrite
+  status?: Letter["status"];
+  specificationId?: string;
+  groupId?: string;
+  url?: string;
+  reasonCode?: string;
+  reasonText?: string;
+};
+
 export const MISchemaBase = z.object({
   id: z.string(),
   lineItem: z.string(),