clarion-shared-types 1.0.106 → 1.0.107

package/dist/types/modules/safety/interfaces/follow-me.dto.d.ts

@@ -0,0 +1,392 @@
+import { GuardianAudience } from '../../alert-dispatch/interfaces/guardian-audience';
+import { GisRoutingProvider } from '../../gis/enums/routing.enum';
+import { TripPoint } from '../../gis/interfaces/trip-point';
+import { FollowMeAuditEventType, FollowMeEventType, FollowMeParticipantKind, FollowMeParticipantStatus, FollowMePromptStatus, FollowMeRealtimeEventType, FollowMeRouteKind, FollowMeSafetyEventType, FollowMeSafetyTrigger, FollowMeStatus, FollowMeTrackingHealth, FollowMeTransportMode, FollowMeWaypointKind } from '../enums/follow-me.enums';
+import { SafetyCheckActorType, SafetyCheckSosTrigger } from '../enums/safety-enums';
+import { SafetyCheckTripSummary } from './safety-check.dto';
+/**
+ * Coordinates and address are null wherever the viewer may not see location (the
+ * admin detail without track access) - the label alone says "Home" or "Work".
+ */
+export interface FollowMeWaypointView {
+    sequence: number;
+    kind: FollowMeWaypointKind;
+    label: string;
+    address: string | null;
+    lat: number | null;
+    lng: number | null;
+    savedPlaceId: string | null;
+}
+/** A computed route as the session stores it. */
+export interface FollowMeRouteView {
+    id: string;
+    kind: FollowMeRouteKind;
+    provider: GisRoutingProvider;
+    transportMode: FollowMeTransportMode;
+    /** Null wherever the viewer may not see location. */
+    polyline: string | null;
+    distanceMeters: number;
+    durationSeconds: number;
+    staticDurationSeconds: number;
+    computedAt: string;
+    /** Why it was recalculated (deviation, ETA check...). Null for the original plan. */
+    reason: string | null;
+    warnings: string[];
+}
+/** The answer to a route preview; start references it by `routeToken`. */
+export interface FollowMeRoutePreview {
+    routeToken: string;
+    expiresAt: string;
+    transportMode: FollowMeTransportMode;
+    waypoints: FollowMeWaypointView[];
+    provider: GisRoutingProvider;
+    polyline: string;
+    distanceMeters: number;
+    durationSeconds: number;
+    staticDurationSeconds: number;
+    etaAt: string;
+    /** The journey would outlast Follow Me's 24 h maximum. */
+    exceedsMaxDuration: boolean;
+    /** What the setup screen should pre-select (travel time plus a buffer, capped at 24 h). */
+    suggestedDurationMinutes: number;
+    warnings: string[];
+}
+export interface FollowMePromptView {
+    id: string;
+    trigger: FollowMeSafetyTrigger;
+    status: FollowMePromptStatus;
+    startedAt: string;
+    /** When the visible countdown ends. */
+    deadlineAt: string;
+    countdownSeconds: number;
+    respondedAt: string | null;
+    /** What the prompt screen says caused it, in plain words. */
+    message: string;
+}
+/** A participant as the SESSION OWNER sees them. */
+export interface FollowMeParticipantView {
+    id: string;
+    kind: FollowMeParticipantKind;
+    status: FollowMeParticipantStatus;
+    guardianUserId: number | null;
+    displayName: string;
+    /** External guardians only, masked (+2547******78). */
+    maskedPhoneNumber: string | null;
+    invitedAt: string;
+    respondedAt: string | null;
+    /** Looked at the journey in the last minute. */
+    watchingNow: boolean;
+}
+/** The session as its OWNER sees it. Timestamps are server time; use serverTime for skew. */
+export interface FollowMeSessionView {
+    id: string;
+    status: FollowMeStatus;
+    reasonId: string | null;
+    reasonCode: string | null;
+    reasonLabel: string;
+    customReason: string | null;
+    durationMinutes: number;
+    startedAt: string;
+    plannedEndAt: string;
+    endedAt: string | null;
+    arrivedAt: string | null;
+    promptCountdownSeconds: number;
+    notifyGuardiansOnStartEnd: boolean;
+    notifyServiceProviderRequested: boolean;
+    notifyServiceProviderAllowed: boolean;
+    transportMode: FollowMeTransportMode | null;
+    waypoints: FollowMeWaypointView[];
+    /** The route being monitored (the latest recalculation, else the plan). */
+    currentRoute: FollowMeRouteView | null;
+    /** Live estimate; null without a destination. */
+    etaAt: string | null;
+    distanceRemainingMeters: number | null;
+    trackingHealth: FollowMeTrackingHealth;
+    lastLocationAt: string | null;
+    crashDetectionEnabled: boolean;
+    activePrompt: FollowMePromptView | null;
+    participants: FollowMeParticipantView[];
+    sosTrigger: SafetyCheckSosTrigger | null;
+    sosCause: FollowMeSafetyTrigger | null;
+    sosTriggeredAt: string | null;
+    incidentId: number | null;
+    tripId: string | null;
+    conversationId: string | null;
+    serverTime: string;
+}
+export interface FollowMeCurrentResponse {
+    session: FollowMeSessionView | null;
+    serverTime: string;
+}
+/**
+ * The journey as a FOLLOWER sees it - an app guardian, an external guardian on the
+ * web page, or provider staff. Never includes guardians' contact details.
+ */
+export interface FollowMeFollowerView {
+    sessionId: string;
+    status: FollowMeStatus;
+    owner: {
+        firstName: string;
+        userId: number | null;
+    };
+    reasonLabel: string;
+    startedAt: string;
+    plannedEndAt: string;
+    endedAt: string | null;
+    arrivedAt: string | null;
+    transportMode: FollowMeTransportMode | null;
+    waypoints: FollowMeWaypointView[];
+    currentRoute: Pick<FollowMeRouteView, 'polyline' | 'distanceMeters' | 'durationSeconds' | 'provider'> | null;
+    etaAt: string | null;
+    distanceRemainingMeters: number | null;
+    trackingHealth: FollowMeTrackingHealth;
+    /** Null once live access has ended, and for a caller who has not accepted. */
+    latestLocation: TripPoint | null;
+    /** Recent path (oldest first) since the `since` the caller sent; empty without live access. */
+    path: TripPoint[];
+    /** Pass as `since` next time. */
+    pathCursor: string | null;
+    /** Other followers: names and states for app guardians, a count on the web page. */
+    otherFollowers: {
+        displayName: string;
+        status: FollowMeParticipantStatus;
+    }[] | {
+        count: number;
+    };
+    providerParticipating: boolean;
+    activePromptTrigger: FollowMeSafetyTrigger | null;
+    incidentId: number | null;
+    myParticipation: {
+        participantId: string;
+        status: FollowMeParticipantStatus;
+    } | null;
+    /** App guardians who accepted: the session chat. */
+    conversationId: string | null;
+    serverTime: string;
+}
+/** Pending requests for an app guardian (checked after sign-in, not only on a push). */
+export interface FollowMeRequestSummary {
+    sessionId: string;
+    participantId: string;
+    ownerFirstName: string;
+    reasonLabel: string;
+    status: FollowMeParticipantStatus;
+    invitedAt: string;
+    plannedEndAt: string;
+}
+/** What the setup screens need, so client and server agree. */
+export interface FollowMeStartOptions {
+    limits: {
+        minDurationMinutes: number;
+        maxDurationMinutes: number;
+        minPromptCountdownSeconds: number;
+        maxPromptCountdownSeconds: number;
+        maxIntermediateStops: number;
+        customReasonMaxLength: number;
+    };
+    defaults: {
+        durationMinutes: number;
+        promptCountdownSeconds: number;
+        notifyServiceProvider: boolean;
+        notifyGuardiansOnStartEnd: boolean;
+        transportMode: FollowMeTransportMode;
+    };
+    tracking: {
+        locationIntervalSeconds: number;
+        distanceFilterMeters: number;
+        uploadIntervalSeconds: number;
+    };
+    crashDetection: Record<string, number | string | boolean> & {
+        enabledTransportModes: FollowMeTransportMode[];
+    };
+    serviceProvider: {
+        available: boolean;
+        tier: string | null;
+        degraded: boolean;
+    };
+    serverTime: string;
+}
+export interface FollowMeSafetyEventView {
+    id: string;
+    type: FollowMeSafetyEventType;
+    occurredAt: string;
+    promptId: string | null;
+    /** Metrics (distances, durations, confidence). Coordinates only for viewers allowed location. */
+    evidence: Record<string, unknown> | null;
+}
+export interface FollowMeAuditEntry {
+    id: string;
+    eventType: FollowMeAuditEventType;
+    fromStatus: FollowMeStatus | null;
+    toStatus: FollowMeStatus | null;
+    actorType: SafetyCheckActorType;
+    actorUserId: number | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: string;
+}
+export interface FollowMeAdminListItem {
+    id: string;
+    status: FollowMeStatus;
+    userId: number;
+    userName: string | null;
+    organizationId: number;
+    controlCentreId: number | null;
+    reasonLabel: string;
+    durationMinutes: number;
+    startedAt: string;
+    plannedEndAt: string;
+    endedAt: string | null;
+    destinationLabel: string | null;
+    transportMode: FollowMeTransportMode | null;
+    providerParticipation: boolean;
+    sosTriggeredAt: string | null;
+    incidentId: number | null;
+    createdAt: string;
+}
+export interface FollowMeAdminDetail {
+    session: FollowMeSessionView & {
+        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;
+        sosAttempts: number;
+        sosFailureReason: string | null;
+        createdAt: string;
+        updatedAt: string;
+    };
+    routes: FollowMeRouteView[];
+    prompts: FollowMePromptView[];
+    safetyEvents: FollowMeSafetyEventView[];
+    audit: FollowMeAuditEntry[];
+    trip: SafetyCheckTripSummary | null;
+    /**
+     * Whether this viewer may see where the user was: the session was shared with
+     * the provider or became an SOS, AND the gateway vouched for track:follow-me
+     * (SAFETY_LOCATION_ACCESS_HEADER). When false every coordinate, address and
+     * polyline in this response is null and GET .../tracking answers 403.
+     */
+    locationAccess: boolean;
+}
+/** GET /safety/admin/follow-me/:id/tracking - track:follow-me, provider-shared or SOS sessions only. */
+export interface FollowMeAdminTracking {
+    sessionId: string;
+    status: FollowMeStatus;
+    waypoints: FollowMeWaypointView[];
+    routes: FollowMeRouteView[];
+    latestLocation: TripPoint | null;
+    /** Oldest first, after `since`; page with pathCursor. */
+    path: TripPoint[];
+    pathCursor: string | null;
+    /** Safety events with the coordinates they were observed at. */
+    safetyEvents: FollowMeSafetyEventView[];
+    trackingHealth: FollowMeTrackingHealth;
+    serverTime: string;
+}
+/** One active session on the staff live map (provider-shared, in the viewer's scope). */
+export interface FollowMeLiveSession {
+    sessionId: string;
+    status: FollowMeStatus;
+    userId: number;
+    userName: string | null;
+    organizationId: number;
+    controlCentreId: number | null;
+    reasonLabel: string;
+    transportMode: FollowMeTransportMode | null;
+    destinationLabel: string | null;
+    etaAt: string | null;
+    trackingHealth: FollowMeTrackingHealth;
+    latestLocation: TripPoint | null;
+    activePromptTrigger: FollowMeSafetyTrigger | null;
+    startedAt: string;
+}
+/**
+ * Kafka payload of every KAFKA_TOPICS.FOLLOW_ME_* topic (outbox, at-least-once,
+ * keyed by session id). NO location and NO access token - an external guardian's
+ * link is minted by clarion-notification at send time through the internal
+ * access-link route.
+ */
+export interface FollowMeEvent {
+    eventId: string;
+    eventType: FollowMeEventType;
+    version: 1;
+    occurredAt: string;
+    correlationId: string | null;
+    sessionId: string;
+    userId: number;
+    organizationId: number;
+    controlCentreId: number | null;
+    appId: string | null;
+    countryCode: string | null;
+    status: FollowMeStatus;
+    reasonLabel: string;
+    startedAt: string;
+    plannedEndAt: string;
+    endedAt: string | null;
+    destinationLabel: string | null;
+    etaAt: string | null;
+    notifyGuardiansOnStartEnd: boolean;
+    providerParticipation: boolean;
+    guardianAudience: GuardianAudience;
+    /** Everyone asked to follow, for invitations and endings. */
+    participants: {
+        participantId: string;
+        kind: FollowMeParticipantKind;
+        status: FollowMeParticipantStatus;
+        guardianUserId: number | null;
+        /** External guardians only (E.164), for the SMS. */
+        phoneNumber: string | null;
+        displayName: string;
+    }[];
+    /** GUARDIAN_RESPONDED: who answered, and how. */
+    respondingParticipantId: string | null;
+    promptId: string | null;
+    promptTrigger: FollowMeSafetyTrigger | null;
+    promptDeadlineAt: string | null;
+    sosTrigger: SafetyCheckSosTrigger | null;
+    sosCause: FollowMeSafetyTrigger | null;
+    incidentId: number | null;
+}
+/**
+ * What clarion-safety publishes on SAFETY_REALTIME_CHANNEL. `rooms` is decided by
+ * clarion-safety from the session's CURRENT audience each time, so a guardian who
+ * stops following or a session that ends stops receiving at once. clarion-socket
+ * validates the rooms and emits SAFETY_SOCKET_EVENT with the envelope minus rooms.
+ */
+export interface FollowMeRealtimeEnvelope {
+    eventId: string;
+    feature: 'FOLLOW_ME';
+    type: FollowMeRealtimeEventType;
+    sessionId: string;
+    organizationId: number;
+    occurredAt: string;
+    rooms: string[];
+    payload: Record<string, unknown>;
+}
+/** The internal access-link answer (clarion-safety -> clarion-notification only). */
+export interface FollowMeExternalLink {
+    url: string;
+    expiresAt: string;
+}
+/** Filters for GET /safety/admin/follow-me (mirrors FollowMeAdminQueryDto). */
+export interface FollowMeAdminQuery {
+    page?: number;
+    limit?: number;
+    status?: FollowMeStatus;
+    activeOnly?: boolean;
+    /** Super-admin only. */
+    organizationId?: number;
+    userId?: number;
+    sosOnly?: boolean;
+    providerParticipation?: boolean;
+    from?: string;
+    to?: string;
+    id?: string;
+    sortBy?: 'startedAt' | 'createdAt';
+}

