grm-shared-library 1.1.205 → 1.1.206

package/dist/types/modules/common/utils/calendar-date.util.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The platform's one definition of a calendar date.
+ *
+ * A date of birth is a CALENDAR DATE, not an instant. It has no time, no zone
+ * and no offset: somebody born on 17 April 1990 was born on that day in Nairobi,
+ * in Kampala and in London alike. Every bug this module exists to prevent comes
+ * from the same mistake - treating that date as a moment, reading it back in a
+ * different zone, and landing a day earlier.
+ *
+ * That mistake had already been made. Before this module the platform carried
+ * four independent copies of the `YYYY-MM-DD` regex and a conversion that did
+ * `new Date(freeText)` and then `.toISOString()`. Under `TZ=Africa/Nairobi`,
+ * which is what the production pods run:
+ *
+ *     '04/17/1990'        -> '1990-04-16'   (a day early)
+ *     new Date(1990,3,17) -> '1990-04-16'   (a day early - and this is exactly
+ *                                            what a date picker hands you)
+ *     '17/04/1990'        -> undefined      (the East African spelling, refused)
+ *
+ * A birth date that is wrong by a day is worse than one that is missing.
+ * Rescue.co cannot delete a member once registered, so a drifted date is
+ * permanent, and it is the field a paramedic uses to size a drug dose. So the
+ * rule here is deliberately narrow: parse what is unambiguous, refuse
+ * everything else, and never guess.
+ */
+/** `YYYY-MM-DD`. The single definition - do not re-declare this anywhere. */
+export declare const ISO_CALENDAR_DATE_PATTERN: RegExp;
+/** Nobody lives longer than this, so anything older is a typo or a placeholder. */
+export declare const MAX_HUMAN_AGE_YEARS = 120;
+/**
+ * The age at which a person is treated as an adult, for COPY ONLY.
+ *
+ * Never a validator. Dependents on a family membership are children by design -
+ * that is the entire point of registering them with an emergency responder -
+ * so a minimum age would refuse exactly the people the feature exists for.
+ */
+export declare const AGE_OF_MAJORITY_YEARS = 18;
+/**
+ * A real `YYYY-MM-DD` day, not merely a string shaped like one.
+ *
+ * Rejects `2026-02-30` and `2026-13-01`: the shape is right and the day does
+ * not exist. Parsed at UTC midnight so the check cannot depend on where it runs.
+ */
+export declare function isCalendarDate(value: unknown): value is string;
+/**
+ * Reduce a stored or submitted value to a calendar date, or refuse it.
+ *
+ * Accepts exactly three things, and nothing else:
+ *
+ *   1. `YYYY-MM-DD`                    - the wire format every client must send
+ *   2. a full ISO-8601 instant in UTC  - `1990-04-17T00:00:00.000Z`, which is
+ *                                        what the spreadsheet importer produces
+ *   3. a `Date`                        - read in UTC, so callers must build it
+ *                                        with `Date.UTC`, never `new Date(y,m,d)`
+ *
+ * Free text is REFUSED rather than guessed at. `'04/17/1990'` and `'17/04/1990'`
+ * are the same eight characters in different orders and the platform serves
+ * Kenya, Uganda and Tanzania, where the second spelling is the common one.
+ * There is no reading of that string that is safe to infer, so the honest
+ * answer is `undefined` - which surfaces as a field the operator is asked to
+ * collect, instead of a wrong birthday nobody ever notices.
+ */
+export declare function toCalendarDate(value: Date | string | null | undefined): string | undefined;
+/**
+ * A date that could belong to a living person.
+ *
+ * Deliberately NOT an age gate. There is no minimum: a dependent on a family
+ * membership may be a newborn. What it refuses is a date that cannot be a birth
+ * date at all - one in the future, or one further back than any human lifespan -
+ * because those are data-entry accidents (a 2026 default on a picker, a
+ * mis-keyed century) rather than facts about a person.
+ *
+ * `now` is injectable so the rule is deterministic under test, matching
+ * `isUsableMembership` and `isMembershipCoverActive`.
+ */
+export declare function isPlausibleBirthDate(value: unknown, now?: Date): boolean;
+/** Whole years, UTC throughout. Returns undefined when the date is unusable. */
+export declare function calculateAge(value: unknown, now?: Date): number | undefined;
+/** True when the person is below the age of majority - for COPY, never a gate. */
+export declare function isMinor(value: unknown, now?: Date): boolean;

package/dist/types/modules/partner/dtos/partner-member-profile.dto.d.ts

