grm-shared-library 1.1.236 → 1.1.237

package/dist/types/modules/dispatch/dtos/response-unit-dispatch-notification.dto.d.ts

@@ -0,0 +1,47 @@
+import { ResponseUnitDispatchNotificationFailure } from '../enums/response-unit-dispatch-notification-failure.enum';
+import { ResponseUnitDispatchNotificationStatus } from '../enums/response-unit-dispatch-notification-status.enum';
+import { ResponseUnitDispatchMessageIncident, ResponseUnitDispatchNotificationRequestedEventV1, ResponseUnitDispatchNotificationResultEventV1 } from '../interfaces/response-unit-dispatch-events';
+export declare class ResponseUnitDispatchMessageIncidentDto implements ResponseUnitDispatchMessageIncident {
+    reference: string;
+    typeName: string | null;
+    categoryName: string | null;
+    priority: string | null;
+    summary: string | null;
+    address: string | null;
+    latitude: number | null;
+    longitude: number | null;
+    reporterName: string | null;
+    reporterPhoneNumber: string | null;
+    anonymous: boolean;
+}
+export declare class ResponseUnitDispatchRecipientDto {
+    phoneNumber: string;
+    responseUnitName: string;
+}
+export declare class ResponseUnitDispatchNotificationRequestedDto implements ResponseUnitDispatchNotificationRequestedEventV1 {
+    schemaVersion: 1;
+    eventId: string;
+    occurredAt: string;
+    dispatchId: number;
+    dispatchReference: string;
+    incidentId: number;
+    organizationId: number;
+    controlCentreId: number | null;
+    responseUnitId: number;
+    attempt: number;
+    appId: string | null;
+    recipient: ResponseUnitDispatchRecipientDto;
+    incident: ResponseUnitDispatchMessageIncidentDto;
+}
+export declare class ResponseUnitDispatchNotificationResultDto implements 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/dtos/response-unit-dispatch-profile-query.dto.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `GET /response-units/dispatch-profiles` (clarion-organization, internal).
+ *
+ * Scoped by the forwarded user context; `organizationId` is honoured for a
+ * Super-Admin only. `includeContact` adds the unit's phone number and is used by
+ * the dispatch command alone - a recommendation never carries one.
+ */
+export declare class ResponseUnitDispatchProfileQueryDto {
+    organizationId?: number;
+    controlCentreId?: number;
+    ids?: number[];
+    includeContact?: boolean;
+}

package/dist/types/modules/dispatch/dtos/response-unit-nearby-query.dto.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `GET /tracking/response-units/nearby` (clarion-response-tracking).
+ *
+ * Tenancy is NOT in the query: the tracking service takes it from the forwarded
+ * user context. `organizationId` is honoured for a Super-Admin only and a
+ * control-centre caller is pinned to their own centre whatever they pass.
+ */
+export declare class ResponseUnitNearbyQueryDto {
+    latitude: number;
+    longitude: number;
+    organizationId?: number;
+    controlCentreId?: number;
+    radiusMetres?: number;
+    limit?: number;
+}

package/dist/types/modules/dispatch/dtos/update-response-unit-dispatch-status.dto.d.ts

@@ -0,0 +1,9 @@
+import { ResponseUnitDispatchStatus } from '../enums/response-unit-dispatch-status.enum';
+/** Every status a dispatch can be MOVED to (DISPATCHED is only ever its first). */
+export declare const SETTABLE_RESPONSE_UNIT_DISPATCH_STATUSES: readonly ResponseUnitDispatchStatus[];
+/** `POST /incidents/:id/response-unit-dispatches/:dispatchId/status`. */
+export declare class UpdateResponseUnitDispatchStatusDto {
+    status: ResponseUnitDispatchStatus;
+    /** Why - e.g. why a unit was stood down. */
+    reason?: string;
+}

package/dist/types/modules/dispatch/enums/incident-dispatch-blocker.enum.d.ts

@@ -0,0 +1,16 @@
+/** Why an INCIDENT cannot take a response-unit dispatch, whatever unit is chosen. */
+export declare enum IncidentDispatchBlocker {
+    /** Resolved, closed, unresolved or archived. */
+    INCIDENT_ENDED = "INCIDENT_ENDED",
+    /** A grievance, not an emergency. */
+    NOT_AN_EMERGENCY_INCIDENT = "NOT_AN_EMERGENCY_INCIDENT",
+    /**
+     * The incident does not reach the control room: the reporter was not
+     * entitled to a provider response, or declined one. Sending a unit IS the
+     * provider response, so the rule that keeps the alert off the control room's
+     * screens also keeps it from being dispatched - see `reachesControlRoom`.
+     */
+    PROVIDER_RESPONSE_NOT_REQUESTED = "PROVIDER_RESPONSE_NOT_REQUESTED",
+    /** Response-unit dispatch is switched off platform-wide. */
+    DISPATCH_DISABLED = "DISPATCH_DISABLED"
+}

package/dist/types/modules/dispatch/enums/response-capability-requirement-source.enum.d.ts

@@ -0,0 +1,7 @@
+/** Where an incident's capability requirement came from. */
+export declare enum ResponseCapabilityRequirementSource {
+    INCIDENT_TYPE = "INCIDENT_TYPE",
+    INCIDENT_CATEGORY = "INCIDENT_CATEGORY",
+    /** Neither the type nor the category names one. */
+    NONE = "NONE"
+}

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

