Feature/ccm 12937- publish supplier letter events

infrastructure/terraform/components/api/README.md

@@ -45,6 +45,7 @@ No requirements.
 | <a name="module_kms"></a> [kms](#module\_kms) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.26/terraform-kms.zip | n/a |
 | <a name="module_letter_status_update"></a> [letter\_status\_update](#module\_letter\_status\_update) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.24/terraform-lambda.zip | n/a |
 | <a name="module_letter_status_updates_queue"></a> [letter\_status\_updates\_queue](#module\_letter\_status\_updates\_queue) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.24/terraform-sqs.zip | n/a |
+| <a name="module_letter_stream_forwarder"></a> [letter\_stream\_forwarder](#module\_letter\_stream\_forwarder) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.26/terraform-lambda.zip | n/a |
 | <a name="module_letter_updates_transformer"></a> [letter\_updates\_transformer](#module\_letter\_updates\_transformer) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.26/terraform-lambda.zip | n/a |
 | <a name="module_logging_bucket"></a> [logging\_bucket](#module\_logging\_bucket) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.26/terraform-s3bucket.zip | n/a |
 | <a name="module_patch_letter"></a> [patch\_letter](#module\_patch\_letter) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.26/terraform-lambda.zip | n/a |

infrastructure/terraform/components/api/ddb_table_letters.tf

@@ -1,6 +1,8 @@
 resource "aws_dynamodb_table" "letters" {
   name         = "${local.csi}-letters"
   billing_mode = "PAY_PER_REQUEST"
+  stream_enabled   = true
+  stream_view_type = "NEW_AND_OLD_IMAGES"
 
   hash_key  = "supplierId"
   range_key = "id"

infrastructure/terraform/components/api/event_source_mapping_letter_updates.tf

@@ -0,0 +1,23 @@
+resource "aws_lambda_event_source_mapping" "letter_stream_forwarder_dynamodb" {
+  event_source_arn                     = aws_dynamodb_table.letters.stream_arn
+  function_name                        = module.letter_stream_forwarder.function_arn
+  starting_position                    = "LATEST"
+  batch_size                           = 10
+  maximum_batching_window_in_seconds   = 1
+
+  depends_on = [
+    module.letter_stream_forwarder       # ensures stream forwarder exists
+  ]
+}
+
+resource "aws_lambda_event_source_mapping" "letter_updates_transformer_kinesis" {
+  event_source_arn                     = aws_kinesis_stream.letter_change_stream.arn
+  function_name                        = module.letter_updates_transformer.function_arn
+  starting_position                    = "LATEST"
+  batch_size                           = 10
+  maximum_batching_window_in_seconds   = 1
+
+  depends_on = [
+    module.letter_updates_transformer    # ensures updates transformer exists
+  ]
+}

infrastructure/terraform/components/api/kinesis_letter_change_stream.tf

@@ -0,0 +1,5 @@
+resource "aws_kinesis_stream" "letter_change_stream" {
+  name             = "${local.csi}-letter-change-stream"
+  shard_count      = 1
+  retention_period = 24
+}

infrastructure/terraform/components/api/module_lambda_letter_stream_forwarder.tf

@@ -0,0 +1,74 @@
+module "letter_stream_forwarder" {
+  source = "https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.26/terraform-lambda.zip"
+
+  function_name = "letter-stream-forwarder"
+  description   = "Kinesis stream forwarder for DDB letter status updates"
+
+  aws_account_id = var.aws_account_id
+  component      = var.component
+  environment    = var.environment
+  project        = var.project
+  region         = var.region
+  group          = var.group
+
+  log_retention_in_days = var.log_retention_in_days
+  kms_key_arn           = module.kms.key_arn
+
+  iam_policy_document = {
+    body = data.aws_iam_policy_document.letter_stream_forwarder_lambda.json
+  }
+
+  function_s3_bucket      = local.acct.s3_buckets["lambda_function_artefacts"]["id"]
+  function_code_base_path = local.aws_lambda_functions_dir_path
+  function_code_dir       = "letter-stream-forwarder/dist"
+  function_include_common = true
+  handler_function_name   = "handler"
+  runtime                 = "nodejs22.x"
+  memory                  = 128
+  timeout                 = 5
+  log_level               = var.log_level
+
+  force_lambda_code_deploy = var.force_lambda_code_deploy
+  enable_lambda_insights   = false
+
+  send_to_firehose          = true
+  log_destination_arn       = local.destination_arn
+  log_subscription_role_arn = local.acct.log_subscription_role_arn
+
+  lambda_env_vars = merge(local.common_lambda_env_vars, {
+    LETTER_CHANGE_STREAM_ARN = "${aws_kinesis_stream.letter_change_stream.arn}"
+  })
+}
+
+data "aws_iam_policy_document" "letter_stream_forwarder_lambda" {
+
+  statement {
+    sid    = "AllowDynamoDBStream"
+    effect = "Allow"
+
+    actions = [
+      "dynamodb:GetRecords",
+      "dynamodb:GetShardIterator",
+      "dynamodb:DescribeStream",
+      "dynamodb:ListStreams",
+    ]
+
+    resources = [
+      "${aws_dynamodb_table.letters.arn}/stream/*"
+    ]
+  }
+
+  statement {
+    sid    = "AllowKinesisPut"
+    effect = "Allow"
+
+    actions = [
+      "kinesis:DescribeStream",
+      "kinesis:PutRecord",
+    ]
+
+    resources = [
+      aws_kinesis_stream.letter_change_stream.arn
+    ]
+  }
+}

infrastructure/terraform/components/api/module_lambda_letter_updates_transformer.tf

@@ -36,35 +36,39 @@ module "letter_updates_transformer" {
   log_subscription_role_arn = local.acct.log_subscription_role_arn
 
   lambda_env_vars = merge(local.common_lambda_env_vars, {
-    EVENTPUB_SNS_TOPIC_ARN = module.eventpub.sns_topic.arn
+    EVENTPUB_SNS_TOPIC_ARN = "${module.eventpub.sns_topic.arn}"
   })
 }
 
 data "aws_iam_policy_document" "letter_updates_transformer_lambda" {
   statement {
-    sid    = "KMSPermissions"
+    sid    = "AllowSNSPublish"
     effect = "Allow"
 
     actions = [
-      "kms:Decrypt",
-      "kms:GenerateDataKey",
+      "sns:Publish"
     ]
 
     resources = [
-      module.kms.key_arn,
+      module.eventpub.sns_topic.arn
     ]
   }
 
   statement {
-    sid    = "AllowSNSPublish"
+    sid    = "AllowKinesisGet"
     effect = "Allow"
 
     actions = [
-      "sns:Publish"
+      "kinesis:GetRecords",
+      "kinesis:GetShardIterator",
+      "kinesis:DescribeStream",
+      "kinesis:DescribeStreamSummary",
+      "kinesis:ListShards",
+      "kinesis:ListStreams",
     ]
 
     resources = [
-      module.eventpub.sns_topic.arn
+      aws_kinesis_stream.letter_change_stream.arn
     ]
   }
 }

internal/events/package.json

@@ -50,5 +50,5 @@
     "typecheck": "tsc --noEmit"
   },
   "types": "dist/index.d.ts",
-  "version": "1.0.3"
+  "version": "1.0.4"
 }

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

@@ -8,12 +8,15 @@ describe("EventEnvelope schema validation", () => {
   const baseValidEnvelope: Envelope = {
     dataschema:
       "https://notify.nhs.uk/cloudevents/schemas/supplier-api/order.READ.1.0.0.schema.json",
+    dataschemaversion: "1.0.0",
     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",
+    plane: "data-plane",
     time: "2025-10-01T10:15:30.000Z",
+    datacontenttype: "application/json",
     data: {
       "notify-payload": {
         "notify-data": { nhsNumber: "9434765919" },
@@ -241,10 +244,13 @@ describe("EventEnvelope schema validation", () => {
       specversion: "1.0" as const,
       id: "6f1c2a53-3d54-4a0a-9a0b-0e02b2c3d479",
       type: "uk.nhs.notify.supplier-api.letter.CREATED.v1" as const,
+      plane: "data-plane",
       dataschema:
         "https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.CREATED.1.0.0.schema.json",
+      dataschemaversion: "1.0.0",
       source: "/data-plane/supplier-api/letters",
       time: "2025-10-01T10:15:30.000Z",
+      datacontenttype: "application/json",
       data: { status: "CREATED" },
       traceparent: "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
       recordedtime: "2025-10-01T10:15:30.250Z",
@@ -294,11 +300,14 @@ describe("EventEnvelope schema validation", () => {
         specversion: "1.0" as const,
         id: "6f1c2a53-3d54-4a0a-9a0b-0e9ae2d4c111",
         type: "uk.nhs.notify.supplier-api.order.READ.v1" as const,
+        plane: "data-plane",
         dataschema:
           "https://notify.nhs.uk/cloudevents/schemas/supplier-api/order.READ.1.0.0.schema.json",
+        dataschemaversion: "1.0.0",
         source: "/data-plane/supplier-api/ordering",
         subject: "order/769acdd4",
         time: "2025-10-01T10:15:30.000Z",
+        datacontenttype: "application/json",
         data: { status: "READ" },
         traceparent: "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
         recordedtime: "2025-10-01T10:15:30.250Z",

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

@@ -18,13 +18,15 @@ describe("MI event validations", () => {
     expect(event).toEqual(
       expect.objectContaining({
         type: "uk.nhs.notify.supplier-api.mi.SUBMITTED.v1",
+        plane: "data-plane",
         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",
+        dataschemaversion: "1.0.0",
         subject: "mi/mi-test-001",
         data: expect.objectContaining({
           id: "mi-test-001",

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

@@ -13,7 +13,9 @@
   },
   "datacontenttype": "application/json",
   "dataschema": "https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.ACCEPTED.0.1.0.schema.json",
+  "dataschemaversion": "1.0.0",
   "id": "23f1f09c-a555-4d9b-8405-0b33490bc920",
+  "plane": "data-plane",
   "recordedtime": "2025-08-28T08:45:00.000Z",
   "severitynumber": 2,
   "severitytext": "INFO",

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

@@ -12,7 +12,9 @@
   },
   "datacontenttype": "application/json",
   "dataschema": "https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.ACCEPTED.1.0.0.schema.json",
+  "dataschemaversion": "1.0.0",
   "id": "23f1f09c-a555-4d9b-8405-0b33490bc920",
+  "plane": "data-plane",
   "recordedtime": "2025-08-28T08:45:00.000Z",
   "severitynumber": 2,
   "severitytext": "INFO",

internal/events/src/events/__tests__/testData/letter.ACCEPTED.json

@@ -13,7 +13,9 @@
   },
   "datacontenttype": "application/json",
   "dataschema": "https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.ACCEPTED.1.0.0.schema.json",
+  "dataschemaversion": "1.0.0",
   "id": "23f1f09c-a555-4d9b-8405-0b33490bc920",
+  "plane": "data-plane",
   "recordedtime": "2025-08-28T08:45:00.000Z",
   "severitynumber": 2,
   "severitytext": "INFO",

internal/events/src/events/__tests__/testData/letter.FORWARDED.json

@@ -15,7 +15,9 @@
   },
   "datacontenttype": "application/json",
   "dataschema": "https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.FORWARDED.1.0.0.schema.json",
+  "dataschemaversion": "1.0.0",
   "id": "23f1f09c-a555-4d9b-8405-0b33490bc920",
+  "plane": "data-plane",
   "recordedtime": "2025-08-28T08:45:00.000Z",
   "severitynumber": 2,
   "severitytext": "INFO",

internal/events/src/events/__tests__/testData/letter.RETURNED.json

@@ -15,7 +15,9 @@
   },
   "datacontenttype": "application/json",
   "dataschema": "https://notify.nhs.uk/cloudevents/schemas/supplier-api/letter.RETURNED.1.0.0.schema.json",
+  "dataschemaversion": "1.0.0",
   "id": "23f1f09c-a555-4d9b-8405-0b33490bc920",
+  "plane": "data-plane",
   "recordedtime": "2025-08-28T08:45:00.000Z",
   "severitynumber": 2,
   "severitytext": "INFO",

internal/events/src/events/__tests__/testData/mi.SUBMITTED-minimal.json

@@ -11,7 +11,9 @@
   },
   "datacontenttype": "application/json",
   "dataschema": "https://notify.nhs.uk/cloudevents/schemas/supplier-api/mi.SUBMITTED.1.0.0.schema.json",
+  "dataschemaversion": "1.0.0",
   "id": "9a3d4c55-5f76-6c2c-b789-2f1cf4e5e333",
+  "plane": "data-plane",
   "recordedtime": "2025-11-16T15:00:00.250Z",
   "severitynumber": 2,
   "severitytext": "INFO",

internal/events/src/events/__tests__/testData/mi.SUBMITTED-with-invalid-major-version.json

@@ -13,7 +13,9 @@
   },
   "datacontenttype": "application/json",
   "dataschema": "https://notify.nhs.uk/cloudevents/schemas/supplier-api/mi.SUBMITTED.2.0.0.schema.json",
+  "dataschemaversion": "1.0.0",
   "id": "8f2c3b44-4e65-5b1b-a678-1f0bf3d4d222",
+  "plane": "data-plane",
   "recordedtime": "2025-11-16T10:30:00.250Z",
   "severitynumber": 2,
   "severitytext": "INFO",

internal/events/src/events/__tests__/testData/mi.SUBMITTED-with-missing-subject.json

@@ -10,7 +10,9 @@
   },
   "datacontenttype": "application/json",
   "dataschema": "https://notify.nhs.uk/cloudevents/schemas/supplier-api/mi.SUBMITTED.1.0.0.schema.json",
+  "dataschemaversion": "1.0.0",
   "id": "8f2c3b44-4e65-5b1b-a678-1f0bf3d4d222",
+  "plane": "data-plane",
   "recordedtime": "2025-11-16T10:30:00.250Z",
   "severitynumber": 2,
   "severitytext": "INFO",

internal/events/src/events/__tests__/testData/mi.SUBMITTED.json

@@ -13,7 +13,9 @@
   },
   "datacontenttype": "application/json",
   "dataschema": "https://notify.nhs.uk/cloudevents/schemas/supplier-api/mi.SUBMITTED.1.0.0.schema.json",
+  "dataschemaversion": "1.0.0",
   "id": "8f2c3b44-4e65-5b1b-a678-1f0bf3d4d222",
+  "plane": "data-plane",
   "recordedtime": "2025-11-16T10:30:00.250Z",
   "severitynumber": 2,
   "severitytext": "INFO",

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

@@ -50,6 +50,12 @@ export function EventEnvelope<TData extends z.ZodTypeAny>(
         examples: typeStrings,
       }),
 
+      plane: z.literal("data-plane").meta({
+        title: "plane",
+        description: "Fixed as data-plane",
+        examples: ["data-plane"],
+      }),
+
       dataschema: z
         .string()
         .regex(
@@ -64,6 +70,15 @@ export function EventEnvelope<TData extends z.ZodTypeAny>(
           examples: schemaExamples,
         }),
 
+      dataschemaversion: z
+        .string()
+        .regex(/^1.\d+.\d+$/)
+        .meta({
+          title: "Data Schema URI",
+          description: `Version of the schema that describes the event data\n\nMust match the version in dataschema`,
+          examples:["1.0.0"],
+        }),
+
       source: z
         .string()
         .regex(/^\/data-plane\/supplier-api(?:\/.*)?$/)
@@ -94,13 +109,13 @@ export function EventEnvelope<TData extends z.ZodTypeAny>(
         examples: ["2025-10-01T10:15:30.000Z"],
       }),
 
-      datacontenttype: z.optional(
+      datacontenttype:
         z.literal("application/json").meta({
           title: "Data Content Type",
           description:
             "Media type for the data field (fixed to application/json).",
           examples: ["application/json"],
-        }),
+        },
       ),
 
       traceparent: z

lambdas/letter-stream-forwarder/.eslintignore

@@ -0,0 +1 @@
+dist

lambdas/letter-stream-forwarder/.gitignore

@@ -0,0 +1,4 @@
+coverage
+node_modules
+dist
+.reports