Merge remote-tracking branch 'origin/main' into feature/CCM-12934-Create-Letter-Queue

Author: stevebux

README.md

@@ -34,6 +34,7 @@ This repository documents the Supplier API specification and provides an SDK wit
       - [CI (Automatic)](#ci-automatic)
       - [CD (Manual)](#cd-manual)
   - [Licence](#licence)
+  - [Postman](#postman)
 
 ## API Consumers - Getting Started
 
@@ -138,3 +139,15 @@ Deployments can be made of any [release](https://github.com/NHSDigital/nhs-notif
 Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation.
 
 Any HTML or Markdown documentation is [© Crown Copyright](https://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/) and available under the terms of the [Open Government Licence v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).
+
+## Postman
+
+Included in this repo are postman collections that allows the user to interact with the sandbox APIs.
+
+To use the collections:
+
+Download the json files located in the postman directory
+Import the files into postman
+Select a target environment in postman
+Run the collection
+The collections must be kept in sync manually

internal/helpers/package.json

@@ -1,5 +1,6 @@
 {
   "dependencies": {
+    "aws-embedded-metrics": "^4.2.1",
     "pino": "^10.3.0",
     "zod": "^4.1.11"
   },

internal/helpers/src/index.ts

@@ -8,3 +8,4 @@ export * from "./version";
 export { default as $Environment } from "./environment";
 export * from "./id-ref";
 export * from "./logger";
+export * from "./metrics";

internal/helpers/src/metrics.ts

@@ -0,0 +1,55 @@
+import { MetricsLogger, Unit } from "aws-embedded-metrics";
+
+export function emitForSingleSupplier(
+  metrics: MetricsLogger,
+  functionName: string,
+  supplierId: string,
+  count: number,
+  message: string,
+  dimensions?: Record<string, string>,
+) {
+  metrics.setNamespace(process.env.AWS_LAMBDA_FUNCTION_NAME || functionName);
+  metrics.putDimensions({
+    ...dimensions,
+    Supplier: supplierId,
+  });
+  metrics.putMetric(message, count, Unit.Count);
+}
+
+export enum MetricStatus {
+  Success = "success",
+  Failure = "failure",
+}
+
+export interface MetricEntry {
+  key: string;
+  value: number;
+  unit: Unit;
+}
+
+// build EMF object
+export function buildEMFObject(
+  functionName: string,
+  dimensions: Record<string, string>,
+  metric: MetricEntry,
+) {
+  const namespace = process.env.AWS_LAMBDA_FUNCTION_NAME || functionName;
+  return {
+    LogGroup: namespace,
+    ServiceName: namespace,
+    ...dimensions,
+    _aws: {
+      Timestamp: Date.now(),
+      CloudWatchMetrics: [
+        {
+          Namespace: namespace,
+          Dimensions: [[...Object.keys(dimensions), "ServiceName", "LogGroup"]],
+          Metrics: [
+            { Name: metric.key, Value: metric.value, Unit: metric.unit },
+          ],
+        },
+      ],
+    },
+    [metric.key]: metric.value,
+  };
+}

lambdas/api-handler/src/handlers/amendment-event-transformer.ts

@@ -2,6 +2,9 @@ import { SQSBatchItemFailure, SQSEvent, SQSHandler } from "aws-lambda";
 import { PublishCommand } from "@aws-sdk/client-sns";
 import { LetterEvent } from "@nhsdigital/nhs-notify-event-schemas-supplier-api/src/events/letter-events";
 import { mapLetterToCloudEvent } from "@nhsdigital/nhs-notify-event-schemas-supplier-api/src/events/letter-mapper";
+import { Unit } from "aws-embedded-metrics";
+import pino from "pino";
+import { MetricEntry, MetricStatus, buildEMFObject } from "@internal/helpers";
 import {
   UpdateLetterCommand,
   UpdateLetterCommandSchema,
@@ -39,6 +42,11 @@ export default function createTransformAmendmentEventHandler(
           messageId: message.messageId,
           correlationId: message.messageAttributes.CorrelationId.stringValue,
         });
+        emitSuccessMetrics(
+          updateLetterCommand.supplierId,
+          updateLetterCommand.status,
+          deps.logger,
+        );
       } catch (error) {
         deps.logger.error({
           description: "Error processing letter status update",
@@ -52,7 +60,7 @@ export default function createTransformAmendmentEventHandler(
     });
 
     await Promise.all(tasks);
-
+    emitFailedItems(batchItemFailures, deps.logger);
     return { batchItemFailures };
   };
 }
@@ -66,3 +74,43 @@ function buildSnsCommand(
     Message: JSON.stringify(letterEvent),
   });
 }
+
+function emitSuccessMetrics(
+  supplierId: string,
+  status: string,
+  logger: pino.Logger,
+) {
+  const dimensions: Record<string, string> = {
+    supplier: supplierId,
+    status,
+  };
+  const metric: MetricEntry = {
+    key: MetricStatus.Success,
+    value: 1,
+    unit: Unit.Count,
+  };
+  const emf = buildEMFObject("amendment-event-transformer", dimensions, metric);
+  logger.info(emf);
+}
+
+function emitFailedItems(
+  batchFailures: SQSBatchItemFailure[],
+  logger: pino.Logger,
+) {
+  for (const item of batchFailures) {
+    const dimensions: Record<string, string> = {
+      identifier: item.itemIdentifier,
+    };
+    const metric: MetricEntry = {
+      key: MetricStatus.Failure,
+      value: 1,
+      unit: Unit.Count,
+    };
+    const emf = buildEMFObject(
+      "amendment-event-transformer",
+      dimensions,
+      metric,
+    );
+    logger.info(emf);
+  }
+}

lambdas/api-handler/src/handlers/get-letter-data.ts

@@ -1,13 +1,13 @@
 import { APIGatewayProxyHandler } from "aws-lambda";
 import { MetricsLogger, metricScope } from "aws-embedded-metrics";
+import { MetricStatus, emitForSingleSupplier } from "@internal/helpers";
 import { assertNotEmpty } from "../utils/validation";
 import { extractCommonIds } from "../utils/common-ids";
 import { ApiErrorDetail } from "../contracts/errors";
 import { processError } from "../mappers/error-mapper";
 import ValidationError from "../errors/validation-error";
 import { getLetterDataUrl } from "../services/letter-operations";
 import type { Deps } from "../config/deps";
-import { MetricStatus, emitForSingleSupplier } from "../utils/metrics";
 
 export default function createGetLetterDataHandler(
   deps: Deps,

lambdas/api-handler/src/handlers/get-letter.ts

@@ -1,5 +1,6 @@
 import { APIGatewayProxyHandler } from "aws-lambda";
 import { MetricsLogger, metricScope } from "aws-embedded-metrics";
+import { MetricStatus, emitForSingleSupplier } from "@internal/helpers";
 import { assertNotEmpty } from "../utils/validation";
 import { extractCommonIds } from "../utils/common-ids";
 import ValidationError from "../errors/validation-error";
@@ -8,7 +9,6 @@ import { getLetterById } from "../services/letter-operations";
 import { processError } from "../mappers/error-mapper";
 import { mapToGetLetterResponse } from "../mappers/letter-mapper";
 import { Deps } from "../config/deps";
-import { MetricStatus, emitForSingleSupplier } from "../utils/metrics";
 
 // Get letter data
 export default function createGetLetterHandler(

lambdas/api-handler/src/handlers/get-letters.ts

@@ -4,6 +4,7 @@ import {
 } from "aws-lambda";
 import { Logger } from "pino";
 import { MetricsLogger, metricScope } from "aws-embedded-metrics";
+import { MetricStatus, emitForSingleSupplier } from "@internal/helpers";
 import { getLettersForSupplier } from "../services/letter-operations";
 import { extractCommonIds } from "../utils/common-ids";
 import { requireEnvVar } from "../utils/validation";
@@ -12,9 +13,7 @@ import { processError } from "../mappers/error-mapper";
 import ValidationError from "../errors/validation-error";
 import { mapToGetLettersResponse } from "../mappers/letter-mapper";
 import type { Deps } from "../config/deps";
-import { MetricStatus, emitForSingleSupplier } from "../utils/metrics";
 
-// List letters Handlers
 // The endpoint should only return pending letters for now
 const status = "PENDING";
 

lambdas/api-handler/src/handlers/patch-letter.ts

@@ -1,5 +1,6 @@
 import { APIGatewayProxyHandler } from "aws-lambda";
 import { MetricsLogger, Unit, metricScope } from "aws-embedded-metrics";
+import { MetricStatus } from "@internal/helpers";
 import { enqueueLetterUpdateRequests } from "../services/letter-operations";
 import {
   PatchLetterRequest,
@@ -13,7 +14,6 @@ import { assertNotEmpty } from "../utils/validation";
 import { extractCommonIds } from "../utils/common-ids";
 import { mapToUpdateCommand } from "../mappers/letter-mapper";
 import type { Deps } from "../config/deps";
-import { MetricStatus } from "../utils/metrics";
 
 export default function createPatchLetterHandler(
   deps: Deps,
@@ -56,6 +56,7 @@ export default function createPatchLetterHandler(
         try {
           patchLetterRequest = PatchLetterRequestSchema.parse(JSON.parse(body));
         } catch (error) {
+          emitErrorMetric(metrics, supplierId);
           const typedError =
             error instanceof Error
               ? new ValidationError(ApiErrorDetail.InvalidRequestBody, {
@@ -79,6 +80,7 @@ export default function createPatchLetterHandler(
         );
 
         if (updateLetterCommand.id !== letterId) {
+          emitErrorMetric(metrics, supplierId);
           throw new ValidationError(
             ApiErrorDetail.InvalidRequestLetterIdsMismatch,
           );
@@ -100,12 +102,16 @@ export default function createPatchLetterHandler(
           body: "",
         };
       } catch (error) {
-        metrics.putDimensions({
-          supplier: supplierId,
-        });
-        metrics.putMetric(MetricStatus.Success, 1, Unit.Count);
+        emitErrorMetric(metrics, supplierId);
         return processError(error, commonIds.value.correlationId, deps.logger);
       }
     };
   });
 }
+
+function emitErrorMetric(metrics: MetricsLogger, supplierId: string) {
+  metrics.putDimensions({
+    supplier: supplierId,
+  });
+  metrics.putMetric(MetricStatus.Failure, 1, Unit.Count);
+}