@fleetless/sdk 1.0.0

package/README.md

@@ -0,0 +1,1217 @@
+# @fleetless/sdk
+
+The official TypeScript SDK for Fleetless client apps (spec §14.3):
+framework-agnostic, TypeScript-first, ESM+CJS. It runs unchanged in a
+browser and in Node — nothing in it assumes either one exists.
+
+W3 scope: **auth** (login, silent refresh, logout) and **datapoints** (get,
+subscribe with automatic reconnect). W4 adds the **command surface** —
+**actions** (invoke, cancel, subscribe to feedback/progress/result),
+**services** (call) and **publishers** (publish) — all correlated by a
+`request_id` over the same realtime channel. W5 adds **cameras** (snapshot
+bytes + age, and a refcounted LiveKit live session) — plain REST, no
+realtime channel involved. W6 adds **history** (recorded samples and
+window-aggregated buckets for a `retention: true` datapoint) — also plain REST.
+W6b adds addressing: a cancel can name the job it means, a camera live
+session can be released on its own, and a call can carry its own patience —
+see each section below for what that changes and what it does not. W6c adds
+self-registration and account recovery — `auth.register` /
+`auth.confirmRegistration`, `auth.changePassword`, `auth.requestPasswordReset` /
+`confirmPasswordReset` — and surfaces `rate_limited` on every unauthenticated
+route, which this SDK never retries automatically. W7a adds
+`assets.prepareUrdfScene`: authenticated loading for **everything** three.js
+fetches to render a robot, not only meshes — a `<texture>` in the URDF and an
+image a `.dae` references internally, both unreachable through
+`createMeshLoader`'s per-loader hook.
+Presence arrives in a later wave, built on the same client core.
+
+**A slug names a place a job may be running, not the job itself.** Two
+`invoke`s on the same slug, one after another, are two different jobs that
+happen to share an address — `subscribe` and the plain `cancel()` both work
+*by slug* on purpose (§11.3: state is observed by slug), and that is a
+feature, not an oversight. But it means a caller who means one *specific*
+job — the one whose id they were handed — has to say so explicitly, which is
+what job-id addressing (below) is for. Conflating the two is how a cancel
+sent a moment too late ends up stopping someone else's job instead of doing
+nothing.
+
+## Install
+
+```sh
+npm i @fleetless/sdk
+```
+
+## Quick start
+
+Five minutes from install to a live value, assuming you already have an app
+identifier and an end user's credentials from the [Fleetless
+Console](https://console.fleetless.dev) (or your own dev stack).
+
+```ts
+import { createClient } from '@fleetless/sdk'
+
+const client = createClient({
+  apiUrl: 'https://api.fleetless.dev',
+  appIdentifier: 'fleet-ops', // the app's identifier, shown in the console
+})
+
+await client.auth.login('user@example.com', 'correct-horse-battery')
+
+// One-shot read.
+const battery = await client.datapoints.get('robot-id', 'battery-percentage')
+console.log(battery.value, battery.timestamp_ms)
+
+// Live updates. The current value arrives immediately, then every change.
+const subscription = client.datapoints.subscribe('robot-id', 'battery-percentage', {
+  onEvent(event) {
+    console.log(event.value, event.timestamp_ms)
+  },
+  onError(error) {
+    console.error(error.code, error.message)
+  },
+})
+
+// Later:
+subscription.unsubscribe()
+await client.auth.logout()
+```
+
+Against a local dev stack (`./infra/dev.sh` from the umbrella repo), point
+`apiUrl` at `http://localhost:8080` — `ws://localhost:8080/realtime` is
+derived automatically (see [Configuration](#configuration)).
+
+## Auth
+
+Fleetless has two kinds of caller (spec §3.4), and the SDK supports both:
+
+### End users — `tokenStore`
+
+```ts
+const client = createClient({ apiUrl, appIdentifier })
+await client.auth.login(email, password) // -> stores a session
+await client.auth.me() // -> ClientIdentity, without decoding a token yourself
+const { revoked } = await client.auth.logout() // revokes server-side, then clears the local store
+```
+
+- **Silent refresh is automatic.** A REST call that meets an expired access
+  token refreshes once and retries transparently. Concurrent calls made
+  while a refresh is already in flight share that one refresh instead of
+  each firing their own.
+- **`logout()` never rejects.** It always clears the local store — a user
+  who presses "log out" ends up logged out locally regardless of the
+  network — but the server-side revoke can still fail (offline, a dead
+  cloud). `revoked: false` means the refresh family may still be alive
+  server-side even though this client has forgotten it; a kiosk or shared
+  workstation might want to warn the user or retry, everyone else can
+  ignore the return value.
+- **What `logout()` does and does not invalidate.** It revokes the whole
+  refresh-token family server-side immediately (a stolen refresh token
+  stops working) and closes this client's live realtime connection, if it
+  has one. It does **not** invalidate the access token already handed out —
+  access-token checks are a signed JWT verified without a server-side
+  lookup, so logout has nothing on that token to flip. A token stolen
+  before logout keeps working on REST, and can still open a *new* realtime
+  connection, until it expires on its own — **at most 15 minutes.** That's
+  the same stateless-JWT tradeoff that lets a role change or a block take
+  effect on the very next request without forcing a fresh token — a
+  deliberate boundary, not a bug, but one a kiosk or shared workstation
+  needs to plan around.
+- **Token storage is pluggable.** By default, sessions live in memory and
+  are lost on reload. Implement `TokenStore` to persist one — localStorage,
+  a cookie, a native keystore:
+
+  ```ts
+  import type { TokenStore, StoredSession } from '@fleetless/sdk'
+
+  const localStorageTokenStore: TokenStore = {
+    load: () => {
+      const raw = localStorage.getItem('fleetless-session')
+      return raw ? (JSON.parse(raw) as StoredSession) : null
+    },
+    save: (session) => {
+      if (session) localStorage.setItem('fleetless-session', JSON.stringify(session))
+      else localStorage.removeItem('fleetless-session')
+    },
+  }
+
+  const client = createClient({ apiUrl, appIdentifier, tokenStore: localStorageTokenStore })
+  ```
+
+### Hosted login (W7b)
+
+A third way to authenticate an end user, alongside `login()` above: redirect
+them to a Fleetless-hosted login page (spec §3.4, §17) instead of collecting
+a password in your own app. The page can federate to your own IdP if you've
+configured one for this app, and the flow is Authorization Code + PKCE
+(OAuth 2.1 — no `implicit` grant, no `plain` challenge). It's also MCP's own
+front door (§17), but nothing about using it from this SDK depends on that.
+
+**Getting a `clientId`.** Register your app's own OAuth client in the
+console, under **App Settings → OAuth clients** — name it and list the
+redirect URIs it's allowed to use; the panel shows you the `client_id` you
+need below. For scripting (a seed, a gate, CI) the same thing is
+`POST /api/apps/:id/oauth-clients` (developer-authenticated:
+`{ client_name, redirect_uris }`, answers with the `client_id`) — what the
+console panel calls underneath. `clientId` is not your `appIdentifier` —
+they're deliberately different identifiers.
+
+```ts
+// 1. Send the browser there. beginHostedLogin makes no network call — it
+//    just builds the URL and generates the values PKCE and CSRF protection
+//    need.
+const request = await client.auth.beginHostedLogin({
+  clientId: 'oauth-client-id-from-the-console',
+  redirectUri: 'https://your-app.example.com/callback',
+})
+
+// Persist these two values before navigating away — a full page redirect
+// does not preserve any in-memory state, so this SDK hands them back to you
+// instead of holding them itself. sessionStorage survives the round trip
+// and clears itself when the tab closes.
+sessionStorage.setItem('fleetless_state', request.state)
+sessionStorage.setItem('fleetless_code_verifier', request.codeVerifier)
+window.location.href = request.url
+
+// 2. On the redirectUri page, once the hosted flow has finished. CHECK FOR
+//    AN ERROR FIRST — the callback can legitimately carry ?error=... instead
+//    of a code (RFC 6749 §5.2), and reading params.get('code')! unconditionally
+//    throws on that assertion instead of showing the user why they aren't
+//    signed in. Not a bug: an account with no membership in this app, or a
+//    federated IdP that's down, both land here as an error, not a crash.
+const params = new URLSearchParams(window.location.search)
+
+// Read once, clear once, before anything else — these are single-use
+// values for this one attempt regardless of what happens below, and doing
+// this first (rather than after an await that might throw) means the
+// cleanup can't be skipped.
+const expectedState = sessionStorage.getItem('fleetless_state')
+const codeVerifier = sessionStorage.getItem('fleetless_code_verifier')
+sessionStorage.removeItem('fleetless_state')
+sessionStorage.removeItem('fleetless_code_verifier')
+
+if (params.has('error')) {
+  // params.get('fleetless_code') is set for five W7b-specific outcomes with
+  // an actionable meaning (e.g. identity_not_provisioned: "ask an app owner
+  // to invite you"; idp_unavailable: "try again shortly") — absent for a
+  // plain protocol-shaped refusal (access_denied, ...), where
+  // error_description is all there is. See docs/recipes/hosted-login/ for
+  // the full table and what to tell the user for each one.
+  handleHostedLoginError(params.get('error')!, params.get('error_description'), params.get('fleetless_code'))
+} else if (!expectedState || !codeVerifier) {
+  // Nothing was persisted for THIS attempt — a callback landing in a
+  // different tab or window, a re-opened redirect URL, or a restored
+  // session all read back as null here, and none of them is an attack.
+  // completeHostedLogin tells this apart from a real mismatch itself
+  // (no_hosted_login_attempt vs state_mismatch) — mirrored here because
+  // there's no codeVerifier to even attempt the call with.
+  handleHostedLoginError('no_hosted_login_attempt', 'This login was not started in this browser tab.', null)
+} else {
+  try {
+    await client.auth.completeHostedLogin({
+      code: params.get('code')!,
+      state: params.get('state')!,
+      expectedState,
+      codeVerifier,
+      clientId: 'oauth-client-id-from-the-console',
+      redirectUri: 'https://your-app.example.com/callback',
+    })
+    // From here on client.auth.me() / logout() / silent refresh behave
+    // exactly as they do after login() — completeHostedLogin stores the
+    // identical session shape, through the same tokenStore.
+  } catch (error) {
+    // completeHostedLogin's own refusals (state_mismatch; invalid_grant for
+    // an expired or already-used code) surface as a thrown FleetlessError
+    // here, not a redirect — the one point in this flow where a thrown
+    // error, not a query parameter, is how a refusal reaches your app.
+    const code = error instanceof Error && 'code' in error ? String(error.code) : 'unknown'
+    handleHostedLoginError(code, error instanceof Error ? error.message : String(error), null)
+  }
+}
+```
+
+- **A `fleetless_code`-less `error` is a protocol-shaped outcome** (e.g.
+  `access_denied` for "the user declined consent") with no Fleetless-specific
+  remedy beyond `error_description`. The five `fleetless_code` values,
+  what each means and what your app can tell the user, are documented in
+  [`docs/recipes/hosted-login/`](../docs/recipes/hosted-login/README.md) —
+  not duplicated here to avoid two tables drifting apart.
+
+- **`sessionStorage.getItem(...)!` is the same tell as `params.get('code')!`
+  above, and this snippet had both, found by Momus-W7b's review the same
+  day the first one was fixed.** A non-null assertion is where a writer
+  knows a value can be absent and decides not to say so — reach for a
+  presence check (`if (!expectedState || !codeVerifier)` above) instead of
+  `!` anywhere a value crossed a boundary this code doesn't control
+  (a query string, `sessionStorage`, a thrown error's `.message`), not just
+  in the one place a reviewer already looked.
+
+- **This SDK never touches `sessionStorage`, or any storage, for you.**
+  `beginHostedLogin` returns `state`/`codeVerifier` rather than holding them
+  itself, because the redirect back is a fresh page load — nothing this SDK
+  keeps in memory survives it. Persist them however fits your app; a popup
+  flow that never truly navigates away can just keep them in a variable
+  instead.
+- **`completeHostedLogin` refuses before any network call** (`state_mismatch`)
+  if `state` doesn't match what `beginHostedLogin` returned for this
+  attempt — it will not complete a login your app did not itself start.
+- **Errors from this exchange use OAuth's own vocabulary, not this SDK's
+  usual `code`/`message` pairs.** `completeHostedLogin` can throw a
+  `FleetlessError` whose `.code` is e.g. `invalid_grant` (an expired or
+  already-used `code`) straight from RFC 6749 §5.2 — the exchange happens
+  against `/oauth/token`, a standards-compliant endpoint any OAuth client
+  can drive, not this SDK's own API.
+- **Never call `completeHostedLogin` a second time for the same redirect
+  while a first call is still in flight** — no timeout, framework retry,
+  or double-click guard should ever resubmit it (W7c; `completeHostedLogin`
+  itself makes exactly one request and has no retry of its own, so this is
+  entirely a call-site discipline). A second presentation of the same
+  authorization code revokes the whole refresh-token family server-side,
+  on purpose — a plain race looks identical to theft on the wire, and the
+  platform treats it as theft. What actually happens: one of the two
+  requests gets back `200` with a refresh token that is already dead, the
+  access token keeps working for the rest of its short TTL, and the
+  failure only surfaces at this session's first silent refresh — as
+  `token_revoked`, possibly minutes later, with nothing pointing back at
+  the retry that caused it. Guard the call site (an in-flight flag,
+  disabling the button) — this method cannot protect you from itself being
+  called twice.
+
+### Registration and account recovery (W6c)
+
+```ts
+// Self-registration into this app's pool — if the app has it enabled for
+// this address's domain. Sets the password now; does NOT log you in — see
+// below for why. Returns { mail } so you can show "check your email".
+await client.auth.register('user@example.com', 'correct-horse-battery')
+await client.auth.confirmRegistration(tokenFromTheEmailedLink) // -> now logged in
+
+// Changing your own password while logged in.
+await client.auth.changePassword('current-password', 'new-correct-horse-battery')
+
+// Forgot it entirely: request a link, then use the token it contains.
+await client.auth.requestPasswordReset('user@example.com')
+await client.auth.confirmPasswordReset(tokenFromTheEmailedLink, 'new-correct-horse-battery')
+```
+
+- **`register` does not log you in.** It sets the password and mails a
+  confirmation link; `confirmRegistration(token)` is the call that proves
+  you own the address and returns a session. This is deliberate, not a
+  missing convenience: a domain filter gates *which domains* may register,
+  never *whether the caller owns the address* — minting a session straight
+  out of `register` would let anybody who knows an allowed domain register
+  as somebody else at it and receive whatever role the app assigns, which on
+  this platform can mean permission to move a robot. **A deployment with no
+  SMTP configured cannot complete a self-registration at all** — unlike an
+  invitation, where a developer can hand the link over directly, there is no
+  other channel for the confirmation link. If you're testing against a
+  mail-less dev cloud, that is why nothing arrives.
+- **`register` does not take a role.** The app's own self-registration
+  setting decides it (§3.2: a pool member gets exactly one role per app,
+  the app owner's to configure, not a self-registering stranger's to pick).
+  It fails the same way whether the app has self-registration turned off or
+  the address's domain isn't on the allowed list — **those two cases are
+  indistinguishable on purpose**, the same reasoning as the reset request
+  below. Don't build a UI that tries to tell them apart. And `register`
+  resolves identically for an address that is new and one that already has
+  an account — same account-enumeration reasoning as `requestPasswordReset`;
+  `mail` in the response describes this deployment's mail configuration, not
+  whether the address exists, so it's safe to read either way.
+- **`confirmRegistration`'s token is single-use and expires**, and both
+  cases answer `token_spent` — same as `confirmPasswordReset` below.
+- **`changePassword` re-issues your session rather than leaving it alone.**
+  It returns fresh tokens, which this method stores for you exactly like
+  `login` does — you don't need to do anything with the return value. Every
+  *other* session of this identity is revoked; only the one that made this
+  call keeps working, and it keeps working because it was just handed new
+  credentials, not because the old ones were spared. Make sure your UI
+  surfaces the "your other sessions are about to end" consequence *before*
+  the user confirms, not after they get a "why was I logged out?" support
+  ticket.
+- **`requestPasswordReset` answers the same way for a known and an unknown
+  address, always.** This is not a bug and not something you can detect or
+  work around: it is the one place in this SDK where telling the two apart
+  would let a stranger enumerate accounts by their email address, so the
+  server (and this method) simply never says. Do not add a "no such
+  account" branch to your UI here — there is nothing in the response for
+  it to key off, on purpose. Show a generic "check your email" message
+  regardless of the outcome.
+- **`confirmPasswordReset`'s token is single-use and expires**, and both
+  cases answer `token_spent` — deliberately one code for both, so a caller
+  cannot tell "already used" from "too late" and learn anything about the
+  token's history. The recovery is the same either way: request a new link.
+  Succeeding revokes every other session, exactly like `changePassword`.
+- **`register` and `requestPasswordReset` are both behind the rate limiter**
+  (W6c) that guards every unauthenticated route — see
+  [Errors](#errors) below for how `rate_limited` surfaces and why this SDK
+  never retries it for you.
+- **`register`, `confirmRegistration` and `changePassword` are not available
+  on a `serverKey` client** — they throw immediately, same as
+  `login`/`logout`. A server key has no "own password" to change; a
+  successful `confirmRegistration`/`changePassword` returns tokens with
+  nowhere to store them (no token store on a serverKey client); and
+  self-registration is specifically the act of a *user* signing themselves
+  up — a backend creating pool members programmatically is a different act
+  with a different audit trail. `requestPasswordReset`/`confirmPasswordReset`
+  work on either kind of client — neither touches a session or a token
+  store, so there is nothing structural to forbid.
+- **These are the end-user routes (`/api/client/password/...`).** The
+  developer-facing console has its own equivalents under `/api/auth/`; this
+  SDK never speaks to that identity space.
+
+### Server-side callers — `serverKey`
+
+For your own backend, automation, or CI — full app rights, no login step:
+
+```ts
+const client = createClient({ apiUrl, appIdentifier, serverKey: 'flk_...' })
+await client.datapoints.get('robot-id', 'battery-percentage') // works immediately
+```
+
+A `serverKey` client has no session to manage: `auth.login`/`auth.logout`
+throw if called. A rejected server key does not refresh — there is nothing
+to refresh into — it just fails.
+
+`tokenStore` and `serverKey` are mutually exclusive; pick one per client.
+
+## Datapoints
+
+```ts
+client.datapoints.get(robotId, slug) // -> Promise<DatapointValue>
+client.datapoints.subscribe(robotId, slug, { onEvent, onError? }) // -> { unsubscribe() }
+```
+
+- **Your session survives a laptop lid being closed.** If a client reconnects
+  after being offline longer than the access token's lifetime, the
+  reconnect's authentication is refused as expired — the SDK refreshes
+  silently and retries the connection once before giving up, the same
+  courtesy a REST call gets. You do not need to detect this or re-login by
+  hand.
+- `subscribe` shares one WebSocket connection across every subscription on a
+  client. It reconnects with exponential backoff on a network drop, and
+  every active subscription is re-established automatically once the
+  connection (and, if the access token has since expired, a silent refresh)
+  comes back — you do not need to resubscribe yourself.
+- A subscription refused by the server (role does not grant the slug, an
+  unknown slug, ...) calls `onError` once with a `FleetlessError`; it never
+  calls `onEvent`. Note that Fleetless deliberately answers `forbidden` both
+  for "your role does not grant this" and for "no such slug" — the SDK does
+  not invent a distinction the API does not make.
+
+## Actions
+
+```ts
+const job = await client.actions.invoke(robotId, 'dock', { 'target_pose.position.x': 1.0 }) // -> Job, id is informative
+const sub = client.actions.subscribe(robotId, 'dock', {
+  onJob(event) {
+    console.log(event.job.state, event.feedback, event.progress) // feedback/progress arrive as the action reports them
+    if (event.job.state === 'succeeded') console.log(event.job.result)
+  },
+  onError(error) {
+    console.error(error.code, error.message)
+  },
+})
+
+// The operator's stop button: whatever is running on this slug, stop it.
+const stopped = await client.actions.cancel(robotId, 'dock')
+
+// Cancel the job you invoked, specifically — not whatever else might be
+// running there by the time this arrives:
+const cancelled = await client.actions.cancel(robotId, 'dock', job.id)
+// cancelled is the Job that was actually stopped, or null if nothing
+// matched. Naming a job.id that is no longer running rejects `not_found` —
+// it never falls back to stopping whatever *is* running instead, because
+// naming an id already said which one you meant.
+
+sub.unsubscribe()
+```
+
+> **Breaking in this release (W6b):** `actions.cancel`'s third argument
+> changed. It used to be `cancel(robotId, slug, options?)`; it is now
+> `cancel(robotId, slug, jobId?, options?)`, and `options` moved to the
+> **fourth** argument. If your code passes an options object third —
+> `cancel(robotId, slug, { timeoutMs: 5000 })` — that object now lands in
+> the `jobId` position instead. In TypeScript this is a compile error. In
+> plain JavaScript it throws `invalid_option` immediately, before anything
+> is sent, naming the mistake in the message — it does not silently send a
+> malformed request. Update the call to `cancel(robotId, slug, undefined,
+> { timeoutMs: 5000 })`, or to `cancel(robotId, slug, job.id)` if you meant
+> to address a specific job all along.
+
+- **`invoke` resolves as soon as the job exists** — the returned job id is
+  informative (spec §11.3), not the result. Feedback, progress and the
+  eventual result arrive separately, over `subscribe`.
+- **State is observed by slug, not by job id.** `subscribe(robotId, slug,
+  ...)` shows whatever job is currently running there — including a job
+  invoked by a different caller — which is also what makes late delivery
+  after a reconnect and two observers watching the same job both work
+  without any special-casing on your part. This does **not** change with
+  job-id cancel below: a slug is still a place a job may be running, not the
+  job itself, and `subscribe` still watches the place.
+- **One job runs per action slug.** A second `invoke` while one is already
+  running rejects `busy`, and `error.details.running` is the `Job` that is
+  already in flight — enough to show the user what is happening, or to
+  `subscribe` and wait for it, without guessing.
+- **`cancel` addresses either a slug or a specific job (W6b).**
+  `cancel(robotId, slug)` is the blunt operator form: stop whatever is
+  running there, whoever started it. `cancel(robotId, slug, job.id)` is a
+  caller cancelling the specific job it invoked — the difference matters
+  because a plain slug-cancel that arrives a moment after its own job ended
+  will happily stop whoever's job runs next on that slug, and a caller who
+  holds a `job.id` usually wants to rule that out. There is no automatic
+  fallback from the id form to the slug form on `not_found`: if you want
+  "stop whatever's there" behaviour, ask for it explicitly by omitting the id,
+  rather than relying on a refused id to degrade into it.
+- `subscribe` is reference-counted per `(robotId, slug)`, exactly like
+  `datapoints.subscribe`: two callers on the same key share one wire
+  subscription, and unsubscribing one never affects the other.
+- **`params` is flat, keyed by the exact `parameterSpec.name` the developer
+  declared** — `'target_pose.position.x'`, not `{ target_pose: { position: {
+  x: 1.0 } } }`. Do not nest it yourself: a field a spec did not declare
+  cannot be set at all (that is what §4.4 parameter checking *is*), and a
+  `parameter_invalid` refusal names the `field` it rejected using this same
+  flat key — nesting it client-side would make the refusal point at a path
+  you never typed.
+- **`options.patienceMs` bounds goal *acceptance* only (W6b)**, not the whole
+  job: `client.actions.invoke(robotId, 'dock', params, { patienceMs: 5_000 })`
+  makes the platform give up if no action server accepts the goal within 5s
+  (`goal_timeout`), but once accepted the job runs as long as it runs — you
+  observe it via `subscribe`, you never await it. Omit it and you get the
+  platform default (currently 15s), unchanged from before this option
+  existed. Outside the platform's `[1s, 120s]` bounds the call is refused
+  with `validation_error` — this SDK does not clamp your number to fit, and
+  does not retry with a different one on your behalf. The floor exists
+  because a too-short patience does not just fail politely: it made the
+  bridge report `goal_timeout` and then issue a corrective cancel against a
+  goal an action server accepted a moment later, so an unreachable deadline
+  was causing a real cancellation on the robot, repeatably.
+
+## Services
+
+```ts
+const result = await client.services.call(robotId, 'get-status', { verbose: true })
+
+// patienceMs bounds the *whole* wait here — unlike an action, a service has
+// no further state to observe once the platform gives up on it:
+const status = await client.services.call(robotId, 'get-status', {}, { patienceMs: 5_000 })
+```
+
+Same flat-key convention for `params` as `actions.invoke`.
+
+A service call is a job underneath — the same disconnect survival as an
+action (spec §6.1: "an action goal or a service call") — but that is
+deliberately invisible here: `call` waits for it internally and resolves
+with the result directly, or rejects with the typed error it failed with.
+There is nothing to subscribe to for a service: no feedback, no progress,
+no cancel.
+
+`options.patienceMs` (W6b) is the platform's own patience for this call —
+distinct from `options.timeoutMs`, which is this SDK's own local bound on the
+**whole call** (default 30s): the ack that a job was created, plus however
+much of that budget is left for the job to then reach a terminal state — not
+two separate 30-second windows back to back (D10). Setting `timeoutMs: 5000`
+bounds total latency at ~5s, once, not ~5s-then-another-5s if the ack happens
+to arrive late. `patienceMs` and `timeoutMs` still bound different things and
+neither derives from the other when both are set: a short `timeoutMs` with a
+long `patienceMs` gives up locally while the platform keeps trying; a short
+`patienceMs` with a long `timeoutMs` means the platform's own refusal
+(`goal_timeout` or similar) usually arrives well before your local timeout
+would have fired anyway.
+
+## Publishers
+
+```ts
+await client.publishers.publish(robotId, 'cmd-vel', { 'linear.x': 0.2, 'angular.z': 0 })
+```
+
+`message` follows the same flat, `parameterSpec.name`-keyed convention as
+`actions.invoke`'s `params` — **not** a nested ROS message tree. (The
+publisher's *failsafe* message, by contrast, is a whole nested message body —
+but that one is authored once by the developer in the console, never sent by
+a caller.)
+
+**Publishing is a plain method call — no more, no less.** There is
+deliberately no deadman switch, rate governor, or "takt" helper in this SDK
+(spec §14.3): the safety pattern for *how often* and *when* to publish is
+your app's responsibility, not something this library does for you. Believing
+the SDK protects you here is more dangerous than knowing it does not.
+
+What the platform *does* guarantee (spec §6.4, §7.2) is the bridge's own
+failsafe: the developer configures a `timeout_ms` and a failsafe message when
+exposing the publisher, and if messages stop arriving for any reason —
+including your process crashing — **the bridge itself** publishes that
+failsafe message on the topic. That is the platform's safety primitive, not
+this SDK; build your app as if it is the only thing standing between a
+dropped connection and a robot that keeps moving, because for the interval up
+to `timeout_ms` it is.
+
+Publishing is also implicitly exclusive: whoever last published holds the
+publisher until they have been quiet for the configured `quiet_timeout_ms`.
+A `publish` call while someone else holds it rejects `publisher_busy`.
+
+## Jobs
+
+```ts
+const jobs = await client.jobs.list(robotId) // -> Job[]
+```
+
+Every job the platform currently believes this robot has — at most one per
+slug, the same shape `actions.subscribe`/`services.call` observe, just
+gathered across the whole robot instead of one named slug at a time (W7,
+register row 2k).
+
+`actions`/`services` require knowing the slug first, which is not always
+true: a bridge reconnecting can name a job the cloud only *adopted*, and a
+configuration change can leave a job on a slug the published document no
+longer contains. Both are jobs no slug can name up front — `jobs.list` is how
+you find them anyway, e.g. to reconcile local UI state against "what is this
+robot actually doing" on load, rather than polling every slug you happen to
+know about.
+
+Grant-filtered like everything else: an end user or server key sees only
+jobs on slugs their role grants; a developer session sees every job on the
+robot. `[]` means the robot is doing nothing, not "we did not look" — the
+array is never `null`.
+
+**Ordered newest first by `started_at`, `job.seq` as the tiebreaker for two
+jobs minted in the same millisecond** — but for an adopted job, `started_at`
+is adoption time, not when it actually started on the robot, so read this as
+newest-*known*-first: a job the robot has been running for an hour can sit
+above one started a minute ago if the hour-long one was only just adopted.
+
+## Cameras
+
+```ts
+const cameras = await client.cameras.list(robotId) // -> CameraDescriptor[]
+```
+
+### Snapshot — always on, independent of live
+
+```ts
+const snap = await client.cameras.snapshot(robotId, 'front')
+if (snap.image === null) {
+  // Nothing captured yet (e.g. right after a fresh publish) — a state, not
+  // an error. Don't treat this as a failure.
+} else {
+  console.log(`${snap.mime}, ${snap.age_ms}ms old`) // an <img> src, a file, whatever you need
+}
+```
+
+- **`age_ms` is the cloud's own figure — always trust it, never recompute
+  it** as `Date.now() - snap.timestamp_ms`. The cloud is the one clock that
+  knows how long it has actually held the frame; your own clock skew would
+  quietly turn "how old is this?" into a lie.
+- A snapshot keeps updating on the camera's configured interval **whether or
+  not anyone is watching live** (spec §10), and keeps being served — with a
+  growing `age_ms` — even while the robot's bridge is offline. It never goes
+  stale silently: you always know exactly how old what you have is.
+- Polling for "did a newer frame arrive?" without re-downloading the image
+  every time: use `client.cameras.snapshotMeta(robotId, slug)`, which returns
+  everything `snapshot` does except `image`.
+
+### Live — on demand, refcounted, and it costs you a release
+
+```ts
+import { Room } from 'livekit-client' // your choice of LiveKit client SDK
+
+const room = new Room()
+const session = await client.cameras.live(robotId, 'front')
+await room.connect(session.url, session.token)
+// ... attach room's video track to your <video> element, however you render it
+
+// When you're done watching — **both calls, together**:
+await room.disconnect()
+await session.release()
+```
+
+- **The first `live()` call on a camera starts the robot publishing; the
+  last viewer leaving stops it** (spec §10) — refcounted in the cloud, not
+  in this SDK.
+- **Each `session` releases only its own hold (W6b).** `session.session_id`
+  identifies *this* call's hold, and `release()` sends exactly that id.
+  Before W6b a `DELETE` carried no id and released **every** hold your
+  logged-in identity had on that camera — so two tabs open on the same
+  stream were one hold as far as the server could tell, and closing either
+  tab stopped the robot for both. The survivor kept rendering a frozen frame
+  rather than an ended session, because a LiveKit token is checked when a
+  `Room` joins and never again — see `expires_at` below. Two independent
+  `live()` calls (two tabs, two component instances, whatever your app's
+  shape is) now get two independent sessions, and releasing one never
+  touches the other.
+- **`session.release()` alone does not stop the stream.** The cloud treats
+  LiveKit room *participation* as the source of truth for who is still
+  watching, not the `DELETE` this method sends — a browser tab that
+  crashes or is force-closed cannot be relied on to tell the cloud
+  anything, but LiveKit's own server notices a participant leaving without
+  needing its cooperation. `release()` is a courteous fast path that speeds
+  the stream stopping up; disconnecting your `Room` is what actually makes
+  it stop. **Always call both together**, as in the example above — a
+  cleanup that only releases while the `Room` stays connected leaks a
+  robot streaming to nobody.
+- The same pairing applies to a framework's unmount hook:
+
+  ```ts
+  import type { CameraLiveSession } from '@fleetless/sdk'
+
+  useEffect(() => {
+    let cancelled = false
+    let session: CameraLiveSession | undefined
+    const room = new Room()
+
+    client.cameras.live(robotId, 'front').then(async (s) => {
+      if (cancelled) {
+        // Unmounted before the request resolved — release immediately,
+        // there is no UI left to show video in.
+        void s.release()
+        return
+      }
+      session = s
+      await room.connect(s.url, s.token)
+    })
+
+    return () => {
+      cancelled = true
+      void room.disconnect()
+      void session?.release()
+    }
+  }, [robotId])
+  ```
+
+- **`session.expires_at` is a join deadline, not a session backstop.**
+  LiveKit checks a token when a `Room` connects, not while it stays
+  connected — so a `Room` that joined before `expires_at` keeps streaming
+  right past that timestamp, untouched. It only bounds how long an *unused*
+  token sits around; it does **not** bound a crashed process or a `kill -9`
+  after joining. What actually ends an already-joined session is the pair
+  of calls above, the cloud noticing (via its own reconciliation) that this
+  viewer's room participation ended, or revocation kicking the participant.
+  Do not design around this field as if it protected you from a forgotten
+  cleanup.
+- `release()` is safe to call more than once and never rejects — it is a
+  courtesy notification, not the thing that actually stops the stream (see
+  above), so there is nothing more useful a caller could do with a failed
+  one. That also makes it safe to use directly as a cleanup callback
+  without wrapping it in a `try`/`catch`.
+- **No video widget, no teleop-style helper here** (spec §14.3 keeps this
+  SDK thin): `live()` hands back exactly what a LiveKit client needs
+  (`url`, `token`) and stops — rendering the video, choosing a UI library,
+  and reconnect/backoff for the *media* connection are yours, the same way
+  `publishers.publish` hands you a plain method call with no rate governor
+  built in.
+
+## Assets
+
+```ts
+const { assets, urdf, urdf_available } = await client.assets.list(robotId)
+```
+
+The asset store (spec §4.6): a robot's URDF and the meshes it references,
+each addressed by uuid, unmodifiable, and reachable only with the same
+`Authorization` header as everything else — no signed URL, no token in the
+query string. Syncing a URDF from the connected bridge is a console action,
+Owner-tier, and out of scope for this SDK on purpose (§4.6 says so
+explicitly) — this surface is for *reading* what has already been synced.
+
+`urdf.missing` names the `package://` URIs the sync could not resolve. Show
+the URIs, not just the count — "2 Meshes fehlen" sends a developer looking
+through a workspace by hand; the URIs are what they can act on.
+`urdf_available` is `true`/`false` when a bridge is connected and reporting,
+`null` when none is — "no robot is online to ask" and "the robot has no
+URDF" are different facts a caller needs to tell apart.
+
+```ts
+const { body, mime } = await client.assets.get(robotId, assetId)
+const xml = await client.assets.urdf(robotId) // -> string, ready for URDFLoader.parse()
+```
+
+`get` answers one asset's raw bytes — a mesh, or anything else by id, the
+same way `createMeshLoader` reaches one internally. `urdf` is a special case
+of the same read: XML text with every `package://` mesh URI already
+rewritten to an absolute Fleetless asset URL, decoded because every consumer
+needs it as a string for `URDFLoader.parse(xml)`.
+
+Neither absorbs a "nothing yet" state the way `cameras.snapshot` absorbs
+`no_snapshot_yet` — a missing or too-large asset is a real failure here, not
+a state a renderer should quietly treat as empty, so both throw a
+`FleetlessError` (`asset_missing`, `asset_too_large`, `forbidden`) like
+every other route.
+
+### Rendering a textured robot — `prepareUrdfScene`
+
+`createMeshLoader` (below) only ever solved meshes, because `loadMeshCb` is
+the one override hook `urdf-loader` has — and three.js's `TextureLoader` has
+no equivalent hook at all. So a `<material><texture>` in the URDF, and an
+image a `.dae` references *internally* (`<init_from>textures/skin.png`,
+resolved by the renderer against wherever it loaded the `.dae` from), were
+both unreachable: rewritten to a real asset URL, fetched by three.js with no
+credential, and refused.
+
+`prepareUrdfScene` covers all three cases — mesh, URDF-level texture,
+`.dae`-internal texture — with one mechanism: three.js's
+`LoadingManager.setURLModifier`. Every load the manager oversees, including
+the images `ColladaLoader` fetches on its own account, is routed through it
+first.
+
+```ts
+import URDFLoader from 'urdf-loader'
+import * as THREE from 'three'
+
+const manager = new THREE.LoadingManager()
+const { urdfText, missing, dispose } = await client.assets.prepareUrdfScene(robotId, manager)
+
+if (missing.length > 0) {
+  // Same strings assets.list()'s urdf.missing reports — decide whether to
+  // warn, block, or just render what resolved. Not thrown.
+  console.warn(`This robot will render incompletely — unresolved: ${missing.join(', ')}`)
+}
+
+const loader = new URDFLoader(manager)
+const robot = loader.parse(urdfText)
+scene.add(robot)
+
+// Once the scene has finished loading (or on unmount):
+dispose()
+```
+
+What it does: fetches the robot's asset list, fetches every mesh and texture
+asset **with the `Authorization` header** into a `Blob`, maps each asset's
+name to a `blob:` URL, and installs `manager.setURLModifier` to resolve
+against that map.
+
+**Only claims what it owns — everything else passes through unchanged.**
+`manager` is frequently your own scene-wide `LoadingManager`, shared for an
+HDRI, an environment map, a font atlas, a ground texture — none of which
+have anything to do with this robot. So the rule is: a `package://`
+reference, or a root-relative path whose leading segment names a ROS package
+this robot's assets (or `missing`) actually mention, is this method's to
+resolve or refuse. Anything else — a relative path, a root-relative path
+under a different namespace, a `data:`/`blob:` URL — is left completely
+alone, exactly as if `prepareUrdfScene` had never been called. **The one
+exception is an absolute `http(s)` URL**, refused regardless of namespace: a
+hostile URDF naming an attacker's host directly (bypassing `package://`
+entirely) must never reach a real network request, so this is the one case
+this method cannot afford to leave ambiguous.
+
+Anything this method owns and cannot resolve — a reference the store never
+got, or that attacker-named absolute URL — resolves to a shared, empty,
+page-local `blob:` URL, never the original string. A loader handed empty
+bytes fails to parse them, which is the same loud failure a genuinely
+missing mesh already produces; nothing quietly renders wrong and nothing
+quietly reaches the network. `dispose()` revokes every real asset `blob:`
+URL this call created — not that shared one, which stays valid for the life
+of the page, which is what lets the installed modifier keep refusing owned
+references correctly even after `dispose()`, rather than reverting to raw,
+unrefused passthrough.
+
+This closes a real gap, not a hypothetical one: `URDFLoader.resolvePath()`
+passes a non-`package://` filename through unchanged, so a `<mesh
+filename="http://attacker.example/x.stl">` on a robot's ROS graph would
+otherwise reach the browser's own `fetch` verbatim. No credential travels
+with it — three.js does not carry the bearer token — but it is still a
+real, attacker-named network request made by every viewer who renders the
+URDF. A `blob:` URL created in this page cannot resolve to any other origin
+by construction, so refusing this way removes the network request entirely
+rather than merely declining to authenticate it.
+
+**`urdf-loader` resolves `package://` itself, before the URL modifier ever
+sees it.** `URDFLoader.parse()`'s own `resolvePath()` rewrites
+`package://pkg/rel` to the root-relative `/pkg/rel` under its default
+`packages: ''`, and *that* rewritten form is what actually reaches the URL
+modifier — not the original string. `prepareUrdfScene` registers both forms
+per asset, so the example above works with a plain `new URDFLoader(manager)`
+and no extra configuration. If you set `loader.packages` to something other
+than the default, results depend on what it produces; setting it to
+`(pkg) => \`package://${pkg}\`` reconstructs the original name and is
+covered too.
+
+**A `.dae`'s own internal references get a second-chance, normalized lookup
+too.** three.js builds the request for one by plain string concatenation
+(`this.path + url`, no `..`/`.` collapsing), while `asset.name` carries the
+*normalized* tail — so `../textures/skin.png` or `./textures/skin.png`
+(ordinary exporter output; Blender writes `./` routinely) would otherwise
+miss the direct lookup. Handled the same way for you: nothing to configure.
+
+The browser **never** fetches an asset directly, for anything this method
+owns — every read goes through this SDK with the bearer token first, same
+as everything else in this package, and the cloud enforces `assets` exactly
+as it does today. Pre-fetch
+is unavoidable, not a design shortcut: a URL modifier cannot be asynchronous,
+so bytes have to already be in memory before `URDFLoader.parse` runs. Fetches
+are bounded to `options.concurrency` (default 6, must be a positive integer —
+`0` or negative throws `invalid_option` rather than silently fetching nothing
+and returning a scene that renders completely blank with no error to explain
+why) and scoped to the mesh and texture assets in the robot's own list —
+which already *is* what its current URDF references (a re-sync reconciles,
+so a mesh the URDF stops naming stops belonging to the robot).
+
+`options.signal` cancels the whole call (register row 244, W7c) — pass an
+`AbortController`'s signal if the caller might navigate away or switch
+robots mid-load. Checked before the first request and forwarded straight to
+every underlying `fetch()`, so an abort tears down connections already in
+flight rather than merely stopping new ones from starting; every `blob:`
+URL already created before the abort is revoked, and the rejection is always
+`FleetlessError('aborted', ...)` regardless of which stage the abort landed
+in or which shape the runtime's own `fetch()` rejects an aborted request
+with.
+
+**Do not also install `createMeshLoader` on the same manager.** They read
+two different URDF sources — this method fetches the URDF's *raw* bytes,
+`createMeshLoader` is meant to pair with `urdf()`'s cloud-rewritten text.
+**Not "double-fetches every mesh"** — a first version of this sentence said
+that, and it was traced and found wrong (Momus-W7a review): what actually
+happens is asymmetric breakage, not duplication. Paired with this method's
+raw text, `createMeshLoader` gets urdf-loader's own `resolvePath()` output
+rather than an absolute Fleetless URL and 404s every mesh while textures
+still work; paired with `urdf()`'s rewritten text instead, meshes load and
+every texture 401s, because `createMeshLoader` bypasses this method's URL
+modifier entirely for meshes and there is no equivalent hook for a texture.
+A developer who combined them by accident would have debugged the wrong
+symptom either way — **enforced now, not only documented**: installing both
+on the same manager fails loudly, before either ever touches the network,
+rather than silently producing one of those two broken scenes. Use
+`prepareUrdfScene` for anything rendered with `urdf-loader`/three.js;
+`createMeshLoader` stays useful only for a mesh-only, non-three.js
+`loadMeshCb`-shaped renderer.
+
+### The mesh callback — `createMeshLoader`
+
+**Superseded by `prepareUrdfScene` above for three.js/`urdf-loader`
+consumers — reach for it there first, especially for anything with
+textures.** Kept because it is renderer-agnostic (any `loadMeshCb`-shaped
+consumer, not only three.js) and mesh-only apps may not need the wider
+mechanism. Do not install both on one load — see the warning above.
+
+An `<img>` tag and the default three.js loaders cannot set an
+`Authorization` header, and the platform deliberately has no signed URLs and
+no token in the query string (see the reasoning in `@fleetless/contracts`'
+`assets.ts`) — so every app would otherwise write this glue itself, and each
+one differently. `createMeshLoader` is that glue, shaped to drop straight
+into [`urdf-loader`](https://github.com/gkjohnson/urdf-loaders)'s own
+`loadMeshCb` hook:
+
+```ts
+import URDFLoader from 'urdf-loader'
+
+const loader = new URDFLoader()
+loader.loadMeshCb = client.assets.createMeshLoader(robotId, loader.defaultMeshLoader.bind(loader))
+
+const xml = await client.assets.urdf(robotId)
+const robot = loader.parse(xml)
+scene.add(robot)
+```
+
+`createMeshLoader(robotId, delegate, options?)` returns a function with
+`loadMeshCb`'s own four-argument signature
+(`path, manager, material, onComplete`) — assign it directly, do not wrap
+it. `delegate` gets the same four arguments and does the actual
+format-specific parsing (STL/OBJ/DAE/GLTF); in practice it is
+`loader.defaultMeshLoader.bind(loader)`, urdf-loader's own built-in mesh
+parser, not something an app writes from scratch.
+
+What this method does that a plain loader can't: it fetches `path` with the
+`Authorization` header attached, wraps the bytes in a `Blob`, and calls
+`delegate` with an **object URL** substituted for `path` — so `delegate`
+never touches the network, and every format-specific parser downstream
+works unmodified against a same-origin `blob:` URL. The object URL is
+revoked the moment `delegate` reports success or failure, or after
+`options.timeoutMs` (default 30s) if it never reports at all — a URDF pulls
+in thirty-odd meshes and this callback can run for days in a long-lived
+dashboard, so a delegate that hangs or never calls back must not leak the
+URL or stall the load forever. A delegate that throws synchronously is
+caught the same way, resolving `onComplete(null, err)` rather than
+propagating into whatever called this callback (typically three.js's own
+URDF traversal).
+
+**`path` is only ever fetched if its origin matches this client's own
+`apiUrl`.** A URDF is ROS graph input, not first-party data — anything on a
+robot's ROS graph can publish one — and the cloud only rewrites `package://`
+URIs; a `<mesh filename="https://...">` naming a URL outright is served
+back unchanged. Without this check, a hostile URDF could point a mesh
+anywhere and this callback would fetch it with the caller's own bearer
+token attached. A mismatched origin is refused before any network call —
+`onComplete(null, err)` with `err.code === 'untrusted_absolute_url'` — never
+fetched anonymously either, so a malicious reference fails loudly instead
+of quietly making an unexpected request on the app's behalf.
+
+## History
+
+Reads recorded data for a datapoint that was published with `retention: true`
+(spec §8) — plain REST, no realtime channel, the same way `cameras.snapshot`
+is. You do not need to learn the underlying query grammar; `history()` takes
+a plain options object and hands back a typed, discriminated result.
+
+### Range — relative or absolute, always a string
+
+```ts
+// Relative to now:
+await client.datapoints.history(robotId, 'battery-percentage', { from: 'now-30s' })
+await client.datapoints.history(robotId, 'battery-percentage', { from: 'now-1h', to: 'now-30m' })
+
+// Absolute unix milliseconds, for a report over a fixed window:
+await client.datapoints.history(robotId, 'battery-percentage', { from: '1700000000000', to: '1700003600000' })
+```
+
+`from` (required) and `to` (optional, defaults to now) each accept `now-30s`
+/ `now-5m` / `now-1h`, or absolute unix milliseconds — **always as a
+string**, whichever form you use. The SDK does not accept a `Date` or a
+`number` and stringify it for you: that would be a decision about which of
+the two forms you meant, made silently on your behalf, and the next person
+reading the actual wire traffic would have no way to tell which of you made
+it. Convert yourself, explicitly, at the call site.
+
+### Two result shapes, chosen by whether you asked for aggregation
+
+```ts
+// Raw samples: leave `aggregate` out.
+const samples = await client.datapoints.history(robotId, 'battery-percentage', { from: 'now-1h' })
+console.log(samples.kind) // 'samples'
+for (const s of samples.samples) console.log(s.timestamp_ms, s.value)
+if (samples.truncated) {
+  // `limit` was hit — say so, rather than let a short array look like a quiet period.
+}
+
+// Aggregated buckets: pass `aggregate`. `window` and `agg` always travel
+// together — the API refuses one without the other, so this SDK models them
+// as one object instead of two independent optional fields you could set
+// only one of.
+const buckets = await client.datapoints.history(robotId, 'battery-percentage', {
+  from: 'now-1h',
+  aggregate: { window: '1m', agg: 'avg' },
+})
+console.log(buckets.kind) // 'buckets'
+for (const b of buckets.buckets) {
+  if (b.sample_count === 0) {
+    // Genuinely empty — nothing was recorded in this bucket. Draw a break in
+    // the line here.
+  } else if (b.value === null) {
+    // Samples DID land here, none of them numeric — a string, a bool, a whole
+    // message. There is data in this interval; it just has no height. Do not
+    // draw this as a gap: that is the same lie as reporting an empty bucket,
+    // and it is what this branch exists to prevent.
+    console.log(b.bucket_start_ms, `${b.sample_count} samples, none numeric`)
+  } else {
+    console.log(b.bucket_start_ms, b.value, b.sample_count)
+  }
+}
+```
+
+`history` is overloaded on whether `aggregate` is present: passing it gets
+you back a `HistoryBucketsResponse` (`kind: 'buckets'`) at the type level
+already, no narrowing required, because you already know that's what you
+asked for; leaving it out gets you `HistorySamplesResponse` (`kind:
+'samples'`). Both still carry `kind` at runtime, so code that holds the
+result in a variable typed as the union can branch on it the same way.
+
+`aggregate.field` names a numeric field inside an object value (`'pose.x'`,
+the same flat-key convention as `actions.invoke`'s `params`) — only needed
+when the datapoint's own value isn't itself a number.
+
+**Buckets align to wall-clock UTC, not to your `from`.** For a clean width
+like `10s`/`1m`/`1h`, `bucket_start_ms` lands on :00/:10/:20 seconds,
+top-of-minute, top-of-hour — never at `from`, `from + window`, `from +
+2*window`, etc. Strictly the boundaries are counted from a fixed origin
+(2000-01-03) rather than from midnight, which is the same thing for any width
+that divides evenly into an hour; a width like `45s` is legal and its
+boundaries will not look like round clock times. This is deliberate: `from` is often relative (`now-30s`), so
+a chart re-polling the same query on an interval gets a slightly different
+absolute `from` on every poll — under `from`-aligned buckets that would
+reshuffle every boundary each time, drawing visibly jittery bars for no
+reason in the data. Wall-clock alignment stays stable across repeated polls
+of the same window width.
+
+One consequence worth knowing: **the first and last bucket in a response can
+be partial.** `bucket_start_ms` is the wall-clock boundary that contains the
+earliest/latest in-range sample, and that boundary can fall before `from` or
+extend past `to` — but `sample_count`/`value` only ever reflect samples that
+actually matched the queried range. A low count on an edge bucket is that
+boundary effect, not a gap in what was recorded.
+
+Two more things that are easy to assume and wrong:
+
+- **A truncated samples response says *why*.** `truncated_by` is `'limit'`
+  when the row cap cut it and `'bytes'` when the response-size budget did.
+  The remedies differ: raising `limit` fixes the first and does nothing for
+  the second, which needs a narrower range or a numeric `field` so whole
+  messages are not carried. `null` when nothing was cut.
+- **`value * sample_count` is not a sum.** `value` aggregates only the numeric
+  samples; `sample_count` counts all of them. The two agree only for a
+  datapoint whose values are always numbers.
+- **The two paths do not currently share a range convention.** Raw samples are
+  inclusive of `to`; buckets are half-open and exclude it. A sample landing
+  exactly on an absolute `to` therefore appears in one and not the other. This
+  is a known inconsistency, not a design: both become half-open, and this
+  paragraph moves with them.
+
+### Errors specific to history
+
+```ts
+try {
+  await client.datapoints.history(robotId, 'robot-details', { from: 'now-1h' })
+} catch (error) {
+  if (error instanceof FleetlessError) {
+    switch (error.code) {
+      case 'not_recorded':
+        // The slug is granted, but was never marked `retention: true`. An
+        // empty samples array would look identical to "recorded, but
+        // nothing happened in this window" — and the two need opposite
+        // fixes, so the API refuses instead of answering with silence.
+        break
+      case 'not_aggregatable':
+        // `aggregate` was requested on a value that isn't a number, and no
+        // numeric `aggregate.field` was given. Refused rather than coerced
+        // — an average of strings or booleans is a number that means
+        // nothing, and it would chart as confidently as a real one.
+        break
+    }
+  }
+}
+```
+
+Neither of these is absorbed into a quiet empty result the way
+`cameras.snapshot` absorbs `no_snapshot_yet` into `image: null` — that
+absorption is right for a snapshot, where an empty answer is the truth; here
+it would erase the distinction between "turn recording on" and "look at a
+different window," so both reach you as a thrown `FleetlessError` instead.
+
+## Errors
+
+Every rejected call throws (or, for a subscription, hands to `onError`) a
+`FleetlessError`:
+
+```ts
+import { FleetlessError } from '@fleetless/sdk'
+
+try {
+  await client.datapoints.get(robotId, 'robot-details')
+} catch (error) {
+  if (error instanceof FleetlessError) {
+    switch (error.code) {
+      case 'forbidden':
+        // your role does not grant this slug
+        break
+      case 'token_expired':
+      case 'token_revoked':
+        // the session could not be refreshed — send the user back to login
+        break
+      default:
+        console.error(error.code, error.message, error.details)
+    }
+  }
+}
+```
+
+`code` is the stable, machine-readable value from the spec's error culture
+(§11.5) — branch on it, never on `message`, which is for logs and humans
+only. It's typed as `ErrorCode | SdkErrorCode | (string & {})`, so a
+`switch` gets autocomplete on both sets while still accepting a code newer
+than your installed version.
+
+**None of these codes ever come from the server** — `SDK_ERROR_CODES` lists
+them:
+
+- `no_session` — a call was made, or a subscription attempted, with nobody
+  logged in. Call `auth.login()` first.
+- `no_websocket` — no `WebSocket` implementation is available in this
+  environment. Pass one via the `WebSocket` option.
+
+  Both fire *before* a request ever reaches the network, and are named
+  apart from the server's own `unauthorized` so you can always tell "the
+  server refused me" from "the SDK refused before asking."
+
+- `unparseable_error` — the opposite direction: a response *did* come back,
+  its body just wasn't shaped like §11.5's error format, so there is no
+  server `code` to relay.
+- `command_timeout` — an `invoke`/`cancel`/`publish`/`services.call` got no
+  reply within its timeout (default 10s, 30s for `services.call`; override
+  with `{ timeoutMs }`). The server may still be working on it — this only
+  means the SDK stopped waiting.
+- `command_outcome_unknown` — worse than a timeout, and told apart from it
+  on purpose: the realtime connection was replaced by a reconnect before any
+  reply to your command arrived, so a reply can now never come — the
+  server, if it answered at all, answered a socket that no longer exists.
+  **The SDK never retries automatically** (that could invoke an action
+  twice); recover by reading the job — `actions.subscribe(robotId, slug,
+  ...)` shows you whatever is actually running, regardless of which
+  connection asked for it.
+- `unexpected_response` — the server said the command succeeded but left out
+  something it is defined to always return (e.g. no job on a successful
+  `invoke`, or W6c: a REST route documented as always returning a body —
+  `login`, `me`, `register`, all the others except the handful documented as
+  answering `204`/a bodyless `202` — coming back with an empty one). A
+  contract violation the SDK noticed, not a refusal.
+- `untrusted_absolute_url` (W7) — `assets.createMeshLoader`'s callback
+  received an absolute URL (from a URDF's rewritten mesh URIs) whose origin
+  does not match this client's own `apiUrl`, and refused to fetch it. Fires
+  before the network call, so no `Authorization` header is ever built for
+  it, let alone attached — a URDF is ROS graph input, not first-party data,
+  and this SDK will not send your credential to whatever host it happens to
+  name. Surfaced through `createMeshLoader`'s `onComplete(null, err)`, the
+  same channel as a network failure.
+- `no_urdf_synced` (W7a) — `assets.prepareUrdfScene` found no `kind: 'urdf'`
+  row in `assets.list()`. Thrown before any asset fetch — the fix is to sync
+  a URDF first (console, Owner-tier), which this error says directly rather
+  than surfacing later as a confusing failure from `URDFLoader.parse`.
+- `aborted` (W7c) — `assets.prepareUrdfScene`'s `options.signal` fired,
+  either before the call started or mid-flight. One code regardless of when
+  the abort landed, rather than whatever shape the runtime's own `fetch()`
+  happens to reject an aborted request with.
+
+### `rate_limited` — surfaced, never retried (W6c)
+
+Unlike the codes above, `rate_limited` **does** come from the server — every
+unauthenticated route (`login`, `register`, `requestPasswordReset`, and the
+rest) sits behind a limiter that refuses before it ever checks a password,
+so a flood of attempts cannot be turned into CPU spent hashing them.
+
+```ts
+import type { RateLimitDetails } from '@fleetless/sdk'
+
+try {
+  await client.auth.login(email, password)
+} catch (error) {
+  if (error instanceof FleetlessError && error.code === 'rate_limited') {
+    const { retry_after_ms } = error.details as RateLimitDetails
+    // wait retry_after_ms, then let the USER retry — see below
+  }
+}
+```
+
+- **It carries exactly one number, `retry_after_ms`** — the same way `busy`
+  carries `error.details.running` (see [Actions](#actions)): when to come
+  back, and nothing else. No window, no attempt count, no ceiling — none of
+  that changes what an honest caller does, and all of it would help a
+  dishonest one, so the server never sends it and there is nothing more to
+  read off `error.details`.
+- **This SDK never retries a `rate_limited` response for you, anywhere, and
+  never will.** A client library that retries a rate limit automatically is
+  exactly the client behaviour the limit exists to stop — building that in
+  would turn every app built on this SDK into the attack. Back off using
+  `retry_after_ms` yourself, and only after the person at the keyboard asks
+  for it again — not on a timer that fires unattended.
+
+## Configuration
+
+```ts
+createClient({
+  apiUrl: string,              // e.g. 'https://api.fleetless.dev'
+  appIdentifier: string,       // the app's identifier, from the console
+  tokenStore?: TokenStore,     // default: in-memory
+  serverKey?: string,          // 'flk_...' — alternative to tokenStore
+  realtimeUrl?: string,        // default: derived from apiUrl (ws(s) + /realtime)
+  fetch?: typeof fetch,        // default: the global fetch
+  WebSocket?: typeof WebSocket, // default: the global WebSocket
+})
+```
+
+`fetch`/`WebSocket` are injectable for testing and for runtimes without a
+global implementation of one of them — the SDK never assumes a browser.
+
+## Contributing
+
+```sh
+pnpm i
+pnpm test   # vitest, against a fake fetch and a fake WebSocket — no cloud needed
+pnpm build  # tsup -> dist/ (ESM + CJS + .d.ts)
+```
+
+`@fleetless/contracts` is the source of truth for every wire type — never
+redefine a shape the SDK reads from or writes to the API; import it.