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

@@ -1,12 +1,15 @@
+import { InsertLetter, Letter, UpdateLetter, UpsertLetter } from "../types";
 import { createTables, DBContext, deleteTables, setupDynamoDBContainer } from './db';
 import { LetterRepository } from '../letter-repository';
-import { Letter } from '../types';
 import { Logger } from 'pino';
 import { createTestLogger, LogStream } from './logs';
 import { PutCommand } from '@aws-sdk/lib-dynamodb';
-import { LetterDto } from '../../../../lambdas/api-handler/src/contracts/letters';
 
-function createLetter(supplierId: string, letterId: string, status: Letter['status'] = 'PENDING'): Omit<Letter, 'ttl' | 'supplierStatus' | 'supplierStatusSk'> {
+function createLetter(
+  supplierId: string,
+  letterId: string,
+  status: Letter["status"] = "PENDING",
+): InsertLetter {
   return {
     id: letterId,
     supplierId: supplierId,
@@ -107,14 +110,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', 'letter1');
     expect(updatedLetter.status).toBe('REJECTED');
@@ -132,7 +135,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'
@@ -145,7 +148,7 @@ describe('LetterRepository', () => {
   });
 
   test('can\'t update a letter that does not exist', async () => {
-    const letterDto: LetterDto = {
+    const letterDto: UpdateLetter = {
       id: 'letter1',
       supplierId: 'supplier1',
       status: 'DELIVERED'
@@ -160,7 +163,7 @@ describe('LetterRepository', () => {
       lettersTableName: 'nonexistent-table'
     });
 
-    const letterDto: LetterDto = {
+    const letterDto: UpdateLetter = {
       id: 'letter1',
       supplierId: 'supplier1',
       status: 'DELIVERED'
@@ -190,7 +193,7 @@ describe('LetterRepository', () => {
     const pendingLetters = await letterRepository.getLettersByStatus('supplier1', 'PENDING');
     expect(pendingLetters.letters).toHaveLength(2);
 
-    const letterDto: LetterDto = {
+    const letterDto: UpdateLetter = {
       id: 'letter1',
       supplierId: 'supplier1',
       status: 'DELIVERED'
@@ -367,4 +370,119 @@ describe('LetterRepository', () => {
     await expect(misconfiguredRepository.putLetterBatch([createLetter('supplier1', 'letter1')]))
       .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

@@ -7,10 +7,17 @@ import {
   UpdateCommand,
   UpdateCommandOutput
 } from '@aws-sdk/lib-dynamodb';
-import { Letter, LetterBase, LetterSchema, LetterSchemaBase } from './types';
 import { Logger } from 'pino';
 import { z } from 'zod';
-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>,
@@ -32,7 +39,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}`,
@@ -54,7 +61,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++) {
 
@@ -134,7 +141,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}`);
     let result: UpdateCommandOutput;
     try {
@@ -201,4 +208,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

@@ -47,6 +47,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(),

lambdas/api-handler/src/contracts/letters.ts

@@ -15,17 +15,17 @@ export const LetterStatusSchema = z.enum([
   'DELIVERED'
 ]);
 
-export const LetterDtoSchema = z.object({
-  id: z.string(),
-  status: LetterStatusSchema,
-  supplierId: z.string(),
-  specificationId: z.string().optional(),
-  groupId: z.string().optional(),
-  reasonCode: z.string().optional(),
-  reasonText: z.string().optional(),
-}).strict();
+export const UpdateLetterSchema = z
+  .object({
+    id: z.string(),
+    supplierId: z.string(),
+    status: LetterStatusSchema,
+    reasonCode: z.string().optional(),
+    reasonText: z.string().optional(),
+  })
+  .strict();
 
-export type LetterDto = z.infer<typeof LetterDtoSchema>;
+export type UpdateLetterCommand = z.infer<typeof UpdateLetterSchema>;
 
 export const PatchLetterRequestResourceSchema = z.object({
   id: z.string(),