grm-shared-library 1.1.197 → 1.1.199

package/dist/types/modules/partner/dtos/amend-partner-dispatch.dto.d.ts

@@ -0,0 +1,27 @@
+/** A corrected location for an emergency a partner is already working. */
+export declare class AmendPartnerDispatchLocationDto {
+    latitude: number;
+    longitude: number;
+    measuredAt?: string;
+}
+/**
+ * Correct the details of an emergency a partner already has.
+ *
+ * The case this exists for is the ordinary one: a caller rings back with a
+ * better address while a responder is already moving. Sending the correction
+ * beats hoping the crew works it out.
+ *
+ * Only the fields a partner will actually accept mid-flight are here - who the
+ * emergency is FOR never changes, so the reporter and their phone number are
+ * deliberately absent. Every field is optional; sending none is a no-op rather
+ * than an error.
+ *
+ * Only meaningful for a partner whose descriptor sets `supportsAmendment`. For
+ * anyone else clarion-partner-services refuses plainly rather than pretending.
+ */
+export declare class AmendPartnerDispatchDto {
+    address?: string;
+    issue?: string;
+    location?: AmendPartnerDispatchLocationDto;
+    reason?: string;
+}

package/dist/types/modules/partner/dtos/update-incident-partner-routing.dto.d.ts

@@ -1,8 +1,21 @@
 import { IncidentPartnerRoutingStatus } from '../enums/incident-partner-routing-status.enum';
+import { PartnerEngagementState } from '../enums/partner-engagement-state.enum';
 import { PartnerDispatchStatus } from '../enums/partner-dispatch-status.enum';
 import { PartnerProviderCode } from '../enums/partner-provider-code.enum';
 import { PartnerRoutingMode } from '../enums/partner-routing-mode.enum';
 import { PartnerServiceCapability } from '../enums/partner-service-capability.enum';
+/** Whoever the partner has put on the job, as carried on the incident. */
+export declare class IncidentPartnerResponderDto {
+    name?: string;
+    phoneNumber?: string;
+    reference?: string;
+}
+/** The unit the partner has assigned, as carried on the incident. */
+export declare class IncidentPartnerVehicleDto {
+    identifier?: string;
+    description?: string;
+    serviceType?: string;
+}
 /** One partner's leg of an incident's routing, as pushed back to clarion-incident. */
 export declare class IncidentPartnerRoutingEntryDto {
     integrationId: number;
@@ -14,6 +27,9 @@ export declare class IncidentPartnerRoutingEntryDto {
     dispatchReference: string;
     status: PartnerDispatchStatus;
     partnerReference?: string;
+    engagementState?: PartnerEngagementState;
+    responder?: IncidentPartnerResponderDto;
+    vehicle?: IncidentPartnerVehicleDto;
     updatedAt: string;
 }
 /**

package/dist/types/modules/partner/enums/partner-adapter-operation.enum.d.ts

@@ -9,5 +9,18 @@ export declare enum PartnerAdapterOperation {
     /** A non-mutating connectivity probe. */
     HEALTH_CHECK = "HEALTH_CHECK",
     /** Submitting the emergency itself. */
-    DISPATCH = "DISPATCH"
+    DISPATCH = "DISPATCH",
+    /** Asking the partner what has happened since. */
+    FETCH_STATUS = "FETCH_STATUS",
+    /** Standing the partner down after they had already accepted it. */
+    WITHDRAW = "WITHDRAW",
+    /** Correcting details of an emergency the partner is already working. */
+    AMEND = "AMEND",
+    /**
+     * Asking the partner whether a request we may have already sent exists.
+     *
+     * Used after a timeout, where the request might have landed but the reply
+     * never arrived - the one case where re-sending could produce a duplicate.
+     */
+    LOOKUP = "LOOKUP"
 }

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

