@carecard/validate 3.1.22 → 3.1.24

package/.codex/AGENTS.md

@@ -0,0 +1,180 @@
+# Codex Instructions For pkg-validate
+
+These instructions apply to the `pkg-validate` repository. This file is self-contained:
+it includes the workspace-level instructions that were previously read from
+`/Users/pankajpriscilla/SO_CareCardCa/.codex/AGENTS.md`, followed by
+repository-specific guidance. Removing the workspace-level `.codex/AGENTS.md`
+must not change the rules for this repository.
+
+## Embedded Workspace Instructions
+
+These instructions apply to the whole workspace. The workspace is a collection of independent repositories, not one monorepo. Treat each `api-*`, `pkg-*`, and `app-dashboard` directory as its own project with its own package scripts, Git status, and test commands.
+
+### Non-Negotiable Instructions
+
+- **Never use TypeScript type `any`.** Always use specific domain types, generics, `unknown` with proper narrowing, or existing project types.
+- **Always follow the owner's coding style.** Preserve the existing style in the file and repository you are editing.
+- **Always follow the owner's naming conventions.** Use meaningful function, variable, file, test, and type names that match the surrounding code.
+- **Always follow the existing project structure.** Put code, tests, docs, services, validation, transforms, components, and helpers where the current repository already expects them.
+- **Always use Test-Driven Development.** Write or update focused tests first, verify they fail for the missing behavior when practical, then implement the code.
+- **Never suppress errors, TypeScript errors, linter warnings, or failing tests.** Do not add `eslint-disable`, `@ts-ignore`, broad catches, empty catches, or other suppression unless the user explicitly requests it. Handle the issue properly.
+- **Do not add new dependencies unless they are clearly necessary.** If a dependency might be needed, stop and ask for confirmation first, with a clear reason, tradeoff, and why existing code cannot reasonably solve it.
+- **Before finalizing any response for a repository, run every script in that repository's `.husky` directory.** Do not bypass hooks. If a `.husky` script fails, fix the underlying issue and rerun it. If it cannot run because of environment constraints, report the exact script and reason.
+
+### Core Coding Principles
+
+- Prefer minimal dependencies. Do not add libraries or frameworks unless the existing stack cannot reasonably solve the problem.
+- Prefer implementing core logic directly with readable code over adding abstractions or packages.
+- Explain architectural tradeoffs before major changes, especially changes that affect shared packages, API contracts, security, persistence, authentication, or frontend/backend boundaries.
+- Favor readable, maintainable code over short clever code.
+- Preserve the existing project style, file structure, naming style, module system, and test framework.
+- Use Test-Driven Development: write or update focused tests first, then implement the code.
+- Use meaningful function and variable names. Names should expose intent and domain behavior.
+- Use specific types everywhere. Do not use `any`.
+- Keep changes scoped and easy to review. Avoid unrelated formatting churn or opportunistic refactors.
+- Use postgres functions and stored procedures instead of raw SQL.
+- Use postgres and database search and other functionalities instead of doing it in controllers.
+- Use different type postgres searches, like fuzzy search, trigram search, full-text search, and vector search.
+- When possible, push the complexity of data saving, edit and access to the database.
+
+### Repo Workflow
+
+- Work from the specific project directory you are changing, such as `api-auth`, `api-contact-us`, `api-institutions`, `pkg-common-util`, or `app-dashboard`.
+- Check local status inside the affected project before editing. These directories are independent Git repositories.
+- Do not revert or overwrite changes you did not make.
+- Before finishing a code change, run the relevant tests and lint/format checks for the affected project.
+- Before finalizing any response after code changes, run all validation commands required by the affected repository. This includes relevant package scripts, all commands in `.husky` hooks, and all scripts or documented validation commands in `.junie`.
+- When a project has a `.junie` directory, read the applicable `.junie` guidance for that repository before editing. Before the final response, run every executable script in `.junie` and every validation/test command explicitly documented there. Fix any issues those commands report before finalizing.
+- When a project has files in `.husky`, run every direct script in `.husky` before finishing. Fix any issue they report before finalizing. Never skip, bypass, or silence these scripts.
+- If a required `.junie` or `.husky` command cannot be run because of a missing dependency, unavailable service, credentials, or environment limitation, clearly report the exact command, the failure reason, and the remaining risk in the final response.
+- Avoid editing generated or heavy-output directories such as `node_modules`, `dist`, `coverage`, `.next`, `logs`, and generated stores unless the task explicitly requires it.
+
+### Backend Microservices
+
+The `api-*` directories are independent Express/Postgres backend services. Most JavaScript services use CommonJS, Mocha, Supertest, Docker Compose database tests, `@carecard/*` packages, and `sub-apps` controller/router/model patterns. TypeScript services such as `api-contact-us` and `api-template-ts` use Jest or TypeScript tooling and should keep their existing TS style.
+
+- Keep service-specific controllers thin. Controllers should read as a clear workflow: parse input, authorize, validate, call domain/model logic, build response, and pass errors to `next`.
+- Extract multiline chunks into descriptively named functions in the appropriate `controllerLib`, `commonLib`, `sub-apps/lib`, model helper, or shared `pkg-*` package.
+- Avoid defining reusable workflow, validation, mapping, response, authorization, parsing, or domain helpers in the same controller/app file where they are immediately used.
+- Prefer straightforward sequencing of named helper calls over deeply nested conditionals.
+- Preserve current behavior unless fixing a clear bug, security issue, or documented contract problem.
+- Keep application setup files such as `app.js`, `app.ts`, `bin/www`, and routers focused on composition and wiring.
+- Use existing Express middleware patterns: `requestContext`, CORS configuration, Helmet, cookie parsing, body-size limits, rate limits where already present, routers, 404 handling, logging middleware, and centralized error handlers.
+- Use structured, actionable logging for important application events, external calls, state transitions, failures, and security-relevant actions.
+- Do not log secrets, tokens, passwords, credentials, personal identifiers, full request payloads, or stack traces in user-facing responses.
+- Keep logs useful for production monitoring. Avoid noisy logs that fire on every trivial branch unless they are request/access logs already established by the service.
+
+### Shared Packages And API Contracts
+
+The `pkg-*` directories are reusable CareCard packages. Shared API response, error, authentication, JWT, and validation behavior belongs there when it is common across services.
+
+- Prefer `@carecard/common-util`, `@carecard/auth-util`, `@carecard/jwt-read`, and `@carecard/validate` over duplicated local implementations.
+- For API responses and errors, use the standardized `@carecard/common-util` behavior where possible: `requestContext`, `sendResponse`, `createError`, `notFound404`, `appErrorHandler`, error throw helpers, case converters, and `ApiErrorType`.
+- Do not create or maintain duplicated common response/error helpers inside each `api-*` service. If a reusable capability is missing, add it to the correct `pkg-*` package and update callers.
+- Keep service-local response code limited to service-specific mapping or wiring.
+- Preserve the standard response shape expected by the dashboard: `success`, `status`, `statusCode`, `code`, `message`, `data`, `error`, `details`, and `meta`.
+- Include request/correlation context where available through `requestId`, `traceId`, and `meta`.
+- Error responses must be safe for users and useful for debugging without exposing secrets, tokens, credentials, stack traces, or sensitive personal data.
+- Map validation, authentication, authorization, not-found, conflict, bad input, file, and unexpected failures to distinct machine-readable codes.
+- Prefer current direct exports from shared packages over deprecated nested exports. For example, prefer direct `@carecard/jwt-read` function names and direct `@carecard/auth-util` helpers.
+
+### Validation Rules
+
+- Keep request-boundary validation close to the API/controller layer.
+- Use `validateWhitelistProperties()` once per validation boundary unless there is a specific documented reason to validate defensively again.
+- Avoid hidden duplicate validation across controller and library layers for the same logical payload.
+- Keep domain/library functions focused on domain behavior and assume validated inputs when called from validated controller paths.
+- If a public/shared library function still needs defensive validation, document why and avoid repeating the exact same validation already done by the caller.
+- Preserve validation behavior for invalid, missing, extra, and valid fields.
+- Pay attention to nested fields, dot-notation paths, camelCase/snake_case conversion, and frontend response transforms.
+
+### Tests
+
+- 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.
+    - TypeScript `api-*`: usually Jest and `tests/index.test.ts`.
+    - `pkg-*`: Mocha plus TypeScript type tests where present.
+    - `app-dashboard`: Vitest, React Testing Library, mock API tests, and Selenium for end-to-end flows.
+- For database tests, use existing seed, migration, rollback, and cleanup patterns. Keep tests isolated and make cleanup reliable even after failures.
+- Add tests for API success responses, validation errors, auth/authz errors, JWT errors, not-found/conflict cases, and unexpected error handling when those paths change.
+- For frontend changes, test validation, transforms, query/mutation wrappers, components, and user-visible flows at the narrowest practical level first.
+- If any test or repository check fails, fix the issue and rerun the failing command. Only finalize with failing checks when the failure is unrelated to the change or blocked by environment constraints, and document that explicitly.
+
+### Dashboard Frontend
+
+`app-dashboard` is a Next.js App Router TypeScript app using MUI, React Query, `next-intl`, and shared CareCard utilities. It consumes `api-auth`, `api-institutions`, `api-contact-us`, and `api-user-profiles` through service modules.
+
+- Keep backend URL definitions centralized in `src/services/api.routes.ts`.
+- Keep fetch behavior centralized in `src/services/common/api`, especially `appFetch`, `api.client`, and `parseApiResponse`.
+- Services should return typed app/domain objects or typed form states, not raw fetch responses.
+- Keep validation in `*.validation.ts`, API calls in `*.queries.ts` or mutation helpers, mapping in `*.transform.ts`, and orchestration in `*.service.ts`.
+- Preserve the standardized `ApiResponse` parsing behavior for both current backend responses and legacy/non-standard responses.
+- Do not expose JWTs, session contents, or sensitive backend details in client components or logs.
+- Respect `basePath: '/secure'`, server actions, middleware session renewal, mock API mode, and existing i18n message patterns.
+- Use existing MUI and app component patterns. Do not introduce a new UI framework.
+
+### Dependency And Version Guidance
+
+- Keep CareCard package usage consistent with the service being changed.
+- When standardizing response/error behavior, prefer `@carecard/common-util` `3.1.15` because it contains response and error functions aligned with `api-auth`.
+- If package version changes are required, update lockfiles and verify affected services.
+- Avoid broad dependency upgrades as part of feature or refactor work unless the task is specifically about dependencies.
+
+### Security Requirements
+
+- Treat authentication, authorization, JWT, password, email confirmation, recovery, file upload, CORS, rate limits, and error response behavior as security-sensitive.
+- Never log or return secrets, tokens, passwords, credentials, private keys, full JWT payloads, or sensitive personal data.
+- Use safe error messages for users and structured details only when they do not reveal sensitive implementation or data.
+- Keep body-size limits, Helmet, CORS allow-lists, and rate-limit behavior intact unless a task explicitly changes them.
+- Document remaining security concerns that require product, infrastructure, or deployment decisions.
+
+## Repository-Specific Instructions
+
+### Non-Negotiable Instructions
+
+- Never use TypeScript type `any`. Use specific value, record, validator, option, result, generic, or `unknown` types with narrowing.
+- Always follow this repository's coding style, naming conventions, and CommonJS project structure.
+- Always use Test-Driven Development: add or update the relevant Mocha or type tests before changing behavior.
+- Never suppress errors, linter warnings, TypeScript errors, or failing tests. Handle the underlying issue.
+- Do not add new dependencies unless they are absolutely needed. Ask for confirmation first with the reason and tradeoff.
+- Before finalizing work in this repository, run every script in `.husky/` and fix anything they report.
+
+### Package Shape
+
+- Keep `index.js` as the centralized public export surface.
+- Keep TypeScript declarations in `index.d.ts` aligned with every public export in `index.js`.
+- Keep direct validators in `lib/validate.js`.
+- Keep key-based property sanitization in `lib/validateProperties.js`.
+- Keep whitelist, nested-path, casing, flattening, and CareCard bad-input behavior in `lib/validateWhitelistProperties.js`.
+- Preserve the package's CommonJS module style unless the repository is intentionally migrated.
+- Keep the deprecated `validate` namespace export backward-compatible while preferring direct top-level exports in new code.
+
+### Validation Rules
+
+- Low-level validators should be deterministic predicate functions that return `true` or `false`.
+- Password failure-message helpers should return `null` for valid input and a user-readable string for invalid input.
+- `validateProperties` should return a new sanitized object and omit unknown or invalid fields without mutating the input.
+- `validateWhitelistProperties` should reject missing or invalid required fields with CareCard `BAD_INPUT` errors through `@carecard/common-util`.
+- Optional whitelist fields should be ignored when absent and rejected when present but invalid.
+- Preserve supported snake_case and camelCase field aliases unless a task explicitly changes the API contract.
+- Preserve nested dot-path handling, the maximum nesting depth, maximum path count, optional snake_case conversion, and flattening behavior.
+- Avoid broad regular expressions or validation changes without focused tests for accepted values, rejected values, length limits, and edge cases.
+
+### Types And API Contracts
+
+- Model input and output records, whitelist options, flattened output behavior, validators, and failure-message helpers explicitly in `index.d.ts`.
+- When existing declarations are too loose, improve them with specific types as part of the touched change instead of adding new loose types.
+- Update `test/types.test.ts` whenever public types, exports, options, return values, or validators change.
+- Keep runtime exports, README examples, and type declarations in sync.
+
+### Tests
+
+- Use Mocha for runtime tests under `test/`.
+- Use `test/types.test.ts` for TypeScript declaration coverage through `npm run test:types`.
+- Add focused tests for valid input, invalid input, missing fields, optional fields, array handling, nested paths, casing conversion, flattening, and error messages when those areas change.
+- Keep tests deterministic and avoid relying on real external services.
+- Before pushing or finalizing, run `.husky/pre-commit`; it runs lint fixing, formatting, and `npm run test:All`.