@@ -0,0 +1,19 @@
+/**
+ * How a unit's capabilities compare with what the incident needs.
+ *
+ * UNKNOWN and NOT_SUITED are deliberately different answers: UNKNOWN means
+ * nobody said what the unit does (it ranks below a match but stays
+ * recommendable), NOT_SUITED means somebody did and it is not this. Treating
+ * missing configuration as "not suitable" would hide every unit of an
+ * organization that has not configured capabilities yet.
+ */
+export declare enum ResponseUnitCapabilityMatch {
+    /** The incident needs a capability and the unit has one of them. */
+    MATCH = "MATCH",
+    /** The incident's type and category name no requirement - any unit fits. */
+    NOT_REQUIRED = "NOT_REQUIRED",
+    /** The incident needs a capability; the unit's capabilities are unknown. */
+    UNKNOWN = "UNKNOWN",
+    /** The unit's known capabilities do not include what the incident needs. */
+    NOT_SUITED = "NOT_SUITED"
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Why a unit cannot be dispatched (a BLOCKER) or, while it can be dispatched by
+ * hand, is not recommended (a CAUTION). One vocabulary for both so the admin
+ * explains either with the same words.
+ */
+export declare enum ResponseUnitDispatchConstraint {
+    /** Switched off in the organization. */
+    INACTIVE = "INACTIVE",
+    /** Non-operational, off duty, on leave or in training. */
+    OPERATIONALLY_UNAVAILABLE = "OPERATIONALLY_UNAVAILABLE",
+    /** Out on another job (an active dispatch, or a manual Engaged / On Mission status). */
+    ENGAGED = "ENGAGED",
+    /** Already has an active dispatch to THIS incident. */
+    ALREADY_DISPATCHED = "ALREADY_DISPATCHED",
+    /** Belongs to another control centre and cross-control-centre dispatch is off. */
+    OTHER_CONTROL_CENTRE = "OTHER_CONTROL_CENTRE",
+    /** Not suited, and the platform is configured to require a capability match. */
+    CAPABILITY_REQUIRED = "CAPABILITY_REQUIRED",
+    /** Its known capabilities do not include what the incident needs. */
+    NOT_SUITED = "NOT_SUITED",
+    /** No position at all, or the tracking service has it offline. */
+    NO_LOCATION = "NO_LOCATION",
+    /** A stale live fix, and stale positions are configured not to be recommended. */
+    LOCATION_STALE = "LOCATION_STALE",
+    /** Live-tracked, but outside the search radius. */
+    OUTSIDE_SEARCH_AREA = "OUTSIDE_SEARCH_AREA"
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Machine-readable codes on a refused recommend/dispatch request (the `code` of
+ * the error body), so a client can react without parsing a sentence. A 409 says
+ * "the world changed since you looked - refresh"; other 4xx say "this was never
+ * going to work".
+ */
+export declare enum ResponseUnitDispatchErrorCode {
+    INCIDENT_NOT_DISPATCHABLE = "INCIDENT_NOT_DISPATCHABLE",
+    RESPONSE_UNIT_NOT_FOUND = "RESPONSE_UNIT_NOT_FOUND",
+    RESPONSE_UNIT_NOT_DISPATCHABLE = "RESPONSE_UNIT_NOT_DISPATCHABLE",
+    /** Another dispatcher got there first - the unit is out on a job. */
+    RESPONSE_UNIT_ENGAGED = "RESPONSE_UNIT_ENGAGED",
+    RESPONSE_UNIT_ALREADY_DISPATCHED = "RESPONSE_UNIT_ALREADY_DISPATCHED",
+    /** The same Idempotency-Key was used for a different unit. */
+    IDEMPOTENCY_KEY_REUSED = "IDEMPOTENCY_KEY_REUSED",
+    DISPATCH_NOT_FOUND = "DISPATCH_NOT_FOUND",
+    INVALID_STATUS_TRANSITION = "INVALID_STATUS_TRANSITION",
+    NOTIFICATION_NOT_RESENDABLE = "NOTIFICATION_NOT_RESENDABLE",
+    /** clarion-organization could not be reached: nothing can be verified, so nothing is sent. */
+    ORGANIZATION_UNAVAILABLE = "ORGANIZATION_UNAVAILABLE"
+}

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

@@ -0,0 +1,13 @@
+/** Why a dispatch message was not sent. */
+export declare enum ResponseUnitDispatchNotificationFailure {
+    /** The unit has no phone number. */
+    NO_PHONE_NUMBER = "NO_PHONE_NUMBER",
+    /** The number on the unit is not one any provider can send to. */
+    INVALID_PHONE_NUMBER = "INVALID_PHONE_NUMBER",
+    /** Every provider in the country's chain failed. */
+    PROVIDER_FAILURE = "PROVIDER_FAILURE",
+    /** No SMS provider is configured for the number's country. */
+    NOT_CONFIGURED = "NOT_CONFIGURED",
+    /** clarion-notification never answered, so nobody knows. Sending again is the remedy. */
+    NO_RESPONSE = "NO_RESPONSE"
+}

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

@@ -0,0 +1,11 @@
+/** What happened to the message telling the unit it was dispatched. */
+export declare enum ResponseUnitDispatchNotificationStatus {
+    /** Requested from clarion-notification; no answer yet. */
+    PENDING = "PENDING",
+    /** A provider accepted it. (Handset delivery is not tracked by the platform.) */
+    SENT = "SENT",
+    /** Every provider refused or failed; it can be sent again. */
+    FAILED = "FAILED",
+    /** Could never be sent - the unit has no usable phone number. The dispatch stands. */
+    NOT_POSSIBLE = "NOT_POSSIBLE"
+}

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

@@ -0,0 +1,28 @@
+/**
+ * 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"
+}

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

@@ -0,0 +1,11 @@
+/** 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",
+    /** Reserved for clarion-workflow orchestration. */
+    WORKFLOW = "WORKFLOW"
+}

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,121 @@
+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;
+    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,103 @@
+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;
+}
+/**
+ * `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;
+}