grm-shared-library 1.1.241 → 1.1.243

package/dist/types/modules/responder/interfaces/responder-policy.d.ts

@@ -0,0 +1,55 @@
+import { ResponderReportField } from '../enums/responder.enums';
+/** One item of the closure checklist an organization asks its responders to confirm. */
+export interface ResponderChecklistItem {
+    /** Stable id, so an answer survives the label being reworded. */
+    id: string;
+    label: string;
+    required: boolean;
+}
+/**
+ * An organization's operational rules for its responders. Trusted configuration:
+ * served by clarion-organization, enforced by the services that own each rule.
+ */
+export interface ResponderPolicy {
+    location: {
+        onDutyIntervalSeconds: number;
+        activeIntervalSeconds: number;
+        distanceFilterMetres: number;
+        maxAccuracyMetres: number;
+        staleAfterSeconds: number;
+    };
+    arrival: {
+        /** Within this distance of the incident a GPS arrival is accepted. */
+        radiusMetres: number;
+        /** Whether a responder outside the radius (or without a fix) may confirm arrival by hand. */
+        allowManualConfirmation: boolean;
+        manualReasonRequired: boolean;
+    };
+    dispatch: {
+        allowDecline: boolean;
+        declineReasonRequired: boolean;
+    };
+    report: {
+        /** The responder cannot mark the dispatch COMPLETED before submitting a report. */
+        requiredToComplete: boolean;
+        requiredFields: ResponderReportField[];
+        checklist: ResponderChecklistItem[];
+        minPhotos: number;
+    };
+    evidence: {
+        allowPhotos: boolean;
+        allowDocuments: boolean;
+        allowVideo: boolean;
+        maxImageMegabytes: number;
+        maxDocumentMegabytes: number;
+        maxVideoMegabytes: number;
+    };
+    reporterContact: {
+        /** Whether a responder sees the (non-anonymous) reporter's name and number. */
+        visible: boolean;
+    };
+}
+/** A partial override as stored on the organization; anything absent keeps the default. */
+export type ResponderPolicyOverride = {
+    [K in keyof ResponderPolicy]?: Partial<ResponderPolicy[K]>;
+};

package/dist/types/modules/responder/interfaces/responder.d.ts

@@ -0,0 +1,113 @@
+import { ResponseUnitAvailability } from '../../response-unit/enums/response-unit/response-unit-availability.enum';
+import { ResponderDutyEndReason, ResponderDutySessionStatus } from '../enums/responder.enums';
+import { ResponderPolicy } from './responder-policy';
+/** A unit as the responder app shows it: enough to pick it and to recognise it. */
+export interface ResponderUnitSummary {
+    id: number;
+    name: string;
+    /** `Vehicle`, `Person` or `Team`. */
+    type: string;
+    /** Vehicle units: `Ambulance`, `Security`, ... */
+    vehicleType: string | null;
+    registrationNumber: string | null;
+    /** The unit's own phone (vehicle / person units); teams have none. */
+    phoneNumber: string | null;
+    capabilities: string[];
+    isActive: boolean;
+    /** The manual status the control room sets (`Operational`, `On Duty`, ...). */
+    operationalStatus: string | null;
+    /** From the manual status only; an active dispatch makes a unit ENGAGED in clarion-incident. */
+    availability: ResponseUnitAvailability;
+    organizationId: number;
+    controlCentreId: number | null;
+    station: {
+        name?: string | null;
+        address?: string | null;
+    } | null;
+}
+/** One stretch of duty: a responder staffing one unit. */
+export interface ResponderDutySession {
+    id: number;
+    userId: number;
+    responseUnitId: number;
+    /** Copied at start so the record reads right after a rename. */
+    responseUnitName: string;
+    organizationId: number;
+    controlCentreId: number | null;
+    status: ResponderDutySessionStatus;
+    startedAt: string;
+    endedAt: string | null;
+    endReason: ResponderDutyEndReason | null;
+    endReasonText: string | null;
+    /** Who ended it - the responder, or the control-room user. */
+    endedByUserId: number | null;
+}
+export interface ResponderOrganizationSummary {
+    id: number;
+    name: string;
+    logo: string | null;
+    phoneNumber: string | null;
+    email: string | null;
+    countryCode: string | null;
+}
+export interface ResponderControlCentreSummary {
+    id: number;
+    name: string;
+    phoneNumber: string | null;
+    email: string | null;
+    logo: string | null;
+}
+/** `GET /responder/me` - everything the app needs to know who and where the responder is. */
+export interface ResponderProfile {
+    userId: number;
+    organization: ResponderOrganizationSummary;
+    controlCentre: ResponderControlCentreSummary | null;
+    /** The units the responder may go on duty with (memberships), active ones first. */
+    units: ResponderUnitSummary[];
+    activeDuty: ResponderDutySession | null;
+    /** The organization's effective policy (defaults merged with its override). */
+    policy: ResponderPolicy;
+    /** The server's clock, so the app can tell how far off the phone's is. */
+    serverTime: string;
+}
+/** A responder linked to a unit, as the admin's unit screen lists them. */
+export interface ResponseUnitResponder {
+    id: number;
+    responseUnitId: number;
+    userId: number;
+    organizationId: number;
+    controlCentreId: number | null;
+    createdByUserId: number | null;
+    createdAt: string;
+    /** The account, when clarion-authentication could be read; null otherwise. */
+    user: {
+        id: number;
+        name: string;
+        email: string | null;
+        phoneNumber: string | null;
+    } | null;
+    /** Set while this responder is on duty with THIS unit. */
+    activeDuty: {
+        sessionId: number;
+        startedAt: string;
+    } | null;
+}
+/** Internal: a user's units, duty and policy - for clarion-incident and clarion-response-tracking. */
+export interface ResponderInternalUnits {
+    userId: number;
+    organizationId: number | null;
+    controlCentreId: number | null;
+    /** Units the user is a member of (whatever their status). */
+    responseUnitIds: number[];
+    activeDuty: {
+        sessionId: number;
+        responseUnitId: number;
+        startedAt: string;
+    } | null;
+    policy: ResponderPolicy;
+}
+/** Internal: who is on duty with a unit - for clarion-notification's dispatch pushes. */
+export interface ResponderInternalUnitOnDuty {
+    responseUnitId: number;
+    userIds: number[];
+}

