CCM-13116 Letter queue operations

[stevebux]

Description

Context

Type of changes

• Refactoring (non-breaking change)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would change existing functionality)
• Bug fix (non-breaking change which fixes an issue)

Checklist

• I am familiar with the contributing guidelines
• I have followed the code style of the project
• I have added tests to cover my changes
• I have updated the documentation accordingly
• This PR is a result of pair or mob programming
• If I have used the 'skip-trivy-package' label I have done so responsibly and in the knowledge that this is being fixed as part of a separate ticket/PR.

---

Sensitive Information Declaration

To ensure the utmost confidentiality and protect your and others privacy, we kindly ask you to NOT including PII (Personal Identifiable Information) / PID (Personal Identifiable Data) or any other sensitive data in this PR (Pull Request) and the codebase changes. We will remove any PR that do contain any sensitive information. We really appreciate your cooperation in this matter.

• I confirm that neither PII/PID nor sensitive data are included in this PR and the codebase changes.

[Copilot]

Pull request overview

This PR shifts “get letters” behaviour to be backed by a dedicated DynamoDB letter queue table (with visibility-style timestamp updates) and extends the update-letter-queue Lambda to both add newly pending letters and remove letters when they transition out of PENDING.

Changes:

• Extend update-letter-queue to insert pending letters on INSERT and delete queued letters when status changes away from PENDING on MODIFY.
• Update API get-letters flow to read from the queue table and update each returned letter’s queueTimestamp using LETTER_QUEUE_VISIBILITY_TIMEOUT.
• Expand LetterQueueRepository with deleteLetter, getLetters, and updateLetterTimestamp, plus new datastore error types and Terraform updates for table/index/env/permissions.

Reviewed changes

Copilot reviewed 25 out of 28 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/e2e-tests/poetry.lock	Bumps Python dependency (authlib).
package.json	Adds npm override for a transitive dependency.
package-lock.json	Lockfile refresh with multiple dependency bumps.
lambdas/update-letter-queue/src/update-letter-queue.ts	Adds delete-on-status-change path and refactors record processing.
lambdas/update-letter-queue/src/tests/update-letter-queue.test.ts	Adds coverage for delete behaviour and replay handling.
lambdas/api-handler/src/services/letter-operations.ts	Replaces “get letters” logic with queue-backed getPendingLetters + timestamp update.
lambdas/api-handler/src/services/tests/letter-operations.test.ts	Updates tests for queue-backed fetch and timestamp update calls.
lambdas/api-handler/src/handlers/get-letters.ts	Switches handler to getPendingLetters and queue repo.
lambdas/api-handler/src/handlers/tests/get-letters.test.ts	Updates mocks/expectations for queue-backed retrieval.
lambdas/api-handler/src/config/env.ts	Adds required env vars for queue table + visibility timeout.
lambdas/api-handler/src/config/deps.ts	Wires LetterQueueRepository into the API handler deps container.
lambdas/api-handler/src/config/tests/env.test.ts	Updates env var test coverage for new required vars.
lambdas/api-handler/src/config/tests/deps.test.ts	Verifies LetterQueueRepository is constructed with correct config.
internal/datastore/src/types.ts	Introduces PendingLetterBase (schema/type) for queue writes.
internal/datastore/src/letter-repository.ts	Removes supplier/status list methods now replaced by queue operations.
internal/datastore/src/letter-queue-repository.ts	Adds delete, query-by-queueTimestamp, and timestamp update operations.
internal/datastore/src/letter-does-not-exist-error.ts	Adds explicit error type for missing queue items.
internal/datastore/src/letter-already-exists-error.ts	Adds explicit error type for duplicate queue items.
internal/datastore/src/index.ts	Updates exports to include new error types and queue repo export.
internal/datastore/src/test/letter-repository.test.ts	Removes tests for removed list/query methods.
internal/datastore/src/test/letter-queue-repository.test.ts	Adds tests for delete/get/update timestamp behaviour.
internal/datastore/src/test/db.ts	Renames LSI to queueTimestamp-index for queue ordering.
infrastructure/terraform/components/api/module_lambda_update_letter_queue.tf	Adds dynamodb:DeleteItem permission for queue maintenance.
infrastructure/terraform/components/api/module_lambda_get_letters.tf	Switches permissions/resources to queue table + adds UpdateItem.
infrastructure/terraform/components/api/locals.tf	Adds queue env vars and visibility timeout to common Lambda env.
infrastructure/terraform/components/api/ddb_table_letter_queue.tf	Adjusts primary key to (supplierId, letterId) + LSI on queueTimestamp.
infrastructure/terraform/components/api/README.md	Updates referenced shared-module versions.
.vscode/settings.json	Pins workspace TypeScript SDK to local node_modules.

---

You can also share your feedback on Copilot code review. Take the survey.