grm-shared-library 1.1.237 → 1.1.239

package/dist/types/modules/incident-sla/interfaces/incident-sla-views.d.ts

@@ -0,0 +1,224 @@
+import { IncidentPriority } from '../../incident/enums/incident-priority.enum';
+import { EmergencyIncidentStage } from '../enums/emergency-incident-stage.enum';
+import { EtaBasis, EtaStatus } from '../enums/eta-status.enum';
+import { IncidentArrivalSource, IncidentClosureReason } from '../enums/incident-closure.enum';
+import { IncidentActorType, IncidentSlaEventSource } from '../enums/incident-sla-actor.enum';
+import { IncidentSlaEventType } from '../enums/incident-sla-event-type.enum';
+import { IncidentSlaStage } from '../enums/incident-sla-stage.enum';
+import { IncidentSlaStatus } from '../enums/incident-sla-status.enum';
+import { SlaEscalationTrigger } from '../enums/sla-escalation.enum';
+import { SlaExceptionReason, SlaExceptionStatus } from '../enums/sla-exception.enum';
+import { SlaOverallState, SlaPriorityLevel } from '../enums/sla-overall-state.enum';
+import { SlaPauseReason, SlaPauseStatus } from '../enums/sla-pause.enum';
+import { SlaPolicyScope } from '../enums/sla-policy-scope.enum';
+import { IncidentSlaContributingPolicy } from './incident-sla-policy';
+/** An approved, rejected or pending exception on one instance. */
+export interface IncidentSlaExceptionView {
+    status: SlaExceptionStatus;
+    reason: SlaExceptionReason | null;
+    note: string | null;
+    requestedBy: number | null;
+    requestedAt: string | null;
+    decidedBy: number | null;
+    decidedAt: string | null;
+    decisionNote: string | null;
+}
+/** One SLA instance as the admin shows it. Times are ISO-8601; durations in seconds. */
+export interface IncidentSlaInstanceView {
+    id: number;
+    stage: IncidentSlaStage;
+    /** 1 for incident-level stages; the dispatch's ordinal for per-dispatch stages. */
+    cycle: number;
+    responseUnitDispatchId: number | null;
+    responseUnitId: number | null;
+    responseUnitName: string | null;
+    priority: IncidentPriority;
+    status: IncidentSlaStatus;
+    targetSeconds: number | null;
+    startedAt: string | null;
+    /** Moves later by the length of each approved pause. */
+    deadlineAt: string | null;
+    /** The deadline before any pause. */
+    originalDeadlineAt: string | null;
+    warningAt: string | null;
+    atRiskAt: string | null;
+    warnedAt: string | null;
+    atRiskSince: string | null;
+    breachedAt: string | null;
+    completedAt: string | null;
+    endedAt: string | null;
+    endReason: string | null;
+    pausedAt: string | null;
+    totalPausedSeconds: number;
+    /** Time on the clock (pauses excluded): to completion, else to the server's now. */
+    elapsedSeconds: number | null;
+    /** Until the deadline at the server's now; negative = overdue. Null when not running. */
+    remainingSeconds: number | null;
+    /** How late it was (completed late) or is (still open past the deadline). */
+    overdueSeconds: number | null;
+    exception: IncidentSlaExceptionView | null;
+    waivedBy: number | null;
+    waivedAt: string | null;
+    waiveReason: string | null;
+    slaPolicyId: number | null;
+    slaPolicyVersion: number | null;
+}
+/** One milestone in the incident's response, for the SLA timeline. */
+export interface IncidentSlaTimelineItem {
+    milestone: EmergencyIncidentStage;
+    state: 'DONE' | 'CURRENT' | 'PENDING' | 'SKIPPED';
+    /** When it was reached. */
+    at: string | null;
+    /** Recorded because a later milestone proved it (dispatching proves acknowledgement). */
+    implied: boolean;
+    actorType: IncidentActorType | null;
+    source: IncidentSlaEventSource | null;
+    /** The SLA stage that measures reaching this milestone, if any. */
+    stage: IncidentSlaStage | null;
+    slaStatus: IncidentSlaStatus | null;
+    /** The deadline for reaching it. */
+    targetAt: string | null;
+    /** Predicted (arrival only). */
+    etaAt: string | null;
+    arrivalSource: IncidentArrivalSource | null;
+}
+/** The incident's historical compliance, apart from its current state. */
+export interface IncidentSlaStats {
+    total: number;
+    /** Instances with an outcome: MET or BREACHED. */
+    decided: number;
+    met: number;
+    breached: number;
+    breachedWithApprovedException: number;
+    open: number;
+    /** Instances that ever turned WARNING. */
+    warnings: number;
+    /** Instances that ever turned AT_RISK. */
+    atRisk: number;
+    /** met / decided, null with nothing decided. */
+    compliancePercent: number | null;
+    /** (met + breaches with an approved exception) / decided. */
+    complianceWithExceptionsPercent: number | null;
+}
+/** A dispatched unit's predicted arrival. */
+export interface IncidentEtaView {
+    dispatchId: number;
+    responseUnitId: number;
+    responseUnitName: string | null;
+    status: EtaStatus;
+    etaSeconds: number | null;
+    predictedArrivalAt: string | null;
+    distanceMetres: number | null;
+    basis: EtaBasis | null;
+    computedAt: string | null;
+    lastLocationAt: string | null;
+    locationAgeSeconds: number | null;
+    arrivalDeadlineAt: string | null;
+}
+export interface IncidentSlaPauseView {
+    id: number;
+    instanceId: number;
+    stage: IncidentSlaStage;
+    reason: SlaPauseReason;
+    note: string | null;
+    status: SlaPauseStatus;
+    requestedBy: number | null;
+    requestedAt: string;
+    decidedBy: number | null;
+    decidedAt: string | null;
+    decisionNote: string | null;
+    startedAt: string | null;
+    endedAt: string | null;
+    pausedSeconds: number;
+}
+/** The alternative unit the workflow last put in front of the dispatcher. */
+export interface IncidentSlaAlternativeView {
+    responseUnitId: number;
+    responseUnitName: string | null;
+    distanceMetres: number | null;
+    etaSeconds: number | null;
+    trigger: SlaEscalationTrigger;
+    /** The dispatch it would replace or back up. */
+    forDispatchId: number | null;
+    recommendedAt: string;
+}
+/** What the caller may do on the card, decided by the server from the caller's role. */
+export interface IncidentSlaAllowedActions {
+    acknowledge: boolean;
+    triage: boolean;
+    recordAssessment: boolean;
+    requestPause: boolean;
+    approvePause: boolean;
+    endPause: boolean;
+    requestException: boolean;
+    approveException: boolean;
+    waive: boolean;
+}
+export interface IncidentSlaClosureView {
+    resolvedAt: string | null;
+    closedAt: string | null;
+    closureReason: IncidentClosureReason | null;
+    closedBy: number | null;
+    autoCloseEnabled: boolean;
+    autoCloseAt: string | null;
+}
+export interface IncidentSlaPolicyReference {
+    id: number | null;
+    key: string | null;
+    version: number | null;
+    name: string;
+    scope: SlaPolicyScope;
+    contributingPolicies: IncidentSlaContributingPolicy[];
+}
+/** `GET /incidents/:id/sla` - everything the SLA card shows. */
+export interface IncidentSlaSummary {
+    incidentId: number;
+    tracked: boolean;
+    notTrackedReason: string | null;
+    serverTime: string;
+    priority: IncidentPriority | null;
+    priorityLevel: SlaPriorityLevel | null;
+    policy: IncidentSlaPolicyReference | null;
+    overall: SlaOverallState;
+    currentStage: EmergencyIncidentStage | null;
+    /** The open instance closest to (or furthest past) its deadline. */
+    currentInstance: IncidentSlaInstanceView | null;
+    instances: IncidentSlaInstanceView[];
+    timeline: IncidentSlaTimelineItem[];
+    stats: IncidentSlaStats;
+    etas: IncidentEtaView[];
+    primaryEta: IncidentEtaView | null;
+    pauses: IncidentSlaPauseView[];
+    alternative: IncidentSlaAlternativeView | null;
+    closure: IncidentSlaClosureView;
+    allowedActions: IncidentSlaAllowedActions;
+    workflowId: string | null;
+}
+/** One row of an incident's SLA history. */
+export interface IncidentSlaEventView {
+    id: number;
+    eventType: IncidentSlaEventType;
+    stage: IncidentSlaStage | null;
+    cycle: number | null;
+    instanceId: number | null;
+    milestone: EmergencyIncidentStage | null;
+    fromStatus: IncidentSlaStatus | null;
+    toStatus: IncidentSlaStatus | null;
+    actorUserId: number | null;
+    actorType: IncidentActorType;
+    source: IncidentSlaEventSource;
+    reason: string | null;
+    note: string | null;
+    metadata: Record<string, unknown> | null;
+    correlationId: string | null;
+    workflowId: string | null;
+    occurredAt: string;
+    recordedAt: string;
+}
+/** `GET /incidents/:id/sla/events` - newest first. */
+export interface IncidentSlaEventPage {
+    data: IncidentSlaEventView[];
+    total: number;
+    page: number;
+    limit: number;
+}

