@carecard/validate 3.1.23 → 3.1.24

package/.codex/AGENTS.md

@@ -92,6 +92,7 @@ The `pkg-*` directories are reusable CareCard packages. Shared API response, err
 
 - Write or update tests before implementation whenever changing behavior.
 - Testing is mandatory before finalizing code changes. Do not stop after implementation if tests, `.junie`, or `.husky` checks remain unrun.
+- Code coverage must never be lower than the previous commit. When coverage tooling exists, compare against the previous commit or recorded baseline before finalizing, add tests to maintain or improve coverage, and never reduce coverage thresholds to make checks pass.
 - Keep tests readable and domain-specific. Prefer explicit helper names over generic test utilities that hide important behavior.
 - Use existing test frameworks and layouts:
     - JavaScript `api-*`: usually Mocha, Supertest, `test/index.test.js`, and Docker-backed Postgres scripts.

package/.husky/pre-commit

@@ -1,5 +1,3 @@
-npm run lint:fix
-npm run format
-
 # Run tests
-npm run test:All
+npm run test
+npm run test:types

package/index.d.ts

@@ -13,18 +13,10 @@ export interface ValidateWhitelistPropertiesOptions {
     convertToSnakeCase?: boolean;
     /**
      * When true, the returned object is flattened so that every validated leaf
-     * becomes a top-level key. No nested objects remain in the output. Applied
-     * after snake_case conversion.
+     * becomes a top-level key, joined by `.` (e.g. `{ 'user.first_name': 'Jane' }`).
+     * No nested objects remain in the output. Applied after snake_case conversion.
      */
     flattenOutput?: boolean;
-    /**
-     * Controls flattened key naming when `flattenOutput` is true.
-     * - `path` uses full dot-notation paths, e.g. `{ "user.email": "Jane" }`.
-     * - `leaf` uses only leaf names, e.g. `{ email: "Jane" }`.
-     *
-     * Defaults to `path`.
-     */
-    flattenKeyStyle?: 'path' | 'leaf';
 }
 
 /**
@@ -46,11 +38,10 @@ export interface ValidateWhitelistPropertiesOptions {
  *   validated elements (e.g. `{ name: ["First", "Other"] }` is validated like
  *   `{ name: "First" }` and `{ name: "Other" }` individually).
  * - Optionally converts the resulting keys (including nested keys) to snake_case.
- * - Optionally flattens the result after snake_case conversion.
  *
  * @param inputObject The input object (e.g. `req.body` or `req.params`).
  * @param requiredProperties Leaf paths that must be present and valid. Dot-notation supported.
- * @param options Optional additional leaf paths plus output transformation flags.
+ * @param options Optional list of additional allowed leaf paths and case-conversion flag.
  */
 export function validateWhitelistProperties(
     inputObject: Record<string, any>,
@@ -58,6 +49,24 @@ export function validateWhitelistProperties(
     options?: ValidateWhitelistPropertiesOptions,
 ): Promise<Record<string, any>>;
 
+export const DEFAULT_USER_ROLE_REQUEST_ROLE: 'student';
+export const REQUIRE_SCOPE_WHEN_ROLE_OR_SCOPE_PRESENT: 'whenRoleOrScopePresent';
+
+export interface ValidateNewUserRoleRequestOptions {
+    defaultRole?: 'student' | undefined;
+    requireScope?: boolean | typeof REQUIRE_SCOPE_WHEN_ROLE_OR_SCOPE_PRESENT;
+}
+
+/**
+ * Normalizes and validates a carecard.new_user_role_request payload.
+ * Only student, intern, and volunteer are accepted. When scope is required,
+ * both institution_id and campus_id must be provided.
+ */
+export function validateNewUserRoleRequestObject(
+    roleRequest?: Record<string, any>,
+    options?: ValidateNewUserRoleRequestOptions,
+): Record<string, any>;
+
 /** Checks if the string is a valid image URL format. */
 export function isImageUrl(imageUrl: any): boolean;
 /** Checks if the value is an integer. */
@@ -112,6 +121,8 @@ export function isTextString(str: any): boolean;
 export function isInStringArray(StringArray: string[], inputString: any): boolean;
 /** Checks if the string is one of the supported user role request statuses. */
 export function isUserRoleRequestStatusString(inputString: any): boolean;
+/** Checks if the string is a supported new user role request role. */
+export function isUserRoleRequestRoleString(inputString: any): boolean;
 /** Checks if the string is a valid country code (e.g., +1). */
 export function isCountryCodeString(str: any): boolean;
 /** Checks if the string is a valid domain name. */
@@ -158,6 +169,7 @@ export const validate: {
     isTextString: typeof isTextString;
     isInStringArray: typeof isInStringArray;
     isUserRoleRequestStatusString: typeof isUserRoleRequestStatusString;
+    isUserRoleRequestRoleString: typeof isUserRoleRequestRoleString;
     isCountryCodeString: typeof isCountryCodeString;
     isValidDomainName: typeof isValidDomainName;
     isValidTimestampzString: typeof isValidTimestampzString;

package/index.js

@@ -1,11 +1,13 @@
 const validate = require('./lib/validate');
 const validateProperties = require('./lib/validateProperties');
 const validateWhitelistProperties = require('./lib/validateWhitelistProperties');
+const validateNewUserRoleRequest = require('./lib/validateNewUserRoleRequest');
 
 module.exports = {
     validate,
     validateProperties,
     validateWhitelistProperties,
+    ...validateNewUserRoleRequest,
     ...validate,
     ...validateProperties,
 };

package/lib/validate.js

@@ -173,6 +173,11 @@ const isUserRoleRequestStatusString = inputString => {
     return isInStringArray(statuses, inputString);
 };
 
+const isUserRoleRequestRoleString = inputString => {
+    const roles = ['student', 'intern', 'volunteer'];
+    return typeof inputString === 'string' && roles.includes(inputString.trim().toLowerCase());
+};
+
 const isCountryCodeString = str => {
     if (typeof str !== 'string' || str.length === 0 || str.length > 4) return false;
 
@@ -243,6 +248,7 @@ module.exports = {
     isTextString,
     isInStringArray,
     isUserRoleRequestStatusString,
+    isUserRoleRequestRoleString,
     isCountryCodeString,
     isValidDomainName,
     isValidTimestampzString,

package/lib/validateNewUserRoleRequest.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const {
+    error: { throwBadInputError },
+} = require('@carecard/common-util');
+const { isUserRoleRequestRoleString } = require('./validate');
+
+const DEFAULT_USER_ROLE_REQUEST_ROLE = 'student';
+const REQUIRE_SCOPE_WHEN_ROLE_OR_SCOPE_PRESENT = 'whenRoleOrScopePresent';
+
+function validateNewUserRoleRequestObject(roleRequest = {}, options = {}) {
+    const normalized = normalizeNewUserRoleRequestObject(roleRequest);
+    const defaultRole = Object.prototype.hasOwnProperty.call(options, 'defaultRole') ? options.defaultRole : DEFAULT_USER_ROLE_REQUEST_ROLE;
+    const requireScope = Object.prototype.hasOwnProperty.call(options, 'requireScope') ? options.requireScope : true;
+
+    if (normalized.role_name === undefined && defaultRole !== undefined) {
+        normalized.role_name = defaultRole;
+    }
+
+    if (normalized.role_name !== undefined && !isUserRoleRequestRoleString(normalized.role_name)) {
+        throwBadInputError({
+            userMessage: 'Invalid property: role.role',
+            details: { role: 'Role requests are limited to student, intern, or volunteer' },
+        });
+    }
+
+    if (shouldRequireScope(normalized, requireScope)) {
+        requireNewUserRoleRequestScope(normalized);
+    }
+
+    return normalized;
+}
+
+function normalizeNewUserRoleRequestObject(roleRequest) {
+    const normalized = { ...roleRequest };
+
+    assignAlias(normalized, 'role_name', 'roleName');
+    assignAlias(normalized, 'role_name', 'role');
+    assignAlias(normalized, 'institution_id', 'institutionId');
+    assignAlias(normalized, 'campus_id', 'campusId');
+    assignAlias(normalized, 'program_id', 'programId');
+
+    delete normalized.roleName;
+    delete normalized.role;
+    delete normalized.institutionId;
+    delete normalized.campusId;
+    delete normalized.programId;
+
+    return normalized;
+}
+
+function assignAlias(target, canonicalKey, aliasKey) {
+    if (target[canonicalKey] === undefined && target[aliasKey] !== undefined) {
+        target[canonicalKey] = target[aliasKey];
+    }
+}
+
+function shouldRequireScope(roleRequest, requireScope) {
+    if (requireScope === true) return true;
+    if (requireScope !== REQUIRE_SCOPE_WHEN_ROLE_OR_SCOPE_PRESENT) return false;
+
+    return roleRequest.role_name !== undefined || roleRequest.institution_id !== undefined || roleRequest.campus_id !== undefined;
+}
+
+function requireNewUserRoleRequestScope(roleRequest) {
+    if (!roleRequest.institution_id) {
+        throwBadInputError({ userMessage: 'Missing property: role.institutionId' });
+    }
+
+    if (!roleRequest.campus_id) {
+        throwBadInputError({ userMessage: 'Missing property: role.campusId' });
+    }
+}
+
+module.exports = {
+    DEFAULT_USER_ROLE_REQUEST_ROLE,
+    REQUIRE_SCOPE_WHEN_ROLE_OR_SCOPE_PRESENT,
+    validateNewUserRoleRequestObject,
+};

package/lib/validateProperties.js

@@ -22,6 +22,7 @@ const {
     isStreetString,
     isTextString,
     isUserRoleRequestStatusString,
+    isUserRoleRequestRoleString,
 } = require('./validate');
 
 function validateProperties(obj = {}) {
@@ -196,6 +197,12 @@ function validateProperties(obj = {}) {
                     returnObj[key] = value;
                 }
                 break;
+            case 'user_role_request_role':
+            case 'userRoleRequestRole':
+                if (isUserRoleRequestRoleString(value)) {
+                    returnObj[key] = value;
+                }
+                break;
             case 'period':
                 if (isCharactersString(value)) {
                     returnObj[key] = value;

package/lib/validateWhitelistProperties.js

@@ -16,8 +16,6 @@ const MAX_NESTING_DEPTH = 5;
  * adversarial inputs.
  */
 const MAX_KEYS_PER_CALL = 5000;
-const DEFAULT_FLATTEN_KEY_STYLE = 'path';
-const VALID_FLATTEN_KEY_STYLES = new Set(['path', 'leaf']);
 
 /**
  * Returns true if the segment contains a mix of snake_case (underscore) and
@@ -163,35 +161,6 @@ function flattenObject(obj, prefix = '', out = {}) {
     return out;
 }
 
-/**
- * Recursively flattens a nested plain object using only each leaf property
- * name as the output key.
- *
- * Example: `{ a: { b: { c: 1, d: 2 } } }` => `{ c: 1, d: 2 }`.
- * If duplicate leaf keys exist at different nesting levels, the higher-level
- * leaf wins. If duplicate leaf keys exist at the same depth, the first
- * traversal wins.
- *
- * @param {Object} obj
- * @param {Object} [out]
- * @param {Object} [depthByKey]
- * @param {number} [depth]
- * @returns {Object}
- */
-function flattenObjectByLeafKey(obj, out = {}, depthByKey = {}, depth = 1) {
-    for (const [key, value] of Object.entries(obj)) {
-        if (value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)) {
-            flattenObjectByLeafKey(value, out, depthByKey, depth + 1);
-        } else {
-            if (!Object.prototype.hasOwnProperty.call(out, key) || depth < depthByKey[key]) {
-                out[key] = value;
-                depthByKey[key] = depth;
-            }
-        }
-    }
-    return out;
-}
-
 /**
  * Validates and transforms whitelisted properties from an input object.
  *
@@ -212,11 +181,8 @@ function flattenObjectByLeafKey(obj, out = {}, depthByKey = {}, depth = 1) {
  * element passes validation, and the returned value is an array of the
  * validated elements (in the same order).
  *  5. Optionally converts all keys (including nested) to snake_case.
- *  6. Optionally flattens the result (`flattenOutput`). Flattened keys use
- *     full dot paths by default (`flattenKeyStyle: 'path'`) or direct leaf
- *     names when requested (`flattenKeyStyle: 'leaf'`). For duplicate leaf
- *     keys in leaf mode, the shallower value wins; ties keep the first value
- *     encountered. Applied after snake_case conversion.
+ *  6. Optionally flattens the result so every leaf is a top-level key,
+ *     joined by `.` (`flattenOutput`). Applied after snake_case conversion.
  *
  * @param {Object} inputObject - The input object (e.g., req.body / req.params).
  * @param {Array<string>} [requiredProperties=[]] - Leaf paths that MUST be present and valid.
@@ -224,26 +190,17 @@ function flattenObjectByLeafKey(obj, out = {}, depthByKey = {}, depth = 1) {
  * @param {Array<string>} [options.optionalProperties=[]] - Leaf paths allowed but not required.
  * @param {boolean} [options.convertToSnakeCase=false] - Whether to convert keys to snake_case.
  * @param {boolean} [options.flattenOutput=false] - Whether to flatten the result so that
- *   every leaf is a top-level key, with no nested objects in the output.
- * @param {'path'|'leaf'} [options.flattenKeyStyle='path'] - Flattened key naming strategy
- *   when `flattenOutput` is true. `path` uses dot-joined paths; `leaf` uses leaf names.
+ *   every leaf is a top-level key (joined by `.`), with no nested objects in the output.
  * @returns {Promise<Object>} Resolves with the validated (and possibly transformed) object.
  */
 function validateWhitelistProperties(
     inputObject,
     requiredProperties = [],
-    options = { optionalProperties: [], convertToSnakeCase: false, flattenOutput: false, flattenKeyStyle: DEFAULT_FLATTEN_KEY_STYLE },
+    options = { optionalProperties: [], convertToSnakeCase: false, flattenOutput: false },
 ) {
     const optionalProperties = (options && options.optionalProperties) || [];
     const convertToSnakeCase = !!(options && options.convertToSnakeCase);
     const flattenOutput = !!(options && options.flattenOutput);
-    const flattenKeyStyle = options && options.flattenKeyStyle !== undefined ? options.flattenKeyStyle : DEFAULT_FLATTEN_KEY_STYLE;
-
-    if (!VALID_FLATTEN_KEY_STYLES.has(flattenKeyStyle)) {
-        throwBadInputError({
-            userMessage: `Invalid flattenKeyStyle: ${String(flattenKeyStyle)}. Expected "path" or "leaf"`,
-        });
-    }
 
     // Cap the total number of paths to validate per call.
     const totalKeys = (requiredProperties ? requiredProperties.length : 0) + optionalProperties.length;
@@ -314,9 +271,9 @@ function validateWhitelistProperties(
         validatedObject = keysToSnakeCase(validatedObject);
     }
 
-    // 6. Optional flattening.
+    // 6. Optional flattening: produce a flat object with dot-joined keys.
     if (flattenOutput) {
-        validatedObject = flattenKeyStyle === 'leaf' ? flattenObjectByLeafKey(validatedObject) : flattenObject(validatedObject);
+        validatedObject = flattenObject(validatedObject);
     }
 
     return Promise.resolve(validatedObject);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@carecard/validate",
-    "version": "3.1.23",
+    "version": "3.1.24",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/CareCard-ca/pkg-validate.git"
@@ -12,7 +12,7 @@
         "test": "mocha --recursive",
         "test:types": "tsc --noEmit && echo \"\\n  ✔ Type tests passed: tsc --noEmit reported 0 errors across index.d.ts and test/**/*.ts\\n\"",
         "test:coverage": "tsc --noEmit && export NODE_ENV=test && nyc mocha --recursive",
-        "test:All": "npm run test && npm run test:types",
+        "test:All": "npm run test:coverage && npm run test:types",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
         "prepare": "husky",
@@ -39,5 +39,17 @@
     },
     "dependencies": {
         "@carecard/common-util": "^3.1.13"
+    },
+    "nyc": {
+        "all": true,
+        "include": [
+            "index.js",
+            "lib/**/*.js"
+        ],
+        "check-coverage": true,
+        "branches": 100,
+        "functions": 100,
+        "lines": 100,
+        "statements": 100
     }
 }