@mentra/cloud-protocol 3.4.0-dev.1071 → 3.4.0-dev.1075

package/package.json

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

package/src/fleet.ts

@@ -17,6 +17,8 @@ export const FLEET_LIMITS = {
   maxBatchBytes: 1_048_576,
   maxSessionsPerCheckpoint: 32,
   maxSessionElapsedMs: 7 * 24 * 60 * 60 * 1000,
+  maxInventoryMiniapps: 500,
+  maxAssignmentEntries: 500,
   phoneQueueMaxRecords: 10_000,
   phoneQueueMaxAgeMs: 7 * 24 * 60 * 60 * 1000,
   replayWindowMs: 14 * 24 * 60 * 60 * 1000,
@@ -60,6 +62,7 @@ export const FLEET_CAPABILITIES = [
   "app_foreground",
   "engine_active",
   "photo_operations",
+  "phone_battery",
 ] as const
 
 const Battery = z.discriminatedUnion("state", [
@@ -86,6 +89,8 @@ export const FleetSnapshotPayloadSchema = z
         appBuild: FleetText,
         engineVersion: FleetText.optional(),
         sdkVersion: FleetText.optional(),
+        /** The phone's own battery; absent from an app that does not report one. */
+        battery: Battery.optional(),
       })
       .strict(),
     glasses: z
@@ -154,6 +159,96 @@ export const FleetPhotoPayloadSchema = z
   .strict()
   .refine((v) => (v.stage === "failed") === (v.failedStage !== undefined), "failedStage goes with stage failed")
 
+/** The provisioning spec's installation reasons. Management reasons are kept apart from the artifact's provenance. */
+export const FLEET_INSTALL_REASONS = ["bundled", "explicit", "manifest", "assignment"] as const
+export type FleetInstallReason = (typeof FLEET_INSTALL_REASONS)[number]
+
+/** Phase 11: the phone's installed miniapps. Sent when the collector starts and whenever the inventory changes. */
+export const FleetMiniappInventoryPayloadSchema = z
+  .object({
+    miniapps: z
+      .array(
+        z
+          .object({
+            packageName: FleetText,
+            versionName: FleetText,
+            digest: FleetText,
+            reasons: z.array(z.enum(FLEET_INSTALL_REASONS)).min(1).max(FLEET_INSTALL_REASONS.length),
+          })
+          .strict(),
+      )
+      .max(FLEET_LIMITS.maxInventoryMiniapps),
+  })
+  .strict()
+
+/** The provisioning spec's outcome states for one assignment on one phone. */
+export const FLEET_ASSIGNMENT_STATES = [
+  "pending",
+  "deferred_running",
+  "downloading",
+  "installing",
+  "installed",
+  "blocked",
+  "retrying",
+  "withdrawn",
+] as const
+export type FleetAssignmentState = (typeof FLEET_ASSIGNMENT_STATES)[number]
+
+/** Stable reasons for a blocked or retrying assignment. Never error text. */
+export const FLEET_ASSIGNMENT_REASONS = [
+  "archived",
+  "access_denied",
+  "not_a_miniapp",
+  "download_failed",
+  "signature_invalid",
+  "incompatible_host",
+  "newer_version_installed",
+  "manifest_conflict",
+  "storage_full",
+] as const
+export type FleetAssignmentReason = (typeof FLEET_ASSIGNMENT_REASONS)[number]
+
+/** A miniapp's address: https, bounded, and with no credentials in it. */
+export const FleetMiniappUrl = z
+  .string()
+  .min(1)
+  .max(2048)
+  .refine((value) => {
+    try {
+      const url = new URL(value)
+      return url.protocol === "https:" && url.username === "" && url.password === ""
+    } catch {
+      return false
+    }
+  }, "a miniapp URL is an https address without credentials")
+
+const FleetRevision = z.number().int().min(1).max(Number.MAX_SAFE_INTEGER)
+
+/** Phase 11: one assignment's state on this phone. */
+export const FleetAssignmentOutcomePayloadSchema = z
+  .object({
+    assignmentId: FleetId,
+    /** The assignment's own revision. */
+    assignmentRevision: FleetRevision,
+    /** The account's desired-state revision the phone acted on. */
+    desiredRevision: FleetRevision,
+    packageName: FleetText,
+    state: z.enum(FLEET_ASSIGNMENT_STATES),
+    reason: z.enum(FLEET_ASSIGNMENT_REASONS).optional(),
+    selectedVersion: FleetText.optional(),
+    installedVersion: FleetText.optional(),
+    attempts: z.number().int().min(0).max(1_000_000),
+    attemptedAt: FleetUtcTime,
+    lastSuccessAt: FleetUtcTime.optional(),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if (value.state === "blocked" && value.reason === undefined)
+      ctx.addIssue({code: "custom", path: ["reason"], message: "a blocked assignment carries its reason"})
+    if (value.state !== "blocked" && value.state !== "retrying" && value.reason !== undefined)
+      ctx.addIssue({code: "custom", path: ["reason"], message: "only a blocked or retrying assignment carries a reason"})
+  })
+
 export const FleetCoverageGapPayloadSchema = z
   .object({
     reason: z.enum(["queue_dropped", "queue_expired", "clock_untrusted", "reporter_stopped", "record_rejected"]),
@@ -170,10 +265,6 @@ const base = {
   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", [
@@ -197,6 +288,8 @@ export const FleetRecordSchema = z.discriminatedUnion("kind", [
     })
     .strict(),
   z.object({...base, kind: z.literal("coverage_gap"), payload: FleetCoverageGapPayloadSchema}).strict(),
+  z.object({...base, kind: z.literal("miniapp_inventory"), payload: FleetMiniappInventoryPayloadSchema}).strict(),
+  z.object({...base, kind: z.literal("assignment_outcome"), payload: FleetAssignmentOutcomePayloadSchema}).strict(),
 ]).superRefine((value, ctx) => {
   // A snapshot's glasses belong to the pair its binding names, so the two come together.
   if (value.kind === "snapshot" && (value.payload.glasses !== undefined) !== (value.deviceBinding !== undefined))
@@ -243,11 +336,57 @@ export const FleetReportAckSchema = z
   .object({
     schemaVersion: z.literal(FLEET_SCHEMA_VERSION),
     results: z.array(FleetRecordResultSchema),
+    /**
+     * The account's current desired-state revision (Phase 11). A phone holding an older one fetches desired state at
+     * once; there is no push channel. Optional so an acknowledgment from an older MFM still parses.
+     */
+    revision: FleetRevision.optional(),
   })
   .strict()
 export type FleetRecordResult = z.infer<typeof FleetRecordResultSchema>
 export type FleetReportAck = z.infer<typeof FleetReportAckSchema>
 
+/**
+ * Desired state, as MFM answers a phone through Core (`GET /api/client/fleet/desired-state`). Every answer carries one
+ * monotonic per-account `revision` and its generation time.
+ *
+ * - `managed`: the account's workspace and the assignment entries, which may be empty. A member of a workspace with
+ *   nothing assigned is still managed.
+ * - `unmanaged`: the account belongs to no workspace. Authoritative: the phone clears its assignment reasons.
+ *
+ * An error, timeout, partial response or missing MFM is never an empty set: MFM answers {@link FLEET_UNAVAILABLE}
+ * (503) and the phone keeps its last complete snapshot. `paused` (Phase 15) is not part of this schema, so a phone
+ * that receives an unknown status keeps its last snapshot.
+ */
+export const FleetDesiredStateEntrySchema = z
+  .object({
+    assignmentId: FleetId,
+    revision: FleetRevision,
+    /** The miniapp's own URL (Mentra-Specs #140). The phone installs it with `installMiniapp(url)` and takes the version it serves. */
+    url: FleetMiniappUrl,
+    /** The package the URL's manifest named when it was assigned. Display and matching only; the URL decides what installs. */
+    packageName: FleetText,
+    selection: z.literal("latest"),
+  })
+  .strict()
+
+export const FleetDesiredStateSchema = z.discriminatedUnion("status", [
+  z
+    .object({
+      status: z.literal("managed"),
+      revision: FleetRevision,
+      generatedAt: FleetUtcTime,
+      workspace: z.object({workspaceId: FleetId, name: z.string().min(1).max(200)}).strict(),
+      entries: z.array(FleetDesiredStateEntrySchema).max(FLEET_LIMITS.maxAssignmentEntries),
+    })
+    .strict(),
+  z.object({status: z.literal("unmanaged"), revision: FleetRevision, generatedAt: FleetUtcTime}).strict(),
+])
+export type FleetDesiredStateEntry = z.infer<typeof FleetDesiredStateEntrySchema>
+export type FleetDesiredState = z.infer<typeof FleetDesiredStateSchema>
+export type FleetMiniappInventoryPayload = z.infer<typeof FleetMiniappInventoryPayloadSchema>
+export type FleetAssignmentOutcomePayload = z.infer<typeof FleetAssignmentOutcomePayloadSchema>
+
 /** Whole-response error codes Core and MFM answer with. */
 export const FLEET_NOT_INSTALLED = "fleet_not_installed"
 export const FLEET_UNAVAILABLE = "fleet_unavailable"