@bikefinder/sdk 0.1.7 → 0.2.0

package/README.md

@@ -50,13 +50,15 @@ 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 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.
+REST calls automatically validate response structure without transforming response JSON. The API uses native Firestore mapping and narrow field converters before responding. Malformed known values fail with `stored_data_invalid`; ordinary document responses no longer carry partial-data `readIssues`. 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`. Unmodeled storage fields are ignored, never forwarded into response extensions. 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 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 use the shared generated union: narrow observation.type before reading its typed value. Current readings expose a nullable typed observation.
 
 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.
 
-AWS staff methods deal with general observation, command and settings resources. Use `requests.readAwsObservations` to select current observation series, `getAwsSettings` to read the singleton settings shadow, and `updateAwsSettings` to patch typed settings with an expected version. The generated `staffRealtime.hub.watchAwsObservations`, `watchAwsCommand` and `watchAwsSettings` methods return native SignalR streams. See the [AWS resource map](../../docs/api/aws.md) for database and command-acceptance semantics.
+Staff diagnostics use the same tracker inventory ID as `getStaffTracker`. Use `requests.readStaffTrackerObservations({path: {id}, query: {series: observationSeriesQuery([{definitionId, subject?}])}})` for current values, `getStaffTrackerSettings` to read settings, and `updateStaffTrackerSettings` to patch typed settings with an expected version. Import `observationSeriesQuery` from this package. These reads use GET; account batches use `readStaffAccounts({query: {ids}})`. `getStaffTrackerCommandCatalog` returns definitions and availability together. The generated `staffRealtime.hub.watchObservations`, `watchCommand(id, operationId)` and `watchSettings` methods return native SignalR streams. Staff tracker pages accept `StaffTrackerPageRequest` with an optional exact `selection`, matching REST filters. See the [tracker diagnostics map](../../docs/api/aws.md) for database, identity and acceptance semantics.
+
+Command and firmware acceptance returns `202` with a `Location` status URL. Recover a command with `getStaffTrackerCommand({path: {id, operationId}})` using the original caller-generated UUID; its numeric hardware request ID is receipt evidence. Do not allocate a new UUID after an uncertain write. SDK 0.2.0 contains intentional prelaunch breaking changes; Support Hub integration remains a separate follow-up.
 
 The runtime requires standard Fetch, Request, Blob, AbortController and `AbortSignal.any`/`throwIfAborted`, plus a WebSocket implementation supported by SignalR. Supply the relevant platform polyfills before creating a client when needed.
 
@@ -73,7 +75,6 @@ From the repository root:
 ```powershell
 dotnet tool restore
 dotnet restore services/api/src/Api.csproj --locked-mode
-dotnet build services/api/src/Api.csproj --no-restore
 npm ci --ignore-scripts
 npm run contract --workspace @bikefinder/sdk
 npm run generate --workspace @bikefinder/sdk
