grm-shared-library 1.1.236 → 1.1.238

package/dist/types/modules/dispatch/enums/response-unit-dispatch-status.enum.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Where one response unit is in answering one incident.
+ *
+ * Only DISPATCHED is set by the dispatch command itself. The middle states exist
+ * so the record can be advanced by whoever learns of progress - a dispatcher
+ * relaying a radio call today, the responder app or clarion-workflow later -
+ * without a schema change. Nothing in this platform advances them on a timer:
+ * escalation, reassignment and SLA belong to the workflow layer.
+ *
+ * ACTIVE = DISPATCHED, ACKNOWLEDGED, EN_ROUTE, ON_SCENE. A unit may hold at most
+ * ONE active dispatch across every incident - a partial unique index in
+ * clarion-incident enforces it, which is what stops two dispatchers sending the
+ * same unit to two emergencies.
+ */
+export declare enum ResponseUnitDispatchStatus {
+    /** Sent: the command was accepted and the unit was asked to respond. */
+    DISPATCHED = "DISPATCHED",
+    /** The unit confirmed it received the job. */
+    ACKNOWLEDGED = "ACKNOWLEDGED",
+    /** On the way. */
+    EN_ROUTE = "EN_ROUTE",
+    /** Arrived at the incident. */
+    ON_SCENE = "ON_SCENE",
+    /** Finished - by the dispatcher, or because the incident itself ended. */
+    COMPLETED = "COMPLETED",
+    /** Stood down before finishing. Frees the unit. */
+    CANCELLED = "CANCELLED",
+    /**
+     * The unit declined the job (before or just after acknowledging it). Frees
+     * the unit, like CANCELLED, but says the unit said no - which is what the
+     * emergency workflow reacts to by recommending the next unit.
+     */
+    REJECTED = "REJECTED"
+}

package/dist/types/modules/dispatch/enums/response-unit-dispatch-transition-source.enum.d.ts

@@ -0,0 +1,13 @@
+/** Who moved a dispatch to its current status. Recorded for the audit trail. */
+export declare enum ResponseUnitDispatchTransitionSource {
+    /** A control-room user, through the admin or the API. */
+    DISPATCHER = "DISPATCHER",
+    /** The incident ended (resolved, closed...), so its active dispatches were completed. */
+    INCIDENT_LIFECYCLE = "INCIDENT_LIFECYCLE",
+    /** Reserved for the responder app. */
+    RESPONDER = "RESPONDER",
+    /** clarion-workflow-manager's emergency incident workflow (e.g. an automatic reassignment). */
+    WORKFLOW = "WORKFLOW",
+    /** Inferred from live tracking: the unit stayed inside the incident's arrival geofence. */
+    TRACKING = "TRACKING"
+}

package/dist/types/modules/dispatch/enums/response-unit-distance-basis.enum.d.ts

@@ -0,0 +1,7 @@
+/** What a candidate's distance (and duration, when present) measures. */
+export declare enum ResponseUnitDistanceBasis {
+    /** Great-circle distance. Always available, never a duration. */
+    STRAIGHT_LINE = "STRAIGHT_LINE",
+    /** A road route from clarion-gis (Google Routes), with a travel time. */
+    ROAD_ROUTE = "ROAD_ROUTE"
+}

package/dist/types/modules/dispatch/enums/response-unit-location-freshness.enum.d.ts

@@ -0,0 +1,16 @@
+/**
+ * How far a candidate's position can be trusted.
+ *
+ * Not a new set of thresholds: CURRENT and STALE are clarion-response-tracking's
+ * own ONLINE / STALE status, which it evaluates against each provider
+ * connection's configured staleAfterSeconds / offlineAfterSeconds. A unit the
+ * tracking service calls OFFLINE has no usable position here (UNKNOWN).
+ */
+export declare enum ResponseUnitLocationFreshness {
+    /** A live fix within the provider's stale threshold. */
+    CURRENT = "CURRENT",
+    /** A live fix older than the stale threshold but not yet offline. */
+    STALE = "STALE",
+    /** No live fix that can be relied on: offline, never tracked, or base-only. */
+    UNKNOWN = "UNKNOWN"
+}

