@carecard/validate 3.1.24 → 3.1.26

package/index.d.ts

@@ -1,60 +1,110 @@
+/**
+ * Runtime-compatible TypeScript declarations for the CommonJS
+ * `@carecard/validate` package.
+ */
+
+export type ValidatePropertiesInput = Record<string, unknown> | null | undefined;
+export type ValidatePropertiesResult = Record<string, unknown>;
+export type BoolValidator = (input: unknown) => boolean;
+export type FailureMessageValidator = (input: unknown) => string | null;
+export type InStringArrayValidator = (stringArray: readonly string[], input: unknown) => boolean;
+
 /**
  * Utility function to validate multiple properties of an object at once.
  */
-export function validateProperties(obj?: Record<string, any>): Record<string, any>;
+export function validateProperties(obj?: ValidatePropertiesInput): ValidatePropertiesResult;
+
+export type ValidateWhitelistFlattenKeyStyle = 'path' | 'leaf';
 
 /**
  * Options for {@link validateWhitelistProperties}.
  */
 export interface ValidateWhitelistPropertiesOptions {
     /** Properties allowed in the input but not required. */
-    optionalProperties?: string[];
+    optionalProperties?: readonly string[] | null;
     /** When true, the returned object's keys are converted to snake_case. */
     convertToSnakeCase?: boolean;
     /**
      * When true, the returned object is flattened so that every validated leaf
-     * 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.
+     * becomes a top-level key. 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?: ValidateWhitelistFlattenKeyStyle;
 }
 
-/**
- * Validates and transforms whitelisted properties from an input object.
- *
- * - Supports nested objects via dot-notation paths (e.g. `"address.city"`),
- *   up to 5 levels deep. The function checks that each path resolves to an
- *   existing leaf property and validates the leaf value by its leaf segment.
- * - Extracts only the whitelisted (required + optional) leaf properties and
- *   rebuilds the same nested shape in the result.
- * - Validates values via {@link validateProperties}.
- * - Throws a "Bad_Input" error when any required property is missing/invalid,
- *   when a provided optional property has an invalid value, when a path
- *   exceeds 5 levels of nesting, or when the combined count of
- *   `requiredProperties` and `options.optionalProperties` exceeds 5000.
- * - Array values are supported: if a leaf value is an array, the per-leaf
- *   validator is applied to each element. The leaf is accepted only when every
- *   element passes validation, and the returned value is an array of the
- *   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.
- *
- * @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 list of additional allowed leaf paths and case-conversion flag.
- */
-export function validateWhitelistProperties(
-    inputObject: Record<string, any>,
-    requiredProperties?: string[],
-    options?: ValidateWhitelistPropertiesOptions,
-): Promise<Record<string, any>>;
+export interface ValidateWhitelistPropertiesFunction {
+    /**
+     * Validates and transforms whitelisted properties from an input object.
+     *
+     * - Supports nested objects via dot-notation paths (e.g. `"address.city"`),
+     *   up to 5 levels deep. The function checks that each path resolves to an
+     *   existing leaf property and validates the leaf value by its leaf segment.
+     * - Extracts only the whitelisted (required + optional) leaf properties and
+     *   rebuilds the same nested shape in the result.
+     * - Validates values via {@link validateProperties}.
+     * - Throws a "Bad_Input" error when any required property is missing/invalid,
+     *   when a provided optional property has an invalid value, when a path
+     *   exceeds 5 levels of nesting, or when the combined count of
+     *   `requiredProperties` and `options.optionalProperties` exceeds 5000.
+     * - Array values are supported: if a leaf value is an array, the per-leaf
+     *   validator is applied to each element. The leaf is accepted only when every
+     *   element passes validation, and the returned value is an array of the
+     *   validated elements.
+     * - Optionally converts the resulting keys, including nested keys, to snake_case.
+     * - Optionally flattens the result after snake_case conversion.
+     *
+     * @param inputObject The input object, for example `req.body` or `req.params`.
+     * @param requiredProperties Leaf paths that must be present and valid. Dot notation is supported.
+     * @param options Optional additional leaf paths plus output transformation flags.
+     */
+    (
+        inputObject?: ValidatePropertiesInput,
+        requiredProperties?: readonly string[] | null,
+        options?: ValidateWhitelistPropertiesOptions | null,
+    ): Promise<ValidatePropertiesResult>;
+    validateWhitelistProperties: ValidateWhitelistPropertiesFunction;
+    MAX_NESTING_DEPTH: 5;
+    MAX_KEYS_PER_CALL: 5000;
+}
+
+export const validateWhitelistProperties: ValidateWhitelistPropertiesFunction;
+
+export type UserRoleRequestRole = 'student' | 'intern' | 'volunteer';
+export type UserRoleRequestScopeRequirement = boolean | typeof REQUIRE_SCOPE_WHEN_ROLE_OR_SCOPE_PRESENT;
 
 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;
+    defaultRole?: UserRoleRequestRole | undefined;
+    requireScope?: UserRoleRequestScopeRequirement;
+}
+
+export interface ValidateNewUserRoleRequestInput extends Record<string, unknown> {
+    role_name?: unknown;
+    roleName?: unknown;
+    role?: unknown;
+    institution_id?: unknown;
+    institutionId?: unknown;
+    campus_id?: unknown;
+    campusId?: unknown;
+    program_id?: unknown;
+    programId?: unknown;
+}
+
+export interface ValidateNewUserRoleRequestPayload extends Record<string, unknown> {
+    role_name?: string;
+    institution_id?: string;
+    campus_id?: string;
+    program_id?: string;
 }
 
 /**
@@ -63,79 +113,78 @@ export interface ValidateNewUserRoleRequestOptions {
  * both institution_id and campus_id must be provided.
  */
 export function validateNewUserRoleRequestObject(
-    roleRequest?: Record<string, any>,
-    options?: ValidateNewUserRoleRequestOptions,
-): Record<string, any>;
+    roleRequest?: ValidateNewUserRoleRequestInput | null,
+    options?: ValidateNewUserRoleRequestOptions | null,
+): ValidateNewUserRoleRequestPayload;
 
 /** Checks if the string is a valid image URL format. */
