feature/CCM-12185 Add new endpoint to get mi information

infrastructure/terraform/components/api/README.md

@@ -64,6 +64,7 @@ No requirements.
 | <a name="module_get_letter"></a> [get\_letter](#module\_get\_letter) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_get_letter_data"></a> [get\_letter\_data](#module\_get\_letter\_data) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_get_letters"></a> [get\_letters](#module\_get\_letters) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
+| <a name="module_get_mi"></a> [get\_mi](#module\_get\_mi) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_get_status"></a> [get\_status](#module\_get\_status) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <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_lambda_alarms"></a> [lambda\_alarms](#module\_lambda\_alarms) | ../../modules/alarms-lambda | n/a |

infrastructure/terraform/components/api/iam_role_api_gateway_execution_role.tf

@@ -52,6 +52,7 @@ data "aws_iam_policy_document" "api_gateway_execution_policy" {
       module.get_letter.function_arn,
       module.get_letter_data.function_arn,
       module.get_letters.function_arn,
+      module.get_mi.function_arn,
       module.patch_letter.function_arn,
       module.post_letters.function_arn,
       module.get_status.function_arn,

infrastructure/terraform/components/api/locals.tf

@@ -17,6 +17,7 @@ locals {
     PATCH_LETTER_LAMBDA_ARN    = module.patch_letter.function_arn
     POST_LETTERS_LAMBDA_ARN    = module.post_letters.function_arn
     POST_MI_LAMBDA_ARN         = module.post_mi.function_arn
+    GET_MI_LAMBDA_ARN          = module.get_mi.function_arn
   })
 
   destination_arn = "arn:aws:logs:${var.region}:${var.shared_infra_account_id}:destination:nhs-main-obs-firehose-logs"

infrastructure/terraform/components/api/locals_alarms.tf

@@ -11,6 +11,7 @@ locals {
     get_letter                  = module.get_letter.function_name
     get_letters                 = module.get_letters.function_name
     get_letter_data             = module.get_letter_data.function_name
+    get_mi                      = module.get_mi.function_name
     get_status                  = module.get_status.function_name
     patch_letter                = module.patch_letter.function_name
     post_letters                = module.post_letters.function_name

infrastructure/terraform/components/api/module_lambda_get_mi.tf

@@ -0,0 +1,68 @@
+module "get_mi" {
+  source = "https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip"
+
+  function_name = "get_mi"
+  description   = "Retrieve management information"
+
+  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.get_mi_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       = "api-handler/dist"
+  function_include_common = true
+  handler_function_name   = "getMI"
+  runtime                 = "nodejs22.x"
+  memory                  = 512
+  timeout                 = 29
+  log_level               = var.log_level
+
+  force_lambda_code_deploy = var.force_lambda_code_deploy
+  enable_lambda_insights   = false
+
+  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, {})
+}
+
+data "aws_iam_policy_document" "get_mi_lambda" {
+  statement {
+    sid    = "KMSPermissions"
+    effect = "Allow"
+
+    actions = [
+      "kms:Decrypt",
+      "kms:GenerateDataKey",
+    ]
+
+    resources = [
+      module.kms.key_arn, ## Requires shared kms module
+    ]
+  }
+
+  statement {
+    sid    = "AllowDynamoDBAccess"
+    effect = "Allow"
+
+    actions = [
+      "dynamodb:GetItem",
+      "dynamodb:Query"
+    ]
+
+    resources = [
+      aws_dynamodb_table.mi.arn,
+    ]
+  }
+}

infrastructure/terraform/components/api/resources/spec.tmpl.json

@@ -306,6 +306,56 @@
           "uri": "arn:aws:apigateway:${AWS_REGION}:lambda:path/2015-03-31/functions/${POST_MI_LAMBDA_ARN}/invocations"
         }
       }
+    },
+    "/mi/{id}": {
+      "get": {
+        "description": "Returns 200 OK with management information.",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "400": {
+            "description": "Bad request, invalid input data"
+          },
+          "404": {
+            "description": "Resource not found"
+          },
+          "500": {
+            "description": "Server error"
+          }
+        },
+        "security": [
+          {
+            "LambdaAuthorizer": []
+          }
+        ],
+        "summary": "Get MI",
+        "x-amazon-apigateway-integration": {
+          "contentHandling": "CONVERT_TO_TEXT",
+          "credentials": "${APIG_EXECUTION_ROLE_ARN}",
+          "httpMethod": "POST",
+          "passthroughBehavior": "WHEN_NO_TEMPLATES",
+          "responses": {
+            ".*": {
+              "statusCode": "200"
+            }
+          },
+          "timeoutInMillis": 29000,
+          "type": "AWS_PROXY",
+          "uri": "arn:aws:apigateway:${AWS_REGION}:lambda:path/2015-03-31/functions/${GET_MI_LAMBDA_ARN}/invocations"
+        }
+      },
+      "parameters": [
+        {
+          "description": "Unique identifier of this resource",
+          "in": "path",
+          "name": "id",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ]
     }
   },
   "x-amazon-apigateway-endpoint-access-mode": "${ENDPOINT_ACCESS_MODE}",

internal/datastore/src/__test__/mi-repository.test.ts

@@ -64,4 +64,54 @@ describe("MiRepository", () => {
       );
     });
   });