package/dist/types/modules/dispatch/enums/response-unit-location-source.enum.d.ts

@@ -0,0 +1,12 @@
+/** Where a candidate's position came from. */
+export declare enum ResponseUnitLocationSource {
+    /** A GPS fix from clarion-response-tracking. */
+    LIVE = "LIVE",
+    /**
+     * The unit's configured base location in clarion-organization - used only
+     * for a unit that is not live-tracked at all, and always labelled as such.
+     */
+    BASE = "BASE",
+    /** No usable position. */
+    NONE = "NONE"
+}

package/dist/types/modules/dispatch/enums/response-unit-recommendation-reason.enum.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The facts a recommendation rests on, in the order the ranking weighs them.
+ * The admin turns these into the "Recommended because:" lines; the numbers
+ * behind them (distance, age) travel on the candidate itself.
+ */
+export declare enum ResponseUnitRecommendationReason {
+    AVAILABLE = "AVAILABLE",
+    CAPABILITY_MATCH = "CAPABILITY_MATCH",
+    NO_CAPABILITY_REQUIREMENT = "NO_CAPABILITY_REQUIREMENT",
+    CAPABILITY_UNKNOWN = "CAPABILITY_UNKNOWN",
+    SAME_CONTROL_CENTRE = "SAME_CONTROL_CENTRE",
+    OTHER_CONTROL_CENTRE = "OTHER_CONTROL_CENTRE",
+    LIVE_LOCATION_CURRENT = "LIVE_LOCATION_CURRENT",
+    LIVE_LOCATION_STALE = "LIVE_LOCATION_STALE",
+    BASE_LOCATION = "BASE_LOCATION",
+    /** Closest of the units that tie on everything above. */
+    NEAREST = "NEAREST",
+    /** Quickest by road of the units that tie on everything above. */
+    QUICKEST = "QUICKEST"
+}

package/dist/types/modules/dispatch/enums/response-unit-recommendation-status.enum.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The overall answer. NO_UNITS_CONFIGURED and NO_ELIGIBLE_UNITS are different
+ * operational facts and the admin treats them differently: the first hides the
+ * whole dispatch panel (this control room simply has no units), the second is
+ * an alarm (it has units and none can go).
+ */
+export declare enum ResponseUnitRecommendationStatus {
+    /** A unit is recommended. */
+    RECOMMENDED = "RECOMMENDED",
+    /** Some units can be dispatched by hand, but none qualifies for a recommendation. */
+    NO_RECOMMENDATION = "NO_RECOMMENDATION",
+    /** Units exist and none of them can be dispatched. */
+    NO_ELIGIBLE_UNITS = "NO_ELIGIBLE_UNITS",
+    /** The caller's scope holds no response units at all. */
+    NO_UNITS_CONFIGURED = "NO_UNITS_CONFIGURED",
+    /** The incident itself cannot take a dispatch (see the blockers). */
+    NOT_DISPATCHABLE = "NOT_DISPATCHABLE"
+}

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

@@ -0,0 +1,31 @@
+export * from './enums/response-unit-dispatch-status.enum';
+export * from './enums/response-unit-dispatch-transition-source.enum';
+export * from './enums/response-unit-capability-match.enum';
+export * from './enums/response-capability-requirement-source.enum';
+export * from './enums/response-unit-location-source.enum';
+export * from './enums/response-unit-location-freshness.enum';
+export * from './enums/response-unit-distance-basis.enum';
+export * from './enums/response-unit-dispatch-constraint.enum';
+export * from './enums/response-unit-recommendation-reason.enum';
+export * from './enums/response-unit-recommendation-status.enum';
+export * from './enums/incident-dispatch-blocker.enum';
+export * from './enums/response-unit-dispatch-notification-status.enum';
+export * from './enums/response-unit-dispatch-notification-failure.enum';
+export * from './enums/response-unit-dispatch-error-code.enum';
+export * from './interfaces/response-unit-dispatch-profile';
+export * from './interfaces/response-unit-proximity';
+export * from './interfaces/response-unit-recommendation';
+export * from './interfaces/incident-response-unit-dispatch';
+export * from './interfaces/response-unit-dispatch-events';
+export * from './constants/response-unit-dispatch-kafka.const';
+export * from './constants/response-unit-dispatch-defaults.const';
+export * from './dtos/dispatch-response-unit.dto';
+export * from './dtos/update-response-unit-dispatch-status.dto';
+export * from './dtos/response-unit-nearby-query.dto';
+export * from './dtos/response-unit-dispatch-profile-query.dto';
+export * from './dtos/response-unit-dispatch-notification.dto';
+export * from './utils/response-unit-dispatch-status.util';
+export * from './utils/response-capability-match.util';
+export * from './utils/incident-dispatchability.util';
+export * from './utils/dispatch-geo.util';
+export * from './utils/response-unit-dispatch-event.util';