@@ -82,70 +83,41 @@ npm test --workspace @bikefinder/sdk
 npm run build --workspace @bikefinder/sdk
 ```
 
-The pinned .NET tool is configured in `.config/dotnet-tools.json`. Contract export runs the built service locally to retrieve OpenAPI; no Firebase credentials or live requests are needed. Generation fails if either generator fails. Generated source is committed and must be regenerated together. `tsc-alias` resolves generated extensionless imports when compiling the ESM package. The focused tests cover authentication, document fidelity, binary writes, uncertain write responses, native proxy invocation/cancellation and disposal.
+The pinned .NET tool is configured in `.config/dotnet-tools.json`. Contract export uses Microsoft's build-time generator with a mock server and inert configuration; no cloud credentials or listening HTTP server are needed. Ordinary builds do not export the contract. Generation fails if either generator fails. Generated source is committed and must be regenerated together. `tsc-alias` resolves generated extensionless imports when compiling the ESM package. The focused tests cover authentication, typed payloads, binary writes, uncertain write responses, native proxy invocation/cancellation and disposal.
 
 ## Publish
 
-Bump this package's version and the root lockfile. **Publish API client**
-(`publish-client.yml`) runs when the package manifest changes on `main`; it can also be run manually. The workflow checks the generated schemas, runs
-the SDK tests, builds and publishes using GitHub OIDC. It does not deploy AWS
-services and requires no npm token or per-release browser approval.
+Bump this package's version and the root lockfile. Generate, check, test and build locally, then publish with `npm publish --workspace @bikefinder/sdk --access public` when release is authorized. Use the existing local npm authentication; never put a token in the repository. Publishing the package does not deploy the API.
+
+The optional **Publish API client** workflow (`publish-client.yml`) uses GitHub OIDC when Actions minutes are available. Local releases do not depend on that workflow.
 
 The npm package's trusted publisher must name organization `bikefinder`,
 repository `aws_cloud`, workflow `publish-client.yml`, with direct `npm publish`
 allowed and no environment name. This account setup is performed once in the
 package's npm settings. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
 
-Command HTTP and SignalR methods return `AwsCommand`. Requests, broker publication and `execution.accepted`/`execution.completed` are distinct stages on that resource. The client no longer joins command-result observations or exposes a separate results endpoint. A completion includes a typed response data union and authenticated receipt time.
+Command HTTP reads return `AwsCommand`; command subscriptions return `AwsCommandUpdate` with a command or an explicit read issue. Requests, broker publication and `execution.accepted`/`execution.completed` are distinct stages on that resource. There is no separate command-result observation endpoint. A completion includes a typed response data union and authenticated receipt time.
 
 ## Observation timestamps
 
-Observation history and current readings expose `measuredAt` and `receivedAt`.
+Observation history exposes `measuredAt` and `receivedAt`. Current readings expose these on `reading.observation`, which is null when no current value exists.
 Observation IDs are opaque server-generated references. They carry no boot or
 sequence information. Distinct rows can have identical capture timestamps;
 clients must not infer physical ordering from their IDs. History can contain
 separate rows for an at-least-once delivery of the same reading.
 
-The source contract has changed after SDK 1.0.14. Before deploying consumers,
-publish the next SDK release and update their registry dependency and lockfile.
-Local validation can use the newly built SDK; keep that temporary override out
-of committed consumer dependencies.
-
 Settings responses use the API-owned `AwsSettingsSnapshot` for HTTP and SignalR: read typed `desired`, `reported`, `application`, capabilities and schema/version evidence directly. `readIssues` identifies stored values the API could not interpret. The resource does not expose the underlying AWS shadow document or its independent owners. Settings fields and bounds come from the same protocol registry as the firmware.
 
 Command reads validate stored identity, catalog arguments, artifacts, and execution evidence. A malformed single-command read returns `command_unreadable`; command pages keep valid items and attach per-request `readIssues`. Both command streams emit `AwsCommandUpdate` with either a validated `command` or a `readIssue`, allowing subsequent events to continue.
 
-## Supported API consumers
-
-`@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
-catalog. Adding or removing catalog choices does not require another SDK release.
-
-API CI installs the oldest supported immutable npm release selected in
-`tools/check-api-compatibility.mjs`. It validates freshly server-serialized
-Firestore, command and settings fixtures with that published reader, exercises
-its HTTP transformer and stream-message schema, and checks additions at envelope
-and nested-settings levels. The package includes its exported OpenAPI contract
-under `@bikefinder/sdk/openapi` for the comparison.
-
-The `compatibility` job runs oasdiff against that published contract, applying the
-same tolerant-read policy to both documents. Request validation stays strict.
-The gate rejects removed endpoints or response fields, incompatible types and
-bounds, newly required inputs, and incompatible enum changes. Add a separate API
-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 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.
+## Current API contract
+
+The API has no external consumers. The owner approved breaking changes during this simplification; the published 0.1.x SDK is not a compatibility baseline. Update the API and generated SDK together. No legacy response wrappers or parallel versioned route tree are retained.
+
+Observation history and events use the shared typed Observation union, discriminated by its catalog-defined type string. Current readings contain the selected series and a nullable typed CurrentObservation. Null means that no current reading exists. HTTP and SignalR use these same models.
+
+Request validation stays strict and response validation checks known fields without dropping additions. Mode IDs remain open strings from catalog data. Protocol schemas still own value bounds, subject rules, conditional constraints and presentation metadata.
+
+Contract export uses Microsoft.Extensions.ApiDescription.Server through the contract script. It executes startup with inert configuration and disables cloud event workers; it does not open a listening HTTP server or need cloud credentials. Ordinary builds do not rewrite the checked-in contract.
+
+Run SDK generation, type checks, runtime contract tests and the build together before release. Publishing the SDK and deploying the API are separate local operations; generated code does not itself publish or deploy anything.

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,7 +5430,9 @@ 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";
@@ -6111,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";
@@ -6122,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";
@@ -6362,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 [{
@@ -8252,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";
@@ -8956,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;
@@ -9099,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;
@@ -9604,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";
     /**
@@ -9689,7 +9695,7 @@ export interface WorkCompleted {
     activityEntries: ActivityEntries;
     recoveries: RecoveryCounts;
     saturated: boolean;
-    mode: string;
+    mode: number;
 }
 export interface ActivityDurations {
     rrc: number;
@@ -9722,7 +9728,7 @@ export interface RecoveryCounts {
  */
 export interface WorkflowExecution {
     workflowVersion: number;
-    mode: string;
+    mode: number;
     state: string;
     owner: "workflow" | "command" | "update" | "recovery" | "shutdown" | "fault" | "settings" | "charging" | "ble" | "network";
     phase: "entered" | "completed" | "cancelled" | "ownerChanged" | "snapshot";
@@ -9940,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.
  */
@@ -10115,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;