Unify envelope with letter-rendering domain events using origin subject prefix

m-houston · m-houston · commit 218662e5be5d · 2025-10-17T23:20:38.000+01:00
diff --git a/internal/events/README.md b/internal/events/README.md
@@ -49,13 +49,13 @@ Defines the constrained CloudEvents 1.0 envelope used across Notify. It enforces
   `PENDING | ACCEPTED | REJECTED | PRINTED | ENCLOSED | CANCELLED | DISPATCHED | FAILED | RETURNED | DESTROYED | FORWARDED | DELIVERED`
 * `$Letter` domain object, extending a `DomainBase('Letter')` (see helpers package) with:
   * `domainId` (branded identifier)
-  * `sourceSubject` – original resource subject
+  * `origin` – resource identifiers from the origin domain
   * `status` – one of `$LetterStatus`
   * Optional `reasonCode`, `reasonText`
 
 ### 3. Per‑Status Event Schemas
 
-`letter-change-events.ts` programmatically creates a schema per status by extending `$EnvelopeProfile` and replacing `data` with the domain payload. Each schema enforces:
+`letter-events.ts` programmatically creates a schema per status by extending `$EnvelopeProfile` and replacing `data` with the domain payload. Each schema enforces:
 
 * `type = uk.nhs.notify.supplier-api.letter.<STATUS>.v1`
 * `dataschema` matches: `https://notify.nhs.uk/events/supplier-api/letter/<STATUS>/1.<minor>.<patch>.json`
