grm-shared-library 1.1.207 → 1.1.209

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

@@ -5,14 +5,17 @@
  * 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.
+ * {@link TrackingProviderCode.TELOX} and {@link TrackingProviderCode.WIALON} have
+ * working adapters. The remaining values are reserved so future adapters can be
+ * added without changing the shared contracts, database columns or Kafka events.
+ *
+ * A value here does NOT mean the provider can be connected — ask the service
+ * (`GET /tracking/providers`, see TrackingProviderDescriptor) which adapters exist.
  */
 export declare enum TrackingProviderCode {
     /** Telox WebSocket platform (G4S Phase 1 integration). */
     TELOX = "TELOX",
-    /** Wialon (reserved — not implemented in Phase 1). */
+    /** Wialon Hosting / Wialon Local, polled over the Remote API. */
     WIALON = "WIALON",
     /** Teltonika direct device ingestion (reserved — not implemented in Phase 1). */
     TELTONIKA = "TELTONIKA",

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

@@ -1,12 +1,12 @@
 /**
  * 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.
+ * clarion-response-tracking. {@link WEBSOCKET} (Telox) and {@link HTTP_POLLING}
+ * (Wialon) are implemented; 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. */
+    /** Outbound HTTP polling loop maintained by the connector worker (Wialon). */
     HTTP_POLLING = "HTTP_POLLING",
     /** Inbound TCP listener (direct device ingestion). */
     TCP = "TCP",

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

@@ -13,6 +13,7 @@ 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 './interfaces/tracking-provider-descriptor';
 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/tracking-provider-descriptor.d.ts

@@ -0,0 +1,117 @@
+import { TrackingProviderCode } from '../enums/tracking-provider-code.enum';
+import { TrackingTransportType } from '../enums/tracking-transport-type.enum';
+/**
+ * Self-description of a tracking provider, published by clarion-response-tracking
+ * (`GET /tracking/providers`) and rendered by the admin client.
+ *
+ * Why it exists: every provider needs different things from an operator. Telox
+ * wants a WebSocket URL, a username, a domain and a password; Wialon wants an
+ * HTTPS host and an API token and has no domain at all; and each scales its raw
+ * telemetry differently. Encoding that in the client meant a form that only fit
+ * one provider and defaults that had to be kept in step with the service by hand.
+ * With a descriptor the service that owns the adapter is the single source of
+ * truth: adding a provider changes no client code, and a default can never drift.
+ *
+ * Only providers with a registered adapter are described, so the catalog also
+ * answers "which providers can I actually connect?" — the enum alone cannot,
+ * because it reserves codes for adapters that do not exist yet.
+ *
+ * SECURITY: a descriptor is static metadata. It never carries a secret, a secret
+ * reference, or anything tenant-specific.
+ */
+export type TrackingProviderSettingType = 'number' | 'boolean' | 'select' | 'text';
+export interface TrackingProviderSettingOption {
+    value: string;
+    label: string;
+}
+/** One key of a provider connection's `configuration` blob. */
+export interface TrackingProviderSettingDescriptor {
+    /** The `configuration` key this setting is stored under. */
+    key: string;
+    label: string;
+    type: TrackingProviderSettingType;
+    /** Key of the {@link TrackingProviderSettingGroupDescriptor} it is shown under. */
+    group: string;
+    /** Applied by the service when the key is absent, and pre-filled by the client. */
+    defaultValue: number | boolean | string;
+    description?: string;
+    /** Display unit, e.g. `s`, `m`, `km/h`. */
+    unit?: string;
+    /** `number` settings only. Bounds are inclusive and enforced by the service. */
+    min?: number;
+    max?: number;
+    step?: number;
+    /** `number` settings only: reject fractional values. */
+    integer?: boolean;
+    /** `text` settings only. */
+    maxLength?: number;
+    /** `select` settings only: the closed set of accepted values. */
+    options?: TrackingProviderSettingOption[];
+}
+export interface TrackingProviderSettingGroupDescriptor {
+    key: string;
+    label: string;
+    description?: string;
+}
+/** An optional connection field whose meaning (or existence) depends on the provider. */
+export interface TrackingProviderFieldDescriptor {
+    /** false ⇒ the provider has no such concept: hide the field and send nothing. */
+    used: boolean;
+    required: boolean;
+    label: string;
+    placeholder?: string;
+    description?: string;
+}
+export interface TrackingProviderEndpointDescriptor {
+    label: string;
+    placeholder: string;
+    description?: string;
+    /** Pre-filled for providers with one well-known public endpoint. */
+    defaultValue?: string;
+    /** Accepted URL schemes, with the trailing colon: `wss:`, `https:`… */
+    protocols: string[];
+}
+/** What the referenced secret must contain. Describes the secret; never holds it. */
+export interface TrackingProviderSecretDescriptor {
+    label: string;
+    description: string;
+    placeholder?: string;
+}
+/** How the provider identifies a unit — what an operator binds to a response unit. */
+export interface TrackingProviderExternalUnitDescriptor {
+    label: string;
+    description: string;
+    placeholder?: string;
+}
+export interface TrackingProviderDescriptor {
+    providerCode: TrackingProviderCode;
+    displayName: string;
+    description: string;
+    /** Supported transports; the first is the default. */
+    transportTypes: TrackingTransportType[];
+    endpoint: TrackingProviderEndpointDescriptor;
+    externalUsername: TrackingProviderFieldDescriptor;
+    externalDomain: TrackingProviderFieldDescriptor;
+    secret: TrackingProviderSecretDescriptor;
+    externalUnitId: TrackingProviderExternalUnitDescriptor;
+    /** Display order of the setting groups. */
+    settingGroups: TrackingProviderSettingGroupDescriptor[];
+    settings: TrackingProviderSettingDescriptor[];
+    documentationUrl?: string;
+}
+/**
+ * The `configuration` a connection gets when the operator supplies none: every
+ * setting at its default. Stored explicitly on the connection so that readers
+ * which know nothing about adapters (the status evaluator, ingestion guards) see
+ * the provider's thresholds rather than the service-wide fallbacks.
+ */
+export declare function buildDefaultTrackingProviderConfiguration(descriptor: Pick<TrackingProviderDescriptor, 'settings'>): Record<string, number | boolean | string>;
+/**
+ * Validate a raw `configuration` blob against a provider's setting descriptors.
+ * Returns human-readable errors (empty ⇒ valid). Absent keys are valid — they
+ * take their default. Keys the descriptor does not know are ignored, not
+ * rejected: a connection saved before a setting was retired must stay editable.
+ *
+ * Cross-field rules (e.g. "offline must not precede stale") are the adapter's.
+ */
+export declare function validateTrackingProviderSettings(settings: readonly TrackingProviderSettingDescriptor[], configuration: Record<string, unknown> | null | undefined): string[];

package/package.json

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