@bikefinder/sdk 0.1.6 → 0.1.8

package/README.md

@@ -50,9 +50,9 @@ The application owns subscription sharing, retained data and account scope. Subs
 
 The application's Auth0 SDK supplies tokens and handles refresh. Create a new client for a new account session. `dispose()` aborts HTTP requests and stops both connections. Requests use bearer authentication, omit cookies and reject redirects. Network/validation failures reject; HTTP Problem Details are available as `result.error` by default. Writes are never automatically retried; a `503 operation_unconfirmed` may already have committed.
 
-REST calls return response JSON unchanged with generated static types. The API validates and converts stored data before responding; `readIssues` identifies unusable stored fields. Response validation is opt-in for both REST and SignalR: import `zTrackerDocument` from `@bikefinder/sdk/schemas` and call `.parse(value)` when the caller requires a runtime boundary check. Both transports reference the same generated payload types. Firestore responses come from the actual C# DTOs in `Firestore/TrackerData.cs` and `Firestore/ResourceData.cs`. Additional metadata remains in explicit JSON extension fields. Server-serialized response fixtures are validated by both API and generated-client tests. IDs are exact Firestore IDs.
+REST calls automatically validate response structure without transforming response JSON. The API validates and converts stored data before responding; `readIssues` identifies unusable stored fields. Stream values use the native SignalR decoder; import `zTrackerDocument` from `@bikefinder/sdk/schemas` and call `.parse(value)` for the same runtime boundary check on a stream message. Both transports reference the same generated payload types. Firestore responses come from the actual C# DTOs in `Firestore/TrackerData.cs` and `Firestore/ResourceData.cs`. Additional metadata remains in explicit JSON extension fields. Server-serialized response fixtures are validated by both API and generated-client tests. IDs are exact Firestore IDs.
 
-Other native resources expose their known fields through resource-specific document types. Their C# contracts expose only interpreted fields; unrelated stored fields stay inside the API. Tracker reports and statistics have concrete models, and access-code storage is omitted from responses. Observation values are generated unions: after `observation.definitionId === 5`, `observation.value.percent` is a number. Current readings expose the same discriminator; check `observationId !== null` before using a present reading. Device settings, the built-in workflow descriptor and command argument tuples are generated from the canonical protocol JSON contracts. Bike and preference patches expose supported properties and distinguish omission from explicit null. Optional response validators preserve additional API fields while checking known values and required properties. Workflow diagnostic states are extensible strings, including `idle` and `rest`; display or preserve unfamiliar states. Request models retain their declared constraints and closed objects reject unknown write fields. Shared payloads have generated read variants so a tolerant response never weakens a request schema.
+Other native resources expose their known fields through resource-specific document types. Their C# contracts expose only interpreted fields; unrelated stored fields stay inside the API. Tracker reports and statistics have concrete models, and access-code storage is omitted from responses. Observation values are generated unions: after `observation.definitionId === 5`, `observation.value.percent` is a number. Current readings expose the same discriminator; check `observationId !== null` before using a present reading. Device settings, the built-in workflow descriptor and command argument tuples are generated from the canonical protocol JSON contracts. Bike and preference patches expose supported properties and distinguish omission from explicit null. Response validators preserve additional API fields while checking known values and required properties. Workflow diagnostic states are extensible strings, including `idle` and `rest`; display or preserve unfamiliar states. Request models retain their declared constraints and closed objects reject unknown write fields. Shared payloads have generated read variants so a tolerant response never weakens a request schema.
 
 The handwritten entry point only configures clients, authentication and disposal. Hub methods, wire names and streaming signatures are generated. A generated type-only bridge reuses OpenAPI payload definitions instead of publishing a second set of models. There is no RxJS or MQTT dependency.
 
@@ -117,9 +117,10 @@ Command reads validate stored identity, catalog arguments, artifacts, and execut
 
 ## Supported API consumers
 