@@ -128,15 +128,19 @@ const schema = statusChangeEvents[`letter.${status}`];
 const event = {
   specversion: '1.0',
   id: randomUUID(),
-  source: '/data-plane/supplier-api',
-  subject: 'customer/1b20f918-bb05-4c78-a4aa-5f6a3b8e0c91/letter/4a5a9cb5-1440-4a12-bd72-baa7cfecd111',
+  source: '/data-plane/supplier-api/prod/letter-status-change',
+  subject: 'origin/letter-rendering/letter/4a5a9cb5-1440-4a12-bd72-baa7cfecd111',
   type: 'uk.nhs.notify.supplier-api.letter.ACCEPTED.v1',
   time: new Date().toISOString(),
   dataschema: 'https://notify.nhs.uk/events/supplier-api/letter/ACCEPTED/1.0.0.json',
   dataschemaversion: '1.0.0',
   data: {
     domainId: 'abc123',
-    sourceSubject: 'customer/.../letter/...',
+    origin: {
+        domain: 'letter-rendering',
+        source: '/data-plane/letter-rendering/prod/render-pdf',
+        subject: 'origin/.../letter-request/...'
+    },
     status: 'ACCEPTED',
   },
   traceparent: '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01',
diff --git a/internal/events/schemas/events/letter.ACCEPTED.schema.json b/internal/events/schemas/events/letter.ACCEPTED.schema.json
@@ -40,7 +40,7 @@
       "title": "Event Subject",
       "description": "Resource path (no leading slash) within the source made of segments separated by '/'.",
       "examples": [
-        "customer/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
+        "origin/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
       ],
       "type": "string",
       "minLength": 5,
diff --git a/internal/events/schemas/events/letter.CANCELLED.schema.json b/internal/events/schemas/events/letter.CANCELLED.schema.json
@@ -40,7 +40,7 @@
       "title": "Event Subject",
       "description": "Resource path (no leading slash) within the source made of segments separated by '/'.",
       "examples": [
-        "customer/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
+        "origin/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
       ],
       "type": "string",
       "minLength": 5,
diff --git a/internal/events/schemas/events/letter.DELIVERED.schema.json b/internal/events/schemas/events/letter.DELIVERED.schema.json
@@ -40,7 +40,7 @@
       "title": "Event Subject",
       "description": "Resource path (no leading slash) within the source made of segments separated by '/'.",
       "examples": [
-        "customer/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
+        "origin/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
       ],
       "type": "string",
       "minLength": 5,
diff --git a/internal/events/schemas/events/letter.DISPATCHED.schema.json b/internal/events/schemas/events/letter.DISPATCHED.schema.json
@@ -40,7 +40,7 @@
       "title": "Event Subject",
       "description": "Resource path (no leading slash) within the source made of segments separated by '/'.",
       "examples": [
-        "customer/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
+        "origin/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
       ],
       "type": "string",
       "minLength": 5,
diff --git a/internal/events/schemas/events/letter.ENCLOSED.schema.json b/internal/events/schemas/events/letter.ENCLOSED.schema.json
@@ -40,7 +40,7 @@
       "title": "Event Subject",
       "description": "Resource path (no leading slash) within the source made of segments separated by '/'.",
       "examples": [
-        "customer/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
+        "origin/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
       ],
       "type": "string",
       "minLength": 5,
diff --git a/internal/events/schemas/events/letter.FAILED.schema.json b/internal/events/schemas/events/letter.FAILED.schema.json
@@ -40,7 +40,7 @@
       "title": "Event Subject",
       "description": "Resource path (no leading slash) within the source made of segments separated by '/'.",
       "examples": [
-        "customer/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
+        "origin/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
       ],
       "type": "string",
       "minLength": 5,
diff --git a/internal/events/schemas/events/letter.FORWARDED.schema.json b/internal/events/schemas/events/letter.FORWARDED.schema.json
@@ -40,7 +40,7 @@
       "title": "Event Subject",
       "description": "Resource path (no leading slash) within the source made of segments separated by '/'.",
       "examples": [
-        "customer/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
+        "origin/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
       ],
       "type": "string",
       "minLength": 5,
diff --git a/internal/events/schemas/events/letter.PENDING.schema.json b/internal/events/schemas/events/letter.PENDING.schema.json
@@ -40,7 +40,7 @@
       "title": "Event Subject",
       "description": "Resource path (no leading slash) within the source made of segments separated by '/'.",
       "examples": [
-        "customer/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
+        "origin/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
       ],
       "type": "string",
       "minLength": 5,
diff --git a/internal/events/schemas/events/letter.PRINTED.schema.json b/internal/events/schemas/events/letter.PRINTED.schema.json
@@ -40,7 +40,7 @@
       "title": "Event Subject",
       "description": "Resource path (no leading slash) within the source made of segments separated by '/'.",
       "examples": [
-        "customer/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
+        "origin/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
       ],
       "type": "string",
       "minLength": 5,
diff --git a/internal/events/schemas/events/letter.REJECTED.schema.json b/internal/events/schemas/events/letter.REJECTED.schema.json
@@ -40,7 +40,7 @@
       "title": "Event Subject",
       "description": "Resource path (no leading slash) within the source made of segments separated by '/'.",
       "examples": [
-        "customer/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
+        "origin/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
       ],
       "type": "string",
       "minLength": 5,
diff --git a/internal/events/schemas/events/letter.RETURNED.schema.json b/internal/events/schemas/events/letter.RETURNED.schema.json
@@ -40,7 +40,7 @@
       "title": "Event Subject",
       "description": "Resource path (no leading slash) within the source made of segments separated by '/'.",
       "examples": [
-        "customer/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
+        "origin/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d"
       ],
       "type": "string",
       "minLength": 5,
diff --git a/internal/events/schemas/examples/letter.DISPATCHED.json b/internal/events/schemas/examples/letter.DISPATCHED.json
@@ -3,7 +3,7 @@
     "domainId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
     "origin": {
       "source": "/data-plane/letter-rendering/prod/render-pdf",
-      "subject": "customer/00f3b388-bbe9-41c9-9e76-052d37ee8988/letter-rendering/letter-request/0o5Fs0EELR0fUjHjbCnEtdUwQe4_0o5Fs0EELR0fUjHjbCnEtdUwQe5"
+      "subject": "origin/00f3b388-bbe9-41c9-9e76-052d37ee8988/letter-rendering/letter-request/0o5Fs0EELR0fUjHjbCnEtdUwQe4_0o5Fs0EELR0fUjHjbCnEtdUwQe5"
     },
     "status": "DISPATCHED"
   },