@@ -18,7 +18,14 @@ export declare class PartnerMemberProfileDto {
      */
     phoneNumber?: string;
     email?: string;
-    /** `YYYY-MM-DD`. A calendar date, never a timestamp. */
+    /**
+     * `YYYY-MM-DD`. A calendar date, never a timestamp.
+     *
+     * `@IsBirthDate` rather than a regex: the regex this replaces accepted
+     * `2026-02-30` and `2999-01-01` - a day that does not exist, and one that
+     * has not happened yet - and Postgres rolls the first quietly forward to
+     * 1 March.
+     */
     dateOfBirth?: string;
     gender?: PartnerMemberGender;
     documentType?: PartnerMemberDocumentType;

package/dist/types/modules/partner/index.d.ts

@@ -31,6 +31,7 @@ export * from './interfaces/partner-connection-test-result';
 export * from './interfaces/partner-dispatch-events';
 export * from './interfaces/partner-member-profile';
 export * from './interfaces/partner-membership-descriptor';
+export * from './interfaces/partner-member-readiness';
 export * from './interfaces/partner-membership';
 export * from './constants/partner-defaults.const';
 export * from './constants/partner-kafka.const';

package/dist/types/modules/partner/interfaces/partner-member-readiness.d.ts

@@ -0,0 +1,60 @@
+import { PartnerMemberProfileFieldDescriptor } from './partner-membership-descriptor';
+/**
+ * One thing still standing between a person and cover with a partner, described
+ * well enough for any client to render an input for it without knowing which
+ * partner asked.
+ *
+ * Carries the DESCRIPTOR and the REASON, and deliberately never the value that
+ * is already held. A prompt exists to collect what is missing; sending back
+ * what is already stored would put a date of birth into a mobile response, a
+ * browser cache and any log that captured it, to redisplay a fact the person
+ * supplied themselves.
+ */
+export interface PartnerMemberRequirement extends PartnerMemberProfileFieldDescriptor {
+    /**
+     * MISSING needs the fact collected; MALFORMED needs it corrected. An
+     * operator shown "missing" for a field that is plainly filled in has
+     * nothing to act on.
+     */
+    reason: 'MISSING' | 'MALFORMED';
+    /** Why this specific value was refused, where that can be said usefully. */
+    detail?: string;
+}
+/**
+ * Whether the platform could register this person with the partners that cover
+ * them, and what it still needs if not.
+ *
+ * The contract behind every capture prompt in the product - the mobile sheet,
+ * the admin worklist, the beneficiary form. All of them render THIS rather than
+ * a hardcoded date-of-birth field, which is what keeps the feature honest as
+ * partners are added: a second partner wanting a national id number is a
+ * descriptor edit in one adapter, not an app release.
+ */
+export interface PartnerMemberReadiness {
+    subjectReference: string;
+    /** True when nothing is outstanding - either satisfied, or nobody needs anything. */
+    ready: boolean;
+    /**
+     * Names of the partners that want something, for copy like "Rescue.co needs
+     * your date of birth". Empty when nothing is outstanding.
+     */
+    awaitingPartnerNames: string[];
+    /**
+     * Merged across every partner covering this person and de-duplicated by
+     * key, because two partners both wanting a date of birth is one question to
+     * ask, not two.
+     */
+    requirements: PartnerMemberRequirement[];
+    /**
+     * True when the person was asked and declined. Kept so "declined" can be
+     * told apart from "never asked" - without it a dismissed prompt is
+     * indistinguishable from a bug, and the only safe response to either is to
+     * ask again, forever.
+     */
+    declined?: boolean;
+}
+/** Readiness for a person and, where they have them, their dependents. */
+export interface PartnerMemberReadinessResult {
+    subject: PartnerMemberReadiness;
+    dependents: PartnerMemberReadiness[];
+}

package/dist/types/modules/partner/utils/partner-membership.util.d.ts

@@ -1,3 +1,4 @@
+import { isCalendarDate, toCalendarDate } from '../../common/utils/calendar-date.util';
 import { PartnerMemberProfileField } from '../enums/partner-member-profile-field.enum';
 import { PartnerMembershipStatus } from '../enums/partner-membership-status.enum';
 import { PartnerMembershipSubjectType } from '../enums/partner-membership-subject-type.enum';
@@ -86,16 +87,26 @@ export declare function membershipRequired(integration: {
  * retried forever against a value that will never become valid.
  */
 export declare function isMemberProfileFieldPresent(profile: PartnerMemberProfileInput, field: PartnerMemberProfileField): boolean;
-/** A real `YYYY-MM-DD` date, not merely one shaped like it (rejects 2026-02-30). */
-export declare function isCalendarDate(value: string): boolean;
+/**
+ * Re-exported so partner code keeps one import, but there is only ONE
+ * implementation and it lives with the rest of the date contract.
+ */
+export { isCalendarDate };
 /**
  * A date of birth reduced to the calendar date partners want.
  *
- * Accepts what the platform actually stores - a `Date`, a timestamp string, a
- * bare date - and returns UTC, never local. Reading a stored instant in the
- * server's zone is how a birthday drifts a day when a pod moves region.
+ * Now a thin alias over the platform contract, and NARROWER than it used to be.
+ * The old body did `new Date(trimmed)` on anything that was not already
+ * `YYYY-MM-DD` and then read the result back in UTC, which under the pods' own
+ * `TZ=Africa/Nairobi` turned '04/17/1990' into '1990-04-16' and refused
+ * '17/04/1990' - the spelling most of East Africa actually writes.
+ *
+ * Ambiguous text is now refused outright. A refused date surfaces as a field an
+ * operator is asked to collect; a drifted one is a permanent wrong birthday at
+ * a partner that cannot delete a member, on the record a paramedic uses to size
+ * a drug dose.
  */
-export declare function toPartnerCalendarDate(value: Date | string | null | undefined): string | undefined;
+export declare const toPartnerCalendarDate: typeof toCalendarDate;
 /**
  * Seats to buy for a member and their dependents.
  *

package/dist/types/modules/partner/utils/partner-payload.util.d.ts

@@ -49,16 +49,6 @@ export declare function sanitizePartnerPayload(value: unknown, depth?: number):
  * case-insensitively.
  */
 export declare const SECRET_KEY_FRAGMENTS: string[];
-/**
- * Key substrings that mark a value as a government identity document number.
- *
- * These are NOT credentials - they cannot be rotated, and unlike an API key,
- * losing one harms the PERSON rather than the platform. That asymmetry is why
- * they are masked rather than redacted: an operator investigating "the partner
- * rejected this member" still needs to tell one document from another, and
- * blanking the field entirely would make the audit trail useless while a full
- * value would put a national id in a table many people can read.
- */
 export declare const IDENTITY_DOCUMENT_KEY_FRAGMENTS: string[];
 /**
  * Key substrings that mark a value as a date of birth.
@@ -68,7 +58,18 @@ export declare const IDENTITY_DOCUMENT_KEY_FRAGMENTS: string[];
  * survives, because "the partner rejected a member born in 1988" is the kind of
  * thing somebody actually has to debug.
  */
+/**
+ * Matched against a key with every separator stripped, so one fragment covers
+ * every spelling a producer might use.
+ *
+ * The previous list matched raw keys and therefore missed `birth_date` and
+ * `date-of-birth` entirely - close enough to the ones it did match that the
+ * gap was invisible, and wide enough that an audit payload using either
+ * spelling was stored with the birth date in the clear.
+ */
 export declare const BIRTH_DATE_KEY_FRAGMENTS: string[];
+/** `1988-04-12` becomes `1988-**-**`; anything unrecognised is blanked. */
+export declare function maskBirthDate(value: string): string;
 /**
  * Personal attributes that carry no diagnostic value at all in an audit record.
  *

package/dist/types/modules/user/dtos/create-user.dto.d.ts

@@ -21,4 +21,5 @@ export declare class CreateUserDto {
     verificationTokenExpiresAt?: Date;
     controlCentreId: number;
     organizationId: number;
+    dateOfBirth?: string;
 }

package/dist/types/modules/user/interfaces/user.d.ts

@@ -19,6 +19,16 @@ export interface User {
     password?: string;
     avatar?: string;
     designation?: string;
+    /**
+     * `YYYY-MM-DD`. A calendar date, never a timestamp.
+     *
+     * PRESENT ONLY WHERE IT WAS EXPLICITLY ASKED FOR. The column is
+     * `select: false` in clarion-authentication, so ordinary reads - user
+     * lists, guardian responses, the batch lookup other services use - do
+     * not load it and this property is simply absent there. Treat an absent
+     * value as "not loaded", never as "this person has no date of birth".
+     */
+    dateOfBirth?: string | null;
     status?: UserStatus;
     guardians?: Guardian[];
     dependentRelations?: GuardianRelation[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grm-shared-library",
-  "version": "1.1.205",
+  "version": "1.1.206",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",