-`@bikefinder/sdk@0.1.6` is the supported baseline for the 2026-11-07 minimum-rest
-and optional response-validation release. Earlier SDKs have closed workflow-state
-validators and should upgrade for the extensible diagnostic response contract.
+`@bikefinder/sdk@0.1.7` is the supported baseline for the 2026-11-07 minimum-rest
+release with automatic response validation and extensible diagnostic strings.
+Older closed-state readers should upgrade for the extensible diagnostic contract.
+SDK 0.1.6 disables automatic response validation; upgrade to 0.1.7 to retain it.
 The preceding prelaunch cutover retired experimental `@bikefinder/api-client`
 releases and their older AWS contracts. The `/v1` route version is unchanged.
 Future breaking changes still require an explicit retirement decision or a
@@ -144,7 +145,7 @@ version for breaking changes and retain the supported v1 routes. Raising the
 oldest supported SDK version is an explicit retirement decision, not a routine
 way to pass CI. Dev deployment and production promotion both require this job.
 
-Explicit runtime validation still rejects malformed known data. Callers choosing
-it should retain last valid stream messages and isolate failures per resource. When patching
+Runtime validation rejects malformed known data. Stream consumers should retain
+last valid messages and isolate failures per resource. When patching
 settings, send only changed supported fields; preserve unfamiliar response fields
 and do not copy a full response into a write payload.

package/dist/device-schema.d.ts

@@ -595,7 +595,7 @@ export declare const observationValueSchema: {
             readonly required: readonly ["pci", "earfcn", "rsrp", "rsrq"];
             readonly additionalProperties: false;
         };