package/dist/types/modules/incident-sla/utils/incident-sla-eta.util.d.ts

@@ -0,0 +1,15 @@
+import { EtaStatus } from '../enums/eta-status.enum';
+/**
+ * An estimated ETA from straight-line distance: distance x road factor at an
+ * assumed speed. The unit's instantaneous GPS speed is deliberately NOT used -
+ * a vehicle stopped at a junction would predict "never", one on a highway
+ * "instantly"; the assumed urban speed is clarion-gis's own ESTIMATE profile.
+ */
+export declare function estimateEtaSeconds(distanceMetres: number, assumedSpeedKph: number, roadFactor: number): number;
+/**
+ * Whether a predicted arrival makes the deadline. Inside `marginPercent` of the
+ * target before the deadline is AT_RISK; after it, LIKELY_BREACH.
+ */
+export declare function classifyEta(predictedArrivalAt: Date, deadlineAt: Date | null, targetSeconds: number | null, marginPercent: number): EtaStatus;
+/** How bad an ETA status is, for "did it get worse?". */
+export declare const ETA_STATUS_SEVERITY: Readonly<Record<EtaStatus, number>>;

package/dist/types/modules/incident-sla/utils/incident-sla-event-id.util.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Deterministic ids for the emergency/SLA history and its events: the same
+ * change always produces the same id, so a retried activity, an outbox
+ * re-publish or a Kafka redelivery is recognised instead of recorded twice.
+ */
+export declare function buildIncidentSlaEventId(incidentId: number, kind: string, ...parts: (string | number | null | undefined)[]): string;
+/** The deterministic id of a milestone being reached (once per incident, or per dispatch). */
+export declare function buildEmergencyMilestoneEventId(incidentId: number, milestone: string, dispatchId?: number | null): string;