package/dist/types/modules/dispatch/interfaces/incident-response-unit-dispatch.d.ts

@@ -0,0 +1,126 @@
+import { IncidentArrivalSource } from '../../incident-sla/enums/incident-closure.enum';
+import { ResponseCapability } from '../../response-unit/enums/response-unit/response-capability.enum';
+import { ResponseUnitAvailability } from '../../response-unit/enums/response-unit/response-unit-availability.enum';
+import { ResponseCapabilityRequirementSource } from '../enums/response-capability-requirement-source.enum';
+import { ResponseUnitCapabilityMatch } from '../enums/response-unit-capability-match.enum';
+import { ResponseUnitDispatchNotificationFailure } from '../enums/response-unit-dispatch-notification-failure.enum';
+import { ResponseUnitDispatchNotificationStatus } from '../enums/response-unit-dispatch-notification-status.enum';
+import { ResponseUnitDispatchStatus } from '../enums/response-unit-dispatch-status.enum';
+import { ResponseUnitDispatchTransitionSource } from '../enums/response-unit-dispatch-transition-source.enum';
+import { ResponseUnitLocationFreshness } from '../enums/response-unit-location-freshness.enum';
+import { ResponseUnitLocationSource } from '../enums/response-unit-location-source.enum';
+import { ResponseUnitRecommendationStatus } from '../enums/response-unit-recommendation-status.enum';
+/** The selected unit as it stood when it was dispatched - frozen for the audit. */
+export interface ResponseUnitDispatchUnitSnapshot {
+    availability: ResponseUnitAvailability;
+    operationalStatus: string | null;
+    capabilities: ResponseCapability[];
+    capabilityMatch: ResponseUnitCapabilityMatch;
+    sameControlCentre: boolean;
+    locationSource: ResponseUnitLocationSource;
+    locationFreshness: ResponseUnitLocationFreshness;
+    locationRecordedAt: string | null;
+    locationAgeSeconds: number | null;
+    distanceMetres: number | null;
+    hasPhoneNumber: boolean;
+}
+/** One ranked alternative, as it stood at dispatch time. */
+export interface ResponseUnitDispatchSnapshotCandidate {
+    responseUnitId: number;
+    rank: number;
+    distanceMetres: number | null;
+    capabilityMatch: ResponseUnitCapabilityMatch;
+    locationFreshness: ResponseUnitLocationFreshness;
+}
+/**
+ * The recommendation the SERVER computed at the moment it accepted the
+ * dispatch. Recomputed rather than taken from the client, so "was the selected
+ * unit the recommended one?" is a fact, not a claim.
+ */
+export interface ResponseUnitDispatchRecommendationSnapshot {
+    generatedAt: string;
+    status: ResponseUnitRecommendationStatus;
+    recommendedResponseUnitId: number | null;
+    /** The recommended unit first, then the alternatives, capped. */
+    ranked: ResponseUnitDispatchSnapshotCandidate[];
+    requiredCapabilities: ResponseCapability[];
+    requirementSource: ResponseCapabilityRequirementSource;
+    liveTrackingAvailable: boolean;
+}
+/** Where the dispatch message stands. */
+export interface ResponseUnitDispatchNotificationState {
+    channel: 'SMS';
+    status: ResponseUnitDispatchNotificationStatus;
+    failureReason: ResponseUnitDispatchNotificationFailure | null;
+    /** Masked (+2547******78). The full number is never stored on the dispatch. */
+    recipient: string | null;
+    /** How many times it was requested (1 + resends). */
+    attempts: number;
+    requestedAt: string | null;
+    /** When clarion-notification last reported on it. */
+    resultAt: string | null;
+    providerCode: string | null;
+}
+/**
+ * One response unit sent to one incident. The authoritative dispatch record,
+ * owned by clarion-incident - and the engagement record: a unit is out on a job
+ * exactly while it has a dispatch in an ACTIVE status.
+ *
+ * Channel-neutral on purpose: the admin reads it today, the responder app and
+ * clarion-workflow can read the same record (and the events built from it)
+ * tomorrow.
+ */
+export interface IncidentResponseUnitDispatch {
+    id: number;
+    /** Stable external identifier (uuid), safe to quote in a call or a ticket. */
+    reference: string;
+    incidentId: number;
+    organizationId: number;
+    /** The incident's control centre. */
+    controlCentreId: number | null;
+    responseUnitId: number;
+    /** Copied at dispatch time so the record survives the unit being renamed or deleted. */
+    responseUnitName: string;
+    responseUnitType: string | null;
+    responseUnitControlCentreId: number | null;
+    status: ResponseUnitDispatchStatus;
+    dispatchedByUserId: number;
+    dispatchedAt: string;
+    /** The server's recommendation at dispatch time named this unit. */
+    wasRecommended: boolean;
+    /** The unit the server would have recommended at dispatch time. */
+    recommendedResponseUnitId: number | null;
+    /** The unit the dispatcher's screen showed as recommended (as reported by the client). */
+    shownRecommendedResponseUnitId: number | null;
+    /** Optional words from a dispatcher who chose another unit. */
+    overrideReason: string | null;
+    notes: string | null;
+    distanceMetres: number | null;
+    unitSnapshot: ResponseUnitDispatchUnitSnapshot;
+    recommendationSnapshot: ResponseUnitDispatchRecommendationSnapshot | null;
+    statusChangedAt: string;
+    statusChangedByUserId: number | null;
+    statusSource: ResponseUnitDispatchTransitionSource;
+    statusReason: string | null;
+    acknowledgedAt: string | null;
+    enRouteAt: string | null;
+    onSceneAt: string | null;
+    completedAt: string | null;
+    cancelledAt: string | null;
+    /** When the unit declined (REJECTED). */
+    rejectedAt: string | null;
+    /** How the arrival on scene came to be known; null until it did. */
+    arrivalSource: IncidentArrivalSource | null;
+    notification: ResponseUnitDispatchNotificationState;
+    createdAt: string;
+    updatedAt: string;
+}
+/** `POST /incidents/:id/response-unit-dispatches`. */
+export interface DispatchResponseUnitResult {
+    dispatch: IncidentResponseUnitDispatch;
+    /**
+     * True when this request repeated an earlier one (same Idempotency-Key) and
+     * the EXISTING dispatch is returned - nothing was dispatched or sent again.
+     */
+    replayed: boolean;
+}