-        readonly CellScan: {
+        readonly CellularEnvironment: {
             readonly type: "object";
             readonly properties: {
                 readonly serving: {
@@ -5216,13 +5216,13 @@ export declare const observationValueSchema: {
                 };
             };
         };
-        readonly "radio.bleScan": {
+        readonly "radio.bleDevices": {
             readonly type: "array";
             readonly items: {
                 readonly $ref: "#/$defs/BleDevice";
             };
             readonly maxItems: 20;
-            readonly title: "Radio ble scan";
+            readonly title: "Nearby BLE devices";
             readonly description: "BLE scan evidence is distinct from BLE enabled/unlocked status.";
             readonly "x-bf": {
                 readonly definitionId: 151;
@@ -5230,37 +5230,37 @@ export declare const observationValueSchema: {
                 readonly subject: "device";
                 readonly producer: "device";
                 readonly presentation: {
-                    readonly displayName: "Radio ble scan";
+                    readonly displayName: "Nearby BLE devices";
                     readonly description: "BLE scan evidence is distinct from BLE enabled/unlocked status.";
                     readonly hiddenByDefault: false;
                     readonly formatter: "bleScan";
                 };
             };
         };
-        readonly "radio.cellScan": {
-            readonly $ref: "#/$defs/CellScan";
-            readonly title: "Radio cell scan";
-            readonly description: "Cell scan and registration latency are distinct facts; distinguish passive serving-cell updates from extended scans.";
+        readonly "radio.cellularEnvironment": {
+            readonly $ref: "#/$defs/CellularEnvironment";
+            readonly title: "Cellular environment";
+            readonly description: "Coherent serving-cell identity, radio technology and signal evidence, with neighbouring or global cells when explicitly requested. Routine tracking reads serving-cell information without an extended cell search.";
             readonly "x-bf": {
                 readonly definitionId: 152;
                 readonly role: "measurement";
                 readonly subject: "device";
                 readonly producer: "device";
                 readonly presentation: {
-                    readonly displayName: "Radio cell scan";
-                    readonly description: "Cell scan and registration latency are distinct facts; distinguish passive serving-cell updates from extended scans.";
+                    readonly displayName: "Cellular environment";
+                    readonly description: "Coherent serving-cell identity, radio technology and signal evidence, with neighbouring or global cells when explicitly requested. Routine tracking reads serving-cell information without an extended cell search.";
                     readonly hiddenByDefault: false;
                     readonly formatter: "cellScan";
                 };
             };
         };
-        readonly "radio.wifiScan": {
+        readonly "radio.wifiAccessPoints": {
             readonly type: "array";
             readonly items: {
                 readonly $ref: "#/$defs/WifiAccessPoint";
             };
             readonly maxItems: 20;
-            readonly title: "Radio wifi scan";
+            readonly title: "Wi-Fi access points";
             readonly description: "The coherent Wi-Fi scan is positioning evidence; retain an empty successful scan separately from a failed scan.";
             readonly "x-bf": {
                 readonly definitionId: 153;
@@ -5268,7 +5268,7 @@ export declare const observationValueSchema: {
                 readonly subject: "device";
                 readonly producer: "device";
                 readonly presentation: {
-                    readonly displayName: "Radio wifi scan";
+                    readonly displayName: "Wi-Fi access points";
                     readonly description: "The coherent Wi-Fi scan is positioning evidence; retain an empty successful scan separately from a failed scan.";
                     readonly hiddenByDefault: false;
                     readonly formatter: "wifiScan";
@@ -5384,7 +5384,9 @@ export declare const observationValueSchema: {
                     readonly type: "boolean";
                 };
                 readonly mode: {
-                    readonly type: "string";
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly maximum: 2;
                 };
             };
             readonly required: readonly ["completedCount", "trigger", "outcome", "elapsedMs", "activeMs", "activityMs", "activityEntries", "recoveries", "saturated", "mode"];
@@ -5428,11 +5430,12 @@ export declare const observationValueSchema: {
                     readonly maximum: 65535;
                 };
                 readonly mode: {
-                    readonly type: "string";
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly maximum: 2;
                 };
                 readonly state: {
                     readonly type: "string";
-                    readonly enum: readonly ["idle", "battery", "connect", "cell", "wifi", "publish", "listen", "gps", "gpsPublish", "rest"];
                 };
                 readonly owner: {
                     readonly type: "string";
@@ -5515,7 +5518,7 @@ export declare const observationValueSchema: {
                         readonly label: "Duration";
                         readonly format: "duration";
                     }];
-                    readonly extensibleEnumFields: readonly ["mode"];
+                    readonly extensibleEnumFields: readonly ["mode", "state"];
                 };
             };
         };
@@ -6112,9 +6115,11 @@ export declare const settingsValueSchema: {
             readonly description: "Advertising interval in 0.625 millisecond units. Applied by the peripheral owner independently of LTE connection work.";
         };
         readonly mode: {
-            readonly type: "string";
-            readonly title: "Tracking mode";
-            readonly description: "Underlying firmware behavior. Offered tracking modes are cloud-configurable profiles.";
+            readonly type: "integer";
+            readonly minimum: 0;
+            readonly maximum: 2;
+            readonly title: "Firmware mode ID";
+            readonly description: "Stable integer firmware mode ID: 0, 1 or 2. Each mode’s stages are defined in firmware. Public mode names are mapped to these IDs by the assigned tracking mode catalog.";
         };
         readonly poweredReportIntervalSeconds: {
             readonly type: "integer";
@@ -6123,47 +6128,47 @@ export declare const settingsValueSchema: {
             readonly title: "Powered report interval";
             readonly description: "Period between tracking reports on confirmed external power.";
         };
-        readonly standardIdleSeconds: {
+        readonly mode0IdleSeconds: {
             readonly type: "integer";
             readonly minimum: 60;
             readonly maximum: 604800;
-            readonly title: "Standard idle duration";
-            readonly description: "Maximum battery idle duration after a standard cycle.";
+            readonly title: "Mode 0 idle duration";
+            readonly description: "Maximum battery idle duration after a mode 0 cycle, measured from the end of work.";
         };
-        readonly securityIdleSeconds: {
+        readonly mode1IdleSeconds: {
             readonly type: "integer";
             readonly minimum: 60;
             readonly maximum: 604800;
-            readonly title: "Security idle duration";
-            readonly description: "Maximum battery idle duration after a security cycle.";
+            readonly title: "Mode 1 idle duration";
+            readonly description: "Maximum battery idle duration after a mode 1 cycle, measured from the end of work.";
         };
-        readonly trackingIdleSeconds: {
+        readonly mode2IdleSeconds: {
             readonly type: "integer";
             readonly minimum: 10;
             readonly maximum: 86400;
-            readonly title: "Tracking idle duration";
-            readonly description: "Maximum battery idle duration after a tracking cycle.";
+            readonly title: "Mode 2 idle duration";
+            readonly description: "Maximum battery idle duration after a mode 2 cycle, measured from the end of work.";
         };
-        readonly standardMinimumRestSeconds: {
+        readonly mode0MinimumRestSeconds: {
             readonly type: "integer";
             readonly minimum: 0;
             readonly maximum: 86400;
-            readonly title: "Standard movement rest";
-            readonly description: "Minimum rest before movement starts another standard cycle.";
+            readonly title: "Mode 0 minimum rest";
+            readonly description: "Duration after a mode 0 cycle with the accelerometer and its wake interrupt disabled. Firmware re-enables motion detection when this period ends.";
         };
-        readonly securityMinimumRestSeconds: {
+        readonly mode1MinimumRestSeconds: {
             readonly type: "integer";
             readonly minimum: 0;
             readonly maximum: 86400;
-            readonly title: "Security movement rest";
-            readonly description: "Minimum rest before movement starts another security cycle.";
+            readonly title: "Mode 1 minimum rest";
+            readonly description: "Duration after a mode 1 cycle with the accelerometer and its wake interrupt disabled. Firmware re-enables motion detection when this period ends.";
         };
-        readonly trackingMinimumRestSeconds: {
+        readonly mode2MinimumRestSeconds: {
             readonly type: "integer";
             readonly minimum: 0;
             readonly maximum: 86400;
-            readonly title: "Tracking movement rest";
-            readonly description: "Minimum rest before movement starts another tracking cycle.";
+            readonly title: "Mode 2 minimum rest";
+            readonly description: "Duration after a mode 2 cycle with the accelerometer and its wake interrupt disabled. Firmware re-enables motion detection when this period ends.";
         };
         readonly psmResidenceSeconds: {
             readonly type: "integer";
@@ -6363,7 +6368,7 @@ export declare const settingsValueSchema: {
     readonly "x-bf": {
         readonly domain: "settings";
         readonly version: 1;
-        readonly settingsSchemaVersion: 28;
+        readonly settingsSchemaVersion: 33;
     };
 };
 export declare const observationDefinitions: readonly [{
@@ -8253,36 +8258,36 @@ export declare const observationDefinitions: readonly [{
     };
 }, {
     readonly id: 151;
-    readonly name: "radio.bleScan";
+    readonly name: "radio.bleDevices";
     readonly role: "measurement";
     readonly subject: "device";
     readonly producer: "device";
     readonly presentation: {
-        readonly displayName: "Radio ble scan";
+        readonly displayName: "Nearby BLE devices";
         readonly description: "BLE scan evidence is distinct from BLE enabled/unlocked status.";
         readonly hiddenByDefault: false;
         readonly formatter: "bleScan";
     };
 }, {
     readonly id: 152;
-    readonly name: "radio.cellScan";
+    readonly name: "radio.cellularEnvironment";
     readonly role: "measurement";
     readonly subject: "device";
     readonly producer: "device";
     readonly presentation: {
-        readonly displayName: "Radio cell scan";
-        readonly description: "Cell scan and registration latency are distinct facts; distinguish passive serving-cell updates from extended scans.";
+        readonly displayName: "Cellular environment";
+        readonly description: "Coherent serving-cell identity, radio technology and signal evidence, with neighbouring or global cells when explicitly requested. Routine tracking reads serving-cell information without an extended cell search.";
         readonly hiddenByDefault: false;
         readonly formatter: "cellScan";
     };
 }, {
     readonly id: 153;
-    readonly name: "radio.wifiScan";
+    readonly name: "radio.wifiAccessPoints";
     readonly role: "measurement";
     readonly subject: "device";
     readonly producer: "device";
     readonly presentation: {
-        readonly displayName: "Radio wifi scan";
+        readonly displayName: "Wi-Fi access points";
         readonly description: "The coherent Wi-Fi scan is positioning evidence; retain an empty successful scan separately from a failed scan.";
         readonly hiddenByDefault: false;
         readonly formatter: "wifiScan";
@@ -8386,7 +8391,7 @@ export declare const observationDefinitions: readonly [{
             readonly label: "Duration";
             readonly format: "duration";
         }];
-        readonly extensibleEnumFields: readonly ["mode"];
+        readonly extensibleEnumFields: readonly ["mode", "state"];
     };
 }, {
     readonly id: 159;
@@ -8957,13 +8962,13 @@ export type WiFiTimeoutCount = number;
  *
  * @maxItems 20
  */
-export type RadioBleScan = BleDevice[];
+export type NearbyBLEDevices = BleDevice[];
 /**
  * The coherent Wi-Fi scan is positioning evidence; retain an empty successful scan separately from a failed scan.
  *
  * @maxItems 20
  */
-export type RadioWifiScan = WifiAccessPoint[];
+export type WiFiAccessPoints = WifiAccessPoint[];
 export interface ObservationValues {
     "agnss.completed"?: AgnssCompleted;
     "agnss.transferTrace"?: AgnssTransferTrace;
@@ -9100,9 +9105,9 @@ export interface ObservationValues {
     "power.wifiScanEntries"?: WiFiScanningEntryCount;
     "power.wifiScanMs"?: WiFiScanningTotalTime;
     "power.wifiTimeouts"?: WiFiTimeoutCount;
-    "radio.bleScan"?: RadioBleScan;
-    "radio.cellScan"?: RadioCellScan;
-    "radio.wifiScan"?: RadioWifiScan;
+    "radio.bleDevices"?: NearbyBLEDevices;
+    "radio.cellularEnvironment"?: CellularEnvironment;
+    "radio.wifiAccessPoints"?: WiFiAccessPoints;
     "system.booted"?: SystemBooted;
     "wifi.scanCompleted"?: WifiScanCompleted;
     "work.completed"?: WorkCompleted;
@@ -9605,9 +9610,9 @@ export interface BleDevice {
     companyId: number;
 }
 /**
- * Cell scan and registration latency are distinct facts; distinguish passive serving-cell updates from extended scans.
+ * Coherent serving-cell identity, radio technology and signal evidence, with neighbouring or global cells when explicitly requested. Routine tracking reads serving-cell information without an extended cell search.
  */
-export interface RadioCellScan {
+export interface CellularEnvironment {
     serving: CellReading;
     rat: "lteM" | "nbIot";
     /**
@@ -9690,7 +9695,7 @@ export interface WorkCompleted {
     activityEntries: ActivityEntries;
     recoveries: RecoveryCounts;
     saturated: boolean;
-    mode: string;
+    mode: number;
 }
 export interface ActivityDurations {
     rrc: number;
@@ -9723,8 +9728,8 @@ export interface RecoveryCounts {
  */
 export interface WorkflowExecution {
     workflowVersion: number;
-    mode: string;
-    state: "idle" | "battery" | "connect" | "cell" | "wifi" | "publish" | "listen" | "gps" | "gpsPublish" | "rest";
+    mode: number;
+    state: string;
     owner: "workflow" | "command" | "update" | "recovery" | "shutdown" | "fault" | "settings" | "charging" | "ble" | "network";
     phase: "entered" | "completed" | "cancelled" | "ownerChanged" | "snapshot";
     outcome: ("done" | "unavailable" | "failed" | "timeout" | "cancelled") | null;
@@ -9941,37 +9946,37 @@ export type BLEAdvertisingRequiresExternalPower = boolean;
  */
 export type BLEAdvertisingInterval = number;
 /**
- * Underlying firmware behavior. Offered tracking modes are cloud-configurable profiles.
+ * Stable integer firmware mode ID: 0, 1 or 2. Each mode’s stages are defined in firmware. Public mode names are mapped to these IDs by the assigned tracking mode catalog.
  */
-export type TrackingMode = string;
+export type FirmwareModeID = number;
 /**
  * Period between tracking reports on confirmed external power.
  */
 export type PoweredReportInterval = number;
 /**
- * Maximum battery idle duration after a standard cycle.
+ * Maximum battery idle duration after a mode 0 cycle, measured from the end of work.
  */
-export type StandardIdleDuration = number;
+export type Mode0IdleDuration = number;
 /**
- * Maximum battery idle duration after a security cycle.
+ * Maximum battery idle duration after a mode 1 cycle, measured from the end of work.
  */
-export type SecurityIdleDuration = number;
+export type Mode1IdleDuration = number;
 /**
- * Maximum battery idle duration after a tracking cycle.
+ * Maximum battery idle duration after a mode 2 cycle, measured from the end of work.
  */
-export type TrackingIdleDuration = number;
+export type Mode2IdleDuration = number;
 /**
- * Minimum rest before movement starts another standard cycle.
+ * Duration after a mode 0 cycle with the accelerometer and its wake interrupt disabled. Firmware re-enables motion detection when this period ends.
  */
-export type StandardMovementRest = number;
+export type Mode0MinimumRest = number;
 /**
- * Minimum rest before movement starts another security cycle.
+ * Duration after a mode 1 cycle with the accelerometer and its wake interrupt disabled. Firmware re-enables motion detection when this period ends.
  */
-export type SecurityMovementRest = number;
+export type Mode1MinimumRest = number;
 /**
- * Minimum rest before movement starts another tracking cycle.
+ * Duration after a mode 2 cycle with the accelerometer and its wake interrupt disabled. Firmware re-enables motion detection when this period ends.
  */
-export type TrackingMovementRest = number;
+export type Mode2MinimumRest = number;
 /**
  * Maximum idle time in PSM before setting the modem offline; capped by the existing idle deadline.
  */
@@ -10116,14 +10121,14 @@ export interface DeviceSettings {
     bleAdvertisingEnabled?: BLEAdvertising;
     bleAdvertisingRequiresExternalPower?: BLEAdvertisingRequiresExternalPower;
     bleAdvertisingIntervalUnits?: BLEAdvertisingInterval;
-    mode?: TrackingMode;
+    mode?: FirmwareModeID;
     poweredReportIntervalSeconds?: PoweredReportInterval;
-    standardIdleSeconds?: StandardIdleDuration;
-    securityIdleSeconds?: SecurityIdleDuration;
-    trackingIdleSeconds?: TrackingIdleDuration;
-    standardMinimumRestSeconds?: StandardMovementRest;
-    securityMinimumRestSeconds?: SecurityMovementRest;
-    trackingMinimumRestSeconds?: TrackingMovementRest;
+    mode0IdleSeconds?: Mode0IdleDuration;
+    mode1IdleSeconds?: Mode1IdleDuration;
+    mode2IdleSeconds?: Mode2IdleDuration;
+    mode0MinimumRestSeconds?: Mode0MinimumRest;
+    mode1MinimumRestSeconds?: Mode1MinimumRest;
+    mode2MinimumRestSeconds?: Mode2MinimumRest;
     psmResidenceSeconds?: PSMResidence;
     commandListenSeconds?: TrackingCommandWindow;
     gnssSearchTimeoutSeconds?: GNSSSearchTimeout;