@@ -16,7 +16,7 @@
   "severitytext": "INFO",
   "source": "/data-plane/supplier-api/prod/update-status",
   "specversion": "1.0",
-  "subject": "customer/letter-renderer/supplier-api/letter/f47ac10b-58cc-4372-a567-0e02b2c3d479",
+  "subject": "origin/letter-rendering/supplier-api/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.DISPATCHED.v1"
diff --git a/internal/events/src/domain/letter.ts b/internal/events/src/domain/letter.ts
@@ -20,11 +20,19 @@ export type LetterStatus = z.infer<typeof $LetterStatus>;
  */
 export const $Letter = DomainBase('Letter').extend({
   origin: z.object({
+    domain: z.string(),
     source: z.string(),
     subject: z.string()
   }).meta({
     title: "Letter origin",
-    description: "The source and subject of the original event that introduced the letter to the supplier-api domain.",
+    description: `The origin domain identifier, source and subject of the original event that introduced the letter to the supplier-api domain.
+
+The identifier will be included as the origin in the subject of any corresponding events emitted by the supplier-api domain.`,
+    examples: [{
+      domain: "letter-rendering",
+      source: "/data-plane/letter-rendering/prod/render-pdf",
+      subject: "customer/00f3b388-bbe9-41c9-9e76-052d37ee8988/letter-rendering/letter-request/0o5Fs0EELR0fUjHjbCnEtdUwQe4_0o5Fs0EELR0fUjHjbCnEtdUwQe5",
+    }]
   }),
   status: $LetterStatus,
   reasonCode: z.string().optional().meta({
diff --git a/internal/events/src/events/__tests__/letter-status-change-events.test.ts b/internal/events/src/events/__tests__/letter-status-change-events.test.ts
@@ -25,11 +25,11 @@ describe("LetterStatus event validations", () => {
         datacontenttype: "application/json",
         dataschema: "https://notify.nhs.uk/events/supplier-api/letter/ACCEPTED/1.0.0.json",
         dataschemaversion: "1.0.0",
-        subject: "customer/letter-renderer/supplier-api/letter/f47ac10b-58cc-4372-a567-0e02b2c3d479",
+        subject: "origin/letter-rendering/supplier-api/letter/f47ac10b-58cc-4372-a567-0e02b2c3d479",
         data: expect.objectContaining({
           origin: expect.objectContaining({
             source: "/data-plane/letter-rendering/prod/render-pdf",
-            subject: "customer/00f3b388-bbe9-41c9-9e76-052d37ee8988/letter-rendering/letter-request/0o5Fs0EELR0fUjHjbCnEtdUwQe4_0o5Fs0EELR0fUjHjbCnEtdUwQe5",
+            subject: "origin/00f3b388-bbe9-41c9-9e76-052d37ee8988/letter-rendering/letter-request/0o5Fs0EELR0fUjHjbCnEtdUwQe4_0o5Fs0EELR0fUjHjbCnEtdUwQe5",
           }),
           status: "ACCEPTED"
         })
diff --git a/internal/events/src/events/__tests__/testData/letter.ACCEPTED-valid.json b/internal/events/src/events/__tests__/testData/letter.ACCEPTED-valid.json
@@ -3,7 +3,7 @@
     "domainId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
     "origin": {
       "source": "/data-plane/letter-rendering/prod/render-pdf",
-      "subject": "customer/00f3b388-bbe9-41c9-9e76-052d37ee8988/letter-rendering/letter-request/0o5Fs0EELR0fUjHjbCnEtdUwQe4_0o5Fs0EELR0fUjHjbCnEtdUwQe5"
+      "subject": "origin/00f3b388-bbe9-41c9-9e76-052d37ee8988/letter-rendering/letter-request/0o5Fs0EELR0fUjHjbCnEtdUwQe4_0o5Fs0EELR0fUjHjbCnEtdUwQe5"
     },
     "status": "ACCEPTED"
   },
@@ -16,7 +16,7 @@
   "severitytext": "INFO",
   "source": "/data-plane/supplier-api/prod/update-status",
   "specversion": "1.0",
-  "subject": "customer/letter-renderer/supplier-api/letter/f47ac10b-58cc-4372-a567-0e02b2c3d479",
+  "subject": "origin/letter-rendering/supplier-api/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"
diff --git a/internal/events/src/events/__tests__/testData/letter.ACCEPTED-with-invalid-major-version.json b/internal/events/src/events/__tests__/testData/letter.ACCEPTED-with-invalid-major-version.json
@@ -3,7 +3,7 @@
     "domainId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
     "origin": {
       "source": "/data-plane/letter-rendering/prod/render-pdf",
-      "subject": "customer/00f3b388-bbe9-41c9-9e76-052d37ee8988/letter-rendering/letter-request/0o5Fs0EELR0fUjHjbCnEtdUwQe4_0o5Fs0EELR0fUjHjbCnEtdUwQe5"
+      "subject": "origin/00f3b388-bbe9-41c9-9e76-052d37ee8988/letter-rendering/letter-request/0o5Fs0EELR0fUjHjbCnEtdUwQe4_0o5Fs0EELR0fUjHjbCnEtdUwQe5"
     },
     "status": "ACCEPTED"
   },
@@ -16,7 +16,7 @@
   "severitytext": "INFO",
   "source": "/data-plane/supplier-api/prod/update-status",
   "specversion": "1.0",
-  "subject": "customer/letter-renderer/supplier-api/letter/f47ac10b-58cc-4372-a567-0e02b2c3d479",
+  "subject": "origin/letter-rendering/supplier-api/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"
diff --git a/internal/events/src/events/__tests__/testData/letter.ACCEPTED-with-missing-fields.json b/internal/events/src/events/__tests__/testData/letter.ACCEPTED-with-missing-fields.json
@@ -2,7 +2,7 @@
   "data": {
     "domainId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
     "origin": {
-      "subject": "customer/00f3b388-bbe9-41c9-9e76-052d37ee8988/letter-rendering/letter-request/0o5Fs0EELR0fUjHjbCnEtdUwQe4_0o5Fs0EELR0fUjHjbCnEtdUwQe5"
+      "subject": "origin/00f3b388-bbe9-41c9-9e76-052d37ee8988/letter-rendering/letter-request/0o5Fs0EELR0fUjHjbCnEtdUwQe4_0o5Fs0EELR0fUjHjbCnEtdUwQe5"
     },
     "status": "ACCEPTED"
   },
@@ -15,7 +15,7 @@
   "severitytext": "INFO",
   "source": "/data-plane/supplier-api/prod/update-status",
   "specversion": "1.0",
-  "subject": "customer/letter-renderer/supplier-api/letter/f47ac10b-58cc-4372-a567-0e02b2c3d479",
+  "subject": "origin/letter-rendering/supplier-api/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"
diff --git a/internal/events/src/events/envelope-profile.ts b/internal/events/src/events/envelope-profile.ts
@@ -34,7 +34,7 @@ export const $EnvelopeProfile = z
         description:
           "Resource path (no leading slash) within the source made of segments separated by '/'.",
         examples: [
-          "customer/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d",
+          "origin/920fca11-596a-4eca-9c47-99f624614658/order/769acdd4-6a47-496f-999f-76a6fd2c3959/item/4f5e17c0-ec57-4cee-9a86-14580cf5af7d",
         ],
       }),
     type: z
@@ -200,14 +200,14 @@ export const $EnvelopeProfile = z
     if (
       /^\/data-plane/.test(obj.source) &&
       // eslint-disable-next-line sonarjs/regex-complexity
-      !/^customer(\/[^\/]+)+$/.test(
+      !/^origin(\/[^\/]+)+$/.test(
         obj.subject,
       )
     ) {
       ctx.addIssue({
         code: "custom",
         message:
-          "For /data-plane sources, subject must start with customer/{id} and may have further segments separated by '/'.",
+          "For /data-plane sources, subject must start with origin/{id} and may have further segments separated by '/'.",
         path: ["subject"],
       });
     }