package/dist/types/modules/dispatch/interfaces/response-unit-dispatch-events.d.ts

@@ -0,0 +1,105 @@
+import { ResponseUnitDispatchNotificationFailure } from '../enums/response-unit-dispatch-notification-failure.enum';
+import { ResponseUnitDispatchNotificationStatus } from '../enums/response-unit-dispatch-notification-status.enum';
+import { ResponseUnitDispatchStatus } from '../enums/response-unit-dispatch-status.enum';
+import { ResponseUnitDispatchTransitionSource } from '../enums/response-unit-dispatch-transition-source.enum';
+/** Fields every dispatch event carries. */
+export interface ResponseUnitDispatchEventBase {
+    schemaVersion: 1;
+    /** Deterministic per (dispatch, change) so a redelivery can be recognised. */
+    eventId: string;
+    occurredAt: string;
+    dispatchId: number;
+    dispatchReference: string;
+    incidentId: number;
+    organizationId: number;
+    controlCentreId: number | null;
+    responseUnitId: number;
+}
+/**
+ * `incident.response-unit-dispatch.created.v1` - a unit was sent to an incident.
+ *
+ * Identifiers and decisions only: no names, numbers or addresses. Every future
+ * consumer (clarion-workflow, the responder app's backend, analytics, audit)
+ * reads it; the few that need the incident's details look them up by id with
+ * their own authorization.
+ */
+export interface IncidentResponseUnitDispatchedEventV1 extends ResponseUnitDispatchEventBase {
+    status: ResponseUnitDispatchStatus.DISPATCHED;
+    responseUnitControlCentreId: number | null;
+    dispatchedByUserId: number;
+    dispatchedAt: string;
+    wasRecommended: boolean;
+    recommendedResponseUnitId: number | null;
+    distanceMetres: number | null;
+    notificationStatus: ResponseUnitDispatchNotificationStatus;
+}
+/**
+ * `incident.response-unit-dispatch.status-changed.v1` - acknowledged, en route,
+ * on scene, completed or stood down. Ordered per incident (keyed by incident id).
+ */
+export interface IncidentResponseUnitDispatchStatusChangedEventV1 extends ResponseUnitDispatchEventBase {
+    previousStatus: ResponseUnitDispatchStatus;
+    status: ResponseUnitDispatchStatus;
+    source: ResponseUnitDispatchTransitionSource;
+    changedByUserId: number | null;
+    reason: string | null;
+}
+/** The incident facts a dispatch message is written from. */
+export interface ResponseUnitDispatchMessageIncident {
+    /** As the control room quotes it, e.g. `#1234`. */
+    reference: string;
+    typeName: string | null;
+    categoryName: string | null;
+    priority: string | null;
+    /** The description, clamped. */
+    summary: string | null;
+    address: string | null;
+    latitude: number | null;
+    longitude: number | null;
+    /** Null when the reporter is anonymous. */
+    reporterName: string | null;
+    /** Null when the reporter is anonymous or left none. */
+    reporterPhoneNumber: string | null;
+    anonymous: boolean;
+    /** When the incident was raised (ISO-8601). Optional: older producers do not send it. */
+    reportedAt?: string | null;
+}
+/**
+ * `incident.response-unit-dispatch.notification-requested.v1` - a COMMAND to
+ * clarion-notification: tell this unit it has been dispatched.
+ *
+ * Kept apart from the domain event on purpose. It is the one message that needs
+ * the unit's phone number and the incident's details (an SMS cannot be written
+ * from identifiers), and it goes to one consumer; the domain event goes to
+ * everyone and carries neither. Self-contained so the message can be sent even
+ * when clarion-incident is down - an SMS that waits on a lookup is an SMS that
+ * arrives after the unit should have left.
+ */
+export interface ResponseUnitDispatchNotificationRequestedEventV1 extends ResponseUnitDispatchEventBase {
+    /** 1 for the dispatch itself, then 2, 3... for each "send again". */
+    attempt: number;
+    /** For organization branding and sender resolution. */
+    appId: string | null;
+    recipient: {
+        /** E.164. */
+        phoneNumber: string;
+        responseUnitName: string;
+    };
+    incident: ResponseUnitDispatchMessageIncident;
+}
+/**
+ * `notification.response-unit-dispatch.notification-result.v1` - what became of
+ * one request. clarion-incident records it on the dispatch.
+ */
+export interface ResponseUnitDispatchNotificationResultEventV1 {
+    schemaVersion: 1;
+    eventId: string;
+    occurredAt: string;
+    dispatchId: number;
+    incidentId: number;
+    organizationId: number;
+    attempt: number;
+    status: ResponseUnitDispatchNotificationStatus;
+    failureReason: ResponseUnitDispatchNotificationFailure | null;
+    providerCode: string | null;
+}

