grm-shared-library 1.1.187 → 1.1.189

package/dist/types/modules/tracking/enums/tracking-unit-online-status.enum.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Freshness of a response unit's last known position, derived by the projector's
+ * scheduled status evaluator from the gap between "now" and the last event time,
+ * using per-connection stale/offline thresholds.
+ */
+export declare enum TrackingUnitOnlineStatus {
+    /** Reporting within the configured stale threshold. */
+    ONLINE = "ONLINE",
+    /** No update within the stale threshold but within the offline threshold. */
+    STALE = "STALE",
+    /** No update within the offline threshold. */
+    OFFLINE = "OFFLINE"
+}

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

@@ -0,0 +1,17 @@
+export * from './enums/tracking-provider-code.enum';
+export * from './enums/tracking-transport-type.enum';
+export * from './enums/tracking-connection-status.enum';
+export * from './enums/tracking-unit-online-status.enum';
+export * from './enums/tracking-event-quality.enum';
+export * from './interfaces/tracking-position-quality-flags';
+export * from './interfaces/response-unit-position-event-v1';
+export * from './interfaces/response-unit-status-event-v1';
+export * from './interfaces/tracking-provider-health-event-v1';
+export * from './interfaces/tracking-device-unmapped-event-v1';
+export * from './interfaces/tracking-ingestion-error-event-v1';
+export * from './interfaces/tracking-unit-current-state';
+export * from './interfaces/tracking-socket-payloads';
+export * from './interfaces/tracking-realtime-envelope';
+export * from './constants/tracking-kafka.const';
+export * from './utils/tracking-event-id.util';
+export * from './utils/tracking-validation.util';

package/dist/types/modules/tracking/interfaces/response-unit-position-event-v1.d.ts

@@ -0,0 +1,62 @@
+import { TrackingProviderCode } from '../enums/tracking-provider-code.enum';
+/**
+ * Canonical, provider-neutral position event (schema v1).
+ *
+ * Produced by clarion-response-tracking after a raw provider location has been
+ * parsed, validated, normalized and bound to a Clarion response unit. Published
+ * on the `tracking.response-unit.position.v1` Kafka topic and consumed by the
+ * projector (history + current state) and any future tracking consumers.
+ *
+ * SECURITY: this contract is deliberately free of provider credentials, secret
+ * references, raw provider payloads and internal Kafka metadata. `organizationId`
+ * and `controlCentreId` are always sourced from trusted Clarion data (the device
+ * binding + response-unit projection), never from provider-supplied fields.
+ */
+export interface ResponseUnitPositionEventV1 {
+    schemaVersion: 1;
+    /** Deterministic id (see buildTrackingEventId) — same fix ⇒ same id. */
+    eventId: string;
+    providerCode: TrackingProviderCode;
+    providerConnectionId: string;
+    organizationId: number;
+    controlCentreId: number;
+    responseUnitId: number;
+    externalUnitId: string;
+    externalDeviceId?: string;
+    imei?: string;
+    /** When the provider recorded the fix (ISO 8601, UTC). */
+    eventTime: string;
+    /** When Clarion received the message (ISO 8601, UTC). */
+    receivedAt: string;
+    position: {
+        latitude: number;
+        longitude: number;
+        altitudeMetres?: number;
+        accuracyMetres?: number;
+    };
+    motion: {
+        /** Normalized to kilometres per hour. */
+        speedKph?: number;
+        /** Degrees clockwise from true north, [0, 360). Omitted when unknown. */
+        courseDegrees?: number;
+        moving?: boolean;
+        ignitionOn?: boolean;
+    };
+    telemetry?: {
+        satellites?: number;
+        odometerKm?: number;
+        batteryPercentage?: number;
+        externalPowerVoltage?: number;
+        gsmSignalPercentage?: number;
+    };
+    providerStatus?: string;
+    quality: {
+        duplicate: boolean;
+        outOfOrder: boolean;
+        coordinatesValid: boolean;
+    };
+    /** Safe, non-sensitive raw values preserved for future re-normalization. */
+    providerMetadata?: Record<string, unknown>;
+    /** Correlation id for tracing across services. */
+    correlationId?: string;
+}

package/dist/types/modules/tracking/interfaces/response-unit-status-event-v1.d.ts

