npm - @mentra/cloud-protocol - Versions diffs - 3.3.0-dev.906 → 3.3.0-dev.909 - Mend

@mentra/cloud-protocol 3.3.0-dev.906 → 3.3.0-dev.909

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/cloud-protocol",
-  "version": "3.3.0-dev.906",
+  "version": "3.3.0-dev.909",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {

package/src/__fixtures__/fleet/ack-invalid-reason-on-accepted.json ADDED Viewed

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "results": [
+    {
+      "index": 0,
+      "recordId": "rec-x-0002",
+      "status": "accepted",
+      "reasonCode": "schema_invalid"
+    }
+  ]
+}

package/src/__fixtures__/fleet/ack-invalid-rejected-without-reason.json ADDED Viewed

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 1,
+  "results": [
+    {
+      "index": 0,
+      "recordId": "rec-x-0001",
+      "status": "rejected"
+    }
+  ]
+}

package/src/__fixtures__/fleet/ack-invalid-unknown-error.json ADDED Viewed

@@ -0,0 +1,3 @@
+{
+  "error": "fleet_broken"
+}

package/src/__fixtures__/fleet/ack-valid-mixed.json ADDED Viewed

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "results": [
+    {
+      "index": 0,
+      "recordId": "rec-mix-0001",
+      "status": "accepted"
+    },
+    {
+      "index": 1,
+      "recordId": "rec-mix-0002",
+      "status": "duplicate"
+    },
+    {
+      "index": 2,
+      "recordId": "rec-mix-0003",
+      "status": "retryable",
+      "retryAfterSeconds": 30
+    },
+    {
+      "index": 3,
+      "recordId": "rec-mix-0004",
+      "status": "rejected",
+      "reasonCode": "content_mismatch"
+    },
+    {
+      "index": 4,
+      "recordId": "rec-mix-0005",
+      "status": "rejected",
+      "reasonCode": "outside_replay_window"
+    }
+  ]
+}

package/src/__fixtures__/fleet/ack-valid-not-installed.json ADDED Viewed

@@ -0,0 +1,3 @@
+{
+  "error": "fleet_not_installed"
+}

package/src/__fixtures__/fleet/ack-valid-unavailable.json ADDED Viewed

@@ -0,0 +1,4 @@
+{
+  "error": "fleet_unavailable",
+  "retryAfterSeconds": 60
+}

package/src/__fixtures__/fleet/report-invalid-battery-zero-when-unsupported.json ADDED Viewed

@@ -0,0 +1,55 @@
+{
+  "schemaVersion": 1,
+  "records": [
+    {
+      "schemaVersion": 1,
+      "recordId": "rec-bad-0007",
+      "phoneDeviceId": "phone-7f3a91",
+      "collectorSessionId": "cs-20261013-01",
+      "sequence": 0,
+      "observedAt": "2026-10-13T11:00:00Z",
+      "capabilities": [
+        "glasses_connection",
+        "glasses_battery",
+        "glasses_versions",
+        "miniapp_execution",
+        "engine_active"
+      ],
+      "kind": "snapshot",
+      "deviceBinding": {
+        "kind": "serial",
+        "manufacturer": "Mentra",
+        "product": "mentra_live",
+        "serial": "ML2A-0042-7731"
+      },
+      "payload": {
+        "phone": {
+          "model": "Pixel 8",
+          "os": "android",
+          "osVersion": "15",
+          "appVersion": "3.4.0",
+          "appBuild": "3400",
+          "engineVersion": "1.12.0",
+          "sdkVersion": "0.9.2"
+        },
+        "glasses": {
+          "model": "mentra_live",
+          "firmware": {
+            "apk": "1.7.3",
+            "mtk": "2.1.0",
+            "bes": "0.8.5"
+          },
+          "connection": {
+            "state": "connected",
+            "observedAt": "2026-10-13T11:00:00Z"
+          },
+          "battery": {
+            "state": "unsupported",
+            "observedAt": "2026-10-13T11:00:00Z",
+            "level": 0
+          }
+        }
+      }
+    }
+  ]
+}

package/src/__fixtures__/fleet/report-invalid-email-identity.json ADDED Viewed

