Feature/ccm 13906 urgent letter priority

[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

Adds support for urgent letter prioritisation by propagating a priority value through supplier allocation and upsert flows, and by updating the letter-queue sort/index strategy so queued letters can be ordered by priority.

Changes:

• Add priority to supplier variant mapping and to the SQS message envelope passed from supplier-allocator → upsert-letter.
• Persist priority on letters/pending-letters and introduce queueSortOrderSk to support priority-ordered queueing.
• Emit per-supplier/per-priority allocation metrics (EMF) from the supplier-allocator Lambda.

Reviewed changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
package-lock.json	Adds aws-embedded-metrics dependency.
lambdas/upsert-letter/src/handler/upsert-handler.ts	Requires/uses supplierSpec.priority and writes priority onto inserted letters.
lambdas/upsert-letter/src/handler/tests/upsert-handler.test.ts	Updates tests to include/assert priority.
lambdas/supplier-allocator/src/handler/allocate-handler.ts	Adds priority to SupplierSpec, forwards it, and emits EMF metrics by supplier+priority.
lambdas/supplier-allocator/src/handler/tests/allocate-handler.test.ts	Adds assertions around forwarded priority and emitted metrics.
lambdas/supplier-allocator/src/config/env.ts	Extends VARIANT_MAP schema to require bounded priority.
lambdas/supplier-allocator/src/config/tests/env.test.ts	Updates env parsing tests for priority.
lambdas/supplier-allocator/package.json	Adds aws-embedded-metrics dependency.
internal/datastore/src/types.ts	Adds optional priority and introduces queueSortOrderSk on PendingLetter.
internal/datastore/src/letter-queue-repository.ts	Builds queueSortOrderSk from priority+timestamp when enqueueing.
internal/datastore/src/test/letter-queue-repository.test.ts	Adds test coverage for padded/defaulted priority in queueSortOrderSk.
internal/datastore/src/test/db.ts	Updates test DynamoDB table definition to use queueSortOrderSk in the LSI.
infrastructure/terraform/components/api/variables.tf	Extends letter_variant_map objects to include priority.
infrastructure/terraform/components/api/ddb_table_letter_queue.tf	Updates the letter-queue LSI sort key to the new queue sort attribute.
infrastructure/terraform/components/api/README.md	Updates generated input docs for the new letter_variant_map shape.
.vscode/settings.json	Pins the TypeScript SDK path for the workspace.

---

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

[stevebux]

This is to prevent failing tests from retrying multiple times, and then hitting the 30 second timeout

[nhsd-david-wass]

Looks good - have you created a PR in https://github.com/NHSDigital/nhs-notify-internal to update infrastructure/terraform/etc/group_nhs-notify-supplier-api-dev.tfvars ?

If you do, you can update your build to reference that PR, so everything works in your dynamic environement - see this commit on my branch:

6245f1a