@carecard/validate 3.1.22 → 3.1.23

package/.codex/AGENTS.md

@@ -0,0 +1,179 @@
+# 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.
+- 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/index.d.ts

@@ -106,8 +106,12 @@ 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 valid country code (e.g., +1). */
 export function isCountryCodeString(str: any): boolean;
 /** Checks if the string is a valid domain name. */
@@ -151,7 +155,9 @@ export const validate: {
     isBoolValue: typeof isBoolValue;
     isPostalCodeString: typeof isPostalCodeString;
     isSafeString: typeof isSafeString;
+    isTextString: typeof isTextString;
     isInStringArray: typeof isInStringArray;
+    isUserRoleRequestStatusString: typeof isUserRoleRequestStatusString;
     isCountryCodeString: typeof isCountryCodeString;
     isValidDomainName: typeof isValidDomainName;
     isValidTimestampzString: typeof isValidTimestampzString;

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,11 @@ 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 isCountryCodeString = str => {
     if (typeof str !== 'string' || str.length === 0 || str.length > 4) return false;
 
@@ -231,7 +240,9 @@ module.exports = {
     isBoolValue,
     isPostalCodeString,
     isSafeString,
+    isTextString,
     isInStringArray,
+    isUserRoleRequestStatusString,
     isCountryCodeString,
     isValidDomainName,
     isValidTimestampzString,

package/lib/validateProperties.js

@@ -20,6 +20,8 @@ const {
     isValidUrl,
     isValidArrayOfStrings,
     isStreetString,
+    isTextString,
+    isUserRoleRequestStatusString,
 } = require('./validate');
 
 function validateProperties(obj = {}) {
@@ -63,6 +65,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 +168,34 @@ 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 'period':
                 if (isCharactersString(value)) {
                     returnObj[key] = value;
@@ -229,10 +257,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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@carecard/validate",
-    "version": "3.1.22",
+    "version": "3.1.23",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/CareCard-ca/pkg-validate.git"