@bikefinder/sdk 0.1.5 → 0.1.7

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 responses use generated Zod validation. Stream values have generated static types and use the native SignalR decoder; for runtime validation, import `zTrackerDocument` from `@bikefinder/sdk/schemas` and call `.parse(value)`. Both transports reference the same generated payload types. Firestore responses come from the actual C# DTOs in `Firestore/TrackerData.cs` and `Firestore/ResourceData.cs`. The API converts stored data before responding; `readIssues` identifies unusable stored fields. 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. Response validators preserve additional API fields while checking known values, required properties and enums. 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,12 +117,14 @@ Command reads validate stored identity, catalog arguments, artifacts, and execut
 
 ## Supported API consumers
 
-`@bikefinder/sdk@0.1.4` is the supported baseline after the owner-approved prelaunch
-cutover on 2026-11-06. Earlier experimental `@bikefinder/api-client` releases and
-SDK 0.1.0–0.1.3 require a one-time consumer upgrade for current AWS commands,
-settings and observation variants. This explicitly retires the former 2.0.0
-baseline; the `/v1` route version is unchanged. Future breaking changes still
-require an explicit retirement decision or a separate API version.
+`@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
+separate API version.
 
 The tolerant response policy remains in place. Mode availability is an ID list,
 and selected mode IDs are open strings validated against each tracker's cloud
@@ -143,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.
 
-Runtime validation still rejects malformed known data. Applications 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

@@ -5384,9 +5384,7 @@ export declare const observationValueSchema: {
                     readonly type: "boolean";
                 };
                 readonly mode: {
-                    readonly type: "integer";
-                    readonly minimum: 0;
-                    readonly maximum: 2;
+                    readonly type: "string";
                 };
             };
             readonly required: readonly ["completedCount", "trigger", "outcome", "elapsedMs", "activeMs", "activityMs", "activityEntries", "recoveries", "saturated", "mode"];
@@ -5430,13 +5428,10 @@ export declare const observationValueSchema: {
                     readonly maximum: 65535;
                 };
                 readonly mode: {
-                    readonly type: "integer";
-                    readonly minimum: 0;
-                    readonly maximum: 2;
+                    readonly type: "string";
                 };
                 readonly state: {
                     readonly type: "string";
-                    readonly enum: readonly ["idle", "battery", "connect", "cell", "wifi", "publish", "listen", "gps", "gpsPublish", "rest"];
                 };
                 readonly owner: {
                     readonly type: "string";
@@ -5519,7 +5514,7 @@ export declare const observationValueSchema: {
                         readonly label: "Duration";
                         readonly format: "duration";
                     }];
-                    readonly extensibleEnumFields: readonly ["mode"];
+                    readonly extensibleEnumFields: readonly ["mode", "state"];
                 };
             };
         };
@@ -6116,11 +6111,9 @@ 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: "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 type: "string";
+            readonly title: "Tracking mode";
+            readonly description: "Underlying firmware behavior. Offered tracking modes are cloud-configurable profiles.";
         };
         readonly poweredReportIntervalSeconds: {
             readonly type: "integer";
@@ -6129,47 +6122,47 @@ export declare const settingsValueSchema: {
             readonly title: "Powered report interval";
             readonly description: "Period between tracking reports on confirmed external power.";
         };
-        readonly mode0IdleSeconds: {
+        readonly standardIdleSeconds: {
             readonly type: "integer";
             readonly minimum: 60;
             readonly maximum: 604800;
-            readonly title: "Mode 0 idle duration";
-            readonly description: "Maximum battery idle duration after a mode 0 cycle, measured from the end of work.";
+            readonly title: "Standard idle duration";
+            readonly description: "Maximum battery idle duration after a standard cycle.";
         };
-        readonly mode1IdleSeconds: {
+        readonly securityIdleSeconds: {
             readonly type: "integer";
             readonly minimum: 60;
             readonly maximum: 604800;
-            readonly title: "Mode 1 idle duration";
-            readonly description: "Maximum battery idle duration after a mode 1 cycle, measured from the end of work.";
+            readonly title: "Security idle duration";
+            readonly description: "Maximum battery idle duration after a security cycle.";
         };
-        readonly mode2IdleSeconds: {
+        readonly trackingIdleSeconds: {
             readonly type: "integer";
             readonly minimum: 10;
             readonly maximum: 86400;
-            readonly title: "Mode 2 idle duration";
-            readonly description: "Maximum battery idle duration after a mode 2 cycle, measured from the end of work.";
+            readonly title: "Tracking idle duration";
+            readonly description: "Maximum battery idle duration after a tracking cycle.";
         };
-        readonly mode0MinimumRestSeconds: {
+        readonly standardMinimumRestSeconds: {
             readonly type: "integer";
             readonly minimum: 0;
             readonly maximum: 86400;
-            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 title: "Standard movement rest";
+            readonly description: "Minimum rest before movement starts another standard cycle.";
         };
-        readonly mode1MinimumRestSeconds: {
+        readonly securityMinimumRestSeconds: {
             readonly type: "integer";
             readonly minimum: 0;
             readonly maximum: 86400;
-            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 title: "Security movement rest";
+            readonly description: "Minimum rest before movement starts another security cycle.";
         };
-        readonly mode2MinimumRestSeconds: {
+        readonly trackingMinimumRestSeconds: {
             readonly type: "integer";
             readonly minimum: 0;
             readonly maximum: 86400;
-            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 title: "Tracking movement rest";
+            readonly description: "Minimum rest before movement starts another tracking cycle.";
         };
         readonly psmResidenceSeconds: {
             readonly type: "integer";
@@ -6369,7 +6362,7 @@ export declare const settingsValueSchema: {
     readonly "x-bf": {
         readonly domain: "settings";
         readonly version: 1;
-        readonly settingsSchemaVersion: 29;
+        readonly settingsSchemaVersion: 28;
     };
 };
 export declare const observationDefinitions: readonly [{
@@ -8392,7 +8385,7 @@ export declare const observationDefinitions: readonly [{
             readonly label: "Duration";
             readonly format: "duration";
         }];
-        readonly extensibleEnumFields: readonly ["mode"];
+        readonly extensibleEnumFields: readonly ["mode", "state"];
     };
 }, {
     readonly id: 159;
@@ -9696,7 +9689,7 @@ export interface WorkCompleted {
     activityEntries: ActivityEntries;
     recoveries: RecoveryCounts;
     saturated: boolean;
-    mode: number;
+    mode: string;
 }
 export interface ActivityDurations {
     rrc: number;
@@ -9729,8 +9722,8 @@ export interface RecoveryCounts {
  */
 export interface WorkflowExecution {
     workflowVersion: number;
-    mode: number;
-    state: "idle" | "battery" | "connect" | "cell" | "wifi" | "publish" | "listen" | "gps" | "gpsPublish" | "rest";
+    mode: string;
+    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;
@@ -9947,37 +9940,37 @@ export type BLEAdvertisingRequiresExternalPower = boolean;
  */
 export type BLEAdvertisingInterval = number;
 /**
- * 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.
+ * Underlying firmware behavior. Offered tracking modes are cloud-configurable profiles.
  */
-export type FirmwareModeID = number;
+export type TrackingMode = string;
 /**
  * Period between tracking reports on confirmed external power.
  */
 export type PoweredReportInterval = number;
 /**
- * Maximum battery idle duration after a mode 0 cycle, measured from the end of work.
+ * Maximum battery idle duration after a standard cycle.
  */
-export type Mode0IdleDuration = number;
+export type StandardIdleDuration = number;
 /**
- * Maximum battery idle duration after a mode 1 cycle, measured from the end of work.
+ * Maximum battery idle duration after a security cycle.
  */
-export type Mode1IdleDuration = number;
+export type SecurityIdleDuration = number;
 /**
- * Maximum battery idle duration after a mode 2 cycle, measured from the end of work.
+ * Maximum battery idle duration after a tracking cycle.
  */
-export type Mode2IdleDuration = number;
+export type TrackingIdleDuration = number;
 /**
- * Duration after a mode 0 cycle with the accelerometer and its wake interrupt disabled. Firmware re-enables motion detection when this period ends.
+ * Minimum rest before movement starts another standard cycle.
  */
-export type Mode0MinimumRest = number;
+export type StandardMovementRest = number;
 /**
- * Duration after a mode 1 cycle with the accelerometer and its wake interrupt disabled. Firmware re-enables motion detection when this period ends.
+ * Minimum rest before movement starts another security cycle.
  */
-export type Mode1MinimumRest = number;
+export type SecurityMovementRest = number;
 /**
- * Duration after a mode 2 cycle with the accelerometer and its wake interrupt disabled. Firmware re-enables motion detection when this period ends.
+ * Minimum rest before movement starts another tracking cycle.
  */
-export type Mode2MinimumRest = number;
+export type TrackingMovementRest = number;
 /**
  * Maximum idle time in PSM before setting the modem offline; capped by the existing idle deadline.
  */
@@ -10122,14 +10115,14 @@ export interface DeviceSettings {
     bleAdvertisingEnabled?: BLEAdvertising;
     bleAdvertisingRequiresExternalPower?: BLEAdvertisingRequiresExternalPower;
     bleAdvertisingIntervalUnits?: BLEAdvertisingInterval;
-    mode?: FirmwareModeID;
+    mode?: TrackingMode;
     poweredReportIntervalSeconds?: PoweredReportInterval;
-    mode0IdleSeconds?: Mode0IdleDuration;
-    mode1IdleSeconds?: Mode1IdleDuration;
-    mode2IdleSeconds?: Mode2IdleDuration;
-    mode0MinimumRestSeconds?: Mode0MinimumRest;
-    mode1MinimumRestSeconds?: Mode1MinimumRest;
-    mode2MinimumRestSeconds?: Mode2MinimumRest;
+    standardIdleSeconds?: StandardIdleDuration;
+    securityIdleSeconds?: SecurityIdleDuration;
+    trackingIdleSeconds?: TrackingIdleDuration;
+    standardMinimumRestSeconds?: StandardMovementRest;
+    securityMinimumRestSeconds?: SecurityMovementRest;
+    trackingMinimumRestSeconds?: TrackingMovementRest;
     psmResidenceSeconds?: PSMResidence;
     commandListenSeconds?: TrackingCommandWindow;
     gnssSearchTimeoutSeconds?: GNSSSearchTimeout;

package/dist/device-schema.js

@@ -6437,9 +6437,7 @@ export const observationValueSchema = {
                     "type": "boolean"
                 },
                 "mode": {
-                    "type": "integer",
-                    "minimum": 0,
-                    "maximum": 2
+                    "type": "string"
                 }
             },
             "required": [
@@ -6500,24 +6498,10 @@ export const observationValueSchema = {
                     "maximum": 65535
                 },
                 "mode": {
-                    "type": "integer",
-                    "minimum": 0,
-                    "maximum": 2
+                    "type": "string"
                 },
                 "state": {
-                    "type": "string",
-                    "enum": [
-                        "idle",
-                        "battery",
-                        "connect",
-                        "cell",
-                        "wifi",
-                        "publish",
-                        "listen",
-                        "gps",
-                        "gpsPublish",
-                        "rest"
-                    ]
+                    "type": "string"
                 },
                 "owner": {
                     "type": "string",
@@ -6674,7 +6658,8 @@ export const observationValueSchema = {
                         }
                     ],
                     "extensibleEnumFields": [
-                        "mode"
+                        "mode",
+                        "state"
                     ]
                 }
             }
@@ -7391,11 +7376,9 @@ export const settingsValueSchema = {
             "description": "Advertising interval in 0.625 millisecond units. Applied by the peripheral owner independently of LTE connection work."
         },
         "mode": {
-            "type": "integer",
-            "minimum": 0,
-            "maximum": 2,
-            "title": "Firmware mode ID",
-            "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."
+            "type": "string",
+            "title": "Tracking mode",
+            "description": "Underlying firmware behavior. Offered tracking modes are cloud-configurable profiles."
         },
         "poweredReportIntervalSeconds": {
             "type": "integer",
@@ -7404,47 +7387,47 @@ export const settingsValueSchema = {
             "title": "Powered report interval",
             "description": "Period between tracking reports on confirmed external power."
         },
-        "mode0IdleSeconds": {
+        "standardIdleSeconds": {
             "type": "integer",
             "minimum": 60,
             "maximum": 604800,
-            "title": "Mode 0 idle duration",
-            "description": "Maximum battery idle duration after a mode 0 cycle, measured from the end of work."
+            "title": "Standard idle duration",
+            "description": "Maximum battery idle duration after a standard cycle."
         },
-        "mode1IdleSeconds": {
+        "securityIdleSeconds": {
             "type": "integer",
             "minimum": 60,
             "maximum": 604800,
-            "title": "Mode 1 idle duration",
-            "description": "Maximum battery idle duration after a mode 1 cycle, measured from the end of work."
+            "title": "Security idle duration",
+            "description": "Maximum battery idle duration after a security cycle."
         },
-        "mode2IdleSeconds": {
+        "trackingIdleSeconds": {
             "type": "integer",
             "minimum": 10,
             "maximum": 86400,
-            "title": "Mode 2 idle duration",
-            "description": "Maximum battery idle duration after a mode 2 cycle, measured from the end of work."
+            "title": "Tracking idle duration",
+            "description": "Maximum battery idle duration after a tracking cycle."
         },
-        "mode0MinimumRestSeconds": {
+        "standardMinimumRestSeconds": {
             "type": "integer",
             "minimum": 0,
             "maximum": 86400,
-            "title": "Mode 0 minimum rest",
-            "description": "Duration after a mode 0 cycle with the accelerometer and its wake interrupt disabled. Firmware re-enables motion detection when this period ends."
+            "title": "Standard movement rest",
+            "description": "Minimum rest before movement starts another standard cycle."
         },
-        "mode1MinimumRestSeconds": {
+        "securityMinimumRestSeconds": {
             "type": "integer",
             "minimum": 0,
             "maximum": 86400,
-            "title": "Mode 1 minimum rest",
-            "description": "Duration after a mode 1 cycle with the accelerometer and its wake interrupt disabled. Firmware re-enables motion detection when this period ends."
+            "title": "Security movement rest",
+            "description": "Minimum rest before movement starts another security cycle."
         },
-        "mode2MinimumRestSeconds": {
+        "trackingMinimumRestSeconds": {
             "type": "integer",
             "minimum": 0,
             "maximum": 86400,
-            "title": "Mode 2 minimum rest",
-            "description": "Duration after a mode 2 cycle with the accelerometer and its wake interrupt disabled. Firmware re-enables motion detection when this period ends."
+            "title": "Tracking movement rest",
+            "description": "Minimum rest before movement starts another tracking cycle."
         },
         "psmResidenceSeconds": {
             "type": "integer",
@@ -7664,7 +7647,7 @@ export const settingsValueSchema = {
     "x-bf": {
         "domain": "settings",
         "version": 1,
-        "settingsSchemaVersion": 29
+        "settingsSchemaVersion": 28
     }
 };
 export const observationDefinitions = [
@@ -9949,7 +9932,8 @@ export const observationDefinitions = [
                 }
             ],
             "extensibleEnumFields": [
-                "mode"
+                "mode",
+                "state"
             ]
         }
     },