@@ -1,15 +1,18 @@
 /**
  * Lifecycle of one incident's routing to one partner.
  *
- * Terminal states are SENT/ACKNOWLEDGED (the partner has the emergency),
- * FAILED, REJECTED, CANCELLED and EXPIRED. Everything else is in flight.
- *
  * MANUAL routing starts at PENDING_APPROVAL and reaches QUEUED only when an
  * operator approves; declining gives REJECTED, withdrawing gives CANCELLED and
  * letting the approval window elapse gives EXPIRED. AUTO routing starts at
  * QUEUED directly. QUEUED -> SENDING -> SENT on success, or back to QUEUED for a
  * transient retry, or FAILED when the failure is permanent or the attempts run
- * out. SENT -> ACKNOWLEDGED when the partner later reports progress.
+ * out.
+ *
+ * Once the partner has it, the remaining transitions come from THEM rather than
+ * from us: SENT -> ACKNOWLEDGED when they assign a responder, and either of
+ * those -> COMPLETED when they close it. WITHDRAWN is the one exception - an
+ * organization standing a partner down after the fact, which is only possible
+ * with a partner whose API supports it.
  */
 export declare enum PartnerDispatchStatus {
     /** MANUAL routing: waiting for the organization to confirm or decline. */
@@ -20,18 +23,40 @@ export declare enum PartnerDispatchStatus {
     SENDING = "SENDING",
     /** The partner accepted the request and returned its own reference. */
     SENT = "SENT",
-    /** The partner has since confirmed progress on the request (status callback). */
+    /** The partner has assigned a responder, or otherwise confirmed it is working it. */
     ACKNOWLEDGED = "ACKNOWLEDGED",
+    /** The partner has closed the request. The engagement is over. */
+    COMPLETED = "COMPLETED",
     /** Permanently failed - rejected by the partner, or out of attempts. */
     FAILED = "FAILED",
     /** Declined by the organization instead of being sent. */
     REJECTED = "REJECTED",
-    /** Withdrawn by the organization (before or after approval, never after SENT). */
+    /** Withdrawn by the organization BEFORE the partner ever received it. */
     CANCELLED = "CANCELLED",
+    /**
+     * Stood down by the organization AFTER the partner received it.
+     *
+     * Kept apart from CANCELLED because they are very different facts: one is an
+     * emergency a partner never heard about, the other is a responder who was
+     * dispatched and recalled. Only the second one costs a partner anything, and
+     * only the second one needs explaining in a monthly report.
+     */
+    WITHDRAWN = "WITHDRAWN",
     /** The manual-approval window elapsed with no decision. */
     EXPIRED = "EXPIRED"
 }
-/** Statuses from which no further transition happens. */
+/**
+ * Statuses from which no further transition happens.
+ *
+ * SENT and ACKNOWLEDGED are deliberately NOT terminal: with a partner that
+ * publishes request status, both still move - to COMPLETED when the partner
+ * closes the request, or to WITHDRAWN if the organization stands them down.
+ */
 export declare const TERMINAL_PARTNER_DISPATCH_STATUSES: readonly PartnerDispatchStatus[];
-/** Statuses that mean the partner is (or should shortly be) working the emergency. */
+/** Statuses that mean the partner received the emergency and acted on it. */
 export declare const DELIVERED_PARTNER_DISPATCH_STATUSES: readonly PartnerDispatchStatus[];
+/**
+ * Statuses where the partner holds the emergency and it is not finished, so
+ * asking them for progress is worthwhile.
+ */
+export declare const POLLABLE_PARTNER_DISPATCH_STATUSES: readonly PartnerDispatchStatus[];

package/dist/types/modules/partner/enums/partner-engagement-state.enum.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What a partner says is happening with an emergency we handed them, reduced to
+ * the only three answers every partner can give.
+ *
+ * Provider-neutral on purpose. Partners describe progress in their own
+ * vocabulary - Rescue.co says CURRENT and CLOSED, another will say OPEN and
+ * RESOLVED, a third will have six intermediate states - and the platform must
+ * not learn any of them. The adapter maps its partner's word onto one of these,
+ * and keeps the original in `partnerStatus` so an operator still sees exactly
+ * what the partner said.
+ */
+export declare enum PartnerEngagementState {
+    /** The partner is working the emergency. */
+    ACTIVE = "ACTIVE",
+    /** The partner has closed it. Nothing further will happen on their side. */
+    CLOSED = "CLOSED",
+    /** The partner reported something this adapter does not recognise. */
+    UNKNOWN = "UNKNOWN"
+}

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

@@ -5,6 +5,7 @@ export * from './enums/partner-integration-environment.enum';
 export * from './enums/partner-integration-status.enum';
 export * from './enums/partner-coverage-match-type.enum';
 export * from './enums/partner-dispatch-status.enum';
+export * from './enums/partner-engagement-state.enum';
 export * from './enums/partner-dispatch-failure-reason.enum';
 export * from './enums/partner-location-provider.enum';
 export * from './enums/partner-adapter-operation.enum';
@@ -14,6 +15,7 @@ export * from './interfaces/partner-provider-descriptor';
 export * from './interfaces/partner-integration';
 export * from './interfaces/partner-coverage-rule';
 export * from './interfaces/partner-dispatch-location';
+export * from './interfaces/partner-dispatch-progress';
 export * from './interfaces/partner-emergency-contact';
 export * from './interfaces/partner-dispatch';
 export * from './interfaces/incident-partner-routing';
@@ -28,6 +30,7 @@ export * from './dtos/create-partner-coverage-rule.dto';
 export * from './dtos/update-partner-coverage-rule.dto';
 export * from './dtos/route-incident-to-partners.dto';
 export * from './dtos/partner-dispatch-decision.dto';
+export * from './dtos/amend-partner-dispatch.dto';
 export * from './dtos/update-incident-partner-routing.dto';
 export * from './utils/partner-routing.util';
 export * from './utils/partner-payload.util';

package/dist/types/modules/partner/interfaces/incident-partner-routing.d.ts

@@ -1,8 +1,10 @@
 import { IncidentPartnerRoutingStatus } from '../enums/incident-partner-routing-status.enum';
+import { PartnerEngagementState } from '../enums/partner-engagement-state.enum';
 import { PartnerDispatchStatus } from '../enums/partner-dispatch-status.enum';
 import { PartnerProviderCode } from '../enums/partner-provider-code.enum';
 import { PartnerRoutingMode } from '../enums/partner-routing-mode.enum';
 import { PartnerServiceCapability } from '../enums/partner-service-capability.enum';
+import { PartnerResponderInfo, PartnerResponderVehicle } from './partner-dispatch-progress';
 /** One partner's leg of an incident's routing, as recorded on the incident. */
 export interface IncidentPartnerRoutingEntry {
     integrationId: number;
@@ -16,6 +18,17 @@ export interface IncidentPartnerRoutingEntry {
     status: PartnerDispatchStatus;
     /** The partner's own reference once it has accepted the request. */
     partnerReference?: string | null;
+    /**
+     * What the partner last reported, carried on the incident itself.
+     *
+     * Denormalized deliberately: "an ambulance is on its way, registration
+     * KAA 123B, crew reachable on +254..." is the single most useful sentence
+     * on an incident screen, and it should not cost a second request to another
+     * service to render it.
+     */
+    engagementState?: PartnerEngagementState | null;
+    responder?: PartnerResponderInfo | null;
+    vehicle?: PartnerResponderVehicle | null;
     updatedAt: string;
 }
 /**

package/dist/types/modules/partner/interfaces/partner-dispatch-progress.d.ts

@@ -0,0 +1,48 @@
+import { PartnerEngagementState } from '../enums/partner-engagement-state.enum';
+/** Whoever the partner has put on the job. */
+export interface PartnerResponderInfo {
+    name?: string | null;
+    /** E.164 where the partner gives one. */
+    phoneNumber?: string | null;
+    /** The partner's own identifier for the responder. */
+    reference?: string | null;
+}
+/** The unit the partner has assigned, described the way a control room needs it. */
+export interface PartnerResponderVehicle {
+    /** Registration, call sign, or whatever the partner uses to identify the unit. */
+    identifier?: string | null;
+    /** Human description, e.g. "White Toyota HiAce". */
+    description?: string | null;
+    /** The partner's own classification of the unit, e.g. "ADVANCED_LIFE_SUPPORT". */
+    serviceType?: string | null;
+}
+/**
+ * What a partner reports about an emergency they are already working.
+ *
+ * This is the answer to the question a control room actually asks after
+ * dispatching: "is anyone coming, who, and where are they taking them?" Every
+ * field is optional because partners differ enormously in what they publish -
+ * some return a full crew and vehicle, some return nothing but a status - and
+ * the platform must be useful with either.
+ *
+ * Provider-neutral: `partnerStatus` keeps the partner's own word verbatim so an
+ * operator sees exactly what was said, while `state` reduces it to something
+ * every screen and every report can rely on.
+ */
+export interface PartnerDispatchProgress {
+    state: PartnerEngagementState;
+    /** The partner's own status string, unmodified. */
+    partnerStatus?: string | null;
+    /** The partner's human-facing reference, if it appears or changes here. */
+    partnerNumber?: string | null;
+    responder?: PartnerResponderInfo | null;
+    vehicle?: PartnerResponderVehicle | null;
+    /** Where the responder is taking the patient, when the partner says. */
+    destination?: string | null;
+    /** The partner's own label for the journey, e.g. "PENDING", "EN_ROUTE". */
+    journeyStatus?: string | null;
+    /** When the partner last changed anything, as the partner reports it. */
+    partnerUpdatedAt?: string | null;
+    /** When this platform last read it. */
+    observedAt: string;
+}

package/dist/types/modules/partner/interfaces/partner-dispatch.d.ts

@@ -5,7 +5,9 @@ import { PartnerDispatchStatus } from '../enums/partner-dispatch-status.enum';
 import { PartnerProviderCode } from '../enums/partner-provider-code.enum';
 import { PartnerRoutingMode } from '../enums/partner-routing-mode.enum';
 import { PartnerServiceCapability } from '../enums/partner-service-capability.enum';
+import { PartnerEngagementState } from '../enums/partner-engagement-state.enum';
 import { PartnerDispatchLocation } from './partner-dispatch-location';
+import { PartnerDispatchProgress } from './partner-dispatch-progress';
 import { PartnerEmergencyContact } from './partner-emergency-contact';
 /**
  * The incident facts a dispatch was built from, frozen at routing time.
@@ -100,6 +102,26 @@ export interface PartnerDispatch {
     partnerNumber?: string | null;
     /** The partner's own status string, passed through verbatim. */
     partnerStatus?: string | null;
+    /**
+     * The partner's status reduced to something every screen can rely on.
+     * Absent for a partner that publishes no status at all.
+     */
+    engagementState?: PartnerEngagementState | null;
+    /**
+     * What the partner last reported - responder, vehicle, destination.
+     *
+     * This is the answer to "is anyone actually coming?", which is the only
+     * question a control room has once a dispatch has left the building.
+     */
+    progress?: PartnerDispatchProgress | null;
+    /** When progress was last read from the partner. */
+    lastPolledAt?: string | null;
+    /** When the partner first confirmed it was working the emergency. */
+    acknowledgedAt?: string | null;
+    /** When the partner closed the request. */
+    closedAt?: string | null;
+    withdrawnByUserId?: number | null;
+    withdrawnAt?: string | null;
     /** The sanitized body sent to the partner. Never contains a credential. */
     requestPayload?: Record<string, unknown> | null;
     /** The sanitized body the partner returned. */

package/dist/types/modules/partner/interfaces/partner-provider-descriptor.d.ts

@@ -51,6 +51,35 @@ export interface PartnerProviderDescriptor {
     credentialFields: PartnerProviderCredentialField[];
     /** True when the adapter implements a non-mutating connectivity probe. */
     supportsHealthCheck: boolean;
+    /**
+     * True when the partner publishes the state of a request we have already
+     * sent, so progress can be polled and shown to a control room.
+     */
+    supportsStatusPolling: boolean;
+    /**
+     * True when the partner lets a request be stood down after they accepted it.
+     *
+     * When false, an organization that changes its mind has to telephone the
+     * partner - and the platform says so plainly rather than offering a button
+     * that quietly does nothing.
+     */
+    supportsWithdrawal: boolean;
+    /**
+     * True when the partner lets the details of a live request be corrected.
+     *
+     * The case that matters is a caller ringing back with a better location
+     * after a responder is already moving.
+     */
+    supportsAmendment: boolean;
+    /**
+     * True when the partner can be asked whether a request we may already have
+     * sent exists.
+     *
+     * This is what makes a retry after a TIMEOUT safe. Without it, a request
+     * that landed but whose reply was lost can only be retried blind, and a
+     * blind retry on a non-idempotent emergency API means two ambulances.
+     */
+    supportsDuplicateDetection: boolean;
     /** False for reserved provider codes that have no working adapter yet. */
     available: boolean;
 }

package/dist/types/modules/permission/enums/permission-actions.enum.d.ts

@@ -9,6 +9,7 @@ export declare enum PermissionActions {
     DELETE_PARTNER = "delete:partner",
     READ_PARTNER_DISPATCH = "read:partner-dispatch",
     APPROVE_PARTNER_DISPATCH = "approve:partner-dispatch",
+    UPDATE_PARTNER_DISPATCH = "update:partner-dispatch",
     CANCEL_PARTNER_DISPATCH = "cancel:partner-dispatch",
     RESEND_PARTNER_DISPATCH = "resend:partner-dispatch",
     CREATE_CONTROL_CENTRE = "create:control-centre",

package/package.json

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