@@ -0,0 +1,23 @@
+import { TrackingProviderCode } from '../enums/tracking-provider-code.enum';
+import { TrackingUnitOnlineStatus } from '../enums/tracking-unit-online-status.enum';
+/**
+ * Canonical online-status change event (schema v1). Emitted by the projector's
+ * status evaluator only when a unit's ONLINE/STALE/OFFLINE status actually
+ * changes, on `tracking.response-unit.status.v1`.
+ */
+export interface ResponseUnitStatusEventV1 {
+    schemaVersion: 1;
+    eventId: string;
+    organizationId: number;
+    controlCentreId: number;
+    responseUnitId: number;
+    providerCode: TrackingProviderCode;
+    providerConnectionId: string;
+    previousStatus?: TrackingUnitOnlineStatus;
+    status: TrackingUnitOnlineStatus;
+    /** ISO 8601, UTC — the eventTime of the last position seen for this unit. */
+    lastEventTime?: string;
+    /** ISO 8601, UTC — when the evaluator computed this status. */
+    evaluatedAt: string;
+    correlationId?: string;
+}

package/dist/types/modules/tracking/interfaces/tracking-device-unmapped-event-v1.d.ts

@@ -0,0 +1,25 @@
+import { TrackingProviderCode } from '../enums/tracking-provider-code.enum';
+/**
+ * Emitted on `tracking.device.unmapped.v1` when telemetry arrives for an external
+ * unit that has no active device binding. Drives the administrative unmapped-unit
+ * projection. Never broadcast to ordinary tracking rooms.
+ *
+ * SECURITY: `payloadSummary` carries only safe, non-sensitive fields (e.g.
+ * coordinates, timestamp, nickname) — never credentials or the raw provider frame.
+ */
+export interface TrackingDeviceUnmappedEventV1 {
+    schemaVersion: 1;
+    eventId: string;
+    providerCode: TrackingProviderCode;
+    providerConnectionId: string;
+    organizationId: number;
+    controlCentreId?: number;
+    externalUnitId: string;
+    externalNickname?: string;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    occurrenceCount: number;
+    payloadSummary?: Record<string, unknown>;
+    evaluatedAt: string;
+    correlationId?: string;
+}

package/dist/types/modules/tracking/interfaces/tracking-ingestion-error-event-v1.d.ts

@@ -0,0 +1,27 @@
+import { TrackingProviderCode } from '../enums/tracking-provider-code.enum';
+/**
+ * Stage at which ingestion of a provider message/location failed.
+ */
+export type TrackingIngestionStage = 'parse' | 'validate' | 'normalize' | 'resolve-binding' | 'persist-history' | 'update-current-state' | 'publish';
+/**
+ * Emitted on `tracking.ingestion.error.v1` for observability when a message or
+ * a single location fails to ingest. One bad location must never terminate the
+ * connection nor block the other locations in the same frame.
+ *
+ * SECURITY: errorMessage must be sanitized before emission — no credentials,
+ * no raw provider frame, no tokens.
+ */
+export interface TrackingIngestionErrorEventV1 {
+    schemaVersion: 1;
+    eventId: string;
+    providerCode: TrackingProviderCode;
+    providerConnectionId: string;
+    organizationId?: number;
+    controlCentreId?: number;
+    externalUnitId?: string;
+    stage: TrackingIngestionStage;
+    errorCode: string;
+    errorMessage: string;
+    occurredAt: string;
+    correlationId?: string;
+}

package/dist/types/modules/tracking/interfaces/tracking-position-quality-flags.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Fine-grained quality booleans attached to an ingested position. Kept
+ * provider-neutral; producers set what they can determine and leave the rest
+ * undefined. `duplicate`, `outOfOrder` and `coordinatesValid` are always set
+ * because the ingestion pipeline always evaluates them.
+ */
+export interface TrackingPositionQualityFlags {
+    /** The same deterministic eventId was already ingested. */
+    duplicate: boolean;
+    /** eventTime is older than the current-state eventTime for this unit. */
+    outOfOrder: boolean;
+    /** Latitude/longitude are within valid WGS84 ranges. */
+    coordinatesValid: boolean;
+    /** eventTime parsed and fell within the accepted tolerance window. */
+    timestampValid?: boolean;
+    /** courseDegrees was present and within [0, 360). */
+    courseValid?: boolean;
+    /** speed parsed to a finite, non-negative value. */
+    speedValid?: boolean;
+    /** Distance/time since the previous fix implies an implausible jump. */
+    positionJumpSuspected?: boolean;
+}

package/dist/types/modules/tracking/interfaces/tracking-provider-health-event-v1.d.ts

