grm-shared-library 1.1.221 → 1.1.222

package/dist/types/modules/safety/constants/safety-taxonomy.const.d.ts

@@ -0,0 +1,31 @@
+import { SafetyFeature, SafetyIncidentCategoryCode, SafetyIncidentTypeCode } from '../enums/safety-enums';
+export interface SafetyIncidentTypeDefinition {
+    code: SafetyIncidentTypeCode;
+    name: string;
+    description: string;
+    feature: SafetyFeature;
+}
+export interface SafetyIncidentCategoryDefinition {
+    code: SafetyIncidentCategoryCode;
+    name: string;
+    description: string;
+    types: readonly SafetyIncidentTypeDefinition[];
+}
+/**
+ * The incident category and types EVERY organization receives - existing ones by
+ * migration and reconciliation, new ones on `org.created`. There is no
+ * per-organization exception (NAVCDP included).
+ *
+ * They are SYSTEM rows in clarion-incident (`isSystem = true`, matched by
+ * `code`, never by name): hidden from the SOS bottom sheet and from package
+ * configuration, immutable through the admin API, and raised only by the
+ * safety features themselves.
+ *
+ * Names are stored once at provisioning; renaming here does not rename existing
+ * rows.
+ */
+export declare const SAFETY_ALERTS_TAXONOMY: SafetyIncidentCategoryDefinition;
+/** The incident type a safety feature raises its SOS as. */
+export declare function safetyIncidentTypeCodeFor(feature: SafetyFeature): SafetyIncidentTypeCode;
+/** True for a code clarion-incident treats as a platform-managed safety type. */
+export declare function isSafetyIncidentTypeCode(code: string | null | undefined): code is SafetyIncidentTypeCode;

package/dist/types/modules/safety/dtos/safety-admin.dto.d.ts

@@ -0,0 +1,39 @@
+import { SafetyCheckStatus } from '../enums/safety-check-status.enum';
+/**
+ * Filters for the admin Safety Check list. Every field NARROWS what the caller
+ * may already see: `organizationId` is honoured only for a super-admin; anybody
+ * else is scoped from their trusted context regardless of what arrives here.
+ */
+export declare class SafetyCheckAdminQueryDto {
+    page?: number;
+    limit?: number;
+    status?: SafetyCheckStatus;
+    organizationId?: number;
+    userId?: number;
+    sosOnly?: boolean;
+    from?: string;
+    to?: string;
+    id?: string;
+}
+export declare class CreateSafetyCheckReasonDto {
+    code: string;
+    label: string;
+    description?: string;
+    organizationId?: number;
+    countryCode?: string;
+    isCustom?: boolean;
+    active?: boolean;
+    displayOrder?: number;
+}
+/** Code, organization and custom-ness are fixed once created; everything shown to users can change. */
+export declare class UpdateSafetyCheckReasonDto {
+    label?: string;
+    description?: string | null;
+    countryCode?: string | null;
+    active?: boolean;
+    displayOrder?: number;
+}
+export declare class SafetyCheckReasonAdminQueryDto {
+    organizationId?: number;
+    includeInactive?: boolean;
+}

package/dist/types/modules/safety/dtos/safety-check.dto.d.ts

@@ -0,0 +1,38 @@
+import { GuardianAudienceDto } from '../../alert-dispatch/dtos/guardian-audience.dto';
+/** A device-reported position. Never logged by any Safety service. */
+export declare class SafetyCheckLocationDto {
+    lat: number;
+    lng: number;
+    accuracy?: number;
+}
+/**
+ * Starting a Safety Check.
+ *
+ * Nothing here is trusted beyond its shape: clarion-safety re-checks the reason
+ * against the database, every guardian against clarion-authentication, and the
+ * provider option against clarion-billing. The duration is bounded here AND in
+ * the domain.
+ */
+export declare class StartSafetyCheckDto {
+    reasonId: string;
+    customReason?: string;
+    durationMinutes: number;
+    promptCountdownSeconds?: number;
+    guardians: GuardianAudienceDto;
+    notifyServiceProvider: boolean;
+    notifyGuardiansOnStartEnd: boolean;
+    startLocation?: SafetyCheckLocationDto;
+}
+export declare class ExtendSafetyCheckDto {
+    additionalMinutes: number;
+}
+/** Body of check-in, stop and manual SOS. The location is optional context. */
+export declare class SafetyCheckActionDto {
+    location?: SafetyCheckLocationDto;
+}
+export declare class SafetyCheckTrackPointDto extends SafetyCheckLocationDto {
+    timestamp: string;
+}
+export declare class SafetyCheckTrackPointsDto {
+    points: SafetyCheckTrackPointDto[];
+}

