@fleetless/sdk 1.0.0 → 2.0.1

package/README.md

@@ -1,68 +1,83 @@
 # @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
+[![npm version](https://img.shields.io/npm/v/@fleetless/sdk)](https://www.npmjs.com/package/@fleetless/sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@fleetless/sdk)](https://www.npmjs.com/package/@fleetless/sdk)
+[![license MIT](https://img.shields.io/npm/l/@fleetless/sdk)](LICENSE)
+[![node >=20](https://img.shields.io/node/v/@fleetless/sdk)](https://nodejs.org)
+
+The official TypeScript SDK for apps built on [Fleetless](https://fleetless.dev),
+which exposes a ROS 2 robot as a hosted REST and realtime API — exactly the
+topics, services and actions a developer chose to publish, under stable slugs,
+behind roles. The SDK covers all of it: datapoints (read, subscribe, recorded
+history), actions, services, publishers, cameras, jobs, assets and URDF, the
+hosted login, and an end user's own consent grants. It is framework-agnostic,
+ships ESM and CJS with its own types, and runs wherever a `fetch` and a
+`WebSocket` exist — a browser, a mobile webview, Node 20 or newer, and
+server-side with a server key instead of a user session.
+
+## Why
+
+- **One connection, however many subscriptions.** Every datapoint and job
+  subscription shares a single authenticated WebSocket. It reconnects with
+  exponential backoff, re-authenticates, and resends its own subscribe frames,
+  so a dropped network shows up as a gap in events rather than as work for you.
+- **Subscriptions are reference-counted per robot and slug.** Two widgets on
+  the same battery value, or one component mounted twice under React
+  StrictMode, share one wire subscription. Unsubscribing one never cuts off the
+  other.
+- **Errors you branch on, not errors you parse.** Every refusal arrives as a
+  `FleetlessError` carrying a stable `code` — `busy`, `forbidden`,
+  `robot_offline`, `rate_limited` — plus the SDK's own codes for refusals that
+  never reached the network. `rate_limited` is surfaced with its
+  `retry_after_ms` and never retried behind your back.
+- **Publishers with a failsafe the robot enforces.** `publishers.publish` sends
+  one message and nothing else. If your app stops publishing — including
+  because it crashed — the bridge on the robot publishes the configured
+  failsafe message itself. The safety primitive lives on the robot, not in your
+  event loop.
+- **Cameras that cost nothing while nobody watches.** Snapshot bytes come with
+  the cloud's own `age_ms`, and keep being served while the robot is offline.
+  `cameras.live` takes a refcounted hold: the first viewer starts the robot
+  publishing, the last one leaving stops it. You get a LiveKit room URL and
+  token to hand to the LiveKit client of your choice.
+- **Hosted login, so your app never handles a password.** OAuth 2.1
+  Authorization Code with PKCE (S256 only). `beginHostedLogin` makes no network
+  call at all, and `completeHostedLogin` checks `state` before it exchanges
+  anything. Federation to a customer's identity provider happens on the hosted
+  page, not in your code.
+- **A token store you control.** Implement two methods to keep a session in
+  `localStorage`, a cookie or a native keystore; the default keeps it in
+  memory. Refresh is silent and single-flight, so ten concurrent calls that
+  meet an expired access token share one refresh instead of firing ten.
+
+## Getting started
 
 ```sh
 npm i @fleetless/sdk
 ```
 
-## Quick start
+You need an app identifier and an end user's credentials from the
+[Fleetless Console](https://console.fleetless.dev), or your own dev stack.
 
-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
+```ts checked
 import { createClient } from '@fleetless/sdk'
 
 const client = createClient({
   apiUrl: 'https://api.fleetless.dev',
-  appIdentifier: 'fleet-ops', // the app's identifier, shown in the console
+  appIdentifier: 'warehouse_dash', // your app's identifier, shown in the console
 })
 
 await client.auth.login('user@example.com', 'correct-horse-battery')
 
+// Robot ids are UUIDs; the console shows the one you want.
+const robotId = '4f2c1a90-7b3e-4d51-9c86-0a1b2c3d4e5f'
+
 // One-shot read.
-const battery = await client.datapoints.get('robot-id', 'battery-percentage')
+const battery = await client.datapoints.get(robotId, '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', {
+const subscription = client.datapoints.subscribe(robotId, 'battery_percentage', {
   onEvent(event) {
     console.log(event.value, event.timestamp_ms)
   },
@@ -74,336 +89,67 @@ const subscription = client.datapoints.subscribe('robot-id', 'battery-percentage
 // Later:
 subscription.unsubscribe()
 await client.auth.logout()
+// logout() already closes the realtime channel. Call close() yourself when a
+// process should exit without logging out — an open WebSocket keeps Node alive.
+client.close()
 ```
 
-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)).
+Against a local dev stack, point `apiUrl` at `http://localhost:8080`; the
+realtime URL (`ws://localhost:8080/realtime`) is derived from it.
 
-## Auth
+Slugs are the names you chose in the console, in `snake_case`
+(`[a-z][a-z0-9]*(_[a-z0-9]+)*`) — never the robot's internal ROS names, which
+is what makes renaming a node on the robot invisible to your app.
 
-Fleetless has two kinds of caller (spec §3.4), and the SDK supports both:
+### Hosted login
 
-### End users — `tokenStore`
+Redirect the end user to the Fleetless-hosted login page instead of collecting
+a password yourself. Register the OAuth client in the console first, under
+**App Settings → OAuth clients**; its `client_id` is not your `appIdentifier`.
 
 ```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.
+// 1. Build the URL. No network call happens here.
 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.
+// A redirect is a fresh page load, so persist these two yourself.
 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.
+// 2. On the callback page. The callback can legitimately carry ?error=...
+//    instead of a code, so check for that first.
 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)
-  }
+if (!params.has('error') && expectedState && codeVerifier) {
+  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 me(), logout() and silent refresh behave exactly as they do
+  // after login(). Never call completeHostedLogin twice for the same code.
 }
 ```
 
-- **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.
+### Running a job
 
-- **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)
+An action is a job with a lifecycle. `invoke` resolves as soon as the job
+exists; feedback, progress and the result arrive over `subscribe`.
 
 ```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.
+const job = await client.actions.invoke(robotId, 'dock', { 'target_pose.position.x': 1.0 })
 
-### 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
+    console.log(event.job.state, event.feedback, event.progress)
     if (event.job.state === 'succeeded') console.log(event.job.result)
   },
   onError(error) {
@@ -411,807 +157,80 @@ const sub = client.actions.subscribe(robotId, 'dock', {
   },
 })
 
-// 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:
+// Cancel the job you started, specifically — not whatever runs there by now.
 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.
+`params` is flat, keyed by the parameter names the developer declared. A second
+`invoke` while one is still running is refused `busy`, with the running job on
+`error.details.running`. A service is the same machinery with a plain result:
+`await client.services.call(robotId, 'set_mode', { mode: 'autonomous' })`.
 
-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
+### Cameras
 
 ```ts
-const jobs = await client.jobs.list(robotId) // -> Job[]
-```
+import { Room } from 'livekit-client' // your choice of LiveKit client
 
-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
+// The snapshot is always there, independent of anyone watching live.
+const snap = await client.cameras.snapshot(robotId, 'camera_front')
+if (snap.image !== null) console.log(snap.mime, `${snap.age_ms}ms old`)
 
+// Live is on demand, and it costs you a release.
 const room = new Room()
-const session = await client.cameras.live(robotId, 'front')
+const session = await client.cameras.live(robotId, 'camera_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**:
+// When you are done watching — both calls, together. Disconnecting the Room is
+// what actually stops the stream; release() is the courteous fast path.
 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.
+## Migrating from 1.0.0
+
+2.0.0 is a breaking release. `CHANGELOG.md` carries the complete inventory —
+established by diffing the published 1.0.0 tarball's types against this one's,
+not read off the commit log. The breaks, one line each:
+
+- `auth.register()` and `auth.confirmRegistration()` are gone with no
+  successor; a group grows by invitation (see [Account recovery](https://docs.fleetless.dev/reference/sdk/#account-recovery) in the SDK reference).
+- `auth.requestPasswordReset()` and `auth.confirmPasswordReset()` are gone.
+  Link the user to `auth.passwordResetUrl()` instead.
+- The types `MailStatus` and `ClientRegisterResponse` went with them.
+- The error code `not_a_member` is gone — a compile break for an exhaustive
+  `switch` on `error.code`.
+- `CameraDescriptor.snapshot_interval_ms` is now `snapshot_interval_seconds`.
+  **Read that twice:** it is a rename *and* a unit change, so renaming the
+  property and nothing else leaves you with a number a thousand times too
+  small.
+- `UrdfCompleteness.missing` and `UrdfSceneResources.missing` are no longer
+  `string[]` but `{ uri, element }[]`, so a missing texture is no longer
+  reported as a missing mesh. For the old shape: `missing.map((m) => m.uri)`.
+
+Nothing else was removed or re-typed. `auth.logout()`'s result grew a field and
+gained a name (`LogoutResult`); `.revoked` is unchanged.
+
+## Documentation and help
+
+- **[SDK reference](https://docs.fleetless.dev/reference/sdk/)** — every method,
+  every option, and what each one deliberately does not do.
+- **[Getting started](https://docs.fleetless.dev/getting-started/)** — from a
+  robot that has never connected to a value in your app.
+- **[REST and realtime API](https://docs.fleetless.dev/reference/api/)** — the
+  wire surface underneath this package.
+- **[Hosted login recipe](https://docs.fleetless.dev/recipes/hosted-login/)** —
+  the full walkthrough, including every error the callback can carry.
+- **[CHANGELOG.md](CHANGELOG.md)** — what changed in each version.
+- Questions, bug reports and feature requests: hello@fleetless.dev.
+
+Fleetless is in closed beta. The waiting list is at
+<https://fleetless.dev/#waiting-list>.
+
+## Maintainers
+
+Maintained by [Dehne Robotik GmbH](https://dehne-robotik.de). The source
+repository is private and takes no outside contributions; questions and bug
+reports go to hello@fleetless.dev.
+
+MIT licensed — see [LICENSE](LICENSE).