@@ -0,0 +1,27 @@
+import { TrackingConnectionStatus } from '../enums/tracking-connection-status.enum';
+import { TrackingProviderCode } from '../enums/tracking-provider-code.enum';
+/**
+ * Provider-connection health event (schema v1), emitted on
+ * `tracking.provider.health.v1` when a connection's status meaningfully changes
+ * (never on every heartbeat). Delivered to administrators only — never broadcast
+ * to ordinary tracking rooms.
+ *
+ * SECURITY: errorMessage is sanitized upstream; it must never contain the
+ * password, the full authentication request, secret references or tokens.
+ */
+export interface TrackingProviderHealthEventV1 {
+    schemaVersion: 1;
+    eventId: string;
+    providerConnectionId: string;
+    providerCode: TrackingProviderCode;
+    organizationId: number;
+    controlCentreId?: number;
+    connectionStatus: TrackingConnectionStatus;
+    connectedAt?: string;
+    disconnectedAt?: string;
+    lastEventAt?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    evaluatedAt: string;
+    correlationId?: string;
+}

package/dist/types/modules/tracking/interfaces/tracking-realtime-envelope.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The message clarion-response-tracking publishes to the Redis `realtime:tracking`
+ * channel for clarion-socket to fan out. Mirrors the flat newsfeed realtime
+ * envelope convention (deliberately simpler than the incident EventEnvelope).
+ *
+ * clarion-socket dedups on `eventId`, derives authorized rooms from
+ * `organizationId`/`controlCentreId`, and emits `payload` under the matching
+ * `SocketEventName` (position/status/removed/provider-health).
+ *
+ * SECURITY: `payload` is always one of the frontend-safe Tracking*SocketPayloadV1
+ * shapes — never a raw provider frame or anything carrying credentials.
+ */
+export type TrackingRealtimeEventType = 'position' | 'status' | 'removed' | 'provider-health';
+export interface TrackingRealtimeEnvelope<TPayload = unknown> {
+    /** Deterministic where possible; used by clarion-socket for dedup. */
+    eventId: string;
+    eventType: TrackingRealtimeEventType;
+    organizationId: number;
+    /** Absent for org-wide-only events; present to also target a CC room. */
+    controlCentreId?: number;
+    responseUnitId?: number;
+    /** ISO 8601, UTC. */
+    occurredAt: string;
+    /**
+     * True for provider-health events, which must only reach administrators —
+     * clarion-socket routes these to admin/role rooms, not org/cc tracking rooms.
+     */
+    adminOnly?: boolean;
+    payload: TPayload;
+    correlationId?: string;
+    sourceService: string;
+}

package/dist/types/modules/tracking/interfaces/tracking-socket-payloads.d.ts

@@ -0,0 +1,53 @@
+import { TrackingConnectionStatus } from '../enums/tracking-connection-status.enum';
+import { TrackingProviderCode } from '../enums/tracking-provider-code.enum';
+import { TrackingUnitOnlineStatus } from '../enums/tracking-unit-online-status.enum';
+/**
+ * Frontend-safe payloads emitted to Socket.IO clients by clarion-socket.
+ *
+ * These are intentionally a minimal projection — no secretReference, no
+ * credentials, no raw provider frame, no internal Kafka metadata. clarion-socket
+ * emits exactly these shapes; the frontend mirror lives in clarion-shared-types.
+ */
+export interface TrackingPositionSocketPayloadV1 {
+    responseUnitId: number;
+    organizationId: number;
+    controlCentreId: number;
+    eventTime: string;
+    receivedAt: string;
+    latitude: number;
+    longitude: number;
+    accuracyMetres?: number;
+    speedKph?: number;
+    /** Degrees clockwise from true north, [0, 360). Omitted when unknown. */
+    courseDegrees?: number;
+    moving?: boolean;
+    ignitionOn?: boolean;
+    status: TrackingUnitOnlineStatus;
+}
+export interface TrackingStatusSocketPayloadV1 {
+    responseUnitId: number;
+    organizationId: number;
+    controlCentreId: number;
+    status: TrackingUnitOnlineStatus;
+    previousStatus?: TrackingUnitOnlineStatus;
+    lastEventTime?: string;
+    evaluatedAt: string;
+}
+export interface TrackingRemovedSocketPayloadV1 {
+    responseUnitId: number;
+    organizationId: number;
+    controlCentreId: number;
+    /** Why the unit was removed (binding disabled/deleted, unit deleted, …). */
+    reason?: string;
+    evaluatedAt: string;
+}
+export interface TrackingProviderHealthSocketPayloadV1 {
+    providerConnectionId: string;
+    providerCode: TrackingProviderCode;
+    organizationId: number;
+    controlCentreId?: number;
+    connectionStatus: TrackingConnectionStatus;
+    lastEventAt?: string;
+    errorCode?: string;
+    evaluatedAt: string;
+}

package/dist/types/modules/tracking/interfaces/tracking-unit-current-state.d.ts