@@ -0,0 +1,57 @@
+{
+  "schemaVersion": 1,
+  "records": [
+    {
+      "schemaVersion": 1,
+      "recordId": "rec-bad-0002",
+      "phoneDeviceId": "phone-7f3a91",
+      "collectorSessionId": "cs-20261013-01",
+      "sequence": 0,
+      "observedAt": "2026-10-13T11:00:00Z",
+      "capabilities": [
+        "glasses_connection",
+        "glasses_battery",
+        "glasses_versions",
+        "miniapp_execution",
+        "engine_active"
+      ],
+      "kind": "snapshot",
+      "deviceBinding": {
+        "kind": "serial",
+        "manufacturer": "Mentra",
+        "product": "mentra_live",
+        "serial": "ML2A-0042-7731"
+      },
+      "payload": {
+        "phone": {
+          "model": "Pixel 8",
+          "os": "android",
+          "osVersion": "15",
+          "appVersion": "3.4.0",
+          "appBuild": "3400",
+          "engineVersion": "1.12.0",
+          "sdkVersion": "0.9.2"
+        },
+        "glasses": {
+          "model": "mentra_live",
+          "firmware": {
+            "apk": "1.7.3",
+            "mtk": "2.1.0",
+            "bes": "0.8.5"
+          },
+          "connection": {
+            "state": "connected",
+            "observedAt": "2026-10-13T11:00:00Z"
+          },
+          "battery": {
+            "state": "measured",
+            "observedAt": "2026-10-13T11:00:00Z",
+            "level": 76,
+            "charging": false
+          }
+        }
+      },
+      "email": "someone@example.com"
+    }
+  ]
+}

package/src/__fixtures__/fleet/report-invalid-empty-batch.json ADDED Viewed

@@ -0,0 +1,4 @@
+{
+  "schemaVersion": 1,
+  "records": []
+}

package/src/__fixtures__/fleet/report-invalid-execution-without-package-name.json ADDED Viewed

@@ -0,0 +1,32 @@
+{
+  "schemaVersion": 1,
+  "records": [
+    {
+      "schemaVersion": 1,
+      "recordId": "rec-bad-0005",
+      "phoneDeviceId": "phone-7f3a91",
+      "collectorSessionId": "cs-20261013-01",
+      "sequence": 1,
+      "observedAt": "2026-10-13T11:03:10Z",
+      "capabilities": [
+        "glasses_connection",
+        "glasses_battery",
+        "glasses_versions",
+        "miniapp_execution",
+        "engine_active"
+      ],
+      "kind": "usage_checkpoint",
+      "payload": {
+        "sessions": [
+          {
+            "activity": "miniapp_execution",
+            "activitySessionId": "act-8d02",
+            "startedAt": "2026-10-13T11:02:10Z",
+            "elapsedMs": 60000,
+            "ended": false
+          }
+        ]
+      }
+    }
+  ]
+}

package/src/__fixtures__/fleet/report-invalid-missing-record-id.json ADDED Viewed

@@ -0,0 +1,55 @@
+{
+  "schemaVersion": 1,
+  "records": [
+    {
+      "schemaVersion": 1,
+      "phoneDeviceId": "phone-7f3a91",
+      "collectorSessionId": "cs-20261013-01",
+      "sequence": 1,
+      "observedAt": "2026-10-13T11:00:00Z",
+      "capabilities": [
+        "glasses_connection",
+        "glasses_battery",
+        "glasses_versions",
+        "miniapp_execution",
+        "engine_active"
+      ],
+      "kind": "snapshot",
+      "deviceBinding": {
+        "kind": "serial",
+        "manufacturer": "Mentra",
+        "product": "mentra_live",
+        "serial": "ML2A-0042-7731"
+      },
+      "payload": {
+        "phone": {
+          "model": "Pixel 8",
+          "os": "android",
+          "osVersion": "15",
+          "appVersion": "3.4.0",
+          "appBuild": "3400",
+          "engineVersion": "1.12.0",
+          "sdkVersion": "0.9.2"
+        },
+        "glasses": {
+          "model": "mentra_live",
+          "firmware": {
+            "apk": "1.7.3",
+            "mtk": "2.1.0",
+            "bes": "0.8.5"
+          },
+          "connection": {
+            "state": "connected",
+            "observedAt": "2026-10-13T11:00:00Z"
+          },
+          "battery": {
+            "state": "measured",
+            "observedAt": "2026-10-13T11:00:00Z",
+            "level": 76,
+            "charging": false
+          }
+        }
+      }
+    }
+  ]
+}

package/src/__fixtures__/fleet/report-invalid-negative-elapsed.json ADDED Viewed

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "records": [
+    {
+      "schemaVersion": 1,
+      "recordId": "rec-bad-0003",
+      "phoneDeviceId": "phone-7f3a91",
+      "collectorSessionId": "cs-20261013-01",
+      "sequence": 1,
+      "observedAt": "2026-10-13T11:03:10Z",
+      "capabilities": [
+        "glasses_connection",
+        "glasses_battery",
+        "glasses_versions",
+        "miniapp_execution",
+        "engine_active"
+      ],
+      "kind": "usage_checkpoint",
+      "payload": {
+        "sessions": [
+          {
+            "activity": "miniapp_execution",
+            "activitySessionId": "act-8d02",
+            "packageName": "com.mentra.notes",
+            "startedAt": "2026-10-13T11:02:10Z",
+            "elapsedMs": -5,
+            "ended": false
+          }
+        ]
+      }
+    }
+  ]
+}