package/dist/types/modules/safety/dtos/safety-internal.dto.d.ts

@@ -0,0 +1,51 @@
+import { GuardianAudienceDto } from '../../alert-dispatch/dtos/guardian-audience.dto';
+import { SafetyCheckSosTrigger, SafetyFeature } from '../enums/safety-enums';
+import { SafetyCheckLocationDto } from './safety-check.dto';
+/**
+ * clarion-safety -> clarion-incident: raise the SOS for a safety feature.
+ *
+ * Internal only (never proxied by the gateway) and token-protected. Idempotent on
+ * (feature, originReferenceId): a retry - from a workflow, the sweeper, or a user
+ * pressing twice - returns the incident the first call created.
+ *
+ * clarion-incident builds the incident itself: the reporter from the user's
+ * account, the Safety Alerts category and type from the organization's system
+ * rows, and entitlement/dispatch through the same pipeline as every SOS. The
+ * caller cannot choose a type, a class or an entitlement tier.
+ */
+export declare class CreateSafetyAlertIncidentDto {
+    feature: SafetyFeature;
+    originReferenceId: string;
+    trigger: SafetyCheckSosTrigger;
+    organizationId: number;
+    userId: number;
+    appId: string;
+    controlCentreId?: number;
+    location?: SafetyCheckLocationDto;
+    notifyServiceProvider: boolean;
+    guardianAudience: GuardianAudienceDto;
+    tripId?: string;
+    description?: string;
+}
+/** clarion-safety -> clarion-workflow-manager: start the durable timer. Idempotent per check. */
+export declare class StartSafetyCheckWorkflowDto {
+    safetyCheckId: string;
+    firstWakeAt: string;
+}
+/**
+ * clarion-safety -> clarion-workflow-manager: something changed. Purely an
+ * optimisation - a lost signal only means the workflow wakes at its previous
+ * time and asks clarion-safety, which answers with the truth.
+ */
+export declare class SignalSafetyCheckWorkflowDto {
+    done?: boolean;
+    nextWakeAt?: string;
+}
+/**
+ * clarion-billing -> clarion-incident: which of these incident type ids are
+ * platform-managed system types (the Safety SOS types). Billing refuses to put
+ * those in a package, whatever the admin UI shows.
+ */
+export declare class ClassifyIncidentTypesDto {
+    ids: number[];
+}

package/dist/types/modules/safety/enums/safety-check-status.enum.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Lifecycle of one Safety Check. clarion-safety is the only writer; every
+ * transition is validated against SAFETY_CHECK_TRANSITIONS
+ * (utils/safety-check-state-machine.ts) and applied as a conditional update, so
+ * two racing writers can never both win.
+ *
+ *   CREATED        accepted and persisted; tracking and the durable timer are
+ *                  still being set up. The user already counts as being in a
+ *                  check (the clock started when it was accepted).
+ *   ACTIVE         running; the user is expected to check in at
+ *                  scheduledCheckInAt.
+ *   PROMPTING      the check-in time has passed and the user is being asked to
+ *                  confirm they are safe. SOS is raised at promptDeadlineAt.
+ *   CHECKED_IN     the user confirmed they are safe. Terminal, successful.
+ *   SOS_TRIGGERED  an SOS was raised - the user missed the check-in or asked for
+ *                  one. Terminal for the check; the incident lives on in
+ *                  clarion-incident. `incidentId` is null until the incident
+ *                  has been created (clarion-safety keeps retrying).
+ *   STOPPED        the user ended the check before it completed. Terminal.
+ *   EXPIRED        the check-in window closed so long ago (a platform outage
+ *                  longer than SAFETY_CHECK_LIMITS.staleSosWindowMinutes) that
+ *                  raising an SOS now would be noise rather than help. Terminal;
+ *                  always an operational alarm.
+ *   CANCELLED      ended by the platform rather than the user (e.g. the account
+ *                  was signed out and the user chose to end it). Terminal.
+ *   FAILED         the SOS could not be raised because clarion-incident refused
+ *                  it outright (a non-retryable error). Terminal; the user is
+ *                  told to call for help and operators are alerted.
+ */
+export declare enum SafetyCheckStatus {
+    CREATED = "CREATED",
+    ACTIVE = "ACTIVE",
+    PROMPTING = "PROMPTING",
+    CHECKED_IN = "CHECKED_IN",
+    SOS_TRIGGERED = "SOS_TRIGGERED",
+    STOPPED = "STOPPED",
+    EXPIRED = "EXPIRED",
+    CANCELLED = "CANCELLED",
+    FAILED = "FAILED"
+}