@@ -0,0 +1,27 @@
+import { TrackingProviderCode } from '../enums/tracking-provider-code.enum';
+import { TrackingUnitOnlineStatus } from '../enums/tracking-unit-online-status.enum';
+/**
+ * Shape of the current-position projection held in Redis
+ * (`tracking:unit-state:{responseUnitId}`) and returned by the current-position
+ * REST endpoints. Frontend-safe: no credentials, no provider raw frame.
+ */
+export interface TrackingUnitCurrentState {
+    organizationId: number;
+    controlCentreId: number;
+    responseUnitId: number;
+    providerCode: TrackingProviderCode;
+    providerConnectionId: string;
+    externalUnitId: string;
+    latitude: number;
+    longitude: number;
+    accuracyMetres?: number | null;
+    speedKph?: number | null;
+    courseDegrees?: number | null;
+    altitudeMetres?: number | null;
+    moving?: boolean | null;
+    ignitionOn?: boolean | null;
+    eventTime: string;
+    receivedAt: string;
+    lastPresenceAt?: string | null;
+    status: TrackingUnitOnlineStatus;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Stable inputs from which a tracking event's id is derived. Chosen so that the
+ * SAME provider fix always yields the SAME id (idempotent history + dedup),
+ * while distinct fixes for the same unit yield distinct ids.
+ */
+export interface TrackingEventIdParts {
+    providerConnectionId: string;
+    externalUnitId: string;
+    /** Provider event time as Unix epoch SECONDS. */
+    eventEpochSeconds: number;
+    latitude: number;
+    longitude: number;
+}
+/**
+ * Build a deterministic tracking event id (sha256 hex) from stable fix inputs.
+ *
+ * Coordinates are quantized to 6 decimal places (~0.11 m) so floating-point
+ * representation differences across services never split one physical fix into
+ * two ids. Epoch seconds are truncated to whole seconds.
+ */
+export declare function buildTrackingEventId(parts: TrackingEventIdParts): string;
+/**
+ * Kafka partition key for position/status events. Keying by
+ * `{organizationId}:{controlCentreId}:{responseUnitId}` guarantees per-unit
+ * ordering within a partition. Never use a random key for these events.
+ */
+export declare function buildTrackingPartitionKey(organizationId: number, controlCentreId: number, responseUnitId: number): string;

package/dist/types/modules/tracking/utils/tracking-validation.util.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Provider-neutral validation/normalization helpers shared by the ingestion
+ * pipeline (and reusable by tests). No provider-specific field names appear here.
+ */
+/** WGS84 latitude range check. */
+export declare function isValidLatitude(value: unknown): value is number;
+/** WGS84 longitude range check. */
+export declare function isValidLongitude(value: unknown): value is number;
+/** A valid course is a finite number in [0, 360). */
+export declare function isValidCourseDegrees(value: unknown): value is number;
+/**
+ * Normalize a raw course/bearing value into degrees in [0, 360), or null when it
+ * cannot be trusted for rotation.
+ *
+ * - A raw value of exactly `unknownSentinel` (default -1) is treated as unknown.
+ * - When `divisor` > 1 the raw value is divided (e.g. 27306 / 100 = 273.06).
+ * - The result is wrapped into [0, 360); a non-finite result yields null.
+ *
+ * The divisor is NOT hardcoded to a provider's scale — callers pass the value
+ * they have configured/confirmed for that connection.
+ */
+export declare function normalizeCourseDegrees(raw: number | null | undefined, divisor?: number, unknownSentinel?: number | null): number | null;
+/** Supported provider speed units for normalization into km/h. */
+export type TrackingSpeedUnit = 'KPH' | 'MPS' | 'MPH' | 'RAW';
+/**
+ * Convert a raw speed into kilometres per hour given the source unit and an
+ * optional multiplier applied to the raw value first. Returns null for
+ * non-finite or negative inputs. `RAW` means "already km/h after the multiplier".
+ */
+export declare function normalizeSpeedToKph(raw: number | null | undefined, unit?: TrackingSpeedUnit, multiplier?: number): number | null;
+/**
+ * Validate a provider epoch-seconds timestamp against a tolerance window and
+ * convert to an ISO 8601 UTC string. Returns null when out of range/unparseable.
+ *
+ * @param epochSeconds provider timestamp in seconds
+ * @param nowMs        current time in ms (injectable for deterministic tests)
+ * @param futureToleranceSeconds max seconds a fix may be ahead of now
+ * @param maxAgeSeconds max seconds a fix may be behind now (0/undefined = no limit)
+ */
+export declare function epochSecondsToIsoUtc(epochSeconds: number | null | undefined, nowMs: number, futureToleranceSeconds?: number, maxAgeSeconds?: number): string | null;

package/package.json

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