package/src/__fixtures__/fleet/report-invalid-offset-time.json ADDED Viewed

@@ -0,0 +1,56 @@
+{
+  "schemaVersion": 1,
+  "records": [
+    {
+      "schemaVersion": 1,
+      "recordId": "rec-bad-0001",
+      "phoneDeviceId": "phone-7f3a91",
+      "collectorSessionId": "cs-20261013-01",
+      "sequence": 0,
+      "observedAt": "2026-10-13T19:00:00+08:00",
+      "capabilities": [
+        "glasses_connection",
+        "glasses_battery",
+        "glasses_versions",
+        "miniapp_execution",
+        "engine_active"
+      ],
+      "kind": "snapshot",
+      "deviceBinding": {
+        "kind": "serial",
+        "manufacturer": "Mentra",
+        "product": "mentra_live",
+        "serial": "ML2A-0042-7731"
+      },
+      "payload": {
+        "phone": {
+          "model": "Pixel 8",
+          "os": "android",
+          "osVersion": "15",
+          "appVersion": "3.4.0",
+          "appBuild": "3400",
+          "engineVersion": "1.12.0",
+          "sdkVersion": "0.9.2"
+        },
+        "glasses": {
+          "model": "mentra_live",
+          "firmware": {
+            "apk": "1.7.3",
+            "mtk": "2.1.0",
+            "bes": "0.8.5"
+          },
+          "connection": {
+            "state": "connected",
+            "observedAt": "2026-10-13T11:00:00Z"
+          },
+          "battery": {
+            "state": "measured",
+            "observedAt": "2026-10-13T11:00:00Z",
+            "level": 76,
+            "charging": false
+          }
+        }
+      }
+    }
+  ]
+}

package/src/__fixtures__/fleet/report-invalid-photo-without-operation-id.json ADDED Viewed

@@ -0,0 +1,30 @@
+{
+  "schemaVersion": 1,
+  "records": [
+    {
+      "schemaVersion": 1,
+      "recordId": "rec-bad-0006",
+      "phoneDeviceId": "phone-7f3a91",
+      "collectorSessionId": "cs-20261013-01",
+      "sequence": 3,
+      "observedAt": "2026-10-13T11:04:00Z",
+      "capabilities": [
+        "glasses_connection",
+        "glasses_battery",
+        "glasses_versions",
+        "miniapp_execution",
+        "engine_active"
+      ],
+      "kind": "photo_operation",
+      "deviceBinding": {
+        "kind": "serial",
+        "manufacturer": "Mentra",
+        "product": "mentra_live",
+        "serial": "ML2A-0042-7731"
+      },
+      "payload": {
+        "stage": "captured"
+      }
+    }
+  ]
+}

package/src/__fixtures__/fleet/report-valid-batch-mixed.json ADDED Viewed