package/dist/types/modules/safety/enums/safety-enums.d.ts

@@ -0,0 +1,81 @@
+/** Why a Safety Check raised an SOS. */
+export declare enum SafetyCheckSosTrigger {
+    /** The prompt countdown ran out without the user confirming they were safe. */
+    MISSED_CHECK_IN = "MISSED_CHECK_IN",
+    /** The user pressed SOS from the Safety Check screen. */
+    USER_REQUESTED = "USER_REQUESTED"
+}
+/** Who caused a Safety Check transition - recorded on every audit entry. */
+export declare enum SafetyCheckActorType {
+    USER = "USER",
+    /** The durable timer in clarion-workflow-manager. */
+    WORKFLOW = "WORKFLOW",
+    /** clarion-safety's backstop sweeper, acting on an overdue check. */
+    RECONCILER = "RECONCILER",
+    SYSTEM = "SYSTEM"
+}
+/** Audit trail entries (safety_check_events.eventType). Never carries a location. */
+export declare enum SafetyCheckAuditEventType {
+    CREATED = "CREATED",
+    ACTIVATED = "ACTIVATED",
+    TRACKING_STARTED = "TRACKING_STARTED",
+    TRACKING_UNAVAILABLE = "TRACKING_UNAVAILABLE",
+    WORKFLOW_STARTED = "WORKFLOW_STARTED",
+    WORKFLOW_START_FAILED = "WORKFLOW_START_FAILED",
+    EXTENDED = "EXTENDED",
+    PROMPT_STARTED = "PROMPT_STARTED",
+    CHECKED_IN = "CHECKED_IN",
+    STOPPED = "STOPPED",
+    CANCELLED = "CANCELLED",
+    SOS_TRIGGERED = "SOS_TRIGGERED",
+    SOS_INCIDENT_CREATED = "SOS_INCIDENT_CREATED",
+    SOS_INCIDENT_RETRY = "SOS_INCIDENT_RETRY",
+    SOS_FAILED = "SOS_FAILED",
+    EXPIRED = "EXPIRED"
+}
+/**
+ * The safety features that can raise an incident. Phase 1 raises only
+ * SAFETY_CHECK; FOLLOW_ME exists because its incident type is provisioned for
+ * every organization from day one.
+ */
+export declare enum SafetyFeature {
+    SAFETY_CHECK = "SAFETY_CHECK",
+    FOLLOW_ME = "FOLLOW_ME"
+}
+/** Stable code of the incident category every organization receives. */
+export declare enum SafetyIncidentCategoryCode {
+    SAFETY_ALERTS = "SAFETY_ALERTS"
+}
+/** Stable codes of the incident types inside the Safety Alerts category. */
+export declare enum SafetyIncidentTypeCode {
+    SAFETY_CHECK_SOS = "SAFETY_CHECK_SOS",
+    FOLLOW_ME_SOS = "FOLLOW_ME_SOS"
+}
+/**
+ * Kafka event types published by clarion-safety (the `eventType` field of
+ * SafetyCheckEvent). One topic per type, see KAFKA_TOPICS.SAFETY_CHECK_*.
+ */
+export declare enum SafetyCheckEventType {
+    STARTED = "SAFETY_CHECK_STARTED",
+    PROMPTING = "SAFETY_CHECK_PROMPTING",
+    ENDED = "SAFETY_CHECK_ENDED",
+    SOS_TRIGGERED = "SAFETY_CHECK_SOS_TRIGGERED"
+}
+/**
+ * Push `data.action` / `data.type` values the mobile app routes on. Sent by
+ * clarion-notification; the app allow-lists them in
+ * notification_deep_link_coordinator.dart. Changing a value is a breaking
+ * change to installed apps.
+ */
+export declare enum SafetyPushAction {
+    /** To the user: it is time to confirm you are safe. */
+    SAFETY_CHECK_PROMPT = "SAFETY_CHECK_PROMPT",
+    /** To the user: an SOS was raised for your Safety Check. */
+    SAFETY_CHECK_SOS_TRIGGERED = "SAFETY_CHECK_SOS_TRIGGERED",
+    /** To the user: the Safety Check ended without them (FAILED/EXPIRED/CANCELLED). */
+    SAFETY_CHECK_ENDED = "SAFETY_CHECK_ENDED",
+    /** To a guardian: somebody who chose you started a Safety Check. */
+    SAFETY_CHECK_GUARDIAN_STARTED = "SAFETY_CHECK_GUARDIAN_STARTED",
+    /** To a guardian: that Safety Check ended safely. */
+    SAFETY_CHECK_GUARDIAN_ENDED = "SAFETY_CHECK_GUARDIAN_ENDED"
+}