package/dist/types/modules/incident-sla/utils/incident-sla-priority.util.d.ts

@@ -0,0 +1,14 @@
+import { IncidentPriority } from '../../incident/enums/incident-priority.enum';
+import { SlaPriorityLevel } from '../enums/sla-overall-state.enum';
+import { IncidentSlaPriorityFloors } from '../interfaces/incident-sla-policy';
+export declare function isIncidentPriority(value: unknown): value is IncidentPriority;
+/** P1..P4 for an incident priority; null for anything unrecognised. */
+export declare function slaPriorityLevel(priority: string | null | undefined): SlaPriorityLevel | null;
+/** The more urgent of two priorities. */
+export declare function higherIncidentPriority(a: IncidentPriority, b: IncidentPriority): IncidentPriority;
+/**
+ * The priority an incident's SLA is measured at: its own priority, raised to
+ * the floor its emergency type sets (an SOS arrives as the column default,
+ * Medium, and must not get a Medium clock). An unknown priority counts as Medium.
+ */
+export declare function resolveSlaPriority(priority: string | null | undefined, emergencyType: string | null | undefined, floors: IncidentSlaPriorityFloors | null | undefined): IncidentPriority;

package/dist/types/modules/incident-sla/utils/incident-sla-time.util.d.ts

@@ -0,0 +1,65 @@
+import { IncidentSlaStatus } from '../enums/incident-sla-status.enum';
+import { SlaExceptionStatus } from '../enums/sla-exception.enum';
+import { SlaOverallState } from '../enums/sla-overall-state.enum';
+export declare function isOpenIncidentSlaStatus(status: string | null | undefined): boolean;
+export declare function isFinalIncidentSlaStatus(status: string | null | undefined): boolean;
+export interface SlaThresholdInstants {
+    warningAt: Date;
+    atRiskAt: Date;
+    deadlineAt: Date;
+}
+/**
+ * When an instance turns WARNING, AT_RISK and BREACHED: the start plus each
+ * percentage of the target, moved later by the time spent paused. Whole
+ * milliseconds, so the workflow and the database agree to the instant.
+ */
+export declare function computeSlaThresholdInstants(startedAt: Date, targetSeconds: number, warningPercent: number, atRiskPercent: number, pausedSeconds?: number): SlaThresholdInstants;
+/**
+ * The status an open instance should have at `now` from its instants alone -
+ * what a timer would have made it. Never goes backwards from `current`.
+ */
+export declare function slaThresholdStatusAt(instants: {
+    warningAt: Date | null;
+    atRiskAt: Date | null;
+    deadlineAt: Date | null;
+}, now: Date, current?: IncidentSlaStatus): IncidentSlaStatus;
+/** MET if the milestone was reached by the deadline, else BREACHED. Decided by timestamps only. */
+export declare function slaOutcome(completedAt: Date, deadlineAt: Date): IncidentSlaStatus.MET | IncidentSlaStatus.BREACHED;
+/** Whole seconds from a to b (negative when b is earlier). */
+export declare function secondsBetween(a: Date, b: Date): number;
+/** The fields compliance and the overall state are worked out from. */
+export interface SlaOutcomeLike {
+    status: IncidentSlaStatus | string;
+    exceptionStatus?: SlaExceptionStatus | string | null;
+    warnedAt?: Date | string | null;
+    atRiskSince?: Date | string | null;
+}
+export interface SlaComplianceFigures {
+    total: number;
+    decided: number;
+    met: number;
+    breached: number;
+    breachedWithApprovedException: number;
+    open: number;
+    warnings: number;
+    atRisk: number;
+    compliancePercent: number | null;
+    complianceWithExceptionsPercent: number | null;
+}
+/**
+ * Historical compliance: met / (met + breached). Cancelled, expired and waived
+ * instances had no outcome and do not count either way; an approved exception
+ * counts only in the second figure, never by erasing the breach.
+ */
+export declare function computeSlaCompliance(instances: readonly SlaOutcomeLike[]): SlaComplianceFigures;
+/**
+ * The incident's CURRENT SLA state in one word: the worst OPEN instance wins (a
+ * breach still open, at risk, warning, paused, on track). With nothing open, how
+ * the finished ones went (any unexcused breach, every breach excused, all met).
+ * A past breach while the current stage runs fine reads ON_TRACK here - the
+ * history is the compliance figures' job, kept apart on purpose.
+ */
+export declare function deriveSlaOverallState(instances: readonly (SlaOutcomeLike & {
+    completedAt?: Date | string | null;
+    endedAt?: Date | string | null;
+})[]): SlaOverallState;

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

