feat(cb2-14934): create recalls brokering API

docs/spec.yml

@@ -585,6 +585,33 @@ paths:
         '404':
           description: No records found matching identifier and criteria 
 
+  '/v3/technical-records/recalls/{vin}':
+    get:
+      summary: 'Brokering API with MOT recalls API'
+      tags:
+        - Call MOT Recalls
+      parameters:
+        - in: path
+          name: vin
+          schema:
+            type: string
+          required: true
+          description: This represents the vin of the vehicle. Used to call MOT Recalls API.
+      responses:
+        '200':
+          description: Returns recall information
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  manufacturer:
+                    type: string
+                  hasRecall:
+                    type: boolean
+        '500':
+          description: Internal server error
+
 components:
   securitySchemes:
     OAuth2:

package.json

@@ -38,13 +38,17 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@dvsa/cvs-type-definitions": "^7.6.3",
+    "@dvsa/aws-utilities": "^1.2.0",
+    "@dvsa/cvs-feature-flags": "^0.15.0",
+    "@dvsa/cvs-microservice-common": "^1.2.4",
+    "@dvsa/cvs-type-definitions": "^7.7.1",
     "@types/luxon": "^3.3.0",
     "jwt-decode": "^3.1.2",
     "luxon": "^3.3.0",
     "polly-js": "^1.8.3"
   },
   "devDependencies": {
+    "@aws-sdk/client-appconfigdata": "^3.693.0",
     "@aws-sdk/client-dynamodb": "^3.359.0",
     "@aws-sdk/client-lambda": "^3.362.0",
     "@aws-sdk/client-s3": "^3.550.0",

src/handler/motRecalls.ts

@@ -0,0 +1,79 @@
+import { SecretsManager } from '@dvsa/aws-utilities/classes/secrets-manager-client';
+import { EnvironmentVariables } from '@dvsa/cvs-microservice-common/classes/misc/env-vars';
+import { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
+import { MotSecret } from '../models/motRecalls';
+import { formatErrorMessage } from '../util/errorMessage';
+import { addHttpHeaders } from '../util/httpHeaders';
+import logger from '../util/logger';
+import {
+  filterMotRecalls, getBearerToken, getMotRecallsByVin,
+} from '../util/motRecalls';
+import { validateFeatureFlags, validateSingleVin } from '../validators/motRecalls';
+
+const cache: Map<string, (string | MotSecret)> = new Map();
+const defaultResponse = addHttpHeaders({
+  statusCode: 200,
+  body: JSON.stringify({
+    manufacturer: null,
+    hasRecall: false,
+  }),
+});
+
+export const handler = async (event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> => {
+  logger.info('Recalls end point called');
+  try {
+    const validateFeatureFlagsRecalls = await validateFeatureFlags();
+    if (validateFeatureFlagsRecalls) {
+      return validateFeatureFlagsRecalls;
+    }
+
+    const vin: string = decodeURIComponent(event.pathParameters?.vin as string);
+    if (!validateSingleVin(vin)) {
+      logger.error(formatErrorMessage('VIN provided in path parameter is not valid.'));
+      return defaultResponse;
+    }
+
+    const cachedMotSecret = cache.get('motSecret') as MotSecret;
+    const motSecret = cachedMotSecret ?? await SecretsManager.get(
+      { SecretId: EnvironmentVariables.get('MOT_RECALL_SECRET') },
+      {},
+      { fromYaml: true },
+    );
+
+    if (!cache.has('motSecret')) {
+      cache.set('motSecret', motSecret);
+    }
+
+    const cachedBearerToken = cache.get('bearerToken');
+    const bearerToken = cachedBearerToken ?? await getBearerToken(motSecret);
+
+    if (!bearerToken) {
+      logger.error('bearer token not found');
+      return defaultResponse;
+    }
+
+    if (!cache.has('bearerToken')) {
+      cache.set('bearerToken', bearerToken);
+    }
+
+    const recalls = await getMotRecallsByVin(vin, cache, motSecret);
+
+    if (!recalls) {
+      return defaultResponse;
+    }
+
+    const recallsResponse = filterMotRecalls(recalls);
+
+    logger.debug(`Final response: ${JSON.stringify(recallsResponse)}`);
+    return addHttpHeaders({
+      statusCode: 200,
+      body: JSON.stringify(recallsResponse),
+    });
+  } catch (err) {
+    console.error(err);
+    return addHttpHeaders({
+      statusCode: 500,
+      body: 'Error calling recalls API',
+    });
+  }
+};

src/models/motRecalls.ts

@@ -0,0 +1,32 @@
+export interface MotRecalls {
+  vin: string,
+  manufacturer: string,
+  recalls: Recall[],
+  lastUpdatedDate: string
+}
+
+export interface Recall {
+  manufacturerCampaignReference: string,
+  dvsaCampaignReference: string,
+  recallCampaignStartDate: string,
+  repairStatus: RepairStatus
+}
+
+export type RepairStatus = 'FIXED' | 'NOT_FIXED';
+
+export interface MotSecret {
+  clientID: string,
+  clientSecret: string,
+  scopeURL: string,
+  accessTokenURL: string,
+  apiKey: string,
+  apiURL: string,
+}
+
+export interface BearerResponse {
+  token_type: string,
+  expires_in: number,
+  ext_expires_in: number,
+  access_token: string
+
+}

src/util/motRecalls.ts

@@ -0,0 +1,112 @@
+import { RecallsSchema } from '@dvsa/cvs-type-definitions/types/v1/recalls';
+import { BearerResponse, MotRecalls, MotSecret } from '../models/motRecalls';
+import logger from './logger';
+
+/**
+ * Search retrieved recall data for an active recall then construct return object.
+ * @param vehicleRecalls
+ * @returns
+ */
+export const filterMotRecalls = (vehicleRecalls: MotRecalls): RecallsSchema => {
+  logger.debug('Filter Recall Response');
+  const foundRecall = vehicleRecalls.recalls.find((recall) => {
+    if (recall.repairStatus === 'NOT_FIXED' && Date.parse(recall.recallCampaignStartDate) < Date.now()) {
+      return recall;
+    }
+    return false;
+  });
+  return {
+    manufacturer: foundRecall ? vehicleRecalls.manufacturer : null,
+    hasRecall: !!foundRecall,
+  };
+};
+
+/**
+ * Retrieve vehicle recall data from MOT recall API
+ * @param vin - vin is query parameter
+ * @param cache - the stored cache with string or mot secret
+ * @param motSecret - mot secret
+ * @returns Promise<motRecalls> - vehicle recall information
+ */
+export const getMotRecallsByVin = async (vin: string, cache: Map<string, (string | MotSecret)>, motSecret: MotSecret):
+Promise<MotRecalls | undefined> => {
+  logger.debug('Calling MOT Recalls');
+
+  try {
+    const bearerToken = cache.get('bearerToken') as string;
+    const motApiUrl = `${motSecret.apiURL}/${vin}`;
+
+    let recallResponse = await fetch(motApiUrl, {
+      headers: {
+        Authorization: `Bearer ${bearerToken}`,
+        'x-api-key': motSecret.apiKey,
+      },
+    });
+
+    let parsedRecallResponse = await recallResponse.json() as MotRecalls;
+
+    logger.debug(`first recall status code: ${recallResponse.status}`);
+    logger.debug(`first recall response: ${JSON.stringify(parsedRecallResponse)}`);
+
+    if (recallResponse.status === 403 || recallResponse.status === 401) {
+      const newBearerToken = await getBearerToken(motSecret);
+      if (!newBearerToken) {
+        return undefined;
+      }
+      logger.debug('got a new bearer token');
+
+      cache.set('bearerToken', newBearerToken);
+      recallResponse = await fetch(motApiUrl, {
+        headers: {
+          Authorization: `Bearer ${bearerToken}`,
+          'x-api-key': motSecret.apiKey,
+        },
+      });
+
+      parsedRecallResponse = await recallResponse.json() as MotRecalls;
+
+      logger.debug(`second recall status code: ${recallResponse.status}`);
+      logger.debug(`second recall response: ${JSON.stringify(parsedRecallResponse)}`);
+    }
+
+    if (recallResponse.status === 200) {
+      return parsedRecallResponse;
+    }
+
+    return undefined;
+  } catch (err) {
+    logger.error(`failed calling MOT endpoint: Error: ${(err as Error).message}`);
+    return undefined;
+  }
+};
+
+/**
+ * Retrieve bearer token from MOT for recall API
+ * @param motSecret - the mot secret details
+ * @returns Promise<BearerToken> - JWT bearer token for recalls
+ */
+export const getBearerToken = async (motSecret: MotSecret): Promise<string | undefined> => {
+  logger.debug('Calling MOT Token');
+
+  const params = new URLSearchParams();
+  params.append('grant_type', 'client_credentials');
+  params.append('client_id', motSecret.clientID);
+  params.append('client_secret', motSecret.clientSecret);
+  params.append('scope', motSecret.scopeURL);
+
+  try {
+    const tokenResponse = await fetch(motSecret.accessTokenURL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: params,
+    });
+
+    const body = await tokenResponse.json() as BearerResponse;
+    return body.access_token;
+  } catch (err) {
+    logger.error(`Failed to get bearer token: Error: ${(err as Error).message}`);
+    return undefined;
+  }
+};

src/validators/motRecalls.ts

@@ -0,0 +1,52 @@
+import { getProfile } from '@dvsa/cvs-feature-flags/profiles/vtx';
+import { addHttpHeaders } from '../util/httpHeaders';
+import logger from '../util/logger';
+
+/**
+ * validate the input vin has a valid format
+ * @param vin - query param
+ * @returns boolean - valid/invalid format
+ */
+export const validateSingleVin = (vin: string) => {
+  if (vin) {
+    if (vin.length < 3
+      || vin.length > 21
+      || typeof vin !== 'string'
+      || !(/^[0-9a-z]+$/i).test(vin)
+      || vin.toUpperCase().includes('O')
+      || vin.toUpperCase().includes('I')
+      || vin.toUpperCase().includes('Q')
+    ) {
+      return false;
+    }
+  } else {
+    return false;
+  }
+  return true;
+};
+
+export const validateFeatureFlags = async () => {
+  logger.debug('validating the mot recalls feature flags');
+  const featureFlags = await getProfile();
+
+  if (!featureFlags.recallsApi) {
+    logger.error('Recall Feature Flag is undefined');
+    return addHttpHeaders({
+      statusCode: 500,
+      body: 'Recall Feature Flag is undefined',
+    });
+  }
+
+  if (!featureFlags.recallsApi.enabled) {
+    logger.warn('Flag disabled: please enable for recalls functionality');
+    return addHttpHeaders({
+      statusCode: 200,
+      body: JSON.stringify({
+        manufacturer: null,
+        hasRecall: false,
+      }),
+    });
+  }
+
+  return undefined;
+};

template.yml

@@ -167,6 +167,19 @@ Resources:
             Properties:
               Path: !GetAtt LocalQueue.Arn
               BatchSize: 10
+
+    RecallsLambdaFunction:
+      Type: 'AWS::Serverless::Function'
+      Properties:
+        CodeUri: src/handler/
+        Handler: motRecalls.handler
+        Runtime: nodejs18.x
+        Events:
+          GetRecallsApi:
+            Type: Api
+            Properties:
+              Path: /v3/technical-records/recalls/{vin}
+              Method: get
 
     MotUpdateVrm:
       Type: 'AWS::Serverless::Function'