package/dist/types/modules/safety/enums/safety-error-code.enum.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Machine-readable `code` on every error clarion-safety returns, so the app can
+ * react (e.g. adopt the check a duplicate start collided with) without parsing
+ * the human message.
+ */
+export declare enum SafetyCheckErrorCode {
+    NOT_FOUND = "SAFETY_CHECK_NOT_FOUND",
+    ALREADY_ACTIVE = "SAFETY_CHECK_ALREADY_ACTIVE",
+    ALREADY_ENDED = "SAFETY_CHECK_ENDED",
+    SOS_ALREADY_TRIGGERED = "SAFETY_CHECK_SOS_ALREADY_TRIGGERED",
+    INVALID_TRANSITION = "SAFETY_CHECK_INVALID_TRANSITION",
+    INVALID_DURATION = "SAFETY_CHECK_INVALID_DURATION",
+    MAX_DURATION_EXCEEDED = "SAFETY_CHECK_MAX_DURATION_EXCEEDED",
+    INVALID_REASON = "SAFETY_CHECK_INVALID_REASON",
+    CUSTOM_REASON_REQUIRED = "SAFETY_CHECK_CUSTOM_REASON_REQUIRED",
+    GUARDIAN_NOT_FOUND = "SAFETY_CHECK_GUARDIAN_NOT_FOUND",
+    GUARDIANS_UNAVAILABLE = "SAFETY_CHECK_GUARDIANS_UNAVAILABLE",
+    NO_SOS_RECIPIENTS = "SAFETY_CHECK_NO_SOS_RECIPIENTS",
+    SERVICE_PROVIDER_NOT_ENTITLED = "SAFETY_CHECK_SERVICE_PROVIDER_NOT_ENTITLED",
+    TRACKING_CLOSED = "SAFETY_CHECK_TRACKING_CLOSED",
+    RATE_LIMITED = "SAFETY_CHECK_RATE_LIMITED"
+}

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

@@ -0,0 +1,13 @@
+export * from './enums/safety-check-status.enum';
+export * from './enums/safety-enums';
+export * from './enums/safety-error-code.enum';
+export * from './constants/safety-check-limits.const';
+export * from './constants/safety-taxonomy.const';
+export * from './constants/safety-integration.const';
+export * from './interfaces/safety-check';
+export * from './interfaces/safety-check-event';
+export * from './dtos/safety-check.dto';
+export * from './dtos/safety-admin.dto';
+export * from './dtos/safety-internal.dto';
+export * from './utils/safety-check-state-machine';
+export * from './utils/safety-check-timing.util';

package/dist/types/modules/safety/interfaces/safety-check-event.d.ts

