grm-shared-library 1.1.220 → 1.1.222

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.220",
+  "version": "1.1.222",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",