-export function isImageUrl(imageUrl: any): boolean;
+export const isImageUrl: BoolValidator;
 /** Checks if the value is an integer. */
-export function isInteger(number: any): boolean;
+export const isInteger: BoolValidator;
 /** Checks if the string is a valid JSON string and can be parsed into an object. */
-export function isValidJsonString(str: any): boolean;
+export const isValidJsonString: BoolValidator;
 /** Checks if the string represents a valid integer. */
-export function isValidIntegerString(str: any): boolean;
+export const isValidIntegerString: BoolValidator;
 /** Checks if the string is a valid UUID. */
-export function isValidUuidString(str: any): boolean;
+export const isValidUuidString: BoolValidator;
 /** Checks if the string contains only alphanumeric characters, spaces, underscores, or hyphens. */
-export function isCharactersString(str: any): boolean;
+export const isCharactersString: BoolValidator;
 /** Checks if the string is a valid street address format. */
-export function isStreetString(str: any): boolean;
+export const isStreetString: BoolValidator;
 /** Checks if the string is a valid name format. */
-export function isNameString(str: any): boolean;
+export const isNameString: BoolValidator;
 /** Checks if the string is safe for search queries. */
-export function isSafeSearchString(str: any): boolean;
+export const isSafeSearchString: BoolValidator;
 /** Checks if the string is a valid email address. */
-export function isEmailString(email: any): boolean;
+export const isEmailString: BoolValidator;
 /** Checks if the string is a valid JWT format. */
-export function isJwtString(jwt: any): boolean;
+export const isJwtString: BoolValidator;
 /** Checks if the string is a valid strong password. */
-export function isPasswordString(password: any): boolean;
+export const isPasswordString: BoolValidator;
 /** Checks if the string is a valid simple password. */
-export function isSimplePasswordString(password: any): boolean;
+export const isSimplePasswordString: BoolValidator;
 /** Returns a failure message if the password is not strong enough. */
