@mentra/cloud-client 3.3.0-dev.909 → 3.3.0-dev.910

package/node/index.ts

@@ -50,5 +50,7 @@ export {
   CloudClientError,
   HttpError,
   AuthExpiredError,
+  AuthUnavailableError,
+  SessionRevocationError,
   noopLogger,
 } from "@mentra/cloud-client";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/cloud-client",
-  "version": "3.3.0-dev.909",
+  "version": "3.3.0-dev.910",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
@@ -12,7 +12,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@mentra/cloud-protocol": "3.3.0-dev.909",
+    "@mentra/cloud-protocol": "3.3.0-dev.910",
     "tweetnacl": "^1.0.3"
   },
   "devDependencies": {

package/src/errors.ts

@@ -25,17 +25,20 @@ export class CloudClientError extends Error {
  * `status` is the HTTP status so a caller can branch (for example a 401 triggers
  * one refresh-and-retry). `code` is the optional machine-readable error code the
  * cloud puts in the JSON body, when present, for finer branching than status
- * alone allows.
+ * alone allows. `retryAfterSeconds` is the server's `Retry-After` delay in whole
+ * seconds, set only when the response carried the delta-seconds form.
  */
 export class HttpError extends CloudClientError {
   status!: number;
   code?: string;
+  retryAfterSeconds?: number;
 
-  constructor(message: string, status: number, code?: string) {
+  constructor(message: string, status: number, code?: string, retryAfterSeconds?: number) {
     super(message);
     this.name = "HttpError";
     this.status = status;
     this.code = code;
+    this.retryAfterSeconds = retryAfterSeconds;
     Object.setPrototypeOf(this, new.target.prototype);
   }
 }
@@ -70,3 +73,25 @@ export class AuthExpiredError extends CloudClientError {
     Object.setPrototypeOf(this, new.target.prototype);
   }
 }
+
+/**
+ * Thrown when a credential request could not be completed for a reason that does
+ * not show the credentials are dead: the network failed or timed out, Core
+ * answered 408, 429 or 5xx, or the answer was not a Core answer at all (a body
+ * that is not JSON, an unrecognized 4xx). The stored credentials were kept, so
+ * the same call may well succeed later; a host retries instead of re-authenticating,
+ * and `onExpired` does not fire. `status` is the HTTP status when something
+ * answered, and `cause` is the underlying failure.
+ */
+export class AuthUnavailableError extends CloudClientError {
+  readonly status?: number;
+  readonly cause: unknown;
+
+  constructor(message: string, options?: { status?: number; cause?: unknown }) {
+    super(message);
+    this.name = "AuthUnavailableError";
+    this.status = options?.status;
+    this.cause = options?.cause;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/src/http.ts

@@ -115,6 +115,19 @@ function isAbortError(error: unknown): boolean {
   return typeof error === "object" && error !== null && "name" in error && error.name === "AbortError";
 }
 
+/**
+ * Read a `Retry-After` header in its delta-seconds form (a non-negative whole
+ * number of seconds). The HTTP-date form, signs, fractions, exponents and any
+ * other text are ignored: a caller that wants a delay gets a number or nothing,
+ * never a guess. A value too large to be an exact integer is also ignored.
+ */
+function parseRetryAfterSeconds(headers: Headers | undefined): number | undefined {
+  const raw = headers?.get("Retry-After")?.trim();
+  if (!raw || !/^\d+$/.test(raw)) return undefined;
+  const seconds = Number(raw);
+  return Number.isSafeInteger(seconds) ? seconds : undefined;
+}
+
 export function createHttpClient(deps: CreateHttpClientDeps): HttpClient {
   const { baseUrl, getToken, logger } = deps;
   const executeFetch = deps.fetch ?? globalThis.fetch;
@@ -304,7 +317,12 @@ export function createHttpClient(deps: CreateHttpClientDeps): HttpClient {
       // No JSON body, or unparseable: fall back to status alone.
     }
     throwIfAborted(signal);
-    return new HttpError(`HTTP ${res.status} on ${method} ${path}${detail}`, res.status, code);
+    return new HttpError(
+      `HTTP ${res.status} on ${method} ${path}${detail}`,
+      res.status,
+      code,
+      parseRetryAfterSeconds(res.headers),
+    );
   }
 
   /**

package/src/index.ts

@@ -41,9 +41,14 @@ export {
   CloudClientError,
   HttpError,
   AuthExpiredError,
+  AuthUnavailableError,
   SessionRevocationError,
 } from "./errors";
 
+// Reads a Core token's claims (`sub` is the Mentra user ID) without verifying it; the cloud verifies every call.
+export { decodeClaims } from "./modules/auth/jwt";
+export type { JwtClaims } from "./modules/auth/jwt";
+
 // The logging hook a host can implement to route library logs.
 export { noopLogger } from "./logger";
 export type { Logger } from "./logger";
@@ -60,6 +65,9 @@ export type {
 export type {
   AddReportArtifactsResult,
   AddReportLogsOptions,
+  FleetAck,
+  FleetAckResult,
+  FleetReportOutcome,
   ReportAttachmentInput,
   ReportContext,
   ReportDetails,

package/src/modules/auth/auth.ts

@@ -14,10 +14,23 @@
  *  - Exchange, refresh, and each per-miniapp mint are single-flighted, so a
  *    reconnect storm cannot fire a burst of competing requests (and a rotated
  *    refresh token cannot be invalidated out from under a concurrent caller).
- *  - If a refresh fails and the host can fetch a fresh subject token on demand,
- *    we clear the dead refresh token and exchange once. If no fresh subject is
- *    available (or exchange also fails), `onExpired` fires once and the host
- *    re-authenticates. We do not retry forever against a dead refresh token.
+ *  - If Core definitively rejects the refresh token (see
+ *    `DEAD_REFRESH_TOKEN_ERRORS`) and the host can fetch a fresh subject token
+ *    on demand, we clear the dead refresh token and exchange once. If no fresh
+ *    subject is available (or exchange also fails), `onExpired` fires once and
+ *    the host re-authenticates. We do not retry forever against a dead refresh
+ *    token.
+ *  - Any other refresh failure (network error, timeout, 408, 429, 5xx, an answer
+ *    that is not Core's) says nothing about the token. It is kept, `onExpired`
+ *    does not fire, no exchange is attempted, and `AuthUnavailableError` is
+ *    thrown so the caller retries later with the same refresh token.
+ *  - Exchange failures are classified the same way: only Core's own refusal of
+ *    the subject token (`EXCHANGE_REFUSAL_ERRORS`) is an `AuthExpiredError`, and
+ *    `onExpired` fires only when that refusal answers the fresh exchange that
+ *    follows a rejected refresh token. Anything else, including the host's
+ *    `getSubjectToken` throwing, is an `AuthUnavailableError` and notifies no one.
+ *  - A rejection or exchange answer that arrives after `clearSession()` is about
+ *    a session that is gone: it notifies no one and restores nothing.
  *
  * Security: the access token is never written to storage, never given to a
  * miniapp, and no token is ever logged.
@@ -29,7 +42,7 @@ import type {AuthConfig, CoreAuthConfig, RuntimeAuthConfig, SubjectTokenType} fr
 import type {HttpClient} from "../../http"
 import type {Logger} from "../../logger"
 import type {HttpTransport} from "../../transports"
-import {AuthExpiredError, HttpError, SessionRevocationError} from "../../errors"
+import {AuthExpiredError, AuthUnavailableError, HttpError, SessionRevocationError} from "../../errors"
 import {systemTimers, type CloudClientTimers} from "../../timers"
 import {decodeClaims} from "./jwt"
 import {TokenStore} from "./token-store"
@@ -62,7 +75,7 @@ export interface AuthModule {
   // credentials are always cleared; rejects with `SessionRevocationError` when
   // Core did not confirm revocation of the server-side session.
   clearSession(): Promise<void>
-  // refresh failed; the host must send the user back through login
+  // Core rejected the refresh token; the host must send the user back through login
   onExpired(handler: () => void): () => void
 }
 
@@ -142,6 +155,88 @@ function isRetryableRevokeError(err: unknown): boolean {
   return err instanceof HttpError && (err.status === 0 || err.status >= 500)
 }
 
+/**
+ * What counts as Core itself refusing a token request, as opposed to a request
+ * that merely failed. Core renders every refusal as `{error, error_description}`
+ * through its global error translator (`api/app.ts`) with the status its
+ * `OauthError` carries (`types/oauth.types.ts`). Only a 400 or 401 whose body has
+ * one of the codes below counts; RFC 6749 lets a server pick between the two
+ * statuses, so both are accepted for every code. A 5xx, 408 or 429, a body that
+ * is not JSON, or any other 4xx is not Core talking about the credentials at all
+ * (a proxy, a captive portal, an outage), so it is never a refusal.
+ */
+const CORE_REFUSAL_STATUSES: ReadonlySet<number> = new Set([400, 401])
+
+/**
+ * The only answers to `POST /api/client/auth/refresh` that say the refresh token
+ * (or the session it belongs to) is gone for good. `refreshSession`
+ * (`services/session.service.ts`) refuses a token for exactly two reasons:
+ *
+ *  - `invalid_grant`, HTTP 400: the token is unknown, expired or already used,
+ *    its session identity is incomplete, or its account is deleted.
+ *  - `unauthorized_client`, HTTP 401: the session's tenant (OEM or enterprise
+ *    org) is unknown or disabled.
+ *
+ * `invalid_request` and `unsupported_grant_type` describe the shape of the
+ * request (a missing `refresh_token` or `grant_type`), which a proxy that drops
+ * or rewrites the form body produces just as well, so they are no verdict on the
+ * token.
+ */
+const DEAD_REFRESH_TOKEN_ERRORS: ReadonlySet<string> = new Set(["invalid_grant", "unauthorized_client"])
+
+/**
+ * The answers to `POST /api/client/auth/exchange` that say the subject token is
+ * unusable (`oem.service.ts`, `session.service.ts`): `invalid_grant` (it failed
+ * verification or lacks required claims), `unauthorized_client` (its OEM is
+ * unknown or disabled), and `invalid_request` (it is not a parseable JWT).
+ * `unsupported_grant_type` is left out for the same reason as on refresh.
+ */
+const EXCHANGE_REFUSAL_ERRORS: ReadonlySet<string> = new Set([
+  "invalid_grant",
+  "unauthorized_client",
+  "invalid_request",
+])
+
+/** OAuth error codes are short snake_case words; anything else is not safe to keep or log. */
+const OAUTH_ERROR_CODE_PATTERN = /^[a-z][a-z0-9_]{0,63}$/
+
+/**
+ * A token endpoint answered with a non-2xx status. `status` is the HTTP status and
+ * `code` is the OAuth `error` from a JSON body, when there was a well-formed one.
+ *
+ * It is an `AuthExpiredError` so the logout refresh, which has always thrown that
+ * for any non-2xx, is unchanged. `requestTokens` lets it out only when it is
+ * Core's refusal (`isCoreRefusal`); every other non-2xx becomes an
+ * `AuthUnavailableError` there.
+ */
+class TokenEndpointError extends AuthExpiredError {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly code?: string,
+  ) {
+    super(message)
+  }
+}
+
+/** Core definitively rejected the refresh token: it is cleared, and the host must re-authenticate. */
+class RefreshTokenRejectedError extends AuthExpiredError {}
+
+/** `err` is Core itself refusing the request: a 400 or 401 carrying one of `codes`. */
+function isCoreRefusal(err: unknown, codes: ReadonlySet<string>): err is TokenEndpointError {
+  return (
+    err instanceof TokenEndpointError &&
+    CORE_REFUSAL_STATUSES.has(err.status) &&
+    err.code !== undefined &&
+    codes.has(err.code)
+  )
+}
+
+/** The caller or the transport cancelled the request. */
+function isAbortError(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "name" in error && error.name === "AbortError"
+}
+
 export class Auth implements AuthModule {
   private readonly http?: HttpClient
   private readonly store: TokenStore
@@ -434,13 +529,12 @@ export class Auth implements AuthModule {
       try {
         return await this.refresh(refreshToken, {deferExpired: this.canExchangeFreshSubject(), generation})
       } catch (err) {
-        if (this.canExchangeFreshSubject()) {
-          this.logger.info("refresh failed; exchanging fresh subject token")
-          try {
-            return await this.exchange(generation)
-          } catch {
-            this.fireExpired()
-          }
+        // Only a definitive rejection of the refresh token earns a fresh subject
+        // exchange. A transient failure would meet the same network, an abort
+        // was the caller's answer, and a cleared session must not reacquire
+        // credentials from the upstream provider.
+        if (err instanceof RefreshTokenRejectedError && this.canExchangeFreshSubject()) {
+          return this.exchangeAfterRejection(generation, err)
         }
         throw err
       }
@@ -448,6 +542,36 @@ export class Auth implements AuthModule {
     return this.exchange(generation)
   }
 
+  /**
+   * One fresh subject exchange after Core rejected the refresh token (the host
+   * can supply a subject token on demand). The dead refresh token is already
+   * cleared, so a failure here leaves the next `getCoreToken` on the first-use
+   * exchange; `onExpired` fires only if Core itself refuses the fresh subject
+   * token, which is when the host really must re-authenticate.
+   */
+  private async exchangeAfterRejection(generation: number, rejection: RefreshTokenRejectedError): Promise<string> {
+    this.assertSessionActive(generation)
+    this.logger.info("refresh token rejected; exchanging fresh subject token")
+    try {
+      return await this.exchange(generation)
+    } catch (err) {
+      if (isAbortError(err)) throw err
+      // A logout that raced the exchange wins over whatever the exchange came to.
+      this.assertSessionActive(generation)
+      if (isCoreRefusal(err, EXCHANGE_REFUSAL_ERRORS)) {
+        this.fireExpired()
+        throw rejection
+      }
+      // Already classified: a retryable failure, or a local problem that is not about the credentials.
+      if (err instanceof AuthUnavailableError || err instanceof AuthExpiredError) throw err
+      // The host's getSubjectToken threw (or the like): nothing was refused.
+      this.logger.warn("fresh subject token could not be exchanged; keeping the session retryable", {
+        error: err instanceof Error ? err.name : typeof err,
+      })
+      throw new AuthUnavailableError("fresh subject token could not be exchanged; try again later", {cause: err})
+    }
+  }
+
   /**
    * First-use exchange: trade the configured subject token for an access +
    * refresh pair and save them.
@@ -481,7 +605,7 @@ export class Auth implements AuthModule {
       subject_token_type: SUBJECT_TOKEN_TYPE_URN[subject.type],
     })
 
-    const tokens = await this.postForm(EXCHANGE_PATH, body, "exchange")
+    const tokens = await this.requestTokens(EXCHANGE_PATH, body, "exchange", EXCHANGE_REFUSAL_ERRORS)
     await this.saveTokenPair(
       {
         accessToken: tokens.access_token,
@@ -500,13 +624,20 @@ export class Auth implements AuthModule {
    * Refresh near expiry: trade the stored refresh token for a new access token
    * and a rotated refresh token, saving both.
    *
-   * On failure (the refresh token is dead or revoked) we clear stored state.
-   * The caller either falls back to one fresh subject-token exchange (for
-   * on-demand subject-token configs) or fires `onExpired` once and surfaces an
-   * `AuthExpiredError`. We do not retry refresh forever: a dead refresh token
-   * will not heal on its own, and retrying would loop.
+   * Only Core's definitive rejection of the refresh token
+   * (`DEAD_REFRESH_TOKEN_ERRORS`) clears the stored state. The caller either
+   * falls back to one fresh subject-token exchange (for on-demand subject-token
+   * configs) or fires `onExpired` once; both surface a
+   * `RefreshTokenRejectedError`. We do not retry refresh forever: a dead
+   * refresh token will not heal on its own, and retrying would loop.
+   *
+   * Every other failure leaves the refresh token in place for the next call: it
+   * says nothing about the token, and Core accepts a retry with the same token
+   * even when it rotated the token and the response never arrived. Those throw
+   * `AuthUnavailableError`, except an abort, which propagates unchanged.
    */
   private async refresh(refreshToken: string, opts?: {deferExpired?: boolean; generation?: number}): Promise<string> {
+    const generation = opts?.generation ?? this.sessionGeneration
     const body = new URLSearchParams({
       grant_type: "refresh_token",
       refresh_token: refreshToken,
@@ -514,15 +645,20 @@ export class Auth implements AuthModule {
 
     let tokens: TokenResponse
     try {
-      tokens = await this.postForm(REFRESH_PATH, body, "refresh")
-    } catch {
-      // The refresh token is unusable: drop it so we do not keep presenting a
-      // known-bad token.
+      tokens = await this.requestTokens(REFRESH_PATH, body, "refresh", DEAD_REFRESH_TOKEN_ERRORS)
+    } catch (err) {
+      // An abort, a retryable failure and a local problem are not a rejection of the token.
+      if (!isCoreRefusal(err, DEAD_REFRESH_TOKEN_ERRORS)) throw err
+      // A rejection that arrives after logout is about a session that is already gone: it must
+      // not notify the host, clear what a newer session saved, or send the caller to exchange.
+      this.assertSessionActive(generation)
+      // Core rejected the refresh token for good: drop it so we do not keep
+      // presenting a known-bad token.
       await this.store.clear()
       if (!opts?.deferExpired) {
         this.fireExpired()
       }
-      throw new AuthExpiredError("token refresh failed; re-auth required")
+      throw new RefreshTokenRejectedError("token refresh failed; re-auth required")
     }
 
     await this.saveTokenPair(
@@ -530,7 +666,7 @@ export class Auth implements AuthModule {
         accessToken: tokens.access_token,
         refreshToken: tokens.refresh_token,
       },
-      opts?.generation ?? this.sessionGeneration,
+      generation,
     )
     this.expiredFired = false
     this.logger.debug("refreshed access token")
@@ -605,6 +741,42 @@ export class Auth implements AuthModule {
     }
   }
 
+  /**
+   * `postForm` for the calls whose failure says something about the credentials
+   * (`/exchange` and `/refresh`). Settles as exactly one of:
+   *  - the tokens;
+   *  - the caller's abort, unchanged;
+   *  - a `TokenEndpointError` that is Core's own refusal (`isCoreRefusal` with
+   *    `refusals`), for the caller to act on;
+   *  - an `AuthExpiredError` that is not a failed request (no Core endpoint
+   *    configured), unchanged;
+   *  - `AuthUnavailableError` for everything else: a network error, a timeout, a
+   *    408, 429 or 5xx, a body that is not Core's JSON, any other 4xx. None of
+   *    those says the credentials are bad, so the caller keeps them and retries.
+   */
+  private async requestTokens(
+    path: string,
+    body: URLSearchParams,
+    label: string,
+    refusals: ReadonlySet<string>,
+  ): Promise<TokenResponse> {
+    try {
+      return await this.postForm(path, body, label)
+    } catch (err) {
+      if (isAbortError(err) || isCoreRefusal(err, refusals)) throw err
+      if (err instanceof AuthExpiredError && !(err instanceof TokenEndpointError)) throw err
+      // Core answering with an error we do not recognize still carries its status;
+      // a transport or parse failure does not.
+      const status = err instanceof TokenEndpointError ? err.status : undefined
+      this.logger.warn("token request failed; keeping the credentials", {
+        label,
+        ...(status !== undefined ? {status} : {}),
+        error: err instanceof Error ? err.name : typeof err,
+      })
+      throw new AuthUnavailableError(`${label} could not be completed; try again later`, {status, cause: err})
+    }
+  }
+
   /**
    * POST a form-encoded body to a token endpoint and parse the RFC token
    * response.
@@ -630,16 +802,30 @@ export class Auth implements AuthModule {
     if (signal?.aborted) throw new Error("Core session revocation timed out")
 
     if (!res.ok) {
-      // The body may carry an RFC `{ error, error_description }`, but we keep the
-      // thrown detail to the status + label so no token field can leak into a
-      // message a host might surface. The caller maps this to re-auth.
-      this.logger.warn("auth token request failed", {label, status: res.status})
-      throw new AuthExpiredError(`${label} request failed with status ${res.status}`)
+      // The body may carry an RFC `{ error, error_description }`. We keep only
+      // the short `error` code (the caller decides what it means) and never the
+      // description, so no token field can leak into a message a host might
+      // surface.
+      // Only a 400 or 401 body is ever consulted, so no other body is read.
+      const code = CORE_REFUSAL_STATUSES.has(res.status) ? await this.readOauthErrorCode(res) : undefined
+      this.logger.warn("auth token request failed", {label, status: res.status, ...(code ? {code} : {})})
+      throw new TokenEndpointError(`${label} request failed with status ${res.status}`, res.status, code)
     }
 
     return (await res.json()) as TokenResponse
   }
 
+  /** The OAuth `error` code of a refusal, or undefined when the body is not Core's `{error}` JSON. */
+  private async readOauthErrorCode(res: Response): Promise<string | undefined> {
+    try {
+      const data: unknown = await res.json()
+      const code = typeof data === "object" && data !== null ? (data as {error?: unknown}).error : undefined
+      return typeof code === "string" && OAUTH_ERROR_CODE_PATTERN.test(code) ? code : undefined
+    } catch {
+      return undefined
+    }
+  }
+
   /**
    * Join the core base URL and a path without a double or missing slash.
    *

package/src/modules/core/core.ts

@@ -6,8 +6,8 @@
  * helper, which attaches the access token from `cloud.auth` as the Bearer, so
  * core never touches credentials itself.
  *
- * Today it exposes the unified report submission surface and the support
- * profile update.
+ * Today it exposes the unified report submission surface, the support
+ * profile update and the Fleet report.
  *
  * Guardrail: this is device-facing only. It deliberately carries none of the
  * Dev Console / OEM Portal / store web UI surface; those are separate clients.
@@ -16,6 +16,8 @@
  * ("src/modules/core/core.ts").
  */
 import type { HttpClient } from "../../http";
+import type { FleetReport } from "@mentra/cloud-protocol";
+import { Fleet, type FleetReportOutcome } from "./fleet";
 import {
   Reports,
   type AddReportArtifactsResult,
@@ -53,6 +55,7 @@ export type {
   SubmitReportInput,
   SubmitReportResult,
 } from "./reports";
+export type { FleetAck, FleetAckResult, FleetReportOutcome } from "./fleet";
 export type {
   SupportConnectionState,
   SupportProfileUpdateResult,
@@ -102,11 +105,20 @@ export class Core {
   readonly supportProfile: {
     update(input: SupportStateInput): Promise<SupportProfileUpdateResult>;
   };
+  readonly fleet: {
+    /**
+     * Rejects only for an authentication failure (`AuthExpiredError`, or an `HttpError` with status 401) or an abort.
+     * Every other result, including any network or unexpected failure, is a `FleetReportOutcome`. `opts.bearer` sends
+     * that Core token instead of the token source's.
+     */
+    report(batch: FleetReport, opts?: { signal?: AbortSignal; bearer?: string }): Promise<FleetReportOutcome>;
+  };
 
   constructor(deps: CoreDeps) {
     const { http } = deps;
     const reports = new Reports({ http });
     const supportProfiles = new SupportProfiles(http);
+    const fleet = new Fleet(http);
 
     this.reports = {
       submit: reports.submit.bind(reports),
@@ -120,5 +132,8 @@ export class Core {
     this.supportProfile = {
       update: supportProfiles.update.bind(supportProfiles),
     };
+    this.fleet = {
+      report: fleet.report.bind(fleet),
+    };
   }
 }

package/src/modules/core/fleet.ts

@@ -0,0 +1,175 @@
+import {FLEET_NOT_INSTALLED, FLEET_SCHEMA_VERSION, type FleetReport} from "@mentra/cloud-protocol"
+import {AuthExpiredError, HttpError} from "../../errors"
+import type {HttpClient} from "../../http"
+
+const FLEET_REPORT_PATH = "/api/client/fleet/report"
+
+/** Core's whole-response error codes are short snake_case words; anything else is not safe to surface. */
+const ERROR_CODE_PATTERN = /^[a-z][a-z0-9_]{0,63}$/
+
+const RESULT_STATUSES = ["accepted", "duplicate", "retryable", "rejected"] as const
+
+/**
+ * Fleet's answer for one record of the batch, as this client reads it. `index` is the record's position in the batch
+ * and `recordId`, when present, names it. A status this client does not know reads as `retryable`, so the record is
+ * kept and sent again. `reasonCode` is given only for a rejection, and only when it is a short snake_case code; one
+ * this client does not know is kept as given.
+ */
+export interface FleetAckResult {
+  index: number
+  recordId?: string
+  status: (typeof RESULT_STATUSES)[number]
+  reasonCode?: string
+  retryAfterSeconds?: number
+}
+
+/** A per-record acknowledgement: one result per record Fleet answered for. */
+export interface FleetAck {
+  schemaVersion: typeof FLEET_SCHEMA_VERSION
+  results: FleetAckResult[]
+}
+
+/**
+ * What one `POST /api/client/fleet/report` came to. Every answer Core or Fleet can give is an outcome, so a caller
+ * branches on `kind` and never on an exception or a status code.
+ */
+export type FleetReportOutcome =
+  /** Core answered 200 with a per-record acknowledgement. */
+  | {kind: "results"; ack: FleetAck}
+  /** Core answered 404 `fleet_not_installed`: Fleet is not installed on this Core. */
+  | {kind: "not_installed"}
+  /**
+   * Something answered 404 without Fleet's own code: a Core from before Fleet, which has no such route, or a proxy in
+   * front of it. Not proof that Fleet is not installed, so a caller stops asking for now but keeps what it holds.
+   */
+  | {kind: "no_fleet_route"}
+  /**
+   * Fleet or the network is not answering usefully right now: 503, 429, any other server or unexpected failure, a
+   * network error or timeout, or a 200 whose body is not an acknowledgement. `retryAfterSeconds` is the server's
+   * `Retry-After` in whole seconds, or null when it gave none.
+   */
+  | {kind: "unavailable"; retryAfterSeconds: number | null}
+  /** Core answered 413. */
+  | {kind: "batch_too_large"}
+  /** Core answered 400. `code` is Core's error code (`invalid_batch`, `invalid_body`, ...), or `unknown`. */
+  | {kind: "batch_invalid"; code: string}
+  /** Core answered 403. */
+  | {kind: "forbidden"}
+
+const unavailable = (retryAfterSeconds: number | null = null): FleetReportOutcome => ({
+  kind: "unavailable",
+  retryAfterSeconds,
+})
+
+/** The caller (or the transport) cancelled the request. */
+function isAbortError(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "name" in error && error.name === "AbortError"
+}
+
+/** The credentials were refused or are gone: the caller must refresh or sign in again, so this is never an outcome. */
+function isAuthFailure(error: unknown): boolean {
+  return error instanceof AuthExpiredError || (error instanceof HttpError && error.status === 401)
+}
+
+function outcomeForHttpError(error: HttpError): FleetReportOutcome {
+  switch (error.status) {
+    // A transport failure (DNS, reset, timeout) after the client's own retries. There was no answer.
+    case 0:
+      return unavailable()
+    case 404:
+      // Only Fleet's own answer means "not installed". Any other 404 (an older Core without the route, a proxy) must
+      // not read as it, because not_installed makes the caller drop its queue.
+      return error.code === FLEET_NOT_INSTALLED ? {kind: "not_installed"} : {kind: "no_fleet_route"}
+    case 413:
+      return {kind: "batch_too_large"}
+    case 400:
+      return {
+        kind: "batch_invalid",
+        code: typeof error.code === "string" && ERROR_CODE_PATTERN.test(error.code) ? error.code : "unknown",
+      }
+    case 403:
+      return {kind: "forbidden"}
+    // 503, 429, 408, 5xx, and anything else Core was not documented to say: keep the records and try later.
+    default:
+      return unavailable(error.retryAfterSeconds)
+  }
+}
+
+export class Fleet {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * Reports one batch of Fleet records to the phone's own Core.
+   *
+   * Rejects in exactly two cases: an authentication failure (`AuthExpiredError`, or an `HttpError` with status 401),
+   * or an abort (an `AbortError`, or any error raised once `opts.signal` is aborted). Every other result is a
+   * {@link FleetReportOutcome}, including network failures, timeouts, a connection that drops while the response
+   * body is being read, a body that is not a valid acknowledgement, and unexpected errors, which are
+   * `{kind: "unavailable", retryAfterSeconds: null}`.
+   *
+   * The request is sent idempotently, so the HTTP client retries a transient network failure before the body is
+   * read; that is safe because Fleet records are idempotent by ID.
+   *
+   * `opts.bearer` sends exactly that Core token instead of asking the token source, for a caller that has already
+   * checked whose token it is.
+   */
+  async report(batch: FleetReport, opts?: {signal?: AbortSignal; bearer?: string}): Promise<FleetReportOutcome> {
+    const signal = opts?.signal
+    const bearer = opts?.bearer
+    let body: unknown
+    try {
+      body = await this.http.post<unknown>(FLEET_REPORT_PATH, batch, {
+        idempotent: true,
+        ...(signal ? {signal} : {}),
+        ...(bearer ? {bearer} : {}),
+      })
+    } catch (error) {
+      // The caller stopped the request: that is its answer, whatever the transport happened to report.
+      if (signal?.aborted || isAbortError(error) || isAuthFailure(error)) throw error
+      if (error instanceof HttpError) return outcomeForHttpError(error)
+      // Anything else (a body that is not JSON, a socket that closed mid-body, a failing token source) is no answer.
+      return unavailable()
+    }
+
+    const ack = readAck(body)
+    return ack ? {kind: "results", ack} : unavailable()
+  }
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function isWholeNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0
+}
+
+/**
+ * Reads an acknowledgement the way a client already in the field must: it ignores keys it does not know, reads a
+ * status it does not know as `retryable`, and keeps a rejection whose reason it does not know. A newer Fleet can
+ * therefore add to the answer without this client reading all of it as no answer and resending the same batch
+ * forever. What it cannot do without is the shape that ties a result to a record: a `results` array of objects,
+ * each with a whole-number `index`, a text `status`, and a `recordId` that is text when present. Anything else is
+ * null, which the caller treats as no answer.
+ *
+ * Producers are still held to the strict `FleetReportAckSchema` in `@mentra/cloud-protocol`.
+ */
+function readAck(body: unknown): FleetAck | null {
+  if (!isObject(body) || body.schemaVersion !== FLEET_SCHEMA_VERSION || !Array.isArray(body.results)) return null
+  const results: FleetAckResult[] = []
+  for (const raw of body.results) {
+    if (!isObject(raw) || !isWholeNumber(raw.index) || typeof raw.status !== "string") return null
+    if (raw.recordId !== undefined && typeof raw.recordId !== "string") return null
+    const status = (RESULT_STATUSES as readonly string[]).includes(raw.status)
+      ? (raw.status as FleetAckResult["status"])
+      : "retryable"
+    const result: FleetAckResult = {index: raw.index, status}
+    if (raw.recordId !== undefined) result.recordId = raw.recordId
+    if (status === "rejected" && typeof raw.reasonCode === "string" && ERROR_CODE_PATTERN.test(raw.reasonCode)) {
+      result.reasonCode = raw.reasonCode
+    }
+    if (isWholeNumber(raw.retryAfterSeconds)) result.retryAfterSeconds = raw.retryAfterSeconds
+    results.push(result)
+  }
+  return {schemaVersion: FLEET_SCHEMA_VERSION, results}
+}