CCM-18132: Get proofing request by ID endpoint

infrastructure/terraform/modules/backend-api/README.md

@@ -56,6 +56,7 @@ No requirements.
 | <a name="module_get_client_lambda"></a> [get\_client\_lambda](#module\_get\_client\_lambda) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_get_contact_details_lambda"></a> [get\_contact\_details\_lambda](#module\_get\_contact\_details\_lambda) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/4.0.0/terraform-lambda.zip | n/a |
 | <a name="module_get_letter_variant_lambda"></a> [get\_letter\_variant\_lambda](#module\_get\_letter\_variant\_lambda) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/3.0.6/terraform-lambda.zip | n/a |
+| <a name="module_get_proofing_request_lambda"></a> [get\_proofing\_request\_lambda](#module\_get\_proofing\_request\_lambda) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/3.1.6/terraform-lambda.zip | n/a |
 | <a name="module_get_routing_config_lambda"></a> [get\_routing\_config\_lambda](#module\_get\_routing\_config\_lambda) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_get_routing_configs_by_template_id_lambda"></a> [get\_routing\_configs\_by\_template\_id\_lambda](#module\_get\_routing\_configs\_by\_template\_id\_lambda) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |
 | <a name="module_get_template_lambda"></a> [get\_template\_lambda](#module\_get\_template\_lambda) | https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/v2.0.29/terraform-lambda.zip | n/a |

infrastructure/terraform/modules/backend-api/iam_role_api_gateway_execution_role.tf

@@ -66,6 +66,7 @@ data "aws_iam_policy_document" "api_gateway_execution_policy" {
       module.get_routing_config_lambda.function_arn,
       module.get_routing_configs_by_template_id_lambda.function_arn,
       module.get_template_lambda.function_arn,
+      module.get_proofing_request_lambda.function_arn,
       module.get_template_letter_variants_lambda.function_arn,
       module.list_contact_details_lambda.function_arn,
       module.list_routing_configs_lambda.function_arn,

infrastructure/terraform/modules/backend-api/locals.tf

@@ -32,6 +32,7 @@ locals {
     GET_ROUTING_CONFIGS_BY_TEMPLATE_ID_LAMBDA_ARN = module.get_routing_configs_by_template_id_lambda.function_arn
     GET_TEMPLATE_LAMBDA_ARN                       = module.get_template_lambda.function_arn
     GET_TEMPLATE_LETTER_VARIANTS_LAMBDA_ARN       = module.get_template_letter_variants_lambda.function_arn
+    GET_PROOFING_REQUEST_LAMBDA_ARN               = module.get_proofing_request_lambda.function_arn
     LIST_CONTACT_DETAILS_LAMBDA_ARN               = module.list_contact_details_lambda.function_arn
     LIST_ROUTING_CONFIGS_LAMBDA_ARN               = module.list_routing_configs_lambda.function_arn
     LIST_TEMPLATES_LAMBDA_ARN                     = module.list_template_lambda.function_arn

infrastructure/terraform/modules/backend-api/module_get_proofing_request_lambda.tf

@@ -0,0 +1,67 @@
+module "get_proofing_request_lambda" {
+  source = "https://github.com/NHSDigital/nhs-notify-shared-modules/releases/download/3.1.6/terraform-lambda.zip"
+
+  project        = var.project
+  environment    = var.environment
+  component      = var.component
+  aws_account_id = var.aws_account_id
+  region         = var.region
+
+  kms_key_arn = var.kms_key_arn
+
+  function_name = "get_routing_config_lambda-proofing-request"
+
+  function_module_name  = "get-proofing-request"
+  handler_function_name = "handler"
+  description           = "Get proofing request API endpoint"
+
+  memory  = 2048
+  timeout = 20
+  runtime = "nodejs22.x"
+
+  log_retention_in_days = var.log_retention_in_days
+  iam_policy_document = {
+    body = data.aws_iam_policy_document.get_proofing_request.json
+  }
+
+  lambda_env_vars         = local.backend_lambda_environment_variables
+  function_s3_bucket      = var.function_s3_bucket
+  function_code_base_path = local.lambdas_dir
+  function_code_dir       = "backend-api/dist/get-proofing-request"
+
+  send_to_firehose          = var.send_to_firehose
+  log_destination_arn       = var.log_destination_arn
+  log_subscription_role_arn = var.log_subscription_role_arn
+}
+
+data "aws_iam_policy_document" "get_proofing_request" {
+  statement {
+    sid    = "AllowKMSAccess"
+    effect = "Allow"
+
+    actions = [
+      "kms:Decrypt",
+      "kms:DescribeKey",
+      "kms:Encrypt",
+      "kms:GenerateDataKey*",
+      "kms:ReEncrypt*",
+    ]
+
+    resources = [
+      var.kms_key_arn
+    ]
+  }
+
+  statement {
+    sid    = "AllowProofingRequestsRead"
+    effect = "Allow"
+
+    actions = [
+      "dynamodb:GetItem",
+    ]
+
+    resources = [
+      aws_dynamodb_table.proof_requests.arn,
+    ]
+  }
+}

infrastructure/terraform/modules/backend-api/spec.tmpl.json

@@ -3278,6 +3278,71 @@
         }
       }
     },
+    "/v1/proofing-request/{proofingRequestId}": {
+      "get": {
+        "description": "Get the proofing request for a digital-channel template",
+        "parameters": [
+          {
+            "description": "ID of the proofing request to get",
+            "in": "path",
+            "name": "proofingRequestId",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProofRequestSuccess"
+                }
+              }
+            },
+            "description": "200 response",
+            "headers": {
+              "Content-Type": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "default": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Failure"
+                }
+              }
+            },
+            "description": "Error"
+          }
+        },
+        "security": [
+          {
+            "authorizer": []
+          }
+        ],
+        "summary": "Get the proofing request for a digital-channel template",
+        "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_PROOFING_REQUEST_LAMBDA_ARN}/invocations"
+        }
+      }
+    },
     "/v1/template/{templateId}/routing-configurations": {
       "get": {
         "description": "Get all routing configurations that reference a specific template",

lambdas/backend-api/README.md

@@ -351,4 +351,15 @@ curl -X POST --location "${APIG_STAGE}/v1/template/${TEMPLATE_ID}/proofing-reque
   }
 }'
 ```
+
+### GET - /v1/proofing-request/:proofingRequestId - Get a digital proofing request by id
+
+Gets a digital proof request by id
+
+```bash
+curl -X GET --location "${APIG_STAGE}/v1/proofing-request/${PROOF_REQUEST_ID}" \
+--header 'Accept: application/json' \
+--header "Authorization: $SANDBOX_TOKEN"
+```
+
 <!-- vale on -->

lambdas/backend-api/build.sh

@@ -31,6 +31,7 @@ npx esbuild \
     src/get-routing-config.ts \
     src/get-routing-configs-by-template-id.ts \
     src/get-template-letter-variants.ts \
+    src/get-proofing-request.ts \
     src/get.ts \
     src/generate-letter-proof.ts \
     src/list-contact-details.ts \

lambdas/backend-api/src/__tests__/api/get-proofing-request.test.ts

@@ -0,0 +1,174 @@
+import type { APIGatewayProxyEvent, Context } from 'aws-lambda';
+import { mock } from 'jest-mock-extended';
+import type { ProofRequest } from 'nhs-notify-web-template-management-types';
+import { createHandler } from '@backend-api/api/get-proofing-request';
+import type { ProofingRequestClient } from '@backend-api/app/proofing-request-client';
+
+function setup() {
+  const proofingRequestClient = mock<ProofingRequestClient>();
+  const mocks = { proofingRequestClient };
+  const handler = createHandler(mocks);
+
+  return { handler, mocks };
+}
+
+describe('Get Proofing Request Handler', () => {
+  beforeEach(jest.resetAllMocks);
+
+  test.each([
+    [
+      'authorizer is undefined',
+      undefined,
+      { proofingRequestId: 'proofing-request-123' },
+    ],
+    [
+      'internalUserId is missing',
+      { clientId: 'client-id', internalUserId: undefined },
+      { proofingRequestId: 'proofing-request-123' },
+    ],
+    [
+      'clientId is missing',
+      { clientId: undefined, internalUserId: 'user-1234' },
+      { proofingRequestId: 'proofing-request-123' },
+    ],
+    [
+      'proofingRequestId is missing',
+      { clientId: 'client-id', internalUserId: 'user-1234' },
+      { proofingRequestId: undefined },
+    ],
+  ])(
+    'should return 500 - Invalid request when %s',
+    async (_, ctx, pathParameters) => {
+      const { handler, mocks } = setup();
+
+      const event = mock<APIGatewayProxyEvent>({
+        requestContext: { authorizer: ctx },
+        pathParameters,
+      });
+
+      const result = await handler(event, mock<Context>(), jest.fn());
+
+      expect(result).toEqual({
+        statusCode: 500,
+        body: JSON.stringify({
+          statusCode: 500,
+          technicalMessage: 'Invalid request',
+        }),
+      });
+
+      expect(mocks.proofingRequestClient.get).not.toHaveBeenCalled();
+    }
+  );
+
+  test('should return error when client returns error', async () => {
+    const { handler, mocks } = setup();
+
+    mocks.proofingRequestClient.get.mockResolvedValueOnce({
+      error: {
+        errorMeta: {
+          code: 500,
+          description: 'Internal server error',
+        },
+      },
+    });
+
+    const event = mock<APIGatewayProxyEvent>({
+      requestContext: {
+        authorizer: { internalUserId: 'user-1234', clientId: 'client-id' },
+      },
+      pathParameters: { proofingRequestId: 'proofing-request-123' },
+    });
+
+    const result = await handler(event, mock<Context>(), jest.fn());
+
+    expect(result).toEqual({
+      statusCode: 500,
+      body: JSON.stringify({
+        statusCode: 500,
+        technicalMessage: 'Internal server error',
+      }),
+    });
+
+    expect(mocks.proofingRequestClient.get).toHaveBeenCalledWith(
+      'proofing-request-123',
+      { internalUserId: 'user-1234', clientId: 'client-id' }
+    );
+  });
+
+  test('should pass validation error details from client', async () => {
+    const { handler, mocks } = setup();
+
+    mocks.proofingRequestClient.get.mockResolvedValueOnce({
+      error: {
+        errorMeta: {
+          code: 400,
+          description: 'Request failed validation',
+          details: {
+            proofingRequestId: 'Required',
+          },
+        },
+      },
+    });
+
+    const event = mock<APIGatewayProxyEvent>({
+      requestContext: {
+        authorizer: { internalUserId: 'user-1234', clientId: 'client-id' },
+      },
+      pathParameters: { proofingRequestId: 'proofing-request-123' },
+      body: undefined,
+    });
+
+    const result = await handler(event, mock<Context>(), jest.fn());
+
+    expect(result).toEqual({
+      statusCode: 400,
+      body: JSON.stringify({
+        statusCode: 400,
+        technicalMessage: 'Request failed validation',
+        details: {
+          proofingRequestId: 'Required',
+        },
+      }),
+    });
+  });
+
+  test('should return 200 with proof request', async () => {
+    const { handler, mocks } = setup();
+
+    const proofRequest: ProofRequest = {
+      contactDetailValue: 'test-patient-nhs-number',
+      createdAt: new Date().toISOString(),
+      createdBy: 'user-1234',
+      id: 'proofing-request-123',
+      templateId: 'template-123',
+      templateType: 'NHS_APP',
+      testPatientNhsNumber: 'test-patient-nhs-number',
+    };
+
+    mocks.proofingRequestClient.get.mockResolvedValueOnce({
+      data: proofRequest,
+    });
+
+    const event = mock<APIGatewayProxyEvent>({
+      requestContext: {
+        authorizer: {
+          internalUserId: 'user-1234',
+          clientId: 'client-id',
+        },
+      },
+      pathParameters: { proofingRequestId: 'proofing-request-123' },
+    });
+
+    const result = await handler(event, mock<Context>(), jest.fn());
+
+    expect(result).toEqual({
+      statusCode: 200,
+      body: JSON.stringify({ statusCode: 200, data: proofRequest }),
+    });
+
+    expect(mocks.proofingRequestClient.get).toHaveBeenCalledWith(
+      'proofing-request-123',
+      { internalUserId: 'user-1234', clientId: 'client-id' }
+    );
+  });
+});