package/dist/types/modules/responder/utils/responder.util.d.ts

@@ -0,0 +1,24 @@
+import { ResponseUnitDispatchStatus } from '../../dispatch/enums/response-unit-dispatch-status.enum';
+import { ResponderPolicy, ResponderPolicyOverride } from '../interfaces/responder-policy';
+/**
+ * The organization's effective policy: the defaults with its override laid over
+ * them, part by part. Unknown keys in a stored override are ignored, so an old
+ * row can never smuggle a setting the code no longer knows into the app.
+ */
+export declare function resolveResponderPolicy(override: ResponderPolicyOverride | null | undefined): ResponderPolicy;
+/** Whether a responder may move a dispatch from `from` to `to`, before policy. */
+export declare function canResponderTransitionDispatch(from: ResponseUnitDispatchStatus, to: ResponseUnitDispatchStatus): boolean;
+/** The statuses a responder may set next, with the policy applied (no decline when it is off). */
+export declare function responderAllowedDispatchStatuses(from: ResponseUnitDispatchStatus, policy: Pick<ResponderPolicy, 'dispatch'>): ResponseUnitDispatchStatus[];
+/** What a responder's report is missing under the policy - field names and `checklist:<id>`. */
+export declare function missingResponderReportItems(report: {
+    summary?: string | null;
+    actionsTaken?: string | null;
+    personsContacted?: string | null;
+    handoverTo?: string | null;
+    remarks?: string | null;
+    checklist?: {
+        itemId: string;
+        checked: boolean;
+    }[] | null;
+}, policy: Pick<ResponderPolicy, 'report'>): string[];

package/dist/types/modules/role/data/roles.data.d.ts

@@ -1,2 +1,9 @@
 import { Role } from "../interfaces/role";
+/**
+ * The responder app, for the people who staff a response unit. Each action is
+ * confined to the caller's own memberships, duty and unit by the service that
+ * owns it (clarion-organization, clarion-incident, clarion-response-tracking),
+ * so holding one says nothing about anybody else's unit.
+ */
+export declare const RESPONDER_APP_PERMISSIONS: string[];
 export declare const ROLES_DATA: Role[];

package/dist/types/modules/tracking/dtos/units-analytics-query.dto.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The period a Units & Tracking analytics read covers (both halves: tracking and
+ * dispatch), and optionally one control centre. Both ends optional: no `from` is
+ * "forever", no `to` is now.
+ */
+export declare class UnitsAnalyticsQueryDto {
+    from?: string;
+    to?: string;
+    timeZone?: string;
+    /** Super-Admin only: one organization's figures instead of every organization's. Ignored for anybody else. */
+    organizationId?: number;
+    /**
+     * One control centre's figures. Within the caller's own organization (a Super-Admin's
+     * pick of one); control-centre staff see their own centre whatever this says.
+     */
+    controlCentreId?: number;
+}

package/dist/types/modules/tracking/enums/tracking-provider-code.enum.d.ts