-export function isPasswordStringFailureMessage(password: any): string | null;
+export const isPasswordStringFailureMessage: FailureMessageValidator;
 /** Returns a failure message if the password is not valid as a simple password. */
-export function isSimplePasswordStringFailureMessage(password: any): string | null;
+export const isSimplePasswordStringFailureMessage: FailureMessageValidator;
 /** Checks if the string is a valid username. */
-export function isUsernameString(str: any): boolean;
+export const isUsernameString: BoolValidator;
 /** Checks if the string is a valid phone number. */
-export function isPhoneNumber(str: any): boolean;
+export const isPhoneNumber: BoolValidator;
 /** Checks if the string is URL-safe. */
-export function isUrlSafeString(inputString: any): boolean;
+export const isUrlSafeString: BoolValidator;
 /** Checks if the string length is between 6 and 24 characters. */
-export function isString6To24CharacterLong(password: any): boolean;
+export const isString6To24CharacterLong: BoolValidator;
 /** Checks if the string length is between 6 and 16 characters. */
-export function isString6To16CharacterLong(password: any): boolean;
+export const isString6To16CharacterLong: BoolValidator;
 /** Checks if the string is a valid Canadian province abbreviation (ON, QC). */
-export function isProvinceString(inputString: any): boolean;
+export const isProvinceString: BoolValidator;
 /** Checks if the value is a boolean. */
-export function isBoolValue(inputValue: any): boolean;
+export const isBoolValue: BoolValidator;
 /** Checks if the string is a valid Canadian postal code. */
-export function isPostalCodeString(inputString: any): boolean;
+export const isPostalCodeString: BoolValidator;
 /** Checks if the string contains only allowed "safe" characters. */
-export function isSafeString(str: any): boolean;
+export const isSafeString: BoolValidator;
 /** 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;
+export const isTextString: BoolValidator;
+/** Checks if a string exists within a given array of strings, case-insensitive. */
+export const isInStringArray: InStringArrayValidator;
 /** Checks if the string is one of the supported user role request statuses. */
-export function isUserRoleRequestStatusString(inputString: any): boolean;
+export const isUserRoleRequestStatusString: BoolValidator;
 /** 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;
+export const isUserRoleRequestRoleString: BoolValidator;
+/** Checks if the string is a valid country code, for example +1. */
+export const isCountryCodeString: BoolValidator;
 /** Checks if the string is a valid domain name. */
-export function isValidDomainName(domain: any): boolean;
+export const isValidDomainName: BoolValidator;
 /** Checks if the string is a valid ISO 8601 timestamp with time zone. */
-export function isValidTimestampzString(str: any): boolean;
+export const isValidTimestampzString: BoolValidator;
 /** Checks if the string is a valid ISO 8601 timestamp without time zone. */
-export function isValidTimestampString(str: any): boolean;
-
+export const isValidTimestampString: BoolValidator;
 /** Checks if the string is a valid URL. */
-export function isValidUrl(url: any): boolean;
+export const isValidUrl: BoolValidator;
 /** Checks if the array contains only safe strings. */