package/dist/types/modules/dispatch/interfaces/response-unit-dispatch-profile.d.ts

@@ -0,0 +1,52 @@
+import { ResponseCapability } from '../../response-unit/enums/response-unit/response-capability.enum';
+import { ResponseUnitAvailability } from '../../response-unit/enums/response-unit/response-unit-availability.enum';
+/**
+ * A response unit as dispatch sees it: the slim, authoritative row
+ * clarion-organization serves from `GET /response-units/dispatch-profiles`.
+ *
+ * Everything the recommendation engine needs to decide "could this unit go?"
+ * and nothing it does not - no crew, no device, no address book. The phone
+ * number is present ONLY when the caller asked for contact details (the
+ * dispatch command, never a recommendation), already in E.164 for the
+ * organization's country so clarion-notification can route it without
+ * guessing.
+ */
+export interface ResponseUnitDispatchProfile {
+    responseUnitId: number;
+    organizationId: number;
+    controlCentreId: number | null;
+    name: string;
+    /** `Vehicle` / `Person` / `Team`. */
+    responseUnitType: string;
+    /** `Ambulance` / `Security` / `Fire` / `Road Rescue` for vehicles; null otherwise. */
+    vehicleType: string | null;
+    registrationNumber: string | null;
+    isActive: boolean;
+    /** The manual status, whichever subtype field holds it (`Operational`, `On Duty`...). */
+    operationalStatus: string | null;
+    /** From the manual status only - clarion-incident layers active dispatches on top. */
+    availability: ResponseUnitAvailability;
+    /** The capabilities the unit is treated as having (configured, else derived from its type). */
+    capabilities: ResponseCapability[];
+    /** True when `capabilities` was configured on the unit rather than derived. */
+    capabilitiesConfigured: boolean;
+    /** The unit's configured base position; null when unset or obviously invalid (0,0). */
+    baseLocation: {
+        latitude: number;
+        longitude: number;
+    } | null;
+    stationName: string | null;
+    /** Whether a dispatch SMS could be sent at all. */
+    hasPhoneNumber: boolean;
+    /** E.164. Present only with `includeContact=true`. */
+    phoneNumber?: string | null;
+}
+/** One page of dispatch profiles - in practice the whole scope, capped. */
+export interface ResponseUnitDispatchProfileList {
+    organizationId: number;
+    /** Every unit in the caller's scope, before the cap. */
+    total: number;
+    units: ResponseUnitDispatchProfile[];
+    /** True when `total` exceeded the cap and `units` is the first slice. */
+    truncated: boolean;
+}