@@ -22,5 +22,13 @@ export declare enum TrackingProviderCode {
     /** Generic WebSocket adapter (reserved). */
     GENERIC_WEBSOCKET = "GENERIC_WEBSOCKET",
     /** Generic HTTP polling adapter (reserved). */
-    GENERIC_HTTP_POLLING = "GENERIC_HTTP_POLLING"
+    GENERIC_HTTP_POLLING = "GENERIC_HTTP_POLLING",
+    /**
+     * The responder app: the phone of the responder on duty with a unit reports
+     * the unit's position (`POST /tracking/responder/positions`). Inbound only -
+     * there is no connection to open, so the connector never runs a session
+     * for it. Used only for units with no enabled hardware tracker binding, so
+     * a vehicle's tracker and a crew member's phone never compete.
+     */
+    MOBILE_APP = "MOBILE_APP"
 }

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

@@ -14,6 +14,8 @@ export * from './interfaces/tracking-unit-current-state';
 export * from './interfaces/tracking-socket-payloads';
 export * from './interfaces/tracking-realtime-envelope';
 export * from './interfaces/tracking-provider-descriptor';
+export * from './interfaces/tracking-analytics';
+export * from './dtos/units-analytics-query.dto';
 export * from './constants/tracking-kafka.const';
 export * from './utils/tracking-event-id.util';
 export * from './utils/tracking-validation.util';

