clarion-shared-types 1.0.118 → 1.0.120

package/dist/types/modules/tracking/interfaces/tracking-analytics.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Units & Tracking analytics, the tracking half (the admin's Units & Tracking
+ * Analytics): the response units in scope and how they are tracked - computed by
+ * clarion-response-tracking. The other half, what was dispatched and how it went, is
+ * DispatchAnalytics (clarion-incident); both answer the same query.
+ *
+ * The fleet and its live status are as they stand NOW. Everything else is the period's,
+ * counted by the hour a position was recorded (`eventTime`): the service keeps an hourly
+ * rollup of the position history, so a year costs no more to read than a day. Counts,
+ * rates and durations only - never a position, a route or a device identifier.
+ */
+/** How the period is cut into points for the charts. Chosen by the service from the length of the period. */
+export type UnitsAnalyticsBucket = 'hour' | 'day' | 'week' | 'month';
+export interface UnitsAnalyticsRange {
+    /** Inclusive, ISO 8601. For "forever", the start of the data in scope. */
+    from: string;
+    /** Exclusive, ISO 8601. */
+    to: string;
+    bucket: UnitsAnalyticsBucket;
+    /** IANA time zone the buckets (and the dispatch hour-of-week grid) are cut in. */
+    timeZone: string;
+}
+/** Whose figures these are, as the service decided from the caller. */
+export interface UnitsAnalyticsScope {
+    /** Null: every organization (a Super-Admin's platform view). */
+    organizationId: number | null;
+    /** Null: every control centre of the organization. */
+    controlCentreId: number | null;
+    platform: boolean;
+}
+/** A count by a key (a type, a status, a provider), largest first unless the section says otherwise. */
+export interface UnitsAnalyticsCount<K extends string = string> {
+    key: K;
+    count: number;
+}
+/** Median and 90th percentile of one duration, in seconds; null when nothing was measured. */
+export interface UnitsAnalyticsDuration {
+    samples: number;
+    medianSeconds: number | null;
+    p90Seconds: number | null;
+}
+/** The response units in scope, as they stand now (deleted units are left out). */
+export interface TrackingAnalyticsFleet {
+    total: number;
+    enabled: number;
+    disabled: number;
+    byType: UnitsAnalyticsCount[];
+    byOperationalStatus: UnitsAnalyticsCount[];
+    /** Enabled units with an enabled device binding: the service is told where they are. */
+    tracked: number;
+    /** Enabled units with no enabled binding. */
+    untracked: number;
+    /** Tracked units by the provider of their binding's connection (a unit bound twice counts under each). */
+    trackedByProvider: UnitsAnalyticsCount[];
+}
+/** The tracked units' state now - the same states as the live map. */
+export interface TrackingAnalyticsLive {
+    online: number;
+    stale: number;
+    offline: number;
+    /** Tracked units with no position in the live store (never reported, or not for a long while). */
+    noPosition: number;
+}
+/** Which units reported in the period. */
+export interface TrackingAnalyticsReporting {
+    /** Units that reported at least one position. */
+    reportingUnits: number;
+    /** The same for the previous period of the same length; null for "forever". */
+    previousReportingUnits: number | null;
+    /** Tracked units (now) that reported nothing in the period. */
+    silentTrackedUnits: number;
+    /** Tracked units that reported, as a percentage of the tracked units; null without tracked units. */
+    reportingRate: number | null;
+}
+/** The positions recorded in the period. */
+export interface TrackingAnalyticsPositions {
+    total: number;
+    /** Null for "forever". */
+    previousTotal: number | null;
+    /** Positions per reporting unit per hour it reported in. */
+    perUnitHour: number | null;
+    /** Percentages of the positions that say: reported while moving, with the ignition on. */
+    movingRate: number | null;
+    ignitionOnRate: number | null;
+    byProvider: UnitsAnalyticsCount[];
+}
+/** How long a position took to reach Clarion once the device recorded it, in bands. */
+export type TrackingDelayBand = 'WITHIN_5S' | 'WITHIN_10S' | 'WITHIN_30S' | 'WITHIN_1M' | 'WITHIN_2M' | 'WITHIN_5M' | 'WITHIN_15M' | 'LATER';
+/** Delivery delay: `receivedAt - eventTime` of every position in the period. */
+export interface TrackingAnalyticsDelivery {
+    /** Estimated from the bands (interpolated within the band the percentile falls in). */
+    medianSeconds: number | null;
+    p90Seconds: number | null;
+    meanSeconds: number | null;
+    /** Every band, fastest first, zero counts included. */
+    bands: UnitsAnalyticsCount<TrackingDelayBand>[];
+    /** Positions that took longer than 5 minutes, as a percentage. */
+    lateRate: number | null;
+}
+/** What the ingestion flagged about the period's positions, and the provider units nobody has bound. */
+export interface TrackingAnalyticsQuality {
+    outOfOrder: number;
+    duplicates: number;
+    invalidCoordinates: number;
+    /** Positions that jumped implausibly far from the previous one. */
+    jumpSuspected: number;
+    /** Positions with an accuracy worse than 100 m. */
+    poorAccuracy: number;
+    /** Provider units reporting without a binding: open now, resolved, and how often they were seen. */
+    unmappedOpen: number;
+    unmappedResolved: number;
+    unmappedOccurrences: number;
+}
+export interface TrackingAnalyticsTimelinePoint {
+    /** Start of the bucket, ISO 8601. */
+    at: string;
+    positions: number;
+    reportingUnits: number;
+    /** Positions that took longer than 5 minutes to arrive. */
+    late: number;
+}
+/** A provider connection in scope: its configuration and health now, and its positions in the period. */
+export interface TrackingAnalyticsConnectionRow {
+    id: number;
+    organizationId: number;
+    controlCentreId: number | null;
+    name: string;
+    providerCode: string;
+    enabled: boolean;
+    connectionStatus: string;
+    lastEventAt: string | null;
+    lastErrorAt: string | null;
+    lastErrorCode: string | null;
+    /** Enabled bindings through it now. */
+    boundUnits: number;
+    positions: number;
+    reportingUnits: number;
+    medianDelaySeconds: number | null;
+    lateRate: number | null;
+}
+/** A response unit in scope: what it is and how it is tracked now, and what it reported in the period. */
+export interface TrackingAnalyticsUnitRow {
+    responseUnitId: number;
+    organizationId: number;
+    controlCentreId: number | null;
+    name: string | null;
+    responseUnitType: string | null;
+    enabled: boolean;
+    tracked: boolean;
+    /** The providers its enabled bindings use. */
+    providers: string[];
+    /** ONLINE, STALE or OFFLINE now; null when not tracked or without a position. */
+    liveStatus: string | null;
+    /** Its newest position in the period. */
+    lastPositionAt: string | null;
+    positions: number;
+    /** Hours in which it reported at least once. */
+    hoursReporting: number;
+    medianDelaySeconds: number | null;
+}
+/** Platform view only: one row per organization. */
+export interface TrackingAnalyticsOrganizationRow {
+    organizationId: number;
+    units: number;
+    tracked: number;
+    reportingUnits: number;
+    positions: number;
+    connections: number;
+    lateRate: number | null;
+}
+export interface TrackingAnalytics {
+    generatedAt: string;
+    range: UnitsAnalyticsRange;
+    scope: UnitsAnalyticsScope;
+    fleet: TrackingAnalyticsFleet;
+    live: TrackingAnalyticsLive;
+    reporting: TrackingAnalyticsReporting;
+    positions: TrackingAnalyticsPositions;
+    delivery: TrackingAnalyticsDelivery;
+    quality: TrackingAnalyticsQuality;
+    timeline: TrackingAnalyticsTimelinePoint[];
+    connections: TrackingAnalyticsConnectionRow[];
+    /** The units in scope, most positions first; capped (see `unitsTruncated`). */
+    units: TrackingAnalyticsUnitRow[];
+    unitsTruncated: boolean;
+    /** Platform view only; null otherwise. */
+    byOrganization: TrackingAnalyticsOrganizationRow[] | null;
+    /** The rollup is complete up to this instant: positions recorded later are not counted yet. */
+    rollupThrough: string | null;
+    /** History older than this is still being rolled up (the first hours after release); null once complete. */
+    backfillingBefore: string | null;
+}
+/** The query both halves answer (UnitsAnalyticsQueryDto in grm-shared-library). All optional. */
+export interface UnitsAnalyticsQuery {
+    /** Inclusive, ISO 8601. Omit for "forever". */
+    from?: string;
+    /** Exclusive, ISO 8601. Omit for "now". */
+    to?: string;
+    /** IANA time zone for the buckets and the hour-of-week grid. */
+    timeZone?: string;
+    /** Super-Admin only. */
+    organizationId?: number;
+    /** One control centre of the organization. */
+    controlCentreId?: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clarion-shared-types",
-  "version": "1.0.118",
+  "version": "1.0.120",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",