@@ -209,6 +209,12 @@ export declare enum PermissionActions {
     READ_FOLLOW_ME = "read:follow-me",
     TRACK_FOLLOW_ME = "track:follow-me",
     MANAGE_SAVED_PLACE = "manage:saved-place",
+    READ_INCIDENT_SLA = "read:incident-sla",
+    UPDATE_INCIDENT_SLA = "update:incident-sla",
+    APPROVE_INCIDENT_SLA = "approve:incident-sla",
+    READ_INCIDENT_SLA_POLICY = "read:incident-sla-policy",
+    MANAGE_INCIDENT_SLA_POLICY = "manage:incident-sla-policy",
+    READ_INCIDENT_SLA_ANALYTICS = "read:incident-sla-analytics",
     /**
      * @deprecated Split into the connection / message / screened-message /
      * analytics actions above, which the gateway now requires instead. Still

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

@@ -15,5 +15,6 @@ export declare enum PermissionsModule {
     NOTIFICATION = "Notification",
     ALERT_INTAKE = "Alert Intake",
     SAFETY = "Safety",
-    PLACES = "Places"
+    PLACES = "Places",
+    INCIDENT_SLA = "Incident SLA"
 }

package/dist/types/modules/sms/enums/sms-template.enum.d.ts

@@ -11,6 +11,8 @@ export declare enum SmsTemplateType {
     FOLLOW_ME_GUARDIAN_REQUEST = "follow_me_guardian_request",
     FOLLOW_ME_GUARDIAN_ENDED = "follow_me_guardian_ended",
     RESPONSE_UNIT_DISPATCH = "response_unit_dispatch",
+    EMERGENCY_STAFF_ALERT = "emergency_staff_alert",
+    EMERGENCY_REPORTER_UPDATE = "emergency_reporter_update",
     APPOINTMENT_REMINDER = "appointment_reminder",
     GENERAL_NOTIFICATION = "general_notification"
 }

package/package.json

@@ -1,72 +1,72 @@
-{
-  "name": "grm-shared-library",
-  "version": "1.1.237",
-  "main": "dist/cjs/index.js",
-  "module": "dist/esm/index.js",
-  "types": "dist/types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/types/index.d.ts",
-      "import": "./dist/esm/index.js",
-      "require": "./dist/cjs/index.js"
-    },
-    "./dist/modules/*": {
-      "types": "./dist/types/modules/*.d.ts",
-      "import": "./dist/esm/modules/*.js",
-      "require": "./dist/cjs/modules/*.js"
-    }
-  },
-  "files": [
-    "dist/**/*"
-  ],
-  "scripts": {
-    "clean": "rimraf dist dist-test",
-    "build:cjs": "tsc -p tsconfig.cjs.json",
-    "build:esm": "tsc -p tsconfig.esm.json",
-    "build:types": "tsc -p tsconfig.types.json",
-    "build": "npm run clean && npm run build:types && npm run build:cjs && npm run build:esm",
-    "prepublishOnly": "npm run build",
-    "pretest": "rimraf dist-test",
-    "test": "tsc -p tsconfig.spec.json && node --test \"dist-test/**/*.spec.js\""
-  },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "description": "",
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "@types/express": "^5.0.3",
-    "@types/geojson": "^7946.0.14",
-    "@types/node": "^22.10.5",
-    "rimraf": "^5.0.5",
-    "typescript": "^5.7.3"
-  },
-  "dependencies": {
-    "@nestjs/common": "^11.0.0",
-    "@nestjs/core": "^11.0.0",
-    "@nestjs/mapped-types": "^2.0.6",
-    "@nestjs/microservices": "^11.0.0",
-    "@nestjs/swagger": "^11.2.0",
-    "@sentry/node": "^8.0.0",
-    "class-transformer": "^0.5.0",
-    "class-validator": "^0.14.0",
-    "express": "^5.1.0",
-    "geojson": "^0.5.0",
-    "grm-shared-library": "^1.1.101",
-    "libphonenumber-js": "^1.13.8",
-    "rxjs": "^7.8.2",
-    "swagger-ui-express": "^5.0.1",
-    "@nestjs/config": "^4.0.0"
-  },
-  "peerDependencies": {
-    "@nestjs/common": "^11.0.0",
-    "@nestjs/core": "^11.0.0",
-    "@nestjs/microservices": "^11.0.0",
-    "@sentry/node": "^8.0.0",
-    "class-transformer": "^0.5.0",
-    "class-validator": "^0.14.0",
-    "@nestjs/config": "^4.0.0"
-  }
-}
+{
+  "name": "grm-shared-library",
+  "version": "1.1.239",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./dist/modules/*": {
+      "types": "./dist/types/modules/*.d.ts",
+      "import": "./dist/esm/modules/*.js",
+      "require": "./dist/cjs/modules/*.js"
+    }
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "scripts": {
+    "clean": "rimraf dist dist-test",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "build": "npm run clean && npm run build:types && npm run build:cjs && npm run build:esm",
+    "prepublishOnly": "npm run build",
+    "pretest": "rimraf dist-test",
+    "test": "tsc -p tsconfig.spec.json && node --test \"dist-test/**/*.spec.js\""
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.3",
+    "@types/geojson": "^7946.0.14",
+    "@types/node": "^22.10.5",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.7.3"
+  },
+  "dependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/mapped-types": "^2.0.6",
+    "@nestjs/microservices": "^11.0.0",
+    "@nestjs/swagger": "^11.2.0",
+    "@sentry/node": "^8.0.0",
+    "class-transformer": "^0.5.0",
+    "class-validator": "^0.14.0",
+    "express": "^5.1.0",
+    "geojson": "^0.5.0",
+    "grm-shared-library": "^1.1.101",
+    "libphonenumber-js": "^1.13.8",
+    "rxjs": "^7.8.2",
+    "swagger-ui-express": "^5.0.1",
+    "@nestjs/config": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/microservices": "^11.0.0",
+    "@sentry/node": "^8.0.0",
+    "class-transformer": "^0.5.0",
+    "class-validator": "^0.14.0",
+    "@nestjs/config": "^4.0.0"
+  }
+}