package/dist/types/modules/tracking/interfaces/tracking-analytics.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Units & Tracking analytics, the tracking half (the admin's Units & Tracking
+ * Analytics): the response units in scope and how they are tracked - computed by
+ * clarion-response-tracking. The other half, what was dispatched and how it went, is
+ * DispatchAnalytics (clarion-incident); both answer the same query.
+ *
+ * The fleet and its live status are as they stand NOW. Everything else is the period's,
+ * counted by the hour a position was recorded (`eventTime`): the service keeps an hourly
+ * rollup of the position history, so a year costs no more to read than a day. Counts,
+ * rates and durations only - never a position, a route or a device identifier.
+ */
+/** How the period is cut into points for the charts. Chosen by the service from the length of the period. */
+export type UnitsAnalyticsBucket = 'hour' | 'day' | 'week' | 'month';
+export interface UnitsAnalyticsRange {
+    /** Inclusive, ISO 8601. For "forever", the start of the data in scope. */
+    from: string;
+    /** Exclusive, ISO 8601. */
+    to: string;
+    bucket: UnitsAnalyticsBucket;
+    /** IANA time zone the buckets (and the dispatch hour-of-week grid) are cut in. */
+    timeZone: string;
+}
+/** Whose figures these are, as the service decided from the caller. */
+export interface UnitsAnalyticsScope {
+    /** Null: every organization (a Super-Admin's platform view). */
+    organizationId: number | null;
+    /** Null: every control centre of the organization. */
+    controlCentreId: number | null;
+    platform: boolean;
+}
+/** A count by a key (a type, a status, a provider), largest first unless the section says otherwise. */
+export interface UnitsAnalyticsCount<K extends string = string> {
+    key: K;
+    count: number;
+}
+/** Median and 90th percentile of one duration, in seconds; null when nothing was measured. */
+export interface UnitsAnalyticsDuration {
+    samples: number;
+    medianSeconds: number | null;
+    p90Seconds: number | null;
+}
+/** The response units in scope, as they stand now (deleted units are left out). */
+export interface TrackingAnalyticsFleet {
+    total: number;
+    enabled: number;
+    disabled: number;
+    byType: UnitsAnalyticsCount[];
+    byOperationalStatus: UnitsAnalyticsCount[];
+    /** Enabled units with an enabled device binding: the service is told where they are. */
+    tracked: number;
+    /** Enabled units with no enabled binding. */
+    untracked: number;
+    /** Tracked units by the provider of their binding's connection (a unit bound twice counts under each). */
+    trackedByProvider: UnitsAnalyticsCount[];
+}
+/** The tracked units' state now - the same states as the live map. */
+export interface TrackingAnalyticsLive {
+    online: number;
+    stale: number;
+    offline: number;
+    /** Tracked units with no position in the live store (never reported, or not for a long while). */
+    noPosition: number;
+}
+/** Which units reported in the period. */
+export interface TrackingAnalyticsReporting {
+    /** Units that reported at least one position. */
+    reportingUnits: number;
+    /** The same for the previous period of the same length; null for "forever". */
+    previousReportingUnits: number | null;
+    /** Tracked units (now) that reported nothing in the period. */
+    silentTrackedUnits: number;
+    /** Tracked units that reported, as a percentage of the tracked units; null without tracked units. */
+    reportingRate: number | null;
+}
+/** The positions recorded in the period. */
+export interface TrackingAnalyticsPositions {
+    total: number;
+    /** Null for "forever". */
+    previousTotal: number | null;
+    /** Positions per reporting unit per hour it reported in. */
+    perUnitHour: number | null;
+    /** Percentages of the positions that say: reported while moving, with the ignition on. */
+    movingRate: number | null;
+    ignitionOnRate: number | null;
+    byProvider: UnitsAnalyticsCount[];
+}
+/** How long a position took to reach Clarion once the device recorded it, in bands. */
+export type TrackingDelayBand = 'WITHIN_5S' | 'WITHIN_10S' | 'WITHIN_30S' | 'WITHIN_1M' | 'WITHIN_2M' | 'WITHIN_5M' | 'WITHIN_15M' | 'LATER';
+/** Delivery delay: `receivedAt - eventTime` of every position in the period. */
+export interface TrackingAnalyticsDelivery {
+    /** Estimated from the bands (interpolated within the band the percentile falls in). */
+    medianSeconds: number | null;
+    p90Seconds: number | null;
+    meanSeconds: number | null;
+    /** Every band, fastest first, zero counts included. */
+    bands: UnitsAnalyticsCount<TrackingDelayBand>[];
+    /** Positions that took longer than 5 minutes, as a percentage. */
+    lateRate: number | null;
+}
+/** What the ingestion flagged about the period's positions, and the provider units nobody has bound. */
+export interface TrackingAnalyticsQuality {
+    outOfOrder: number;
+    duplicates: number;
+    invalidCoordinates: number;
+    /** Positions that jumped implausibly far from the previous one. */
+    jumpSuspected: number;
+    /** Positions with an accuracy worse than 100 m. */
+    poorAccuracy: number;
+    /** Provider units reporting without a binding: open now, resolved, and how often they were seen. */
+    unmappedOpen: number;
+    unmappedResolved: number;
+    unmappedOccurrences: number;
+}
+export interface TrackingAnalyticsTimelinePoint {
+    /** Start of the bucket, ISO 8601. */
+    at: string;
+    positions: number;
+    reportingUnits: number;
+    /** Positions that took longer than 5 minutes to arrive. */
+    late: number;
+}
+/** A provider connection in scope: its configuration and health now, and its positions in the period. */
+export interface TrackingAnalyticsConnectionRow {
+    id: number;
+    organizationId: number;
+    controlCentreId: number | null;
+    name: string;
+    providerCode: string;
+    enabled: boolean;
+    connectionStatus: string;
+    lastEventAt: string | null;
+    lastErrorAt: string | null;
+    lastErrorCode: string | null;
+    /** Enabled bindings through it now. */
+    boundUnits: number;
+    positions: number;
+    reportingUnits: number;
+    medianDelaySeconds: number | null;
+    lateRate: number | null;
+}
+/** A response unit in scope: what it is and how it is tracked now, and what it reported in the period. */
+export interface TrackingAnalyticsUnitRow {
+    responseUnitId: number;
+    organizationId: number;
+    controlCentreId: number | null;
+    name: string | null;
+    responseUnitType: string | null;
+    enabled: boolean;
+    tracked: boolean;
+    /** The providers its enabled bindings use. */
+    providers: string[];
+    /** ONLINE, STALE or OFFLINE now; null when not tracked or without a position. */
+    liveStatus: string | null;
+    /** Its newest position in the period. */
+    lastPositionAt: string | null;
+    positions: number;
+    /** Hours in which it reported at least once. */
+    hoursReporting: number;
+    medianDelaySeconds: number | null;
+}
+/** Platform view only: one row per organization. */
+export interface TrackingAnalyticsOrganizationRow {
+    organizationId: number;
+    units: number;
+    tracked: number;
+    reportingUnits: number;
+    positions: number;
+    connections: number;
+    lateRate: number | null;
+}
+export interface TrackingAnalytics {
+    generatedAt: string;
+    range: UnitsAnalyticsRange;
+    scope: UnitsAnalyticsScope;
+    fleet: TrackingAnalyticsFleet;
+    live: TrackingAnalyticsLive;
+    reporting: TrackingAnalyticsReporting;
+    positions: TrackingAnalyticsPositions;
+    delivery: TrackingAnalyticsDelivery;
+    quality: TrackingAnalyticsQuality;
+    timeline: TrackingAnalyticsTimelinePoint[];
+    connections: TrackingAnalyticsConnectionRow[];
+    /** The units in scope, most positions first; capped (see `unitsTruncated`). */
+    units: TrackingAnalyticsUnitRow[];
+    unitsTruncated: boolean;
+    /** Platform view only; null otherwise. */
+    byOrganization: TrackingAnalyticsOrganizationRow[] | null;
+    /** The rollup is complete up to this instant: positions recorded later are not counted yet. */
+    rollupThrough: string | null;
+    /** History older than this is still being rolled up (the first hours after release); null once complete. */
+    backfillingBefore: string | null;
+}

package/package.json

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