package/dist/types/modules/dispatch/interfaces/response-unit-proximity.d.ts

@@ -0,0 +1,45 @@
+import { TrackingUnitOnlineStatus } from '../../tracking/enums/tracking-unit-online-status.enum';
+/**
+ * One live-tracked unit near a point, as clarion-response-tracking answers
+ * `GET /tracking/response-units/nearby`.
+ *
+ * Found through the tracking service's Redis GEO index (maintained on every
+ * GPS fix), so the answer never involves reading every unit's state. The
+ * distance is great-circle, computed by Redis from the same position the live
+ * map shows.
+ */
+export interface ResponseUnitLivePosition {
+    responseUnitId: number;
+    organizationId: number;
+    controlCentreId: number | null;
+    latitude: number;
+    longitude: number;
+    /** Straight-line distance from the query point. */
+    distanceMetres: number;
+    /** The tracking service's own ONLINE / STALE / OFFLINE classification. */
+    status: TrackingUnitOnlineStatus;
+    /** When the fix was taken (provider time). */
+    eventTime: string;
+    /** Seconds between `eventTime` and the moment the answer was produced. */
+    ageSeconds: number;
+    accuracyMetres: number | null;
+}
+export interface ResponseUnitNearbyResult {
+    organizationId: number;
+    /** Set when the answer was confined to one control centre. */
+    controlCentreId: number | null;
+    latitude: number;
+    longitude: number;
+    radiusMetres: number;
+    limit: number;
+    generatedAt: string;
+    /** Nearest first. */
+    units: ResponseUnitLivePosition[];
+    /**
+     * Units in scope that ARE live-tracked but were not returned - beyond the
+     * radius or past the limit. Lets a consumer say "outside the search area"
+     * instead of falling back to a base location that would put a moving vehicle
+     * back in its depot.
+     */
+    outsideSearchUnitIds: number[];
+}

package/dist/types/modules/dispatch/interfaces/response-unit-recommendation.d.ts