+
+  describe("getMi", () => {
+    it("throws an error when fetching MI information that does not exist", async () => {
+      await expect(miRepository.getMI("XXX", "supplier1")).rejects.toThrow(
+        "Management information not found: supplierId=supplier1, miId=XXX",
+      );
+    });
+
+    it("creates MI with id and timestamps", async () => {
+      jest.useFakeTimers();
+      // Month is zero-indexed in JS Date
+      jest.setSystemTime(new Date(2020, 1, 1));
+      const mi = {
+        specificationId: "spec1",
+        supplierId: "supplier1",
+        groupId: "group1",
+        lineItem: "item1",
+        quantity: 12,
+        timestamp: new Date().toISOString(),
+        stockRemaining: 0,
+      };
+
+      const persistedMi = await miRepository.putMI(mi);
+
+      expect(persistedMi).toEqual(
+        expect.objectContaining({
+          id: expect.any(String),
+          createdAt: "2020-02-01T00:00:00.000Z",
+          updatedAt: "2020-02-01T00:00:00.000Z",
+          ttl: 1_580_518_800, // 2020-02-01T00:01:00.000Z, seconds since epoch
+          ...mi,
+        }),
+      );
+
+      const fetchedMi = await miRepository.getMI(
+        persistedMi.id,
+        persistedMi.supplierId,
+      );
+
+      expect(fetchedMi).toEqual(
+        expect.objectContaining({
+          id: expect.any(String),
+          createdAt: "2020-02-01T00:00:00.000Z",
+          updatedAt: "2020-02-01T00:00:00.000Z",
+          ttl: 1_580_518_800, // 2020-02-01T00:01:00.000Z, seconds since epoch
+          ...mi,
+        }),
+      );
+    });
+  });
 });

internal/datastore/src/errors/mi-not-found-error.ts

@@ -0,0 +1,14 @@
+/**
+ * Error thrown when management information is not found in the database.
+ */
+export default class MiNotFoundError extends Error {
+  constructor(
+    public readonly supplierId: string,
+    public readonly miId: string,
+  ) {
+    super(
+      `Management information not found: supplierId=${supplierId}, miId=${miId}`,
+    );
+    this.name = "MiNotFoundError";
+  }
+}

internal/datastore/src/index.ts

@@ -7,3 +7,4 @@ export { default as LetterQueueRepository } from "./letter-queue-repository";
 export { default as DBHealthcheck } from "./healthcheck";
 export { default as LetterAlreadyExistsError } from "./errors/letter-already-exists-error";
 export { default as LetterNotFoundError } from "./errors/letter-not-found-error";
+export { default as MiNotFoundError } from "./errors/mi-not-found-error";

internal/datastore/src/mi-repository.ts

@@ -1,7 +1,12 @@
-import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
+import {
+  DynamoDBDocumentClient,
+  GetCommand,
+  PutCommand,
+} from "@aws-sdk/lib-dynamodb";
 import { Logger } from "pino";
 import { randomUUID } from "node:crypto";
 import { MI, MISchema } from "./types";
+import MiNotFoundError from "./errors/mi-not-found-error";
 
 export type MIRepositoryConfig = {
   miTableName: string;
@@ -36,4 +41,22 @@ export class MIRepository {
 
     return MISchema.parse(miDb);
   }
+
+  async getMI(miId: string, supplierId: string): Promise<MI> {
+    const result = await this.ddbClient.send(
+      new GetCommand({
+        TableName: this.config.miTableName,
+        Key: {
+          id: miId,
+          supplierId,
+        },
+      }),
+    );
+
+    if (!result.Item) {
+      throw new MiNotFoundError(supplierId, miId);
+    }
+
+    return MISchema.parse(result.Item);
+  }
 }

lambdas/api-handler/src/contracts/errors.ts

@@ -12,7 +12,7 @@ export interface ApiError {
 export enum ApiErrorCode {
   InternalServerError = "NOTIFY_INTERNAL_SERVER_ERROR",
   InvalidRequest = "NOTIFY_INVALID_REQUEST",
-  NotFound = "NOTIFY_LETTER_NOT_FOUND",
+  NotFound = "NOTIFY_NOT_FOUND",
 }
 
 export enum ApiErrorTitle {
@@ -28,10 +28,11 @@ export enum ApiErrorStatus {
 }
 
 export enum ApiErrorDetail {
-  NotFoundLetterId = "No resource found with that ID",
+  NotFoundId = "No resource found with that ID",
   InvalidRequestMissingBody = "The request is missing the body",
   InvalidRequestMissingLetterIdPathParameter = "The request is missing the letter id path parameter",
   InvalidRequestLetterIdsMismatch = "The letter ID in the request body does not match the letter ID path parameter",
+  InvalidRequestMissingMiIdPathParameter = "The request is missing the mi id path parameter",
   InvalidRequestBody = "The request body is invalid",
   InvalidRequestLimitNotANumber = "The limit parameter is not a number",
   InvalidRequestLimitNotInRange = "The limit parameter must be a positive number not greater than %s",

lambdas/api-handler/src/contracts/mi.ts

@@ -37,3 +37,16 @@ export type PostMIResponse = z.infer<typeof PostMIResponseSchema>;
 export type IncomingMI = PostMIRequest["data"]["attributes"] & {
   supplierId: string;
 };
+
+export const GetMIResponseResourceSchema = z
+  .object({
+    id: z.string(),
+    ...PostMIRequestResourceSchema.shape,
+  })
+  .strict();
+
+export const GetMIResponseSchema = makeDocumentSchema(
+  GetMIResponseResourceSchema,
+);
+
+export type GetMIResponse = z.infer<typeof GetMIResponseSchema>;

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

@@ -120,7 +120,7 @@ describe("API Lambda handler", () => {
   it("returns 404 Not Found when letter matching id is not found", async () => {
     const mockedGetLetterById = letterService.getLetterById as jest.Mock;
     mockedGetLetterById.mockImplementation(() => {
-      throw new NotFoundError(ApiErrorDetail.NotFoundLetterId);
+      throw new NotFoundError(ApiErrorDetail.NotFoundId);
     });
 
     const event = makeApiGwEvent({