package/.github/CODEOWNERS

@@ -0,0 +1,14 @@
+# Full repository owner
+* @singh-pankaj-k
+
+# Repository workflow and ownership metadata
+.github/ @singh-pankaj-k
+README.md @singh-pankaj-k
+package.json @singh-pankaj-k
+package-lock.json @singh-pankaj-k
+
+# Package source, declarations, and tests
+index.js @singh-pankaj-k
+index.d.ts @singh-pankaj-k
+lib/ @singh-pankaj-k
+test/ @singh-pankaj-k

package/.github/workflows/auto-draft-pr.yml

@@ -23,6 +23,8 @@ on:
     push:
         branches:
             - 'feature/**'
+            - 'feat/**'
+            - 'improvement/**'
             - 'releases/**'
             - 'release*'
             - 'hotfix/**'
@@ -30,6 +32,8 @@ on:
             - 'fix/**'
             - 'main-*'
             - 'main-**'
+            - 'data**'
+            - 'data/**'
         paths-ignore:
             - '**.md'
     workflow_dispatch:

package/.github/workflows/ci.yml

@@ -1,17 +1,54 @@
 name: CI
 
 on:
+    workflow_dispatch:
     push:
+        branches:
+            - main
+            - develop
+            - development
+            - dev*
+            - feature/**
+            - feat/**
+            - improvement/**
+            - releases/**
+            - release*
+            - hotfix/**
+            - iss/**
+            - fix/**
+            - data**
+            - data/**
+        paths-ignore:
+            - '**.md'
     pull_request:
+        types: [opened, synchronize, reopened, ready_for_review]
+        branches:
+            - main
+            - develop
+            - development
+            - dev*
+            - feature/**
+            - feat/**
+            - improvement/**
+            - releases/**
+            - release*
+            - hotfix/**
+            - iss/**
+            - fix/**
+            - data**
+            - data/**
+        paths-ignore:
+            - '**.md'
 
 jobs:
     test:
         runs-on: ubuntu-latest
 
         steps:
-            - uses: actions/checkout@v4
+            - name: Checkout repository
+              uses: actions/checkout@v4
 
-            - name: Use Node.js
+            - name: Set up Node.js
               uses: actions/setup-node@v4
               with:
                   node-version: '25'
@@ -20,5 +57,8 @@ jobs:
             - name: Install dependencies
               run: npm ci
 
-            - name: Run tests and coverage
+            - name: Run tests
               run: npm run test:All
+
+            - name: Run tests with coverage
+              run: npm run test:coverage

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. */
@@ -106,8 +115,14 @@ export function isBoolValue(inputValue: any): boolean;
 export function isPostalCodeString(inputString: any): boolean;
 /** Checks if the string contains only allowed "safe" characters. */
 export function isSafeString(str: any): boolean;