@@ -0,0 +1,130 @@
+import { ResponseCapability } from '../../response-unit/enums/response-unit/response-capability.enum';
+import { ResponseUnitAvailability } from '../../response-unit/enums/response-unit/response-unit-availability.enum';
+import { IncidentDispatchBlocker } from '../enums/incident-dispatch-blocker.enum';
+import { ResponseCapabilityRequirementSource } from '../enums/response-capability-requirement-source.enum';
+import { ResponseUnitCapabilityMatch } from '../enums/response-unit-capability-match.enum';
+import { ResponseUnitDispatchConstraint } from '../enums/response-unit-dispatch-constraint.enum';
+import { ResponseUnitDistanceBasis } from '../enums/response-unit-distance-basis.enum';
+import { ResponseUnitLocationFreshness } from '../enums/response-unit-location-freshness.enum';
+import { ResponseUnitLocationSource } from '../enums/response-unit-location-source.enum';
+import { ResponseUnitRecommendationReason } from '../enums/response-unit-recommendation-reason.enum';
+import { ResponseUnitRecommendationStatus } from '../enums/response-unit-recommendation-status.enum';
+import { IncidentResponseUnitDispatch } from './incident-response-unit-dispatch';
+/** What the incident needs, and where that came from. */
+export interface ResponseCapabilityRequirement {
+    /** A unit with ANY of these is suitable. Empty = no requirement. */
+    capabilities: ResponseCapability[];
+    source: ResponseCapabilityRequirementSource;
+}
+/** Where a candidate is, and how far that can be trusted. */
+export interface ResponseUnitCandidateLocation {
+    source: ResponseUnitLocationSource;
+    freshness: ResponseUnitLocationFreshness;
+    latitude: number | null;
+    longitude: number | null;
+    /** When the position was recorded. Null for a base location. */
+    recordedAt: string | null;
+    /** Age of the position when the recommendation was produced. */
+    ageSeconds: number | null;
+    accuracyMetres: number | null;
+}
+/** How far, and - when road routing is on - how long. */
+export interface ResponseUnitTravelEstimate {
+    distanceMetres: number;
+    /** Only for a road route; a straight line has no honest duration. */
+    durationSeconds: number | null;
+    basis: ResponseUnitDistanceBasis;
+    trafficAware: boolean;
+}
+/**
+ * One unit, as the dispatcher sees it. The scoring that ordered the list is
+ * internal; what is exposed is the facts behind it (`reasons`, distance,
+ * freshness, match) - enough for the admin to say why, nothing to reverse-
+ * engineer weights from.
+ */
+export interface ResponseUnitCandidate {
+    responseUnitId: number;
+    name: string;
+    responseUnitType: string;
+    vehicleType: string | null;
+    registrationNumber: string | null;
+    controlCentreId: number | null;
+    /** The unit belongs to the incident's control centre. */
+    sameControlCentre: boolean;
+    operationalStatus: string | null;
+    availability: ResponseUnitAvailability;
+    /** The other incident this unit is out on, when it is ENGAGED by a dispatch. */
+    engagedIncidentId: number | null;
+    capabilities: ResponseCapability[];
+    capabilityMatch: ResponseUnitCapabilityMatch;
+    /** The required capabilities this unit has. */
+    matchedCapabilities: ResponseCapability[];
+    location: ResponseUnitCandidateLocation;
+    /** Straight-line distance to the incident; null without a usable position. */
+    distanceMetres: number | null;
+    /** A road estimate, for the top candidates when routing is enabled. */
+    travel: ResponseUnitTravelEstimate | null;
+    /** Whether a dispatch SMS could be sent. */
+    hasPhoneNumber: boolean;
+    /** The server would accept a dispatch of this unit now. */
+    dispatchable: boolean;
+    /** Dispatchable AND good enough to be suggested. */
+    recommendable: boolean;
+    /** Why it cannot be dispatched (blockers) and why it is not recommended (cautions). */
+    constraints: ResponseUnitDispatchConstraint[];
+    /** Why it ranks where it does. Empty for a unit that is not recommendable. */
+    reasons: ResponseUnitRecommendationReason[];
+    /** 1 = recommended. Null for units outside the recommendable ranking. */
+    rank: number | null;
+}
+export interface ResponseUnitRecommendationSummary {
+    /** Units in the caller's scope for this incident's organization. */
+    configuredUnits: number;
+    dispatchableUnits: number;
+    recommendableUnits: number;
+    engagedUnits: number;
+    /** Inactive or operationally unavailable. */
+    unavailableUnits: number;
+    /** Units with no usable position (offline, never tracked and no base). */
+    unitsWithoutLocation: number;
+    /** The unit list was capped; some units were not considered. */
+    truncated: boolean;
+}
+/**
+ * `GET /incidents/:id/response-unit-recommendation`.
+ *
+ * Advisory and side-effect free: generating one assigns nothing and reserves
+ * nothing. The dispatch command re-evaluates everything when it arrives.
+ */
+export interface ResponseUnitRecommendation {
+    incidentId: number;
+    organizationId: number;
+    controlCentreId: number | null;
+    generatedAt: string;
+    status: ResponseUnitRecommendationStatus;
+    /** Why the incident cannot take a dispatch; empty unless NOT_DISPATCHABLE. */
+    incidentBlockers: IncidentDispatchBlocker[];
+    requirement: ResponseCapabilityRequirement;
+    recommended: ResponseUnitCandidate | null;
+    /** Further recommendable units, best first. */
+    alternatives: ResponseUnitCandidate[];
+    /** Everything else in scope: dispatchable-by-hand first, then blocked. Capped. */
+    otherUnits: ResponseUnitCandidate[];
+    /** Units already out on THIS incident. */
+    activeDispatches: IncidentResponseUnitDispatch[];
+    summary: ResponseUnitRecommendationSummary;
+    /**
+     * False when the incident has no usable location. Nothing can be "nearest"
+     * then, so nothing is recommended - every dispatchable unit is listed for the
+     * dispatcher to choose from.
+     */
+    incidentLocationAvailable: boolean;
+    /**
+     * False when clarion-response-tracking could not be asked. Live positions are
+     * then unknown, so nothing is recommended (a depot location would put moving
+     * vehicles back at base); units are listed by base location, labelled as such.
+     */
+    liveTrackingAvailable: boolean;
+    /** True when road travel times were requested for the top candidates. */
+    travelTimeEnabled: boolean;
+}

