init

Author: alexnuttall

internal/events/schemas/supplier-api.yaml

@@ -49,10 +49,10 @@ components:
         This indicates that a letter has been accepted for processing by a supplier.
       contentType: application/json
       payload:
-        $ref: './events/letter.ACCEPTED.schema.json'
+        $ref: './events/letter.accepted.schema.json'
       examples:
         - payload:
-            $ref: './examples/letter.ACCEPTED.json'
+            $ref: './examples/letter.accepted.json'
 
     letter-cancelled:
       name: letter-cancelled
@@ -63,7 +63,7 @@ components:
         This indicates that a letter has been cancelled and will not be printed or dispatched.
       contentType: application/json
       payload:
-        $ref: './events/letter.CANCELLED.schema.json'
+        $ref: './events/letter.cancelled.schema.json'
 
     letter-delivered:
       name: letter-delivered
@@ -74,7 +74,7 @@ components:
         This indicates that a letter has been delivered to the recipient.
       contentType: application/json
       payload:
-        $ref: './events/letter.DELIVERED.schema.json'
+        $ref: './events/letter.delivered.schema.json'
 
     letter-dispatched:
       name: letter-dispatched
@@ -85,7 +85,7 @@ components:
         This indicates that a letter has been dispatched from the supplier to a down-stream access (DSA) provider.
       contentType: application/json
       payload:
-        $ref: './events/letter.DISPATCHED.schema.json'
+        $ref: './events/letter.dispatched.schema.json'
 
     letter-enclosed:
       name: letter-enclosed
@@ -96,7 +96,7 @@ components:
         This indicates that a letter has been printed and packaged in an envelope.
       contentType: application/json
       payload:
-        $ref: './events/letter.ENCLOSED.schema.json'
+        $ref: './events/letter.enclosed.schema.json'
 
     letter-failed:
       name: letter-failed
@@ -107,7 +107,7 @@ components:
         This indicates that a letter has failed to be processed by a supplier.
       contentType: application/json
       payload:
-        $ref: './events/letter.FAILED.schema.json'
+        $ref: './events/letter.failed.schema.json'
 
     letter-forwarded:
       name: letter-forwarded
@@ -118,10 +118,10 @@ components:
         This indicates that a letter has been forwarded to another supplier for processing.
       contentType: application/json
       payload:
-        $ref: './events/letter.FORWARDED.schema.json'
+        $ref: './events/letter.forwarded.schema.json'
       examples:
         - payload:
-            $ref: './examples/letter.FORWARDED.json'
+            $ref: './examples/letter.forwarded.json'
 
     letter-pending:
       name: letter-pending
@@ -132,7 +132,7 @@ components:
         This indicates that a letter has been queued for processing by a supplier.
       contentType: application/json
       payload:
-        $ref: './events/letter.PENDING.schema.json'
+        $ref: './events/letter.pending.schema.json'
 
     letter-printed:
       name: letter-printed
@@ -143,7 +143,7 @@ components:
         This indicates that a letter has been printed by the supplier.
       contentType: application/json
       payload:
-        $ref: './events/letter.PRINTED.schema.json'
+        $ref: './events/letter.printed.schema.json'
 
     letter-rejected:
       name: letter-rejected
@@ -154,7 +154,7 @@ components:
         This indicates that a letter has been rejected by the supplier and will not be processed.
       contentType: application/json
       payload:
-        $ref: './events/letter.REJECTED.schema.json'
+        $ref: './events/letter.rejected.schema.json'
 
     letter-returned:
       name: letter-returned
@@ -165,10 +165,10 @@ components:
         This indicates that a letter has been returned to the supplier.
       contentType: application/json
       payload:
-        $ref: './events/letter.RETURNED.schema.json'
+        $ref: './events/letter.returned.schema.json'
       examples:
         - payload:
-            $ref: './examples/letter.RETURNED.json'
+            $ref: './examples/letter.returned.json'
 
     letter-any:
       name: letter-any
@@ -188,7 +188,7 @@ components:
         This indicates that MI data has been submitted to the NHS Notify Supplier API.
       contentType: application/json
       payload:
-        $ref: './events/mi.SUBMITTED.schema.json'
+        $ref: './events/mi.submitted.schema.json'
 
   schemas:
     letter:

internal/events/src/domain/letter.ts

@@ -107,6 +107,16 @@ The identifier will be included as the origin domain in the subject of any corre
           "Optional human-readable reason for the status change, if applicable.",
         examples: ["Undeliverable", "Recipient moved"],
       }),