@@ -0,0 +1,36 @@
+import { GuardianAudience } from '../../alert-dispatch/interfaces/guardian-audience';
+import { SafetyCheckStatus } from '../enums/safety-check-status.enum';
+import { SafetyCheckEventType, SafetyCheckSosTrigger } from '../enums/safety-enums';
+/**
+ * The Kafka payload for every KAFKA_TOPICS.SAFETY_CHECK_* topic. Published by
+ * clarion-safety through its transactional outbox (at-least-once, keyed by the
+ * check id so one check's events stay in order); consumers dedupe on `eventId`.
+ *
+ * Carries NO location. `guardianAudience` holds guardian identifiers because
+ * clarion-notification needs them to reach exactly the chosen guardians.
+ */
+export interface SafetyCheckEvent {
+    eventId: string;
+    eventType: SafetyCheckEventType;
+    version: 1;
+    occurredAt: string;
+    correlationId: string | null;
+    safetyCheckId: string;
+    userId: number;
+    organizationId: number;
+    controlCentreId: number | null;
+    appId: string | null;
+    countryCode: string | null;
+    status: SafetyCheckStatus;
+    reasonLabel: string;
+    durationMinutes: number;
+    startedAt: string;
+    scheduledCheckInAt: string;
+    promptStartedAt: string | null;
+    promptDeadlineAt: string | null;
+    endedAt: string | null;
+    notifyGuardiansOnStartEnd: boolean;
+    guardianAudience: GuardianAudience;
+    sosTrigger: SafetyCheckSosTrigger | null;
+    incidentId: number | null;
+}

package/dist/types/modules/safety/interfaces/safety-check.d.ts