package/dist/types/modules/dispatch/utils/dispatch-geo.util.d.ts

@@ -0,0 +1,16 @@
+/** Great-circle distance in metres. */
+export declare function haversineMetres(lat1: number, lng1: number, lat2: number, lng2: number): number;
+/**
+ * A coordinate worth computing a distance from: finite, in range, and not the
+ * (0,0) a form leaves behind when nobody picked a point (Null Island, in the
+ * Gulf of Guinea, is where every unset location in the world quietly sits).
+ */
+export declare function isUsableCoordinate(latitude: unknown, longitude: unknown): boolean;
+/**
+ * Read a {lat,lng} / {latitude,longitude} / {lat,lon} shaped location - the
+ * platform stores all three - as a usable coordinate, or null.
+ */
+export declare function readCoordinate(location: unknown): {
+    latitude: number;
+    longitude: number;
+} | null;

package/dist/types/modules/dispatch/utils/incident-dispatchability.util.d.ts

@@ -0,0 +1,18 @@
+import { IncidentStatus } from '../../incident/enums/incident-status.enum';
+import { IncidentDispatchBlocker } from '../enums/incident-dispatch-blocker.enum';
+/** Incident statuses after which nothing is sent to it. */
+export declare const INCIDENT_STATUSES_ENDING_DISPATCH: readonly IncidentStatus[];
+/** The incident facts dispatchability reads. */
+export interface DispatchableIncidentFacts {
+    class?: string | null;
+    status?: string | null;
+    notifyServiceProvider?: boolean | null;
+    entitlementTier?: string | null;
+}
+/**
+ * Why this incident cannot take a dispatch - empty when it can. Every reason is
+ * returned, not just the first, so the admin can say all of it at once.
+ */
+export declare function resolveIncidentDispatchBlockers(incident: DispatchableIncidentFacts): IncidentDispatchBlocker[];
+/** Whether an incident status ends every dispatch still active on it. */
+export declare function incidentStatusEndsDispatch(status: string | null | undefined): boolean;