+/** Checks if the value is non-empty text up to the supported maximum length. */
+export function isTextString(str: any): boolean;
 /** Checks if a string exists within a given array of strings (case-insensitive). */
 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. */
@@ -151,7 +166,10 @@ export const validate: {
     isBoolValue: typeof isBoolValue;
     isPostalCodeString: typeof isPostalCodeString;
     isSafeString: typeof isSafeString;
+    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

@@ -156,6 +156,10 @@ const isSafeString = str => {
     return /^[\da-zA-Z-_.,#*'()[\]: ]+$/.test(str);
 };
 
+const isTextString = str => {
+    return typeof str === 'string' && str.length > 0 && str.length <= 10000;
+};
+
 const isInStringArray = (StringArray, inputString) => {
     if (isNameString(inputString)) {
         return StringArray.includes(inputString.toLowerCase().trim());
@@ -164,6 +168,16 @@ const isInStringArray = (StringArray, inputString) => {
     return false;
 };
 
+const isUserRoleRequestStatusString = inputString => {
+    const statuses = ['pending', 'approved', 'rejected', 'cancelled', 'expired', 'hidden', 'on_hold', 'in_progress', 'info_needed'];
+    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;
 
@@ -231,7 +245,10 @@ module.exports = {
     isBoolValue,
     isPostalCodeString,
     isSafeString,
+    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

@@ -20,6 +20,9 @@ const {
     isValidUrl,
     isValidArrayOfStrings,
     isStreetString,
+    isTextString,
+    isUserRoleRequestStatusString,
+    isUserRoleRequestRoleString,
 } = require('./validate');
 
 function validateProperties(obj = {}) {
@@ -63,6 +66,8 @@ function validateProperties(obj = {}) {
             case 'entityType':
             case 'action_type':
             case 'actionType':
+            case 'approved_by_role':
+            case 'approvedByRole':
             case 'city':
             case 'state':
             case 'country':
@@ -164,10 +169,40 @@ function validateProperties(obj = {}) {
             case 'changedBy':
             case 'request_id':
             case 'requestId':
+            case 'approved_by_user_id':
+            case 'approvedByUserId':
                 if (isValidUuidString(value)) {
                     returnObj[key] = value;
                 }
                 break;
+            case 'requested_by_name':
+            case 'requestedByName':
+            case 'requested_by_email':
+            case 'requestedByEmail':
+            case 'requested_by_phone':
+            case 'requestedByPhone':
+            case 'approved_by_name':
+            case 'approvedByName':
+            case 'approved_by_email':
+            case 'approvedByEmail':
+            case 'approved_by_phone':
+            case 'approvedByPhone':
+                if (isTextString(value)) {
+                    returnObj[key] = value;
+                }
+                break;
+            case 'approved_status':
+            case 'approvedStatus':
+                if (isUserRoleRequestStatusString(value)) {
+                    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;
@@ -229,10 +264,14 @@ function validateProperties(obj = {}) {
                 break;
             case 'expires_at':
             case 'expiresAt':
+            case 'starts_at':
+            case 'startsAt':
             case 'start_time':
             case 'startTime':
             case 'end_time':
             case 'endTime':
+            case 'approved_at':
+            case 'approvedAt':
                 if (isValidTimestampzString(value) || isValidTimestampString(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.22",
+    "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
     }
 }