package/dist/types/modules/safety/interfaces/safety-alert-context.d.ts

@@ -0,0 +1,8 @@
+/** See SafetyAlertContextDto: why a safety feature raised an SOS, as labelled facts. */
+export interface SafetyAlertContext {
+    summary: string;
+    facts: {
+        label: string;
+        value: string;
+    }[];
+}

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

@@ -1,5 +1,5 @@
 import { GuardianAudience } from '../../alert-dispatch/interfaces/guardian-audience';
-import { SafetyCheckActorType, SafetyCheckAuditEventType, SafetyCheckSosTrigger, SafetyCheckStatus } from '../enums/safety-enums';
+import { SafetyCheckActorType, SafetyCheckAuditEventType, SafetyCheckSosTrigger, SafetyCheckStatus, SafetyFeature } from '../enums/safety-enums';
 /**
  * Response shapes of clarion-safety, mirrored from grm-shared-library
  * (modules/safety/interfaces/safety-check.ts). Timestamps are ISO 8601 strings
@@ -14,6 +14,8 @@ export interface SafetyCheckReasonView {
     /** The "Write my own" entry: the user types the reason. */
     isCustom: boolean;
     displayOrder: number;
+    /** Which feature offers it; absent from a service older than Follow Me means SAFETY_CHECK. */
+    feature?: SafetyFeature;
 }
 /** A reason as the admin manages it. */
 export interface SafetyCheckReasonAdminView extends SafetyCheckReasonView {
@@ -29,6 +31,8 @@ export interface SafetyCheckReasonAdminView extends SafetyCheckReasonView {
 export interface CreateSafetyCheckReasonRequest {
     code: string;
     label: string;
+    /** Which feature offers it; SAFETY_CHECK when omitted. */
+    feature?: SafetyFeature;
     description?: string;
     organizationId?: number;
     countryCode?: string;

package/dist/types/modules/safety/utils/follow-me-display.util.d.ts

@@ -0,0 +1,27 @@
+import { FollowMeAuditEventType, FollowMeParticipantKind, FollowMeParticipantStatus, FollowMePromptStatus, FollowMeRouteKind, FollowMeSafetyEventType, FollowMeSafetyTrigger, FollowMeStatus, FollowMeTrackingHealth, FollowMeTransportMode, FollowMeWaypointKind } from '../enums/follow-me.enums';
+import { SafetyTone } from './safety-display.util';
+/**
+ * Human labels for the Follow Me enums, so every screen names the same state the
+ * same way. Paired with an icon or text wherever colour is used - never colour alone.
+ */
+export declare const FOLLOW_ME_STATUS_LABELS: Readonly<Record<FollowMeStatus, string>>;
+export declare const FOLLOW_ME_PARTICIPANT_STATUS_LABELS: Readonly<Record<FollowMeParticipantStatus, string>>;
+export declare const FOLLOW_ME_PARTICIPANT_KIND_LABELS: Readonly<Record<FollowMeParticipantKind, string>>;
+export declare const FOLLOW_ME_TRANSPORT_MODE_LABELS: Readonly<Record<FollowMeTransportMode, string>>;
+export declare const FOLLOW_ME_WAYPOINT_KIND_LABELS: Readonly<Record<FollowMeWaypointKind, string>>;
+export declare const FOLLOW_ME_ROUTE_KIND_LABELS: Readonly<Record<FollowMeRouteKind, string>>;
+export declare const FOLLOW_ME_TRIGGER_LABELS: Readonly<Record<FollowMeSafetyTrigger, string>>;
+export declare const FOLLOW_ME_PROMPT_STATUS_LABELS: Readonly<Record<FollowMePromptStatus, string>>;
+export declare const FOLLOW_ME_SAFETY_EVENT_LABELS: Readonly<Record<FollowMeSafetyEventType, string>>;
+export declare const FOLLOW_ME_AUDIT_EVENT_LABELS: Readonly<Record<FollowMeAuditEventType, string>>;
+export declare const FOLLOW_ME_TRACKING_HEALTH_LABELS: Readonly<Record<FollowMeTrackingHealth, string>>;
+export declare function followMeStatusTone(status: FollowMeStatus): SafetyTone;
+export declare function followMeParticipantTone(status: FollowMeParticipantStatus): SafetyTone;
+export declare function followMeTrackingHealthTone(health: FollowMeTrackingHealth): SafetyTone;
+/** Whether the session is still running. */
+export declare function isOpenFollowMe(status: FollowMeStatus): boolean;
+/**
+ * "Live", "Updated 3 min ago" or "No location yet" - so a stale position is never
+ * presented as live. `now` is injectable for tests.
+ */
+export declare function describeFollowMeFreshness(health: FollowMeTrackingHealth, lastLocationAt: string | null | undefined, now?: Date): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clarion-shared-types",
-  "version": "1.0.106",
+  "version": "1.0.107",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",