+
+    supplierId: z
+      .string()
+      .optional()
+      .meta({
+        title: "Supplier ID",
+        description:
+          "Optional identifier for the supplier handling this letter, if applicable.",
+        examples: ["supplier-12345"],
+      }),
   })
   .meta({
     title: "Letter",

internal/events/src/events/__tests__/event-envelope.test.ts

@@ -7,12 +7,12 @@ describe("EventEnvelope schema validation", () => {
 
   const baseValidEnvelope: Envelope = {
     dataschema:
-      "https://notify.nhs.uk/cloudevents/schemas/supplier-api/order.READ.1.0.0.schema.json",
+      "https://notify.nhs.uk/cloudevents/schemas/supplier-api/order.read.1.0.0.schema.json",
     specversion: "1.0",
     id: "6f1c2a53-3d54-4a0a-9a0b-0e9ae2d4c111",
     source: "/data-plane/supplier-api/ordering",
     subject: "order/769acdd4",
-    type: "uk.nhs.notify.supplier-api.order.READ.v1",
+    type: "uk.nhs.notify.supplier-api.order.read.v1",
     time: "2025-10-01T10:15:30.000Z",
     data: {
       "notify-payload": {
@@ -230,7 +230,7 @@ describe("EventEnvelope schema validation", () => {
 
   describe("subject prefix validation", () => {
     const $EnvelopeWithPrefix = EventEnvelope(
-      "letter.CREATED",
+      "letter.created",
       "letter",
       z.any(),
       ["CREATED"],
@@ -240,9 +240,9 @@ describe("EventEnvelope schema validation", () => {
     const baseLetterEnvelope = {
       specversion: "1.0" as const,
       id: "6f1c2a53-3d54-4a0a-9a0b-0e02b2c3d479",
-      type: "uk.nhs.notify.supplier-api.letter.CREATED.v1" as const,
+      type: "uk.nhs.notify.supplier-api.letter.created.v1" as const,
       dataschema:
-        "https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.CREATED.1.0.0.schema.json",
+        "https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.created.1.0.0.schema.json",
       source: "/data-plane/supplier-api/letters",
       time: "2025-10-01T10:15:30.000Z",
       data: { status: "CREATED" },
@@ -286,16 +286,16 @@ describe("EventEnvelope schema validation", () => {
     });
 
     it("should accept subject without prefix when no prefix is specified", () => {
-      const $EnvelopeNoPrefix = EventEnvelope("order.READ", "order", z.any(), [
+      const $EnvelopeNoPrefix = EventEnvelope("order.read", "order", z.any(), [
         "READ",
       ]);
 
       const envelope = {
         specversion: "1.0" as const,
         id: "6f1c2a53-3d54-4a0a-9a0b-0e9ae2d4c111",
-        type: "uk.nhs.notify.supplier-api.order.READ.v1" as const,
+        type: "uk.nhs.notify.supplier-api.order.read.v1" as const,
         dataschema:
-          "https://notify.nhs.uk/cloudevents/schemas/supplier-api/order.READ.1.0.0.schema.json",
+          "https://notify.nhs.uk/cloudevents/schemas/supplier-api/order.read.1.0.0.schema.json",
         source: "/data-plane/supplier-api/ordering",
         subject: "order/769acdd4",
         time: "2025-10-01T10:15:30.000Z",
@@ -313,7 +313,7 @@ describe("EventEnvelope schema validation", () => {
 
     it("should accept various prefix formats", () => {
       const $EnvelopeMultiSegmentPrefix = EventEnvelope(
-        "letter.CREATED",
+        "letter.created",
         "letter",
         z.any(),
         ["CREATED"],

internal/events/src/events/__tests__/letter-status-change-events.test.ts

@@ -12,21 +12,24 @@ describe("LetterStatus event validations", () => {
   it.each(["ACCEPTED", "FORWARDED", "RETURNED"])(
     "should parse %s letter statuses successfully",
     (status) => {
-      const json = readJson(`letter.${status}.json`);
+      const statusLower = status.toLowerCase();
+
+      const json = readJson(`letter.${statusLower}.json`);
 
       const { data: event, error } =
-        letterEventMap[`letter.${status}`].safeParse(json);
+        letterEventMap[`letter.${statusLower}`].safeParse(json);
+
       expect(error).toBeUndefined();
       expect(event).toBeDefined();
       expect(event).toEqual(
         expect.objectContaining({
-          type: `uk.nhs.notify.supplier-api.letter.${status}.v1`,
+          type: `uk.nhs.notify.supplier-api.letter.${statusLower}.v1`,
           specversion: "1.0",
           source: "/data-plane/supplier-api/prod/update-status",
           id: "23f1f09c-a555-4d9b-8405-0b33490bc920",
           time: "2025-08-28T08:45:00.000Z",
           datacontenttype: "application/json",
-          dataschema: `https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.${status}.1.0.0.schema.json`,
+          dataschema: `https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.${statusLower}.1.0.0.schema.json`,
           subject:
             "letter-origin/letter-rendering/letter/f47ac10b-58cc-4372-a567-0e02b2c3d479",
           data: expect.objectContaining({
@@ -46,9 +49,10 @@ describe("LetterStatus event validations", () => {
   );
 
   it("should parse reason code and text correctly for returned mail", () => {
-    const json = readJson("letter.RETURNED.json");
+    const json = readJson("letter.returned.json");
+
+    const event = letterEventMap["letter.returned"].parse(json);
 
-    const event = letterEventMap["letter.RETURNED"].parse(json);
     expect(event).toBeDefined();
     expect(event.data).toEqual(
       expect.objectContaining({
@@ -59,9 +63,10 @@ describe("LetterStatus event validations", () => {
   });
 
   it("should parse reason code and text correctly for forwarded mail", () => {
-    const json = readJson("letter.FORWARDED.json");
+    const json = readJson("letter.forwarded.json");
+
+    const event = letterEventMap["letter.forwarded"].parse(json);
 
-    const event = letterEventMap["letter.FORWARDED"].parse(json);
     expect(event).toBeDefined();
     expect(event.data).toEqual(
       expect.objectContaining({
@@ -71,18 +76,18 @@ describe("LetterStatus event validations", () => {
     );
   });
 
-  it("should throw error for letter.ACCEPTED event with missing sourceSubject", () => {
-    const json = readJson("letter.ACCEPTED-with-missing-fields.json");
+  it("should throw error for letter.accepted event with missing sourceSubject", () => {
+    const json = readJson("letter.accepted-with-missing-fields.json");
 
-    expect(() => letterEventMap["letter.ACCEPTED"].parse(json)).toThrow(
+    expect(() => letterEventMap["letter.accepted"].parse(json)).toThrow(
       "subject",
     );
   });
 
-  it("should throw error for letter.ACCEPTED event with invalid major schema version", () => {
-    const json = readJson("letter.ACCEPTED-with-invalid-major-version.json");
+  it("should throw error for letter.accepted event with invalid major schema version", () => {
+    const json = readJson("letter.accepted-with-invalid-major-version.json");
 
-    expect(() => letterEventMap["letter.ACCEPTED"].parse(json)).toThrow(
+    expect(() => letterEventMap["letter.accepted"].parse(json)).toThrow(
       "dataschema",
     );
   });

internal/events/src/events/__tests__/mi-events.test.ts

@@ -9,22 +9,22 @@ function readJson(filename: string): unknown {
 }
 
 describe("MI event validations", () => {
-  it("should parse mi.SUBMITTED event successfully", () => {
-    const json = readJson("mi.SUBMITTED.json");
+  it("should parse mi.submitted event successfully", () => {
+    const json = readJson("mi.submitted.json");
 
     const { data: event, error } = $MISubmittedEvent.safeParse(json);
     expect(error).toBeUndefined();
     expect(event).toBeDefined();
     expect(event).toEqual(
       expect.objectContaining({
-        type: "uk.nhs.notify.supplier-api.mi.SUBMITTED.v1",
+        type: "uk.nhs.notify.supplier-api.mi.submitted.v1",
         specversion: "1.0",
         source: "/data-plane/supplier-api/prod/submit-mi",
         id: "8f2c3b44-4e65-5b1b-a678-1f0bf3d4d222",
         time: "2025-11-16T10:30:00.000Z",
         datacontenttype: "application/json",
         dataschema:
-          "https://notify.nhs.uk/cloudevents/schemas/supplier-api/mi.SUBMITTED.1.0.0.schema.json",
+          "https://notify.nhs.uk/cloudevents/schemas/supplier-api/mi.submitted.1.0.0.schema.json",
         subject: "mi/mi-test-001",
         data: expect.objectContaining({
           id: "mi-test-001",
@@ -40,8 +40,8 @@ describe("MI event validations", () => {
     );
   });
 
-  it("should parse minimal mi.SUBMITTED event successfully", () => {
-    const json = readJson("mi.SUBMITTED-minimal.json");
+  it("should parse minimal mi.submitted event successfully", () => {
+    const json = readJson("mi.submitted-minimal.json");
 
     const event = $MISubmittedEvent.parse(json);
     expect(event).toBeDefined();
@@ -59,7 +59,7 @@ describe("MI event validations", () => {
   });
 
   it("should parse MI data fields correctly", () => {
-    const json = readJson("mi.SUBMITTED.json");
+    const json = readJson("mi.submitted.json");
 
     const event = $MISubmittedEvent.parse(json);
     expect(event).toBeDefined();
@@ -72,14 +72,14 @@ describe("MI event validations", () => {
     expect(event.data.groupId).toBe("group-456");
   });
 
-  it("should throw error for mi.SUBMITTED event with missing subject", () => {
-    const json = readJson("mi.SUBMITTED-with-missing-subject.json");
+  it("should throw error for mi.submitted event with missing subject", () => {
+    const json = readJson("mi.submitted-with-missing-subject.json");
 
     expect(() => $MISubmittedEvent.parse(json)).toThrow("subject");
   });
 
-  it("should throw error for mi.SUBMITTED event with invalid major schema version", () => {
-    const json = readJson("mi.SUBMITTED-with-invalid-major-version.json");
+  it("should throw error for mi.submitted event with invalid major schema version", () => {
+    const json = readJson("mi.submitted-with-invalid-major-version.json");
 
     expect(() => $MISubmittedEvent.parse(json)).toThrow("dataschema");
   });

internal/events/src/events/__tests__/testData/letter.ACCEPTED-with-invalid-major-version.json

@@ -5,14 +5,14 @@
     "origin": {
       "domain": "letter-rendering",
       "event": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
-      "source": "/data-plane/letter-rendering/prod/render-pdf",
+      "source": "/data-plane/letter-rendering/prod/letter-renderer",
       "subject": "client/00f3b388-bbe9-41c9-9e76-052d37ee8988/letter-request/0o5Fs0EELR0fUjHjbCnEtdUwQe4_0o5Fs0EELR0fUjHjbCnEtdUwQe5"
     },
     "specificationId": "1y3q9v1zzzz",
     "status": "ACCEPTED"
   },
   "datacontenttype": "application/json",
-  "dataschema": "https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.ACCEPTED.0.1.0.schema.json",
+  "dataschema": "https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.accepted.0.1.0.schema.json",
   "id": "23f1f09c-a555-4d9b-8405-0b33490bc920",
   "recordedtime": "2025-08-28T08:45:00.000Z",
   "severitynumber": 2,
@@ -22,5 +22,5 @@
   "subject": "letter-origin/letter-rendering/letter/f47ac10b-58cc-4372-a567-0e02b2c3d479",
   "time": "2025-08-28T08:45:00.000Z",
   "traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
-  "type": "uk.nhs.notify.supplier-api.letter.ACCEPTED.v1"
+  "type": "uk.nhs.notify.supplier-api.letter.accepted.v1"
 }

internal/events/src/events/__tests__/testData/letter.ACCEPTED-with-missing-fields.json

@@ -5,13 +5,13 @@
     "origin": {
       "domain": "letter-rendering",
       "event": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
-      "source": "/data-plane/letter-rendering/prod/render-pdf"
+      "source": "/data-plane/letter-rendering/prod/letter-renderer"
     },
     "specificationId": "1y3q9v1zzzz",
     "status": "ACCEPTED"
   },
   "datacontenttype": "application/json",
-  "dataschema": "https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.ACCEPTED.1.0.0.schema.json",
+  "dataschema": "https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.accepted.1.0.0.schema.json",
   "id": "23f1f09c-a555-4d9b-8405-0b33490bc920",
   "recordedtime": "2025-08-28T08:45:00.000Z",
   "severitynumber": 2,
@@ -21,5 +21,5 @@
   "subject": "letter-origin/letter-rendering/letter/f47ac10b-58cc-4372-a567-0e02b2c3d479",
   "time": "2025-08-28T08:45:00.000Z",
   "traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
-  "type": "uk.nhs.notify.supplier-api.letter.ACCEPTED.v1"
+  "type": "uk.nhs.notify.supplier-api.letter.accepted.v1"
 }