@@ -0,0 +1,172 @@
+{
+  "schemaVersion": 1,
+  "records": [
+    {
+      "schemaVersion": 1,
+      "recordId": "rec-mix-0001",
+      "phoneDeviceId": "phone-7f3a91",
+      "collectorSessionId": "cs-20261013-01",
+      "sequence": 10,
+      "observedAt": "2026-10-13T11:00:00Z",
+      "capabilities": [
+        "glasses_connection",
+        "glasses_battery",
+        "glasses_versions",
+        "miniapp_execution",
+        "engine_active"
+      ],
+      "kind": "snapshot",
+      "deviceBinding": {
+        "kind": "serial",
+        "manufacturer": "Mentra",
+        "product": "mentra_live",
+        "serial": "ML2A-0042-7731"
+      },
+      "payload": {
+        "phone": {
+          "model": "Pixel 8",
+          "os": "android",
+          "osVersion": "15",
+          "appVersion": "3.4.0",
+          "appBuild": "3400",
+          "engineVersion": "1.12.0",
+          "sdkVersion": "0.9.2"
+        },
+        "glasses": {
+          "model": "mentra_live",
+          "firmware": {
+            "apk": "1.7.3",
+            "mtk": "2.1.0",
+            "bes": "0.8.5"
+          },
+          "connection": {
+            "state": "connected",
+            "observedAt": "2026-10-13T11:00:00Z"
+          },
+          "battery": {
+            "state": "measured",
+            "observedAt": "2026-10-13T11:00:00Z",
+            "level": 76,
+            "charging": false
+          }
+        }
+      }
+    },
+    {
+      "schemaVersion": 1,
+      "recordId": "rec-mix-0002",
+      "phoneDeviceId": "phone-7f3a91",
+      "collectorSessionId": "cs-20261013-01",
+      "sequence": 11,
+      "observedAt": "2026-10-13T11:02:10Z",
+      "capabilities": [
+        "glasses_connection",
+        "glasses_battery",
+        "glasses_versions",
+        "miniapp_execution",
+        "engine_active"
+      ],
+      "kind": "miniapp_launch",
+      "payload": {
+        "packageName": "com.mentra.notes",
+        "miniappName": "Mentra Notes",
+        "versionName": "2.0.1",
+        "start": "user",
+        "outcome": "started"
+      }
+    },
+    {
+      "schemaVersion": 1,
+      "recordId": "rec-mix-0003",
+      "phoneDeviceId": "phone-7f3a91",
+      "collectorSessionId": "cs-20261013-01",
+      "sequence": 12,
+      "observedAt": "2026-10-13T11:03:10Z",
+      "capabilities": [
+        "glasses_connection",
+        "glasses_battery",
+        "glasses_versions",
+        "miniapp_execution",
+        "engine_active"
+      ],
+      "kind": "usage_checkpoint",
+      "payload": {
+        "sessions": [
+          {
+            "activity": "glasses_connection",
+            "activitySessionId": "act-conn-01",
+            "deviceBinding": {
+              "kind": "serial",
+              "manufacturer": "Mentra",
+              "product": "mentra_live",
+              "serial": "ML2A-0042-7731"
+            },
+            "startedAt": "2026-10-13T10:59:00Z",
+            "elapsedMs": 250000,
+            "ended": false
+          },
+          {
+            "activity": "miniapp_execution",
+            "activitySessionId": "act-8d02",
+            "packageName": "com.mentra.notes",
+            "startedAt": "2026-10-13T11:02:10Z",
+            "elapsedMs": 60000,
+            "ended": false
+          }
+        ]
+      }
+    },
+    {
+      "schemaVersion": 1,
+      "recordId": "rec-mix-0004",
+      "phoneDeviceId": "phone-7f3a91",
+      "collectorSessionId": "cs-20261013-01",
+      "sequence": 13,
+      "observedAt": "2026-10-13T11:04:00Z",
+      "capabilities": [
+        "glasses_connection",
+        "glasses_battery",
+        "glasses_versions",
+        "miniapp_execution",
+        "engine_active"
+      ],
+      "kind": "photo_operation",
+      "operationId": "op-photo-41c9",
+      "deviceBinding": {
+        "kind": "serial",
+        "manufacturer": "Mentra",
+        "product": "mentra_live",
+        "serial": "ML2A-0042-7731"
+      },
+      "payload": {
+        "stage": "requested"
+      }
+    },
+    {
+      "schemaVersion": 1,
+      "recordId": "rec-mix-0005",
+      "phoneDeviceId": "phone-7f3a91",
+      "collectorSessionId": "cs-20261013-01",
+      "sequence": 14,
+      "observedAt": "2026-10-13T11:04:02Z",
+      "capabilities": [
+        "glasses_connection",
+        "glasses_battery",
+        "glasses_versions",
+        "miniapp_execution",
+        "engine_active"
+      ],
+      "kind": "photo_operation",
+      "operationId": "op-photo-41c9",
+      "deviceBinding": {
+        "kind": "serial",
+        "manufacturer": "Mentra",
+        "product": "mentra_live",
+        "serial": "ML2A-0042-7731"
+      },
+      "payload": {
+        "stage": "captured"
+      }
+    }
+  ]
+}

package/src/__fixtures__/fleet/report-valid-coverage-gap.json ADDED Viewed

@@ -0,0 +1,27 @@
+{
+  "schemaVersion": 1,
+  "records": [
+    {
+      "schemaVersion": 1,
+      "recordId": "rec-gap-0001",
+      "phoneDeviceId": "phone-7f3a91",
+      "collectorSessionId": "cs-20261013-01",
+      "sequence": 9,
+      "observedAt": "2026-10-13T12:00:00Z",
+      "capabilities": [
+        "glasses_connection",
+        "glasses_battery",
+        "glasses_versions",
+        "miniapp_execution",
+        "engine_active"
+      ],
+      "kind": "coverage_gap",
+      "payload": {
+        "reason": "queue_dropped",
+        "from": "2026-10-13T11:20:00Z",
+        "to": "2026-10-13T11:55:00Z",
+        "droppedRecordCount": 31
+      }
+    }
+  ]
+}

