grm-shared-library 1.1.188 → 1.1.190

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

@@ -0,0 +1,22 @@
+/**
+ * Lifecycle state of a provider connection as observed by the connector worker.
+ * Surfaced in provider-health events and the provider-connection REST resource.
+ */
+export declare enum TrackingConnectionStatus {
+    /** Administratively disabled — the worker will not attempt to connect. */
+    DISABLED = "DISABLED",
+    /** Not currently connected (idle, or between reconnect attempts). */
+    DISCONNECTED = "DISCONNECTED",
+    /** Transport handshake in progress. */
+    CONNECTING = "CONNECTING",
+    /** Transport is up; provider authentication / subscription in progress. */
+    AUTHENTICATING = "AUTHENTICATING",
+    /** Authenticated, subscribed and receiving (or ready to receive) telemetry. */
+    CONNECTED = "CONNECTED",
+    /** Connected but unhealthy (e.g. no telemetry for longer than expected). */
+    DEGRADED = "DEGRADED",
+    /** Provider rejected the credentials — a config problem, not a network blip. */
+    AUTHENTICATION_FAILED = "AUTHENTICATION_FAILED",
+    /** Non-auth error state (transport failure, protocol error, etc.). */
+    ERROR = "ERROR"
+}

package/dist/types/modules/tracking/enums/tracking-event-quality.enum.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Coarse classification of an ingested location, used for diagnostics and to
+ * decide whether an event updates current state (only fresh, in-order, valid
+ * events do). Fine-grained booleans live in {@link TrackingPositionQualityFlags}.
+ */
+export declare enum TrackingEventQuality {
+    /** Valid, fresh and in order. */
+    GOOD = "GOOD",
+    /** Already seen (same deterministic eventId). */
+    DUPLICATE = "DUPLICATE",
+    /** Older than the current state for this unit. */
+    OUT_OF_ORDER = "OUT_OF_ORDER",
+    /** Coordinates outside the valid WGS84 range. */
+    INVALID_COORDINATES = "INVALID_COORDINATES",
+    /** Timestamp missing, unparseable, or outside the accepted tolerance. */
+    INVALID_TIMESTAMP = "INVALID_TIMESTAMP"
+}

package/dist/types/modules/tracking/enums/tracking-provider-code.enum.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Identifies the third-party tracking platform a provider connection integrates
+ * with. Provider-neutral: the core ingestion pipeline, tenant model, device
+ * bindings and canonical events never branch on a specific provider — only the
+ * per-provider adapter inside clarion-response-tracking understands the raw
+ * wire format.
+ *
+ * Only {@link TrackingProviderCode.TELOX} has a working adapter in Phase 1. The
+ * remaining values are reserved so future adapters can be added without changing
+ * the shared contracts, database columns or Kafka events.
+ */
+export declare enum TrackingProviderCode {
+    /** Telox WebSocket platform (G4S Phase 1 integration). */
+    TELOX = "TELOX",
+    /** Wialon (reserved — not implemented in Phase 1). */
+    WIALON = "WIALON",
+    /** Teltonika direct device ingestion (reserved — not implemented in Phase 1). */
+    TELTONIKA = "TELTONIKA",
+    /** Generic WebSocket adapter (reserved). */
+    GENERIC_WEBSOCKET = "GENERIC_WEBSOCKET",
+    /** Generic HTTP polling adapter (reserved). */
+    GENERIC_HTTP_POLLING = "GENERIC_HTTP_POLLING"
+}

package/dist/types/modules/tracking/enums/tracking-transport-type.enum.d.ts

@@ -0,0 +1,17 @@
+/**
+ * How a provider connection physically transports telemetry into
+ * clarion-response-tracking. Phase 1 implements only {@link WEBSOCKET} (Telox);
+ * the remaining values are reserved for future adapters.
+ */
+export declare enum TrackingTransportType {
+    /** Outbound WebSocket client maintained by the connector worker (Telox). */
+    WEBSOCKET = "WEBSOCKET",
+    /** Outbound HTTP polling loop. */
+    HTTP_POLLING = "HTTP_POLLING",
+    /** Inbound TCP listener (direct device ingestion). */
+    TCP = "TCP",
+    /** Inbound UDP listener (direct device ingestion). */
+    UDP = "UDP",
+    /** MQTT subscription. */
+    MQTT = "MQTT"
+}

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,18 @@
+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/response-unit-lifecycle-events';
+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-lifecycle-events.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Response-unit lifecycle events published by clarion-organization (source of
+ * truth) and consumed by clarion-response-tracking to keep its local read
+ * projection in sync. Versioned (schema v1), provider-neutral, and free of
+ * provider/tracking-specific data.
+ *
+ * `sourceUpdatedAt` is the authoritative "when the change happened upstream"
+ * timestamp used by the consumer for idempotent, monotonic (older-event-reject)
+ * projection updates. `occurredAt` is when the event itself was produced.
+ */
+export interface ResponseUnitLifecycleEventBase {
+    schemaVersion: 1;
+    /** Stable/deterministic id per the producer's convention (dedup + audit). */
+    eventId: string;
+    responseUnitId: number;
+    organizationId: number;
+    controlCentreId: number | null;
+    /** ISO 8601 UTC — upstream change time (ordering key for the projection). */
+    sourceUpdatedAt: string;
+    /** ISO 8601 UTC — when this event was produced. */
+    occurredAt: string;
+    correlationId?: string;
+}
+/** Descriptive response-unit fields carried by create/update/status events. */
+export interface ResponseUnitDescriptor {
+    name?: string | null;
+    registrationNumber?: string | null;
+    responseUnitType?: string | null;
+    operationalStatus?: string | null;
+    enabled?: boolean;
+}
+export interface ResponseUnitCreatedEventV1 extends ResponseUnitLifecycleEventBase, ResponseUnitDescriptor {
+}
+export interface ResponseUnitUpdatedEventV1 extends ResponseUnitLifecycleEventBase, ResponseUnitDescriptor {
+}
+export interface ResponseUnitStatusChangedEventV1 extends ResponseUnitLifecycleEventBase, ResponseUnitDescriptor {
+    /** Whether the unit is enabled after the change (explicit for status events). */
+    enabled: boolean;
+}
+export interface ResponseUnitControlCentreChangedEventV1 extends ResponseUnitLifecycleEventBase, ResponseUnitDescriptor {
+    /** The control centre the unit moved FROM (null if it had none). */
+    previousControlCentreId: number | null;
+}
+export interface ResponseUnitDeletedEventV1 extends ResponseUnitLifecycleEventBase {
+    deleted: true;
+}
+/** Union of all response-unit lifecycle events. */
+export type ResponseUnitLifecycleEventV1 = ResponseUnitCreatedEventV1 | ResponseUnitUpdatedEventV1 | ResponseUnitStatusChangedEventV1 | ResponseUnitControlCentreChangedEventV1 | ResponseUnitDeletedEventV1;

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;