CCM-17221: Add priority field to LetterVariant schema

[m-houston]

Description

The supplier configuration schema currently has no concept of priority across letter variants. As NHS Notify scales to support more suppliers and higher message volumes, the ability to prioritise certain letter variants (e.g. urgent clinical communications) over others is necessary to meet SLA and contractual requirements.

This ticket introduces a priority field to the LetterVariant config schema. The field uses a 1–100 integer scale where lower values represent higher priority (i.e. 1 is the highest priority). This value will be used by the letter processing system to order pending letters in the queue and allow higher-priority letters to be promoted ahead of lower-priority ones.

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

• This PR includes code generated by a coding agent

---

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 a priority field to the LetterVariant schema so letter variants can be ordered for supplier dispatch/queueing using a 1–100 integer scale (lower number = higher priority), with a default applied when omitted.

Changes:

• Extend LetterVariant Zod schema with priority: int(1..100) defaulting to 50.
• Update examples and unit tests across packages to include/validate priority (range checks, integer enforcement, defaulting).
• Bump @nhsdigital/nhs-notify-event-schemas-supplier-config package version to 1.1.0.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
packages/events/src/domain/letter-variant.ts	Adds priority field (validated + defaulted) to the core LetterVariant schema.
packages/events/src/events/tests/letter-variant-events.test.ts	Extends event fixtures and adds validation tests for priority (int/range/default).
packages/events/src/examples/specification-examples.ts	Updates example LetterVariant objects to include priority values.
packages/file-store/src/tests/config-store-validator.test.ts	Updates mocked schema and adds validator coverage for out-of-range priority.
packages/event-builder/src/tests/letter-variant-event-builder.test.ts	Updates builder test input to include priority in LetterVariant partial.
packages/events/package.json	Version bump to reflect the schema change.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.