package/src/__fixtures__/fleet/report-valid-miniapp-launch.json ADDED Viewed

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": 1,
+  "records": [
+    {
+      "schemaVersion": 1,
+      "recordId": "rec-launch-0001",
+      "phoneDeviceId": "phone-7f3a91",
+      "collectorSessionId": "cs-20261013-01",
+      "sequence": 1,
+      "observedAt": "2026-10-13T11:02:10Z",
+      "capabilities": [
+        "glasses_connection",
+        "glasses_battery",
+        "glasses_versions",
+        "miniapp_execution",
+        "engine_active"
+      ],
+      "kind": "miniapp_launch",
+      "payload": {
+        "packageName": "com.acme.inventory",
+        "miniappName": "Acme Inventory",
+        "versionName": "2.0.1",
+        "start": "user",
+        "outcome": "started"
+      }
+    }
+  ]
+}

package/src/__fixtures__/fleet/report-valid-photo-operation.json ADDED Viewed

@@ -0,0 +1,25 @@
+{
+  "schemaVersion": 1,
+  "records": [
+    {
+      "schemaVersion": 1,
+      "recordId": "rec-photo-0001",
+      "phoneDeviceId": "phone-7f3a91",
+      "collectorSessionId": "cs-20261013-01",
+      "sequence": 3,
+      "observedAt": "2026-10-13T11:04:00Z",
+      "capabilities": ["glasses_connection", "photo_operations"],
+      "kind": "photo_operation",
+      "operationId": "op-photo-41c9",
+      "deviceBinding": {
+        "kind": "serial",
+        "manufacturer": "Mentra",
+        "product": "mentra_live",
+        "serial": "ML2A-0042-7731"
+      },
+      "payload": {
+        "stage": "captured"
+      }
+    }
+  ]
+}

package/src/__fixtures__/fleet/report-valid-snapshot-provisional.json ADDED Viewed

@@ -0,0 +1,53 @@
+{
+  "schemaVersion": 1,
+  "records": [
+    {
+      "schemaVersion": 1,
+      "recordId": "rec-snap-0002",
+      "phoneDeviceId": "phone-7f3a91",
+      "collectorSessionId": "cs-20261013-01",
+      "sequence": 0,
+      "observedAt": "2026-10-13T11:00:00Z",
+      "capabilities": [
+        "glasses_connection",
+        "glasses_battery",
+        "glasses_versions",
+        "miniapp_execution",
+        "engine_active"
+      ],
+      "kind": "snapshot",
+      "deviceBinding": {
+        "kind": "provisional",
+        "bindingId": "bind-5c21e0",
+        "product": "mentra_live"
+      },
+      "payload": {
+        "phone": {
+          "model": "Pixel 8",
+          "os": "android",
+          "osVersion": "15",
+          "appVersion": "3.4.0",
+          "appBuild": "3400",
+          "engineVersion": "1.12.0",
+          "sdkVersion": "0.9.2"
+        },
+        "glasses": {
+          "model": "mentra_live",
+          "firmware": {
+            "apk": "1.7.3",
+            "mtk": "2.1.0",
+            "bes": "0.8.5"
+          },
+          "connection": {
+            "state": "connected",
+            "observedAt": "2026-10-13T11:00:00Z"
+          },
+          "battery": {
+            "state": "unsupported",
+            "observedAt": "2026-10-13T11:00:00Z"
+          }
+        }
+      }
+    }
+  ]
+}

package/src/__fixtures__/fleet/report-valid-snapshot.json ADDED Viewed

@@ -0,0 +1,56 @@
+{
+  "schemaVersion": 1,
+  "records": [
+    {
+      "schemaVersion": 1,
+      "recordId": "rec-snap-0001",
+      "phoneDeviceId": "phone-7f3a91",
+      "collectorSessionId": "cs-20261013-01",
+      "sequence": 0,
+      "observedAt": "2026-10-13T11:00:00Z",
+      "capabilities": [
+        "glasses_connection",
+        "glasses_battery",
+        "glasses_versions",
+        "miniapp_execution",
+        "engine_active"
+      ],
+      "kind": "snapshot",
+      "deviceBinding": {
+        "kind": "serial",
+        "manufacturer": "Mentra",
+        "product": "mentra_live",
+        "serial": "ML2A-0042-7731"
+      },
+      "payload": {
+        "phone": {
+          "model": "Pixel 8",
+          "os": "android",
+          "osVersion": "15",
+          "appVersion": "3.4.0",
+          "appBuild": "3400",
+          "engineVersion": "1.12.0",
+          "sdkVersion": "0.9.2"
+        },
+        "glasses": {
+          "model": "mentra_live",
+          "firmware": {
+            "apk": "1.7.3",
+            "mtk": "2.1.0",
+            "bes": "0.8.5"
+          },
+          "connection": {
+            "state": "connected",
+            "observedAt": "2026-10-13T11:00:00Z"
+          },
+          "battery": {
+            "state": "measured",
+            "observedAt": "2026-10-13T11:00:00Z",
+            "level": 76,
+            "charging": false
+          }
+        }
+      }
+    }
+  ]
+}