-export function isValidArrayOfStrings(arr: any): boolean;
+export const isValidArrayOfStrings: BoolValidator;
 
 /**
  * Utility functions for validating various types of strings and values.

package/lib/validateProperties.js

@@ -23,6 +23,7 @@ const {
     isTextString,
     isUserRoleRequestStatusString,
     isUserRoleRequestRoleString,
+    isCountryCodeString,
 } = require('./validate');
 
 function validateProperties(obj = {}) {
@@ -124,6 +125,12 @@ function validateProperties(obj = {}) {
                     returnObj[key] = value;
                 }
                 break;
+            case 'country_code':
+            case 'countryCode':
+                if (isCountryCodeString(value)) {
+                    returnObj[key] = value;
+                }
+                break;
             case 'token':
             case 'email_confirm_token':
             case 'emailConfirmToken':

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@carecard/validate",
-    "version": "3.1.24",
+    "version": "3.1.26",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/CareCard-ca/pkg-validate.git"
@@ -27,18 +27,18 @@
     "license": "ISC",
     "devDependencies": {
         "@types/mocha": "10.0.10",
-        "@types/node": "25.6.2",
+        "@types/node": "25.9.1",
         "eslint": "9.39.4",
         "husky": "9.1.7",
-        "lint-staged": "17.0.3",
-        "mocha": "11.7.5",
+        "lint-staged": "17.0.5",
+        "mocha": "11.7.6",
         "nyc": "18.0.0",
         "prettier": "3.8.3",
         "ts-node": "10.9.2",
-        "typescript": "5.9.3"
+        "typescript": "6.0.3"
     },
     "dependencies": {
-        "@carecard/common-util": "^3.1.13"
+        "@carecard/common-util": "3.1.15"
     },
     "nyc": {
         "all": true,

package/readme.md

@@ -106,6 +106,7 @@ where the package supports both.
 | `isString6To16CharacterLong` and `isPasswordString`       | `strong_password`, `strongPassword`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `isEmailString`                                           | `email`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `isPhoneNumber`                                           | `phone_number`, `phoneNumber`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `isCountryCodeString`                                     | `country_code`, `countryCode`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `isUrlSafeString`                                         | `token`, `email_confirm_token`, `emailConfirmToken`, `verification_token`, `verificationToken`                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `isValidUuidString`                                       | `uuid`, `item_id`, `itemId`, `user_id`, `userId`, `address_id`, `addressId`, `image_id`, `imageId`, `order_id`, `orderId`, `category_id`, `categoryId`, `parent_id`, `parentId`, `college_id`, `collegeId`, `campus_id`, `campusId`, `program_id`, `programId`, `id`, `institution_id`, `institutionId`, `role_assignment_id`, `roleAssignmentId`, `user_role_id`, `userRoleId`, `phone_number_id`, `phoneNumberId`, `entity_id`, `entityId`, `changed_by`, `changedBy`, `request_id`, `requestId`                                          |
 | `isValidIntegerString`                                    | `offset_number`, `offsetNumber`, `number_of_orders`, `numberOfOrders`, `price`, `from`, `number`, `limit`, `offset`                                                                                                                                                                                                                                                                                                                                                                                                                         |
@@ -120,7 +121,7 @@ where the package supports both.
 
 `validateWhitelistProperties` extracts only the required and optional property
 paths you provide, validates each leaf through `validateProperties`, and returns
-a `Promise<Record<string, any>>` with the sanitized output.
+a `Promise<ValidatePropertiesResult>` with the sanitized output.
 
 ```js
 const body = {
@@ -332,10 +333,11 @@ await validateWhitelistProperties(input, ['name', 'user.name', 'user.email'], {
 The package ships `index.d.ts` and declares types for the CommonJS exports.
 
 ```ts
-import { validateWhitelistProperties, isEmailString } from '@carecard/validate';
+import { validateWhitelistProperties, isEmailString, ValidatePropertiesResult } from '@carecard/validate';
 
 const valid: boolean = isEmailString('jane@example.com');
-const output: Record<string, any> = await validateWhitelistProperties({ first_name: 'Jane' }, ['first_name']);
+const output: ValidatePropertiesResult = await validateWhitelistProperties({ first_name: 'Jane' }, ['first_name']);
+const maxDepth: 5 = validateWhitelistProperties.MAX_NESTING_DEPTH;
 ```
 
 ## Project Layout
@@ -363,3 +365,16 @@ npm run format:check
 
 CI runs on Node.js 25 and executes `npm run test:All`. Publishing to npm happens
 from `main` through the `Publish to npm` GitHub workflow.
+
+## Auth Boundary
+
+Validation protects request shape, not authorization. `ms-auth` owns its
+auth-table RLS contract: normal users are self-row only, JWT `roles: ["ad"]`
+is the auth super-admin signal, and public auth flows use narrow system
+contexts. Do not use validators as a replacement for service RLS or database
+context checks.
+
+Docs that mention `ms-auth` controller internals should use concise action
+names such as `loginUser`, `registerUser`, `getUserDetail`, and `renewJwt`.
+Access level is conveyed by route middleware and endpoint placement, not by
+`public`/`protected`/`admin`/`Handler` suffixes.