clarion-shared-types 1.0.106 → 1.0.108

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;
+    }[];
+}