package/src/__fixtures__/fleet/report-valid-usage-checkpoint.json ADDED Viewed

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "records": [
+    {
+      "schemaVersion": 1,
+      "recordId": "rec-cp-0001",
+      "phoneDeviceId": "phone-7f3a91",
+      "collectorSessionId": "cs-20261013-01",
+      "sequence": 2,
+      "observedAt": "2026-10-13T11:03:10Z",
+      "capabilities": [
+        "glasses_connection",
+        "glasses_battery",
+        "glasses_versions",
+        "miniapp_execution",
+        "engine_active"
+      ],
+      "kind": "usage_checkpoint",
+      "payload": {
+        "sessions": [
+          {
+            "activity": "miniapp_execution",
+            "activitySessionId": "act-8d02",
+            "packageName": "com.mentra.notes",
+            "startedAt": "2026-10-13T11:02:10Z",
+            "elapsedMs": 60000,
+            "ended": false
+          }
+        ]
+      }
+    }
+  ]
+}

package/src/__fixtures__/fleet/report-valid-usage-packed.json ADDED Viewed

@@ -0,0 +1,62 @@
+{
+  "schemaVersion": 1,
+  "records": [
+    {
+      "schemaVersion": 1,
+      "recordId": "rec-pack-0001",
+      "phoneDeviceId": "phone-7f3a91",
+      "collectorSessionId": "cs-20261013-01",
+      "sequence": 4,
+      "observedAt": "2026-10-13T11:03:10Z",
+      "capabilities": ["glasses_connection", "miniapp_execution", "app_foreground", "engine_active"],
+      "kind": "usage_checkpoint",
+      "payload": {
+        "sessions": [
+          {
+            "activity": "glasses_connection",
+            "activitySessionId": "act-conn-01",
+            "deviceBinding": {
+              "kind": "serial",
+              "manufacturer": "Mentra",
+              "product": "mentra_live",
+              "serial": "ML2A-0042-7731"
+            },
+            "startedAt": "2026-10-13T10:59:00Z",
+            "elapsedMs": 250000,
+            "ended": false
+          },
+          {
+            "activity": "miniapp_execution",
+            "activitySessionId": "act-8d02",
+            "packageName": "com.mentra.notes",
+            "startedAt": "2026-10-13T11:02:10Z",
+            "elapsedMs": 60000,
+            "ended": false
+          },
+          {
+            "activity": "miniapp_execution",
+            "activitySessionId": "act-8c91",
+            "packageName": "com.acme.inventory",
+            "startedAt": "2026-10-13T11:00:30Z",
+            "elapsedMs": 120000,
+            "ended": true
+          },
+          {
+            "activity": "app_foreground",
+            "activitySessionId": "act-fg-01",
+            "startedAt": "2026-10-13T10:58:30Z",
+            "elapsedMs": 280000,
+            "ended": false
+          },
+          {
+            "activity": "engine_active",
+            "activitySessionId": "act-eng-01",
+            "startedAt": "2026-10-13T08:00:00Z",
+            "elapsedMs": 10990000,
+            "ended": false
+          }
+        ]
+      }
+    }
+  ]
+}

package/src/fleet.ts ADDED Viewed

