@dvsa/appdev-api-common 0.3.2 → 0.4.0

package/README.md

@@ -35,3 +35,15 @@ There are two ways in which this package can/should be published:
 ###### Requires manual version bump via the PR
 
 - Upon merge into `main` branch, the package will be published via a GHA workflow.
+
+### Developing locally
+To test our your changes before publishing to `npm`, you can use the following command:
+
+`npm run localLink`
+
+Then in the project you wish to use this package, run:
+
+`npm link @dvsa/appdev-api-common`
+
+Once you've completed your local testing and/or to start again from scratch, you can run:
+`npm unlink @dvsa/appdev-api-common`

package/auth/auth-checker.d.ts

@@ -8,7 +8,8 @@ export declare class JWTAuthChecker {
     /**
      * Perform a JWT token verification and role check
      * @param {RoutingControllersRequest} request
-     * @param roles
+     * @param {string | string[]} roles
+     * @returns {Promise<boolean>}
      */
     static execute({ request }: Action, roles?: string | string[]): Promise<boolean>;
 }

package/auth/auth-checker.js

@@ -9,14 +9,17 @@ class JWTAuthChecker {
     /**
      * Perform a JWT token verification and role check
      * @param {RoutingControllersRequest} request
-     * @param roles
+     * @param {string | string[]} roles
+     * @returns {Promise<boolean>}
      */
     static async execute({ request }, roles = []) {
         // if running locally, skip the token auth and role check
-        if (process.env.IS_OFFLINE === "true" && process.env.FORCE_LOCAL_AUTH !== "true")
+        if (process.env.IS_OFFLINE === "true" &&
+            process.env.FORCE_LOCAL_AUTH !== "true")
             return true;
         // extract the token from the request headers
-        const headers = request?.apiGateway.event.headers;
+        const headers = request?.apiGateway.event
+            .headers;
         const token = headers?.Authorization || headers?.authorization;
         // if no token is found, then deny access to resource
         if (!token || token.trim()?.length === 0) {

package/auth/client-credentials.d.ts

@@ -11,9 +11,32 @@ export declare class ClientCredentials {
     private readonly scope;
     private readonly debugMode;
     private static accessToken;
-    private static readonly grant_type;
+    private static readonly grantType;
+    /**
+     * Create a new instance of the ClientCredentials class
+     * @param tokenUrl - The URL to fetch the access token from
+     * @param clientId - The client id
+     * @param clientSecret - The client secret
+     * @param scope - The scope of the access token
+     * @param debugMode - Whether to log debug messages
+     */
     constructor(tokenUrl: string, clientId: string, clientSecret: string, scope: string, debugMode?: boolean);
+    /**
+     * Helper method to perform the client credentials flow and return the access token
+     * This method will check for the existence of the token and if it is expired, it will fetch a new one
+     * @returns {Promise<string>} - The access token
+     */
     getAccessToken(): Promise<string>;
+    /**
+     * Fetch the client credentials from the token URL
+     * @returns {Promise<ClientCredentialsResponse>} - The response from the token URL
+     * @private
+     */
     private fetchClientCredentials;
+    /**
+     * Check if the access token is expired
+     * @returns {boolean} - Whether the access token is expired
+     * @private
+     */
     private isAccessTokenExpired;
 }

package/auth/client-credentials.js

@@ -10,7 +10,15 @@ class ClientCredentials {
     scope;
     debugMode;
     static accessToken;
-    static grant_type = "client_credentials";
+    static grantType = "client_credentials";
+    /**
+     * Create a new instance of the ClientCredentials class
+     * @param tokenUrl - The URL to fetch the access token from
+     * @param clientId - The client id
+     * @param clientSecret - The client secret
+     * @param scope - The scope of the access token
+     * @param debugMode - Whether to log debug messages
+     */
     constructor(tokenUrl, clientId, clientSecret, scope, debugMode = false) {
         this.tokenUrl = tokenUrl;
         this.clientId = clientId;
@@ -18,6 +26,11 @@ class ClientCredentials {
         this.scope = scope;
         this.debugMode = debugMode;
     }
+    /**
+     * Helper method to perform the client credentials flow and return the access token
+     * This method will check for the existence of the token and if it is expired, it will fetch a new one
+     * @returns {Promise<string>} - The access token
+     */
     async getAccessToken() {
         if (!ClientCredentials.accessToken || this.isAccessTokenExpired()) {
             const { access_token } = await this.fetchClientCredentials();
@@ -30,12 +43,17 @@ class ClientCredentials {
         }
         return ClientCredentials.accessToken;
     }
+    /**
+     * Fetch the client credentials from the token URL
+     * @returns {Promise<ClientCredentialsResponse>} - The response from the token URL
+     * @private
+     */
     async fetchClientCredentials() {
         const response = await fetch(this.tokenUrl, {
             method: "POST",
             headers: { "Content-Type": "application/x-www-form-urlencoded" },
             body: (0, node_querystring_1.stringify)({
-                grant_type: ClientCredentials.grant_type,
+                grant_type: ClientCredentials.grantType,
                 client_id: this.clientId,
                 client_secret: this.clientSecret,
                 scope: this.scope,
@@ -47,6 +65,11 @@ class ClientCredentials {
         }
         return (await response.json());
     }
+    /**
+     * Check if the access token is expired
+     * @returns {boolean} - Whether the access token is expired
+     * @private
+     */
     isAccessTokenExpired() {
         try {
             const decodedAccessToken = (0, jose_1.decodeJwt)(ClientCredentials.accessToken);

package/auth/verify-jwt.d.ts

@@ -5,9 +5,14 @@ export declare class JwtAuthoriser {
     private static readonly tokenExpiryEnvExclusionList;
     private static readonly JWKS_URI;
     private static JWKS;
+    /**
+     * Create a new instance of the JwtAuthoriser class
+     * @param clientId - the client id to validate the token against
+     */
     constructor(clientId?: string | null);
     /**
      * Validate a JWT and return the decoded payload
+     * @param {string} token - the JWT token to validate
      * @returns {Promise<JWTPayload>}
      */
     verify(token: string): Promise<JWTPayload>;

package/auth/verify-jwt.js

@@ -13,11 +13,16 @@ class JwtAuthoriser {
     ];
     static JWKS_URI = new URL("https://login.microsoftonline.com/common/discovery/keys");
     static JWKS = (0, jose_1.createRemoteJWKSet)(JwtAuthoriser.JWKS_URI);
+    /**
+     * Create a new instance of the JwtAuthoriser class
+     * @param clientId - the client id to validate the token against
+     */
     constructor(clientId = null) {
         this.clientId = clientId;
     }
     /**
      * Validate a JWT and return the decoded payload
+     * @param {string} token - the JWT token to validate
      * @returns {Promise<JWTPayload>}
      */
     async verify(token) {

package/index.d.ts

@@ -3,4 +3,5 @@ export * from "./auth/auth-checker";
 export * from "./auth/auth-errors";
 export * from "./auth/client-credentials";
 export * from "./auth/verify-jwt";
+export * from "./utils/date-time";
 export * from "./validation/request-body";

package/index.js

@@ -19,4 +19,5 @@ __exportStar(require("./auth/auth-checker"), exports);
 __exportStar(require("./auth/auth-errors"), exports);
 __exportStar(require("./auth/client-credentials"), exports);
 __exportStar(require("./auth/verify-jwt"), exports);
+__exportStar(require("./utils/date-time"), exports);
 __exportStar(require("./validation/request-body"), exports);

package/jest.config.ts

@@ -0,0 +1,8 @@
+import type { Config } from "jest";
+
+const config: Config = {
+	preset: "ts-jest",
+	testEnvironment: "node",
+};
+
+export default config;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dvsa/appdev-api-common",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "keywords": [
     "dvsa",
     "nodejs",
@@ -13,18 +13,22 @@
     "access": "public"
   },
   "scripts": {
+    "localLink": "npm run clean && npm version patch && npm run build && cp package.json dist && cd dist && npm link",
     "clean": "rimraf coverage dist",
     "clean:temp": "rimraf auth api",
     "lint": "biome check src",
     "lint:fix": "npm run lint -- --write",
     "build": "npm run clean && tsc",
     "build:package": "npm run build",
+    "test": "jest",
+    "test:coverage": "jest --coverage",
     "prepublishOnly": "npm run build:package && cp -r ./dist/* . && rm -rf ./dist",
     "postpublish": "git clean -fd && npm run clean:temp",
     "gitSecrets": "git secrets --scan . && git log -p -- . | scanrepo"
   },
   "dependencies": {
     "ajv": "^8.17.1",
+    "dayjs": "^1.11.13",
     "jose": "^5.9.6"
   },
   "devDependencies": {
@@ -38,9 +42,12 @@
     "jest": "^29.7.0",
     "lint-staged": "^15.2.10",
     "rimraf": "^6.0.1",
-    "routing-controllers": "^0.10.4",
+    "routing-controllers": "^0.11.2",
     "ts-jest": "^29.2.5",
     "ts-node": "^10.9.2",
     "typescript": "^5.5.2"
+  },
+  "lint-staged": {
+    "*.{js,ts,mjs,css,md,ts,json}": "npm run lint:fix -- --no-errors-on-unmatched"
   }
 }

package/utils/date-time.d.ts

@@ -0,0 +1,24 @@
+import dayjs from "dayjs";
+type AcceptableDate = DateTime | string | Date | null;
+export declare class DateTime {
+    private instance;
+    private static readonly UKLocalDateTimeFormat;
+    private static readonly UKLocalDateFormat;
+    constructor(sourceDateTime?: AcceptableDate, format?: string | undefined);
+    static at(sourceDateTime: AcceptableDate, format?: string | undefined): DateTime | null;
+    static StandardUkLocalDateTimeAdapter(sourceDateTime: AcceptableDate): string | null;
+    static StandardUkLocalDateAdapter(sourceDateTime: AcceptableDate): string | null;
+    add(amount: number, unit: dayjs.ManipulateType): DateTime;
+    subtract(amount: number, unit: dayjs.ManipulateType): DateTime;
+    format(formatString: string): string;
+    day(): number;
+    toString(): string;
+    toISOString(): string;
+    isAfter(targetDate: AcceptableDate): boolean;
+    diff(targetDate: AcceptableDate, unit: dayjs.QUnitType, precise?: boolean): number;
+    daysDiff(targetDate: AcceptableDate): number;
+    compareDuration(targetDate: AcceptableDate, unit: dayjs.QUnitType): number;
+    isBefore(targetDate: AcceptableDate): boolean;
+    static today(): Date;
+}
+export {};

package/utils/date-time.js

@@ -0,0 +1,85 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DateTime = void 0;
+const dayjs_1 = __importDefault(require("dayjs"));
+const customParseFormat_1 = __importDefault(require("dayjs/plugin/customParseFormat"));
+class DateTime {
+    instance;
+    static UKLocalDateTimeFormat = "DD/MM/YYYY HH:mm:ss";
+    static UKLocalDateFormat = "DD/MM/YYYY";
+    constructor(sourceDateTime, format = undefined) {
+        dayjs_1.default.extend(customParseFormat_1.default);
+        if (sourceDateTime === undefined || sourceDateTime === null) {
+            this.instance = (0, dayjs_1.default)();
+        }
+        else if (typeof sourceDateTime === "string" ||
+            sourceDateTime instanceof Date) {
+            this.instance = (0, dayjs_1.default)(sourceDateTime, format);
+        }
+        else {
+            this.instance = (0, dayjs_1.default)(sourceDateTime.instance, format);
+        }
+    }
+    static at(sourceDateTime, format = undefined) {
+        if (!sourceDateTime) {
+            return null;
+        }
+        return new DateTime(sourceDateTime, format);
+    }
+    static StandardUkLocalDateTimeAdapter(sourceDateTime) {
+        return (DateTime.at(sourceDateTime)?.format(DateTime.UKLocalDateTimeFormat) ||
+            null);
+    }
+    static StandardUkLocalDateAdapter(sourceDateTime) {
+        return (DateTime.at(sourceDateTime)?.format(DateTime.UKLocalDateFormat) || null);
+    }
+    add(amount, unit) {
+        this.instance = this.instance.add(amount, unit);
+        return this;
+    }
+    subtract(amount, unit) {
+        this.instance = this.instance.subtract(amount, unit);
+        return this;
+    }
+    format(formatString) {
+        return this.instance.format(formatString);
+    }
+    day() {
+        return this.instance.day();
+    }
+    toString() {
+        return this.instance.toString();
+    }
+    toISOString() {
+        return this.instance.toISOString();
+    }
+    isAfter(targetDate) {
+        const date = new DateTime(targetDate);
+        return this.instance.isAfter(date.instance);
+    }
+    diff(targetDate, unit, precise) {
+        const date = new DateTime(targetDate);
+        return this.instance.diff(date.instance, unit, precise);
+    }
+    daysDiff(targetDate) {
+        const date = new DateTime(targetDate);
+        return this.instance
+            .startOf("day")
+            .diff(date.instance.startOf("day"), "day");
+    }
+    compareDuration(targetDate, unit) {
+        const date = new DateTime(targetDate);
+        return date.instance.diff(this.instance, unit);
+    }
+    isBefore(targetDate) {
+        const date = new DateTime(targetDate);
+        return this.instance.isBefore(date.instance);
+    }
+    static today() {
+        return (0, dayjs_1.default)().toDate();
+    }
+}
+exports.DateTime = DateTime;

package/validation/request-body.d.ts

@@ -1,10 +1,13 @@
+interface ValidateRequestBodyOptions {
+    isArray?: boolean;
+    errorDetails?: boolean;
+}
 /**
  * Decorator tp validate an express request body against a specified schema
  * @param {object} schema - the json schema you wish to use as the validator
- * @param isArray - whether the body is expected to be an array
- * @param errorDetails - whether to return detailed error messages (Note: errors are logged regardless of this setting)
+ * @param {ValidateRequestBodyOptions} opts
+ * - isArray: whether the body is expected to be an array
+ * - errorDetails: whether to return detailed error messages (Note: errors are logged regardless of this setting)
  */
-export declare function ValidateRequestBody<T>(schema: object, { isArray, errorDetails }?: {
-    isArray: boolean;
-    errorDetails: boolean;
-}): (_target: T, _propertyKey: string, descriptor: PropertyDescriptor) => void;
+export declare function ValidateRequestBody<T>(schema: object, opts?: ValidateRequestBodyOptions): (_target: T, _propertyKey: string, descriptor: PropertyDescriptor) => void;
+export {};

package/validation/request-body.js

@@ -11,10 +11,11 @@ ajv.addKeyword("tsEnumNames");
 /**
  * Decorator tp validate an express request body against a specified schema
  * @param {object} schema - the json schema you wish to use as the validator
- * @param isArray - whether the body is expected to be an array
- * @param errorDetails - whether to return detailed error messages (Note: errors are logged regardless of this setting)
+ * @param {ValidateRequestBodyOptions} opts
+ * - isArray: whether the body is expected to be an array
+ * - errorDetails: whether to return detailed error messages (Note: errors are logged regardless of this setting)
  */
-function ValidateRequestBody(schema, { isArray, errorDetails } = { isArray: false, errorDetails: false }) {
+function ValidateRequestBody(schema, opts = { isArray: false, errorDetails: false }) {
     return (_target, _propertyKey, descriptor) => {
         const originalMethod = descriptor.value;
         descriptor.value = async function (body, res, next) {
@@ -27,8 +28,8 @@ function ValidateRequestBody(schema, { isArray, errorDetails } = { isArray: fals
             const payload = Buffer.isBuffer(body)
                 ? JSON.parse(body.toString("utf-8"))
                 : body;
-            // Create the appropriate schema based on whether we're validating an array
-            const schemaToValidate = isArray
+            // Create the appropriate schema based on whether we're validating an array or a single object
+            const schemaToValidate = opts?.isArray
                 ? { type: "array", items: schema }
                 : schema;
             const validateFunction = ajv.compile(schemaToValidate);
@@ -40,7 +41,7 @@ function ValidateRequestBody(schema, { isArray, errorDetails } = { isArray: fals
                 const response = {
                     message: "Validation error",
                 };
-                if (errorDetails) {
+                if (opts?.errorDetails) {
                     Object.assign(response, { errors: validateFunction.errors });
                 }
                 return res.status(http_status_codes_1.HttpStatus.BAD_REQUEST).json(response);