@@ -0,0 +1,180 @@
+import { GuardianAudience } from '../../alert-dispatch/interfaces/guardian-audience';
+import { SafetyCheckStatus } from '../enums/safety-check-status.enum';
+import { SafetyCheckActorType, SafetyCheckAuditEventType, SafetyCheckSosTrigger } from '../enums/safety-enums';
+/** A reason as the app's dropdown shows it. */
+export interface SafetyCheckReasonView {
+    id: string;
+    code: string;
+    label: string;
+    description: string | null;
+    /** The "Write my own" entry: the user types the reason. */
+    isCustom: boolean;
+    displayOrder: number;
+}
+/** A reason as the admin manages it. */
+export interface SafetyCheckReasonAdminView extends SafetyCheckReasonView {
+    /** Null for a platform-wide reason. */
+    organizationId: number | null;
+    /** Null for every country. */
+    countryCode: string | null;
+    active: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * One Safety Check as its owner sees it.
+ *
+ * Timestamps are ISO 8601 from the SERVER clock. `serverTime` lets the app work
+ * out its own clock skew: remaining = scheduledCheckInAt - serverTime, counted
+ * down from when the response arrived.
+ */
+export interface SafetyCheckView {
+    id: string;
+    status: SafetyCheckStatus;
+    reasonId: string | null;
+    reasonCode: string | null;
+    /** What to show: the typed reason for "Write my own", else the reason's label at start. */
+    reasonLabel: string;
+    customReason: string | null;
+    /** Total minutes from start to the (possibly extended) check-in time. */
+    durationMinutes: number;
+    extensionCount: number;
+    startedAt: string;
+    scheduledCheckInAt: string;
+    promptCountdownSeconds: number;
+    promptStartedAt: string | null;
+    /** When the visible countdown ends. */
+    promptDeadlineAt: string | null;
+    checkedInAt: string | null;
+    endedAt: string | null;
+    guardians: GuardianAudience;
+    notifyGuardiansOnStartEnd: boolean;
+    /** What the user asked for. */
+    notifyServiceProviderRequested: boolean;
+    /** Whether the provider option was available to them at start (billing). */
+    notifyServiceProviderAllowed: boolean;
+    sosTrigger: SafetyCheckSosTrigger | null;
+    sosTriggeredAt: string | null;
+    /** Null until clarion-incident has created the SOS. */
+    incidentId: number | null;
+    tripId: string | null;
+    serverTime: string;
+}
+export interface SafetyCheckCurrentResponse {
+    /** The user's open check, or the one that most recently raised an SOS still awaiting its incident. */
+    check: SafetyCheckView | null;
+    serverTime: string;
+}
+/** What the setup screens need from the server, so client and server agree. */
+export interface SafetyCheckStartOptions {
+    limits: {
+        minDurationMinutes: number;
+        maxDurationMinutes: number;
+        presetDurationsMinutes: number[];
+        minPromptCountdownSeconds: number;
+        maxPromptCountdownSeconds: number;
+        customReasonMaxLength: number;
+    };
+    defaults: {
+        durationMinutes: number;
+        promptCountdownSeconds: number;
+        notifyServiceProvider: boolean;
+        notifyGuardiansOnStartEnd: boolean;
+    };
+    serviceProvider: {
+        /** Offer the "notify the service provider" option at all. */
+        available: boolean;
+        /** Billing tier (PREMIUM/TRIAL/FREE), null when billing could not be asked. */
+        tier: string | null;
+        /** Billing could not be asked; the option is offered and the SOS decides. */
+        degraded: boolean;
+    };
+    serverTime: string;
+}
+/** The recorded trip, WITHOUT coordinates - location is never shown before an SOS. */
+export interface SafetyCheckTripSummary {
+    id: string;
+    status: string;
+    visibility: string;
+    purpose: string;
+    incidentId: number | null;
+    startedAt: string;
+    endedAt: string | null;
+    sharedAt: string | null;
+    distanceMeters: number | null;
+    trackPointCount: number;
+}
+export interface SafetyCheckAuditEntry {
+    id: string;
+    eventType: SafetyCheckAuditEventType;
+    fromStatus: SafetyCheckStatus | null;
+    toStatus: SafetyCheckStatus | null;
+    actorType: SafetyCheckActorType;
+    actorUserId: number | null;
+    /** Identifiers and timings only - never a location or a message body. */
+    metadata: Record<string, unknown> | null;
+    createdAt: string;
+}
+/** A row of the admin list. */
+export interface SafetyCheckAdminListItem {
+    id: string;
+    status: SafetyCheckStatus;
+    userId: number;
+    userName: string | null;
+    organizationId: number;
+    controlCentreId: number | null;
+    reasonLabel: string;
+    durationMinutes: number;
+    startedAt: string;
+    scheduledCheckInAt: string;
+    checkedInAt: string | null;
+    endedAt: string | null;
+    sosTrigger: SafetyCheckSosTrigger | null;
+    incidentId: number | null;
+    createdAt: string;
+}
+/** The admin detail view. */
+export interface SafetyCheckAdminDetail {
+    check: SafetyCheckView & {
+        userId: number;
+        userName: string | null;
+        userPhoneNumber: string | null;
+        organizationId: number;
+        controlCentreId: number | null;
+        appId: string | null;
+        countryCode: string | null;
+        entitlementTierAtStart: string | null;
+        workflowId: string | null;
+        workflowStartedAt: string | null;
+        trackPointCount: number;
+        lastLocationAt: string | null;
+        sosAttempts: number;
+        sosFailureReason: string | null;
+        createdAt: string;
+        updatedAt: string;
+    };
+    events: SafetyCheckAuditEntry[];
+    trip: SafetyCheckTripSummary | null;
+}
+/** What the durable timer gets back from every advance. */
+export interface SafetyCheckAdvanceResult {
+    status: SafetyCheckStatus;
+    /** Nothing more for the timer to do. */
+    done: boolean;
+    /** When to call advance again (server clock). Null when done. */
+    nextWakeAt: string | null;
+}
+/** clarion-incident's answer to CreateSafetyAlertIncidentDto. */
+export interface SafetyAlertIncidentResult {
+    incidentId: number;
+    /** False when an earlier call already created it (idempotent replay). */
+    created: boolean;
+    conversationId: string | null;
+    notifyServiceProvider: boolean;
+    notifyGuardians: boolean;
+    entitlementTier: string | null;
+}
+/** clarion-incident's answer to "which of these type ids are system types". */
+export interface IncidentTypeClassification {
+    systemTypeIds: number[];
+}

package/dist/types/modules/safety/utils/safety-check-state-machine.d.ts

@@ -0,0 +1,30 @@
+import { SafetyCheckStatus } from '../enums/safety-check-status.enum';
+/**
+ * Every legal Safety Check transition. clarion-safety refuses anything else, and
+ * applies each allowed one as `UPDATE ... WHERE status IN (<allowed sources>)`, so
+ * the database - not the caller - decides a race.
+ *
+ * Re-applying a transition to a check already in the target state is NOT listed
+ * here: it is an idempotent no-op, answered with the current check
+ * (see isIdempotentRepeat).
+ */
+export declare const SAFETY_CHECK_TRANSITIONS: Readonly<Record<SafetyCheckStatus, readonly SafetyCheckStatus[]>>;
+/** States in which the user is "in a Safety Check": at most one per user. */
+export declare const OPEN_SAFETY_CHECK_STATUSES: readonly SafetyCheckStatus[];
+/** States from which the check will never move again. */
+export declare const TERMINAL_SAFETY_CHECK_STATUSES: readonly SafetyCheckStatus[];
+/**
+ * States in which location is still being recorded for the check. SOS_TRIGGERED
+ * is included: the recorded trip becomes the incident's trip and keeps growing.
+ */
+export declare const TRACKING_SAFETY_CHECK_STATUSES: readonly SafetyCheckStatus[];
+export declare function isOpenSafetyCheckStatus(status: SafetyCheckStatus | string | null | undefined): boolean;
+export declare function isTerminalSafetyCheckStatus(status: SafetyCheckStatus | string | null | undefined): boolean;
+export declare function canTransitionSafetyCheck(from: SafetyCheckStatus, to: SafetyCheckStatus): boolean;
+/** The states a check may be in for a transition to `to` to be applied. */
+export declare function allowedSourcesFor(to: SafetyCheckStatus): SafetyCheckStatus[];
+/**
+ * A repeated request for the state the check is already in - a retried "I'm OK",
+ * a second stop. Answered with the current check, never an error.
+ */
+export declare function isIdempotentRepeat(current: SafetyCheckStatus, requested: SafetyCheckStatus): boolean;

package/dist/types/modules/safety/utils/safety-check-timing.util.d.ts

@@ -0,0 +1,37 @@
+export interface SafetyCheckDurationValidation {
+    valid: boolean;
+    reason?: 'NOT_AN_INTEGER' | 'TOO_SHORT' | 'TOO_LONG';
+}
+/** Validates a requested duration against the platform limits. */
+export declare function validateSafetyCheckDuration(minutes: unknown): SafetyCheckDurationValidation;
+/** Whether a prompt countdown (seconds) is within the configurable range. */
+export declare function isValidPromptCountdownSeconds(seconds: unknown): boolean;
+/** The latest moment a check started at `startedAt` may be scheduled to check in. */
+export declare function latestAllowedCheckInAt(startedAt: Date): Date;
+export interface SafetyCheckExtensionPlan {
+    allowed: boolean;
+    /** New check-in time when allowed. */
+    scheduledCheckInAt?: Date;
+    /** Total minutes from start to the new check-in time. */
+    totalDurationMinutes?: number;
+    /** Most minutes that could still be added right now (0 when at the cap). */
+    maxAdditionalMinutes: number;
+}
+/**
+ * Plans an extension. While the check-in time is still ahead the extension is
+ * added to it; once it has passed (the user is being prompted) it counts from
+ * now. Either way the result may not end more than maxDurationMinutes after the
+ * check started - an extension never lets a check outlive the 24 hour cap.
+ */
+export declare function planSafetyCheckExtension(input: {
+    startedAt: Date;
+    scheduledCheckInAt: Date;
+    now: Date;
+    additionalMinutes: number;
+}): SafetyCheckExtensionPlan;
+/** When the prompt shown at `promptStartedAt` runs out (what the user sees). */
+export declare function promptDeadlineFrom(promptStartedAt: Date, promptCountdownSeconds: number): Date;
+/** When the server actually raises the SOS: the visible deadline plus the grace. */
+export declare function sosDueAt(promptDeadlineAt: Date): Date;
+/** Whether an SOS that fell due at `dueAt` is too stale to raise at `now`. */
+export declare function isSosTooStale(dueAt: Date, now: Date): boolean;

package/dist/types/modules/sms/enums/sms-template.enum.d.ts

@@ -6,6 +6,8 @@ export declare enum SmsTemplateType {
     SECURITY_ALERT = "security_alert",
     INCIDENT_NOTIFICATION = "incident_notification",
     INCIDENT_GUARDIAN_NOTIFICATION = "incident_guardian_notification",
+    SAFETY_CHECK_GUARDIAN_STARTED = "safety_check_guardian_started",
+    SAFETY_CHECK_GUARDIAN_ENDED = "safety_check_guardian_ended",
     APPOINTMENT_REMINDER = "appointment_reminder",
     GENERAL_NOTIFICATION = "general_notification"
 }

package/package.json

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