@@ -0,0 +1,245 @@
+/**
+ * @fileoverview The Fleet report and acknowledgement contract.
+ *
+ * The Mentra App reports what a phone and its glasses did to the organization's Fleet service (MFM), through the
+ * phone's own Core. The reporter (via `@mentra/cloud-client`) and MFM both parse with these schemas, so this file is
+ * the one definition of what may cross that wire.
+ *
+ * Records are validated one at a time. The envelope accepts any record shape so that one bad record is rejected on
+ * its own, and never strands the rest of its batch.
+ */
+import {z} from "zod"
+export const FLEET_SCHEMA_VERSION = 1 as const
+export const FLEET_LIMITS = {
+  maxRecordsPerBatch: 500,
+  maxBatchBytes: 1_048_576,
+  maxSessionsPerCheckpoint: 32,
+  maxSessionElapsedMs: 7 * 24 * 60 * 60 * 1000,
+  phoneQueueMaxRecords: 10_000,
+  phoneQueueMaxAgeMs: 7 * 24 * 60 * 60 * 1000,
+  replayWindowMs: 14 * 24 * 60 * 60 * 1000,
+  maxFutureSkewMs: 5 * 60 * 1000,
+} as const
+const FleetId = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[A-Za-z0-9._:-]+$/)
+const FLEET_UTC_TIME = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d{1,3}))?Z$/
+/**
+ * Whether `value` names a real instant. `Date.parse` alone is not enough: it normalizes a calendar-invalid date (such
+ * as `2025-02-30`) to a later instant, and accepts `24:00:00`. So the parsed instant is formatted back and must
+ * reproduce every field of the input, with a missing or short fraction read as milliseconds.
+ */
+function isRoundTripUtcTime(value: string): boolean {
+  const match = FLEET_UTC_TIME.exec(value)
+  if (!match) return false
+  const instant = Date.parse(value)
+  if (Number.isNaN(instant)) return false
+  return new Date(instant).toISOString() === `${match[1]}.${(match[2] ?? "").padEnd(3, "0")}Z`
+}
+/** RFC 3339 UTC with a `Z`; a numeric offset, a calendar-invalid date, `24:00:00` and a leap second are refused. */
+const FleetUtcTime = z.string().regex(FLEET_UTC_TIME).refine(isRoundTripUtcTime, "not a date")
+const FleetText = z.string().min(1).max(128)
+export const FleetDeviceBindingSchema = z.discriminatedUnion("kind", [
+  z.object({kind: z.literal("serial"), manufacturer: FleetText, product: FleetText, serial: FleetText}).strict(),
+  z.object({kind: z.literal("provisional"), bindingId: FleetId, product: FleetText}).strict(),
+])
+export const FLEET_CAPABILITIES = [
+  "glasses_connection",
+  "glasses_battery",
+  "glasses_versions",
+  "miniapp_execution",
+  "app_foreground",
+  "engine_active",
+  "photo_operations",
+] as const
+const Battery = z.discriminatedUnion("state", [
+  z
+    .object({
+      state: z.literal("measured"),
+      observedAt: FleetUtcTime,
+      level: z.number().int().min(0).max(100),
+      charging: z.boolean().optional(),
+    })
+    .strict(),
+  z.object({state: z.literal("unsupported"), observedAt: FleetUtcTime}).strict(),
+  z.object({state: z.literal("unknown"), observedAt: FleetUtcTime}).strict(),
+])
+export const FleetSnapshotPayloadSchema = z
+  .object({
+    phone: z
+      .object({
+        model: FleetText.optional(),
+        os: z.enum(["ios", "android"]),
+        osVersion: FleetText,
+        appVersion: FleetText,
+        appBuild: FleetText,
+        engineVersion: FleetText.optional(),
+        sdkVersion: FleetText.optional(),
+      })
+      .strict(),
+    glasses: z
+      .object({
+        model: FleetText,
+        firmware: z
+          .object({
+            apk: FleetText.optional(),
+            mtk: FleetText.optional(),
+            bes: FleetText.optional(),
+            os: FleetText.optional(),
+          })
+          .strict()
+          .optional(),
+        connection: z
+          .object({state: z.enum(["connected", "disconnected", "connecting", "unknown"]), observedAt: FleetUtcTime})
+          .strict(),
+        battery: Battery.optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict()
+export const FleetLaunchPayloadSchema = z
+  .object({
+    packageName: FleetText,
+    miniappName: FleetText.optional(),
+    versionName: FleetText.optional(),
+    start: z.enum(["user", "automatic"]),
+    outcome: z.enum(["started", "failed"]),
+  })
+  .strict()
+export const FLEET_ACTIVITIES = ["glasses_connection", "miniapp_execution", "app_foreground", "engine_active"] as const
+export const FleetActivityCheckpointSchema = z
+  .object({
+    activity: z.enum(FLEET_ACTIVITIES),
+    activitySessionId: FleetId,
+    packageName: FleetText.optional(),
+    deviceBinding: FleetDeviceBindingSchema.optional(),
+    startedAt: FleetUtcTime,
+    /** Cumulative monotonic elapsed time of this session, never wall-clock subtraction. */
+    elapsedMs: z.number().int().min(0).max(FLEET_LIMITS.maxSessionElapsedMs),
+    ended: z.boolean(),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if ((value.activity === "miniapp_execution") !== (value.packageName !== undefined))
+      ctx.addIssue({code: "custom", message: "packageName is required for, and only for, miniapp_execution"})
+    if ((value.activity === "glasses_connection") !== (value.deviceBinding !== undefined))
+      ctx.addIssue({code: "custom", message: "deviceBinding is required for, and only for, glasses_connection"})
+  })
+export type FleetActivity = (typeof FLEET_ACTIVITIES)[number]
+export const FleetUsagePayloadSchema = z
+  .object({
+    sessions: z.array(FleetActivityCheckpointSchema).min(1).max(FLEET_LIMITS.maxSessionsPerCheckpoint),
+  })
+  .strict()
+export const FleetPhotoPayloadSchema = z
+  .object({
+    stage: z.enum(["requested", "captured", "delivered", "failed"]),
+    failedStage: z.enum(["requested", "captured", "delivered"]).optional(),
+  })
+  .strict()
+  .refine((v) => (v.stage === "failed") === (v.failedStage !== undefined), "failedStage goes with stage failed")
+export const FleetCoverageGapPayloadSchema = z
+  .object({
+    reason: z.enum(["queue_dropped", "queue_expired", "clock_untrusted", "reporter_stopped", "record_rejected"]),
+    from: FleetUtcTime,
+    to: FleetUtcTime,
+    droppedRecordCount: z.number().int().min(0).optional(),
+  })
+  .strict()
+const base = {
+  schemaVersion: z.literal(FLEET_SCHEMA_VERSION),
+  recordId: FleetId,
+  phoneDeviceId: FleetId,
+  collectorSessionId: FleetId,
+  sequence: z.number().int().min(0),
+  observedAt: FleetUtcTime,
+  management: z
+    .object({associationId: FleetId, generation: z.number().int().min(0)})
+    .strict()
+    .optional(),
+  capabilities: z.array(z.enum(FLEET_CAPABILITIES)).max(FLEET_CAPABILITIES.length),
+}
+export const FleetRecordSchema = z.discriminatedUnion("kind", [
+  z
+    .object({
+      ...base,
+      kind: z.literal("snapshot"),
+      deviceBinding: FleetDeviceBindingSchema.optional(),
+      payload: FleetSnapshotPayloadSchema,
+    })
+    .strict(),
+  z.object({...base, kind: z.literal("miniapp_launch"), payload: FleetLaunchPayloadSchema}).strict(),
+  z.object({...base, kind: z.literal("usage_checkpoint"), payload: FleetUsagePayloadSchema}).strict(),
+  z
+    .object({
+      ...base,
+      kind: z.literal("photo_operation"),
+      operationId: FleetId,
+      deviceBinding: FleetDeviceBindingSchema,
+      payload: FleetPhotoPayloadSchema,
+    })
+    .strict(),
+  z.object({...base, kind: z.literal("coverage_gap"), payload: FleetCoverageGapPayloadSchema}).strict(),
+])
+export type FleetRecord = z.infer<typeof FleetRecordSchema>
+export type FleetDeviceBinding = z.infer<typeof FleetDeviceBindingSchema>
+/** The envelope. Records are validated one at a time, so one bad record cannot strand a batch. */
+export const FleetReportSchema = z
+  .object({
+    schemaVersion: z.literal(FLEET_SCHEMA_VERSION),
+    records: z.array(z.unknown()).min(1).max(FLEET_LIMITS.maxRecordsPerBatch),
+  })
+  .strict()
+export type FleetReport = {schemaVersion: 1; records: FleetRecord[]}
+export const FLEET_REJECT_REASONS = [
+  "schema_invalid",
+  "unsupported_schema_version",
+  "content_mismatch",
+  "outside_replay_window",
+  "timestamp_out_of_bounds",
+  "account_deleted",
+] as const
+export const FleetRecordResultSchema = z
+  .object({
+    index: z.number().int().min(0),
+    recordId: FleetId.optional(),
+    status: z.enum(["accepted", "duplicate", "retryable", "rejected"]),
+    reasonCode: z.enum(FLEET_REJECT_REASONS).optional(),
+    retryAfterSeconds: z.number().int().min(0).optional(),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if ((value.status === "rejected") !== (value.reasonCode !== undefined))
+      ctx.addIssue({code: "custom", message: "reasonCode is required for, and only for, status rejected"})
+  })
+export const FleetReportAckSchema = z
+  .object({
+    schemaVersion: z.literal(FLEET_SCHEMA_VERSION),
+    results: z.array(FleetRecordResultSchema),
+  })
+  .strict()
+export type FleetRecordResult = z.infer<typeof FleetRecordResultSchema>
+export type FleetReportAck = z.infer<typeof FleetReportAckSchema>
+/** Whole-response error codes Core and MFM answer with. */
+export const FLEET_NOT_INSTALLED = "fleet_not_installed"
+export const FLEET_UNAVAILABLE = "fleet_unavailable"

package/src/index.ts CHANGED Viewed

@@ -17,3 +17,4 @@ export * from "./languages";
 export * from "./camera";
 export * from "./maps";
 export * from "./report-automation";
+export * from "./fleet";