grm-shared-library 1.1.199 → 1.1.201

package/dist/types/modules/partner/interfaces/partner-membership.d.ts

@@ -0,0 +1,149 @@
+import { CountryCode } from '../../country/enums/country-code.enum';
+import { PartnerDispatchFailureReason } from '../enums/partner-dispatch-failure-reason.enum';
+import { PartnerMemberState } from '../enums/partner-member-state.enum';
+import { PartnerMembershipStatus } from '../enums/partner-membership-status.enum';
+import { PartnerMembershipSubjectType } from '../enums/partner-membership-subject-type.enum';
+import { PartnerProviderCode } from '../enums/partner-provider-code.enum';
+import { PartnerMemberProfile } from './partner-member-profile';
+import { UnsatisfiedMemberProfileField } from './partner-membership-descriptor';
+/**
+ * One dependent's state at the partner.
+ *
+ * The important field is `partnerDependentId`: it records what the partner
+ * CONFIRMED, not what Clarion intended. Every diff runs against the confirmed
+ * set, because adding a dependent to a partner like Rescue.co is a one-way
+ * door - a duplicate cannot be withdrawn until the end of the term and
+ * permanently consumes one of the membership's seats, which the API only lets
+ * you increase. Reconciling against intent rather than confirmation is how a
+ * family's cover gets eaten by phantoms.
+ */
+export interface PartnerMembershipDependent {
+    /** Clarion's stable handle - a billing beneficiary id. Idempotency key for the sync. */
+    dependentReference: string;
+    /** The platform user this dependent is, when they have one. */
+    userId?: number | null;
+    /** The partner's own id, once it has issued one. Absent means NOT yet sent. */
+    partnerDependentId?: string | null;
+    /** The name as Clarion holds it. */
+    name: string;
+    /**
+     * The name the partner ACCEPTED, which many partners will not let change
+     * afterwards. Held separately so a later correction on our side is visible
+     * as a divergence rather than silently believed to have applied.
+     */
+    partnerName?: string | null;
+    /** True once the partner has accepted this dependent. */
+    synced: boolean;
+    /**
+     * True when Clarion has stopped covering them but the partner will only
+     * drop them at the end of the term. Recorded rather than acted on, because
+     * the divergence is real and somebody has to be able to see it.
+     */
+    pendingRemovalAtTermEnd?: boolean;
+    /** Sanitized reason the last sync of THIS dependent failed. Never a credential. */
+    lastErrorMessage?: string | null;
+    syncedAt?: string | null;
+}
+/**
+ * One Clarion subject's registration with one partner.
+ *
+ * The row exists so that when an emergency is raised, "who is this person to
+ * Rescue.co?" is a local primary-key lookup rather than a call to a partner in
+ * the middle of an alert. It is a CACHE of the partner's truth with a
+ * lifecycle, not the truth itself - which is why a stale or failed one degrades
+ * to sending the emergency without a member id rather than blocking it.
+ */
+export interface PartnerMembership {
+    id: number;
+    organizationId: number;
+    integrationId: number;
+    /** Copied from the partnership so history survives it being reconfigured. */
+    providerCode: PartnerProviderCode;
+    subjectType: PartnerMembershipSubjectType;
+    /**
+     * Clarion's stable identity for the subject, e.g. `individual-client:12` or
+     * `corporate-member:45`. Unique per partnership - this is what stops two
+     * activations creating two memberships for one person.
+     */
+    subjectReference: string;
+    /** The platform user, when the subject has one. The SOS-time lookup key. */
+    userId?: number | null;
+    subscriptionId?: number | null;
+    packageId?: number | null;
+    status: PartnerMembershipStatus;
+    /** The partner's member id (a UUID for Rescue.co). Present only when ACTIVE. */
+    partnerMemberId?: string | null;
+    /** The partner's own status word, passed through verbatim, e.g. `waitingPeriod`. */
+    partnerStatus?: string | null;
+    /**
+     * The partner's standing reduced to something every screen can rely on,
+     * without any of them learning a partner's vocabulary. The direct analogue
+     * of `engagementState` on a dispatch.
+     */
+    memberState?: PartnerMemberState | null;
+    /**
+     * When the partner's cover actually begins.
+     *
+     * Rescue.co returns a new member as `waitingPeriod` with a `startDate`
+     * some way off. Without this the admin can only say "Active", and an
+     * organization will tell a subscriber they are covered on the day they
+     * paid - which is the single most damaging thing this feature could get
+     * wrong.
+     */
+    coverageStartsAt?: string | null;
+    /** When the partner's cover ends. A membership past it is no longer quoted. */
+    coverageEndsAt?: string | null;
+    /** True when the partner has confirmed cover is in force right now. */
+    coverActive?: boolean;
+    /** Seats the partner CONFIRMED, which many partners will only let increase. */
+    partnerSeats?: number | null;
+    /** Short label quoted alongside the member id on an emergency, e.g. the package name. */
+    membershipLabel?: string | null;
+    /** The provider-neutral profile last sent, frozen for audit and drift detection. */
+    profile: PartnerMemberProfile;
+    /**
+     * What stops this profile being sent, and why - MISSING or MALFORMED.
+     *
+     * Empty unless the status is INCOMPLETE_PROFILE. This is what the admin
+     * renders as "collect a date of birth" or "this date of birth is not a
+     * date", rather than an operator reading a partner's 400.
+     */
+    unsatisfiedFields: UnsatisfiedMemberProfileField[];
+    dependents: PartnerMembershipDependent[];
+    attemptCount: number;
+    maxAttempts: number;
+    nextAttemptAt?: string | null;
+    failureReason?: PartnerDispatchFailureReason | null;
+    lastErrorCode?: string | null;
+    /** Sanitized - never contains a credential, token or document number. */
+    lastErrorMessage?: string | null;
+    countryCode: CountryCode;
+    /**
+     * The highest upstream sequence applied to this row.
+     *
+     * The fence that makes an unordered event stream safe. Billing publishes
+     * each lifecycle change on its OWN topic, and Kafka guarantees no ordering
+     * whatsoever across topics - so an `expired` and an `activated` emitted
+     * three seconds apart can be applied in either order. Without this, a
+     * cancelled subscription can end up ACTIVE with a live member id, and the
+     * reconciliation sweep will not correct it because the row looks healthy.
+     */
+    lastAppliedSequence?: number | null;
+    provisionedAt?: string | null;
+    lastSyncedAt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * What a dispatch is told about the caller's membership, when they have one.
+ *
+ * Resolved from the membership row before the payload is built, and OMITTED
+ * entirely rather than half-filled: an adapter should never have to reason
+ * about a membership that is present but unusable.
+ */
+export interface PartnerDispatchMembership {
+    partnerMemberId: string;
+    label?: string | null;
+    /** The partner's own status at the time it was resolved, for the audit trail. */
+    partnerStatus?: string | null;
+}

package/dist/types/modules/partner/interfaces/partner-provider-descriptor.d.ts

@@ -1,4 +1,5 @@
 import { PartnerIntegrationEnvironment } from '../enums/partner-integration-environment.enum';
+import type { PartnerMembershipDescriptor } from './partner-membership-descriptor';
 import { PartnerProviderCode } from '../enums/partner-provider-code.enum';
 import { PartnerServiceCapability } from '../enums/partner-service-capability.enum';
 /** A credential a partnership must supply before it can dispatch. */
@@ -80,6 +81,21 @@ export interface PartnerProviderDescriptor {
      * blind retry on a non-idempotent emergency API means two ambulances.
      */
     supportsDuplicateDetection: boolean;
+    /**
+     * True when the partner registers people as MEMBERS ahead of an emergency,
+     * and the adapter implements that.
+     *
+     * Membership is an enrichment, never a precondition: a partner that has it
+     * still accepts an emergency for somebody unknown to it. The flag governs
+     * whether the platform provisions members in the background at all, not
+     * whether it will dispatch.
+     */
+    supportsMembership: boolean;
+    /**
+     * What this partner needs to register a member, and what it does with one.
+     * Present exactly when {@link supportsMembership} is true.
+     */
+    membership?: PartnerMembershipDescriptor;
     /** False for reserved provider codes that have no working adapter yet. */
     available: boolean;
 }

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

@@ -0,0 +1,156 @@
+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';
+import { PartnerMembershipPackageScope } from '../enums/partner-membership-package-scope.enum';
+import { PartnerMembershipDescriptor, UnsatisfiedMemberProfileField } from '../interfaces/partner-membership-descriptor';
+import { PartnerMemberProfile } from '../interfaces/partner-member-profile';
+/**
+ * A profile as it comes out of a database or off the wire: every field may be
+ * absent OR explicitly null.
+ *
+ * {@link PartnerMemberProfile} models a profile that has been ASSEMBLED, where
+ * a missing field is simply absent. Readiness is checked against what is
+ * actually stored, and a nullable column reads back as null - so checking
+ * against the assembled shape would reject the very data this exists to inspect.
+ */
+export type PartnerMemberProfileInput = {
+    [K in keyof PartnerMemberProfile]?: PartnerMemberProfile[K] | null;
+};
+/**
+ * Clarion's stable handle for a membership subject.
+ *
+ * Keyed on the PERSON wherever there is one, not on the subscription that paid
+ * for them. A partner registers a human being: an employee covered by their
+ * company who also buys personal cover is one member with one member id, and
+ * keying on the billing relationship would register them twice - two member ids
+ * for one person, two seats consumed, double-billed at the partner, and an
+ * emergency quoting whichever of the two the database happened to return first.
+ *
+ * Only a corporate member never linked to a platform login falls back to the
+ * relationship key, because for them there is no person key to use.
+ *
+ * Prefixed by kind so the two spaces can never collide on a bare numeric id.
+ * This is what the unique index on (integrationId, subjectReference) relies on
+ * to stop one person acquiring two memberships when an activation event is
+ * redelivered.
+ */
+export declare function buildMembershipSubjectReference(subject: {
+    subjectType: PartnerMembershipSubjectType;
+    subjectId: number;
+    userId?: number | null;
+}): string;
+/**
+ * Which of a partner's REQUIRED profile fields this profile cannot satisfy.
+ *
+ * Generic over the descriptor rather than per-partner, so a partner that starts
+ * insisting on a national id needs a one-line descriptor change and no new
+ * validation code. An empty result means the profile is ready to send.
+ */
+export declare function findMissingMemberProfileFields(profile: PartnerMemberProfileInput | null | undefined, descriptor: Pick<PartnerMembershipDescriptor, 'requiredProfileFields'>): PartnerMemberProfileField[];
+/**
+ * What stops this profile being sent, and WHY.
+ *
+ * "Missing" and "malformed" are different problems with different remedies:
+ * one needs the fact collected, the other needs it corrected. Reporting a
+ * mistyped date of birth as missing leaves an operator staring at a field that
+ * is plainly filled in, with nothing to do - and reporting nothing at all
+ * leaves the membership in FAILED with an empty list.
+ *
+ * Also checks any partner-declared `profileFields` marked required, whose
+ * values live in `attributes` - so a partner asking for a policy number gets
+ * the same treatment as one asking for a date of birth.
+ */
+export declare function findUnsatisfiedMemberProfileFields(profile: PartnerMemberProfileInput | null | undefined, descriptor: Pick<PartnerMembershipDescriptor, 'requiredProfileFields'> & Partial<Pick<PartnerMembershipDescriptor, 'profileFields'>>): UnsatisfiedMemberProfileField[];
+/**
+ * Whether a partnership should register the subscribers of one package.
+ *
+ * The single expression of membership eligibility, used by every trigger so
+ * they cannot disagree. Deliberately NOT derived from coverage rules: those
+ * answer "where does THIS EMERGENCY go", which is an incident-shaped question
+ * that a package cannot be asked - a partnership whose only rule matches on
+ * emergency type would evaluate as covering nobody, and one whose package names
+ * no incident types at all (which this platform reads as "covers everything")
+ * would buy a paid membership for every free subscriber.
+ */
+export declare function membershipRequired(integration: {
+    enabled?: boolean;
+    membershipEnabled?: boolean;
+    membershipPackageScope?: PartnerMembershipPackageScope;
+    membershipPackageIds?: number[] | null;
+}, packageId: number | null | undefined): boolean;
+/**
+ * Whether one profile field carries a usable value.
+ *
+ * A date of birth is checked for SHAPE as well as presence: an unparseable one
+ * is worse than an absent one, because it is sent, refused by the partner, and
+ * 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;
+/**
+ * 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.
+ */
+export declare function toPartnerCalendarDate(value: Date | string | null | undefined): string | undefined;
+/**
+ * Seats to buy for a member and their dependents.
+ *
+ * Always at least one - the member's own - and never more than the partner
+ * allows, so a subscription with more beneficiaries than a partner's ceiling
+ * buys the maximum rather than being refused outright.
+ */
+export declare function resolveMemberSeatCount(dependentCount: number, maxDependents: number | null | undefined): number;
+/**
+ * A person's name as a partner should record it, from whatever parts exist.
+ *
+ * Returns undefined rather than an empty or half-formed name: a member called
+ * " " is worse than a membership that is honestly reported as incomplete.
+ */
+export declare function buildMemberFullName(parts: {
+    name?: string | null;
+    firstName?: string | null;
+    lastName?: string | null;
+}): string | undefined;
+/**
+ * Mask a document number for logs.
+ *
+ * A national id identifies a person as surely as their name and outlives any
+ * credential rotation, so it is treated more carefully than one: the last two
+ * characters are enough to match a support query against a record, and the mask
+ * is fixed width so the length of the original is not disclosed either.
+ */
+export declare function maskMemberDocumentNumber(value: string | null | undefined): string;
+/**
+ * Whether a membership may be quoted on an emergency right now.
+ *
+ * Deliberately does NOT require the partner's cover to have started. A member
+ * inside a waiting period is still that person's real member id, and telling
+ * the partner who is calling is accurate and useful whatever their cover state.
+ * What is excluded is a membership the partner has finished with: quoting an
+ * id past its term risks an outright rejection of the SOS, which costs an
+ * ambulance to add a field that was optional anyway.
+ */
+export declare function isUsableMembership(membership: {
+    status: PartnerMembershipStatus;
+    partnerMemberId?: string | null;
+    coverageEndsAt?: string | Date | null;
+}, now?: Date): boolean;
+/**
+ * Whether the PARTNER's cover has actually begun.
+ *
+ * Separate from {@link isUsableMembership} because the two answer different
+ * questions and conflating them misleads a human. Rescue.co returns a new
+ * member as `waitingPeriod`: they exist, they are quotable, and they are not
+ * yet covered. An admin screen that renders a green "Active" chip the day
+ * somebody paid will have told them they are covered when they are not.
+ */
+export declare function isMembershipCoverActive(membership: {
+    status: PartnerMembershipStatus;
+    partnerMemberId?: string | null;
+    coverageStartsAt?: string | Date | null;
+    coverageEndsAt?: string | Date | null;
+}, now?: Date): boolean;

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

@@ -49,6 +49,33 @@ 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.
+ *
+ * A full date of birth beside a name is close to uniquely identifying, and an
+ * audit record is read by far more people than the member screen is. The year
+ * survives, because "the partner rejected a member born in 1988" is the kind of
+ * thing somebody actually has to debug.
+ */
+export declare const BIRTH_DATE_KEY_FRAGMENTS: string[];
+/**
+ * Personal attributes that carry no diagnostic value at all in an audit record.
+ *
+ * Unlike a date of birth, knowing somebody's gender never helps explain why a
+ * partner refused a request, so there is nothing to trade against keeping it.
+ */
+export declare const REDACTED_PERSONAL_KEY_FRAGMENTS: string[];
 /**
  * A URL safe to store on an attempt record: origin and path only, with any
  * query string replaced.

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

@@ -69,3 +69,12 @@ export declare function retryDelaySeconds(attemptNumber: number, baseSeconds?: n
  * and failed is reported as PARTIALLY_ROUTED rather than rounded to either.
  */
 export declare function summarizeIncidentRoutingStatus(statuses: PartnerDispatchStatus[]): IncidentPartnerRoutingStatus;
+/**
+ * Parses an incident-list `partnerRoutingStatus` query value.
+ *
+ * Returns `undefined` rather than a default for anything unrecognised: unlike
+ * the entitlement and dispatch scopes, "no partner filter" is the correct
+ * reading of a junk value here - there is no all-encompassing member to fall
+ * back to, and silently picking one would hide incidents.
+ */
+export declare function parseIncidentPartnerRoutingStatus(value?: string | null): IncidentPartnerRoutingStatus | undefined;

package/dist/types/modules/permission/enums/permission-actions.enum.d.ts

@@ -12,6 +12,8 @@ export declare enum PermissionActions {
     UPDATE_PARTNER_DISPATCH = "update:partner-dispatch",
     CANCEL_PARTNER_DISPATCH = "cancel:partner-dispatch",
     RESEND_PARTNER_DISPATCH = "resend:partner-dispatch",
+    READ_PARTNER_MEMBERSHIP = "read:partner-membership",
+    MANAGE_PARTNER_MEMBERSHIP = "manage:partner-membership",
     CREATE_CONTROL_CENTRE = "create:control-centre",
     READ_CONTROL_CENTRE = "read:control-centre",
     UPDATE_CONTROL_CENTRE = "update:control-centre",

package/package.json

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