@fleetless/sdk 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,1681 @@
+import { z } from 'zod';
+
+/**
+ * Jobs (spec §6.1, §11.3): one running unit of work on a robot — an action
+ * goal or a service call — with an id both sides know, so bridge and cloud
+ * stay in sync across a disconnect.
+ *
+ * Two rules shape everything here:
+ *
+ * 1. **State is observed by slug, not by id.** The id is informative (§11.3);
+ *    a client watches `robot × slug` and sees whatever job is running there,
+ *    which is also why every observer of a slug sees the same job.
+ * 2. **`lost` is a real outcome and must be said out loud** (§6.1). Job state
+ *    lives only in the bridge's memory; if it restarts mid-job, the results
+ *    are gone. The cloud then marks the job `lost` — never leaves it reading
+ *    "running" because nobody contradicted it. A system that reports a
+ *    machine is still working when it does not know is worse than one that
+ *    admits it lost track.
+ */
+declare const jobState: z.ZodEnum<{
+    running: "running";
+    succeeded: "succeeded";
+    failed: "failed";
+    cancelled: "cancelled";
+    lost: "lost";
+}>;
+type JobState = z.infer<typeof jobState>;
+declare const job: z.ZodObject<{
+    id: z.ZodUUID;
+    robot_id: z.ZodUUID;
+    slug: z.ZodString;
+    state: z.ZodEnum<{
+        running: "running";
+        succeeded: "succeeded";
+        failed: "failed";
+        cancelled: "cancelled";
+        lost: "lost";
+    }>;
+    started_at: z.ZodISODateTime;
+    updated_at: z.ZodISODateTime;
+    seq: z.ZodNumber;
+    result: z.ZodNullable<z.ZodUnknown>;
+    error: z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type Job = z.infer<typeof job>;
+/**
+ * One update about a job, pushed to subscribers of its slug.
+ *
+ * `timestamp_ms` is the bridge's capture time, exactly as for a datapoint
+ * (§6.3 says action feedback carries it too) — so a client computes the age
+ * of a progress report the same way it computes the age of a sensor value,
+ * and a burst of late-delivered feedback after a reconnect is visibly late
+ * rather than looking current.
+ */
+declare const jobEvent: z.ZodObject<{
+    type: z.ZodLiteral<"job">;
+    robot_id: z.ZodUUID;
+    slug: z.ZodString;
+    job: z.ZodObject<{
+        id: z.ZodUUID;
+        robot_id: z.ZodUUID;
+        slug: z.ZodString;
+        state: z.ZodEnum<{
+            running: "running";
+            succeeded: "succeeded";
+            failed: "failed";
+            cancelled: "cancelled";
+            lost: "lost";
+        }>;
+        started_at: z.ZodISODateTime;
+        updated_at: z.ZodISODateTime;
+        seq: z.ZodNumber;
+        result: z.ZodNullable<z.ZodUnknown>;
+        error: z.ZodNullable<z.ZodObject<{
+            code: z.ZodString;
+            message: z.ZodString;
+            details: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    feedback: z.ZodNullable<z.ZodUnknown>;
+    progress: z.ZodNullable<z.ZodNumber>;
+    timestamp_ms: z.ZodNumber;
+}, z.core.$strip>;
+type JobEvent = z.infer<typeof jobEvent>;
+/**
+ * What a busy refusal tells the caller (spec §11.3: "inkl. Information, was
+ * läuft"). A refusal that only says "busy" forces the caller to guess whether
+ * to wait or to give up.
+ */
+declare const busyDetails: z.ZodObject<{
+    running: z.ZodObject<{
+        id: z.ZodUUID;
+        robot_id: z.ZodUUID;
+        slug: z.ZodString;
+        state: z.ZodEnum<{
+            running: "running";
+            succeeded: "succeeded";
+            failed: "failed";
+            cancelled: "cancelled";
+            lost: "lost";
+        }>;
+        started_at: z.ZodISODateTime;
+        updated_at: z.ZodISODateTime;
+        seq: z.ZodNumber;
+        result: z.ZodNullable<z.ZodUnknown>;
+        error: z.ZodNullable<z.ZodObject<{
+            code: z.ZodString;
+            message: z.ZodString;
+            details: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type BusyDetails = z.infer<typeof busyDetails>;
+
+/**
+ * The REST read of one datapoint. For bridge-captured data `timestamp_ms`
+ * is the capture time at the bridge (spec §6.3); for the cloud-observed
+ * built-in `bridge-state` it is the time the cloud observed the state.
+ */
+declare const datapointValue: z.ZodObject<{
+    slug: z.ZodString;
+    value: z.ZodUnknown;
+    timestamp_ms: z.ZodNumber;
+}, z.core.$strip>;
+type DatapointValue = z.infer<typeof datapointValue>;
+/**
+ * Every job the platform currently believes this robot has — `GET
+ * /api/robots/:id/jobs` (W6b).
+ *
+ * `jobResponse` answers "what is on this slug", which requires knowing the
+ * slug first. That was enough while a job could only exist on a slug the
+ * published configuration named. W6b breaks that assumption twice: a
+ * reconnecting bridge can name a job the cloud has **no row for** and the
+ * cloud adopts it, and a configuration change can leave a job on a slug the
+ * document no longer contains. Both are jobs nobody can ask about, because
+ * asking requires already knowing what to ask for.
+ *
+ * So this route exists to answer the question the per-slug route cannot: not
+ * "is something running here", but "what is this robot doing". A restarted
+ * cloud that has just reconciled a robot's `hello.active_jobs` has exactly
+ * this list and, until now, no way to say it out loud.
+ *
+ * The array is ordered newest first and is **never null**: a robot doing
+ * nothing answers `{ jobs: [] }`. "Nothing is running" and "we did not look"
+ * are different facts, and a nullable list would merge them — the same
+ * distinction `robotDeletionSummary` was made all-required for.
+ *
+ * **At most one entry per slug: the current job there, exactly what
+ * `jobResponse` would answer for that slug.** This is not a history endpoint
+ * and must not become one. The first implementation returned every job the
+ * registry still held — six rows and four complete Fibonacci results after a
+ * few minutes of gate traffic, and unbounded in both count and payload for a
+ * robot that has been working all day. The list would have grown until a
+ * console page carried a robot's entire past, and the one thing it exists to
+ * answer — *what is this robot doing* — would have been the first line of a
+ * scroll.
+ *
+ * A settled job stays visible as its slug's current entry until something
+ * else runs there, which is what makes a job that just failed still findable.
+ * Read `state` to tell a live one from a finished one, exactly as with
+ * `jobResponse`.
+ */
+/**
+ * What a `rate_limited` refusal tells the caller (W6c).
+ *
+ * One number, and it is the only one that matters: **when to come back.** A
+ * limit that says "too many" without saying "in 800 ms" produces a client that
+ * retries immediately, which is the behaviour the limit exists to stop — so
+ * omitting it would make the refusal part of the attack.
+ *
+ * Deliberately **not** carrying the limit, the window, or how many attempts
+ * remain: those describe the defence to whoever is probing it, and none of
+ * them changes what an honest caller does.
+ */
+declare const rateLimitDetails: z.ZodObject<{
+    retry_after_ms: z.ZodNumber;
+}, z.core.$strip>;
+type RateLimitDetails = z.infer<typeof rateLimitDetails>;
+declare const cameraDescriptor: z.ZodObject<{
+    slug: z.ZodString;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    fps: z.ZodNumber;
+    snapshot_interval_ms: z.ZodNumber;
+}, z.core.$strip>;
+type CameraDescriptor = z.infer<typeof cameraDescriptor>;
+/**
+ * Raw samples. `timestamp_ms` is the **bridge's capture time** (§6.3) — the
+ * same instant the live value carried, so a recorded point and a live one can
+ * be placed on one axis without apology.
+ *
+ * `truncated` says the response was cut short. A short array that does not
+ * admit it is indistinguishable from a quiet period, and the two lead a
+ * developer to opposite conclusions.
+ */
+declare const historySamplesResponse: z.ZodObject<{
+    slug: z.ZodString;
+    kind: z.ZodLiteral<"samples">;
+    samples: z.ZodArray<z.ZodObject<{
+        timestamp_ms: z.ZodNumber;
+        value: z.ZodUnknown;
+    }, z.core.$strip>>;
+    truncated: z.ZodBoolean;
+    truncated_by: z.ZodNullable<z.ZodEnum<{
+        limit: "limit";
+        bytes: "bytes";
+    }>>;
+}, z.core.$strip>;
+type HistorySamplesResponse = z.infer<typeof historySamplesResponse>;
+/**
+ * Aggregated buckets — a **separate shape**, not the samples shape with nulls
+ * in it, so a client knows by type what it received rather than by
+ * inspection.
+ *
+ * `sample_count` exists because an empty bucket and a bucket whose average is
+ * zero are different facts. W5 established at some cost what happens when two
+ * facts share one representation, and a chart is the easiest place in this
+ * product to draw a gap as a line.
+ */
+declare const historyBucketsResponse: z.ZodObject<{
+    slug: z.ZodString;
+    kind: z.ZodLiteral<"buckets">;
+    window_ms: z.ZodNumber;
+    agg: z.ZodEnum<{
+        min: "min";
+        max: "max";
+        avg: "avg";
+    }>;
+    buckets: z.ZodArray<z.ZodObject<{
+        bucket_start_ms: z.ZodNumber;
+        value: z.ZodNullable<z.ZodNumber>;
+        sample_count: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type HistoryBucketsResponse = z.infer<typeof historyBucketsResponse>;
+
+/**
+ * One datapoint sample pushed to a subscriber. The current value arrives
+ * immediately on subscribe, then every change. `timestamp_ms` semantics as
+ * in `datapointValue` (capture time; cloud-observed for `bridge-state`).
+ */
+declare const datapointEvent: z.ZodObject<{
+    type: z.ZodLiteral<"datapoint">;
+    robot_id: z.ZodUUID;
+    slug: z.ZodString;
+    value: z.ZodUnknown;
+    timestamp_ms: z.ZodNumber;
+}, z.core.$strip>;
+type DatapointEvent = z.infer<typeof datapointEvent>;
+
+/**
+ * Access plus refresh (spec §3.4). The access token is short-lived; the
+ * refresh token rotates on every use, so a stolen one is detectable when the
+ * original is presented again.
+ */
+declare const sessionTokens: z.ZodObject<{
+    access_token: z.ZodString;
+    refresh_token: z.ZodString;
+    expires_in: z.ZodNumber;
+}, z.core.$strip>;
+type SessionTokens = z.infer<typeof sessionTokens>;
+/**
+ * An invitation carries its own accept URL: the link is the primary path
+ * (the developer shares it), mail is the second. A cloud with no SMTP
+ * configured still issues invitations — it just cannot send them, and says so
+ * via `mail_sent`.
+ */
+/**
+ * What happened to the mail, in three words instead of one (W6c).
+ *
+ * `mail_sent: boolean` could not tell **"we have no SMTP configured"** from
+ * **"we tried and the server refused"**, so the console had to pick a sentence
+ * for a cause it could not know — and picked the reassuring one, because a
+ * link-only invitation is a normal outcome and a bounced one is not. The two
+ * need opposite actions from whoever reads them: configure a mail server, or
+ * go and look at why the existing one rejected the message.
+ *
+ * - `sent`           — the SMTP server accepted the message. Not "delivered":
+ *                      no sender can promise that, and this value must never
+ *                      be rendered as if it could.
+ * - `not_configured` — no SMTP is set up. **An expected state, not a failure**
+ *                      (spec §3.2: invitations work without mail; the link is
+ *                      the primary path). The console must not show it as an
+ *                      error.
+ * - `failed`         — SMTP was configured, was tried, and refused or was
+ *                      unreachable. This one is worth someone's attention.
+ */
+declare const mailStatus: z.ZodEnum<{
+    failed: "failed";
+    sent: "sent";
+    not_configured: "not_configured";
+}>;
+type MailStatus = z.infer<typeof mailStatus>;
+/**
+ * What registering answers — deliberately **the same for an address that is
+ * new and one that already has an account**.
+ *
+ * Anything else is an account-enumeration oracle on an unauthenticated route,
+ * the same reasoning `passwordResetRequest` carries. An address that already
+ * exists still gets a mail, saying so; the caller cannot tell which mail was
+ * sent, and there is nothing in this response to tell them.
+ *
+ * `mail` is safe to return because it describes **the server's configuration**,
+ * not the address: `not_configured` means this deployment has no SMTP, which
+ * is true regardless of who registered. Note that a deployment with no mail
+ * server cannot complete a self-registration at all — the link is the only way
+ * through, unlike an invitation, where a developer can hand it over directly.
+ */
+declare const clientRegisterResponse: z.ZodObject<{
+    mail: z.ZodEnum<{
+        failed: "failed";
+        sent: "sent";
+        not_configured: "not_configured";
+    }>;
+}, z.core.$strip>;
+type ClientRegisterResponse = z.infer<typeof clientRegisterResponse>;
+
+/**
+ * Who the caller turned out to be. Returned by the "who am I" endpoint and by
+ * the realtime `auth_ok` frame, so a client can render a session without
+ * decoding a token itself — decoding a JWT in the client is how apps end up
+ * trusting claims nobody verified.
+ *
+ * **Three kinds of caller reach the client API, not two.** Besides end users
+ * and server keys, a **developer** does: spec §15.2 says the console's
+ * playground runs over the real client API and appears in the audit as the
+ * developer, and the console's own live views (robot list badges, the Live
+ * tab) subscribe on `/realtime` as one. A developer is **org-scoped, not
+ * app-scoped** — they own the configuration of every robot in their org — so
+ * `app_id` and `role_id` are null for them, and roles do not filter what they
+ * see. `kind` states this explicitly rather than leaving it to be inferred
+ * from which id happens to be set.
+ */
+declare const clientIdentity: z.ZodObject<{
+    kind: z.ZodEnum<{
+        server_key: "server_key";
+        developer: "developer";
+        end_user: "end_user";
+    }>;
+    developer_id: z.ZodNullable<z.ZodUUID>;
+    end_user_id: z.ZodNullable<z.ZodUUID>;
+    server_key_id: z.ZodNullable<z.ZodUUID>;
+    app_id: z.ZodNullable<z.ZodUUID>;
+    role_id: z.ZodNullable<z.ZodUUID>;
+    email: z.ZodNullable<z.ZodEmail>;
+}, z.core.$strip>;
+type ClientIdentity = z.infer<typeof clientIdentity>;
+
+declare const asset: z.ZodObject<{
+    id: z.ZodUUID;
+    robot_id: z.ZodUUID;
+    kind: z.ZodEnum<{
+        urdf: "urdf";
+        mesh: "mesh";
+        texture: "texture";
+        other: "other";
+    }>;
+    name: z.ZodString;
+    media_type: z.ZodString;
+    size_bytes: z.ZodNumber;
+    sha256: z.ZodString;
+    created_at: z.ZodISODateTime;
+}, z.core.$strip>;
+type Asset = z.infer<typeof asset>;
+/**
+ * Whether a URDF can actually be rendered, which is not the same as whether it
+ * was uploaded.
+ *
+ * `missing` carries **the reference, verbatim, that no asset answers** — for
+ * a `package://` mesh the URI the bridge could not resolve in the workspace,
+ * and since W7's security fix also the absolute paths and bare relative paths
+ * a URDF may carry, which the extractor sees and the sync deliberately never
+ * offers. The sentence used to say "the `package://` URIs" and the field
+ * carried three kinds of string (Momus-W7); it is widened here rather than
+ * narrowed, because a developer whose URDF names `/opt/meshes/arm.stl` is
+ * entitled to be told that nothing will ever fetch it.
+ *
+ * The spec's example is "2 Meshes fehlen" and that number alone is a dead
+ * end: it tells a developer to go looking through a workspace by hand. The
+ * references are what they can act on, so the references travel.
+ *
+ * **Every entry must be actionable, and that is a constraint on the
+ * producers, not on this field (W7a).** An entry a developer cannot make
+ * disappear by fixing what it names is a defect in whoever put it there: for
+ * a whole wave `<texture>` references were listed here and no sync would ever
+ * offer them, so the honest instruction behind the list was "fix this, it
+ * will not help".
+ */
+declare const urdfCompleteness: z.ZodObject<{
+    present: z.ZodBoolean;
+    mesh_count: z.ZodNumber;
+    missing: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type UrdfCompleteness = z.infer<typeof urdfCompleteness>;
+declare const assetListResponse: z.ZodObject<{
+    assets: z.ZodArray<z.ZodObject<{
+        id: z.ZodUUID;
+        robot_id: z.ZodUUID;
+        kind: z.ZodEnum<{
+            urdf: "urdf";
+            mesh: "mesh";
+            texture: "texture";
+            other: "other";
+        }>;
+        name: z.ZodString;
+        media_type: z.ZodString;
+        size_bytes: z.ZodNumber;
+        sha256: z.ZodString;
+        created_at: z.ZodISODateTime;
+    }, z.core.$strip>>;
+    urdf: z.ZodObject<{
+        present: z.ZodBoolean;
+        mesh_count: z.ZodNumber;
+        missing: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    urdf_available: z.ZodNullable<z.ZodBoolean>;
+}, z.core.$strip>;
+type AssetListResponse = z.infer<typeof assetListResponse>;
+
+/**
+ * One violated §4.4 rule. `details` on the envelope stays `unknown` — codes
+ * are an open set, so their payloads cannot all be enumerated — but the
+ * payload of `parameter_invalid` **is** pinned here, because otherwise every
+ * consumer guesses: the cloud emits one shape, the SDK sniffs for two, the
+ * console renders a third, and each is right in its own tests.
+ *
+ * `field` is the **flat key exactly as the caller sent it** — the same string
+ * as the `parameterSpec.name` it violated. That is the entire justification
+ * for the flat parameter form: a refusal has to name something the caller can
+ * find in what they typed, and a console can attach the error to that one
+ * input rather than to the form.
+ */
+declare const parameterViolation: z.ZodObject<{
+    field: z.ZodString;
+    rule: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+type ParameterViolation = z.infer<typeof parameterViolation>;
+/**
+ * The `details` of a `parameter_invalid` refusal. Always at least one
+ * violation: a refusal that names none would leave the caller with nothing to
+ * fix. All violations are reported at once, not just the first — a caller
+ * fixing parameters one round-trip at a time is a caller who gives up.
+ */
+declare const parameterInvalidDetails: z.ZodObject<{
+    violations: z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        rule: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type ParameterInvalidDetails = z.infer<typeof parameterInvalidDetails>;
+/**
+ * The codes in use as of W2. The wire deliberately allows any string — this
+ * list is the shared vocabulary, not a closed set, so a new refusal never
+ * needs a contracts release before it can be reported honestly.
+ */
+declare const ERROR_CODES: readonly ["not_found", "validation_error", "bad_request", "unknown_datapoint", "invalid_token", "protocol_mismatch", "invalid_frame", "duplicate_slug", "reserved_slug", "unknown_field_path", "unknown_type", "unknown_topic", "invalid_rate", "invalid_range", "config_conflict", "no_data", "robot_offline", "bridge_timeout", "unauthorized", "forbidden", "invalid_credentials", "token_expired", "token_revoked", "invite_expired", "invite_used", "email_taken", "identifier_taken", "weak_password", "not_a_member", "account_blocked", "busy", "parameter_invalid", "job_lost", "publisher_busy", "unknown_command", "not_subscribable", "camera_offline", "no_snapshot_yet", "live_unavailable", "wrong_kind", "not_recorded", "not_aggregatable", "quota_exceeded", "credential_in_use", "goal_timeout", "robot_in_use", "robot_deletion_partial", "job_queue_full", "invalid_uuid", "rate_limited", "tier_required", "token_spent", "service_timeout", "asset_missing", "asset_too_large", "dynamic_registration_disabled", "client_limit_reached", "identity_conflict", "identity_not_provisioned", "idp_unavailable", "mcp_disabled", "tool_not_available"];
+type ErrorCode = (typeof ERROR_CODES)[number];
+
+/**
+ * Codes the SDK produces itself rather than relaying from the server. Kept
+ * out of `@fleetless/contracts`' `ERROR_CODES` deliberately — that list is
+ * the *wire* vocabulary, every entry something a server may actually send,
+ * and none of these are. Two kinds:
+ *
+ * - `no_session` / `no_websocket`: a client-side refusal *before* a request
+ *   ever reaches the network (not logged in; no WebSocket implementation
+ *   available). Named apart from the server's own `unauthorized` so a
+ *   caller can tell "the server refused me" from "the SDK refused before
+ *   asking" by the code alone.
+ * - `unparseable_error`: the opposite direction — a real response *did*
+ *   arrive, its body just wasn't shaped like §11.5's error format. Not a
+ *   refusal at all, just "we don't know what the server said."
+ * - `command_timeout` (W4): a realtime command (`invoke`/`cancel`/`publish`)
+ *   got no `command_result` within its timeout. The server may still answer
+ *   later on the same socket — nobody knows — but the caller cannot be made
+ *   to wait forever for that.
+ * - `command_outcome_unknown` (W4): worse than a timeout, and told apart
+ *   from it on purpose — the realtime connection that carried the command
+ *   was replaced by a new one (a reconnect) before any reply arrived. A
+ *   reply can now never come: the server, if it answered at all, answered a
+ *   socket that no longer exists. The command may or may not have run.
+ *   Never retried automatically — that could run an action twice — the
+ *   caller recovers by reading the job (e.g. `actions.subscribe`), since
+ *   state is observed by slug regardless of which connection asked for it.
+ * - `unexpected_response` (W4): the server answered `ok:true` but left out
+ *   something the command is defined to always return (e.g. no `job` on a
+ *   successful `invoke`) — a contract violation the SDK noticed, not a
+ *   refusal.
+ * - `invalid_option` (W6b): the caller passed an *SDK-level* argument or
+ *   option that cannot mean what it looks like it means. Two cases so far:
+ *   `timeoutMs < patienceMs` on `invoke`/`call` (see `resolveLocalWaitMs` in
+ *   `commands.ts`) — the SDK would give up locally before the platform's own
+ *   patience runs out, and report `command_timeout` for a call the platform
+ *   never actually refused; and a non-string, non-null, non-omitted `jobId`
+ *   on `cancel` (D6, see `assertValidJobId`) — almost always a caller who
+ *   upgraded past the pre-W6b `cancel(robotId, slug, options?)` signature
+ *   and is still passing an options object third. Both are thrown
+ *   synchronously, before any request is sent — a client-side mistake to
+ *   fix, not something a server response could ever produce, which is why
+ *   this code belongs here and not in `@fleetless/contracts`' `ERROR_CODES`.
+ * - `untrusted_absolute_url` (W7): `HttpClient` refused to fetch an absolute
+ *   URL whose origin does not match this client's own configured `baseUrl`
+ *   — thrown before the request is ever sent, so no `Authorization` header
+ *   is ever built for it, let alone attached. The one caller that hands
+ *   `HttpClient` an absolute URL at all is `assets.createMeshLoader`
+ *   (§4.6), fetching a URDF's rewritten mesh URIs — and a URDF is ROS graph
+ *   input, not first-party data, so an app rendering one must not silently
+ *   trust wherever it points. `assets.createMeshLoader`'s `onComplete`
+ *   surfaces this the same way it surfaces a network failure: `(null, err)`.
+ * - `no_urdf_synced` (W7a): `assets.prepareUrdfScene` looked for a
+ *   `kind: 'urdf'` row in `assets.list()` and found none. Thrown before any
+ *   asset fetch, rather than left to surface as a confusing downstream
+ *   failure from `URDFLoader.parse(undefined)` or similar — the caller's
+ *   fix is "sync a URDF first" (console, Owner-tier, §4.6), which this
+ *   error can say directly.
+ * - `no_hosted_login_attempt` (W7b, Momus's review): `auth.completeHostedLogin()`
+ *   was called with an empty `expectedState` — nothing was persisted for
+ *   this attempt. A callback landing in a different tab or window than the
+ *   one that called `beginHostedLogin`, a restored session, or storage
+ *   cleared in between all produce exactly this, and none of them is an
+ *   attack. Told apart from `state_mismatch` on purpose: the two diagnoses
+ *   have different remedies ("check how you persisted the value" versus
+ *   "this response belongs to a login you did not start"), the same
+ *   reasoning this wave already applied once to `identity_conflict` versus
+ *   `identity_not_provisioned`. Also closes a real gap — comparing two
+ *   *empty* strings with `!==` is `false`, so without this check first, a
+ *   caller with nothing persisted at all could reach `state_mismatch`'s
+ *   comparison having contributed no defence whatsoever.
+ * - `aborted` (register row 244, W7c): `assets.prepareUrdfScene()` was given
+ *   an `AbortSignal` and it fired — either already-aborted before the call
+ *   started, or mid-flight while a fetch was in progress. Normalized to this
+ *   one code regardless of which stage the abort landed in, rather than
+ *   surfacing whatever shape the underlying `fetch()` rejects an aborted
+ *   request with (a `DOMException` named `AbortError` in a browser, an
+ *   `Error` named `AbortError` under Node's `fetch` — two different shapes a
+ *   caller would otherwise have to detect themselves to tell "I cancelled
+ *   this" from "the network actually failed"). Every partial resource this
+ *   call had already created (`blob:` URLs) is revoked before this throws —
+ *   an aborted load must not leak what it fetched before the signal fired,
+ *   the same guarantee a failed load already had (D6).
+ * - `state_mismatch` (W7b): `auth.completeHostedLogin()` was called with a
+ *   `state` that does not match the `expectedState` its own `beginHostedLogin()`
+ *   returned for this attempt (or with no `state` at all — `beginHostedLogin`
+ *   always sets one, so a callback carrying none does not look like a reply
+ *   to a flow this client started). Thrown before `/oauth/token` is ever
+ *   called — RFC 6749 §10.12's whole point is that a caller must not
+ *   complete an authorization response it did not itself request, so this
+ *   check happens client-side, first, rather than being left to the server
+ *   to catch (by which point a code exchange would already have been
+ *   attempted for a flow this client never started).
+ */
+declare const SDK_ERROR_CODES: readonly ["no_session", "no_websocket", "unparseable_error", "command_timeout", "command_outcome_unknown", "unexpected_response", "invalid_option", "untrusted_absolute_url", "state_mismatch", "no_hosted_login_attempt", "no_urdf_synced", "aborted"];
+type SdkErrorCode = (typeof SDK_ERROR_CODES)[number];
+/**
+ * A stable code a caller can branch on: a server-defined code (open-ended —
+ * see `ErrorCode`'s own doc comment), one of the SDK's own client-side
+ * codes above, or, since neither list is exhaustive, any other string.
+ * `(string & {})` is the standard trick to keep autocomplete on the known
+ * values while still accepting an arbitrary one.
+ */
+type FleetlessErrorCode = ErrorCode | SdkErrorCode | (string & {});
+/**
+ * The one error type the SDK throws for a refused API call (spec §11.5): a
+ * stable machine-readable `code` a caller can branch on (`forbidden` vs
+ * `token_expired`) plus a human `message` for logs and debugging. Never
+ * parse `message` — it is not part of the contract, only `code` is.
+ */
+interface FleetlessErrorOptions {
+    /** Field-level detail for validation errors, passed through verbatim. */
+    details?: unknown;
+    /** The HTTP status of the response that produced this error, if any. */
+    status?: number;
+}
+declare class FleetlessError extends Error {
+    readonly code: FleetlessErrorCode;
+    readonly details?: unknown;
+    readonly status?: number;
+    constructor(code: FleetlessErrorCode, message: string, options?: FleetlessErrorOptions);
+}
+
+interface SendCommandOptions {
+    /** How long to wait for a `command_result` before rejecting `command_timeout`. Default 10s. */
+    timeoutMs?: number;
+}
+/**
+ * `invoke`-only: how long **the platform itself** should wait for this one
+ * call before giving up on the robot (W6b) — the whole wait for a service
+ * call, goal *acceptance* only for an action (once accepted, a job runs as
+ * long as it runs and is observed, not awaited).
+ *
+ * Optional; absent means the platform's own default (`DEFAULT_PATIENCE_MS`,
+ * 15s) — exactly today's behaviour for a caller who names no preference.
+ * Outside `[MIN_PATIENCE_MS, MAX_PATIENCE_MS]` the platform refuses with
+ * `validation_error` rather than clamping, and this SDK does not clamp
+ * locally or retry — surfacing the refusal is the whole of what it does
+ * with this field. The floor exists because impatience reaches the robot,
+ * not just the platform: a patience too short to survive a goal-acceptance
+ * round trip made the bridge report `goal_timeout` and then issue a
+ * *corrective cancel* against a goal an action server accepted a moment
+ * later — a caller who names an unreachable deadline was causing a real
+ * cancellation on the machine, repeatably, not just receiving an error.
+ *
+ * `timeoutMs` bounds how long *this SDK* waits locally for a reply on the
+ * wire it already sent on; `patienceMs` travels to the platform and bounds
+ * what *it* is willing to wait for from the robot. **They are not set
+ * independently of each other, and D3a exists because the first version of
+ * this doc comment said they were.** `timeoutMs` left unset is *derived*
+ * from `patienceMs` (see `resolveLocalWaitMs`), not defaulted to a fixed
+ * number that might be shorter — the SDK giving up locally before the
+ * platform's own deadline would report `command_timeout` for a call the
+ * platform never actually refused, which is exactly the two-clocks defect
+ * this wave exists to remove, just relocated into this SDK instead of
+ * between the cloud and the bridge. Setting both explicitly with
+ * `timeoutMs < patienceMs` is refused with `invalid_option` before any
+ * request is sent, for the same reason.
+ */
+interface InvokeOptions extends SendCommandOptions {
+    patienceMs?: number;
+}
+
+interface JobSubscriptionHandlers {
+    /** Called on every update pushed for the slug's current job — state, feedback, progress and result. */
+    onJob(event: JobEvent): void;
+    /** Called once if the subscription is refused (§11.5: e.g. `forbidden`, an unknown slug). */
+    onError?(error: FleetlessError): void;
+}
+interface JobSubscription {
+    /** Stops the subscription and, if the channel is currently connected, tells the server. */
+    unsubscribe(): void;
+}
+
+interface ActionsApi {
+    /**
+     * Invokes an action (spec §11.3). Resolves as soon as the job is created
+     * — the job id is informative, not the result. Feedback, progress and the
+     * eventual result arrive separately over `subscribe`. A second invoke of
+     * the same slug while one is already running is refused `busy`, with
+     * `error.details.running` naming the job that is running.
+     *
+     * `options.patienceMs` bounds goal *acceptance* only (W6b) — once a goal
+     * is accepted this call has already resolved; the job then runs as long
+     * as it runs, observed via `subscribe`, never awaited. `options.timeoutMs`
+     * (this SDK's own local wait for the acceptance reply) is derived from
+     * `patienceMs` when left unset, and the combination `timeoutMs <
+     * patienceMs` is refused with `invalid_option` rather than raced — see
+     * `resolveLocalWaitMs` in `commands.ts`, D3a.
+     */
+    invoke(robotId: string, slug: string, params: Record<string, unknown>, options?: InvokeOptions): Promise<Job>;
+    /**
+     * Cancels a job — a real ROS goal cancel on the robot, not a local forget.
+     * Resolves with the `Job` the cancel was actually sent to, or `null` if
+     * nothing matched.
+     *
+     * **Two different requests, both legitimate (W6b):**
+     * - `cancel(robotId, slug)` — no `jobId` — is the operator's stop button:
+     *   whatever is running on this slug, stop it. This is unchanged from
+     *   before W6b.
+     * - `cancel(robotId, slug, jobId)` cancels **that** job specifically. If
+     *   it is not the one running, the platform answers `not_found` — this
+     *   never silently falls back to stopping whatever *is* running, because
+     *   a caller who named an id has already ruled that out. The failure this
+     *   closes: a cancel arriving just after its own job ended used to stop
+     *   the *next* caller's job on the same slug.
+     *
+     * Read the returned job either way: "I stopped the one I meant", "there
+     * was nothing there", and "I stopped a job that started after I last
+     * looked" are three different outcomes a discarded result cannot tell
+     * apart.
+     */
+    cancel(robotId: string, slug: string, jobId?: string | null, options?: SendCommandOptions): Promise<Job | null>;
+    /**
+     * Subscribes to the slug's job: state, feedback, progress and result, as
+     * they happen. State is observed **by slug**, not by job id (§11.3) — this
+     * is what makes late delivery after a reconnect and a second observer
+     * watching the same job both work without special-casing either. Naming a
+     * job to `cancel` does not change this: a slug is still a *place a job may
+     * be running*, not the job itself, and it is still what `subscribe` watches.
+     */
+    subscribe(robotId: string, slug: string, handlers: JobSubscriptionHandlers): JobSubscription;
+}
+
+/** An asset's bytes plus its declared media type — the shape `assets.get` answers with. */
+interface AssetBytes {
+    body: Uint8Array;
+    mime: string | null;
+}
+/**
+ * The signature `urdf-loader`'s own `loadMeshCb` uses (verified against that
+ * library's docs, not guessed): `manager`/`material` pass straight through
+ * from whatever called this, and `onComplete` is how a mesh loader reports
+ * success or failure — it never throws.
+ *
+ * This SDK does not depend on `urdf-loader` or three.js — `manager`,
+ * `material` and the resolved object are all opaque here, exactly what makes
+ * `createMeshLoader` usable from any renderer that speaks this same shape,
+ * not only that one library.
+ */
+type MeshLoaderDelegate = (path: string, manager: unknown, material: unknown, onComplete: (obj: unknown | null, err?: Error) => void) => void;
+interface CreateMeshLoaderOptions {
+    /**
+     * How long to wait for `delegate`'s `onComplete` before giving up.
+     * Defaults to 30s. A URDF pulls in thirty-odd meshes and a dashboard
+     * using this callback can run for days — a delegate that never calls back
+     * (an exception three.js swallowed internally, a parser stuck on a
+     * malformed mesh) must not leak the object URL or hang the load forever.
+     */
+    timeoutMs?: number;
+}
+/**
+ * three.js's own `LoadingManager.setURLModifier(callback)` shape (W7a, D2).
+ * Every load the manager oversees is routed through `callback` first — not
+ * only the loader you handed the manager to, but every loader it constructs
+ * internally on the same manager (`ColladaLoader`'s own `TextureLoader` for
+ * a `.dae`'s `<init_from>` images, in particular). That is the one hook
+ * that exists "one level up, for everything" (D2) where `createMeshLoader`'s
+ * per-loader `loadMeshCb` override does not reach: `TextureLoader` has no
+ * override hook of its own.
+ *
+ * Structural, not `import('three')` — this SDK does not depend on three.js
+ * or `urdf-loader`, same discipline as `MeshLoaderDelegate` above.
+ */
+interface UrdfSceneManager {
+    setURLModifier(callback: (url: string) => string): unknown;
+}
+interface PrepareUrdfSceneOptions {
+    /**
+     * How many assets to fetch in parallel. Default 6 — a default that keeps
+     * memory and connection counts sane for the common case (dozens of
+     * meshes), not a number with a sweep behind it. Pass your own if you have
+     * a reason to.
+     *
+     * 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.
+     */
+    concurrency?: number;
+    /**
+     * Cancels this call (register row 244, W7c) — a caller who navigates away
+     * or switches to a different robot mid-load can abort every in-flight
+     * fetch this method has started, not merely stop it from starting new
+     * ones. Checked before the first request; if it fires while a request is
+     * already in progress, `HttpClient` forwards it straight to `fetch()`
+     * (`http.ts`'s own `RequestOptions.signal`), so the connection itself is
+     * torn down, not just abandoned by this SDK while it keeps running in the
+     * background.
+     *
+     * Every `blob:` URL already created before the abort is revoked before
+     * this call rejects with `FleetlessError('aborted', ...)` — the same
+     * guarantee a load that fails outright already had (D6): an aborted load
+     * must not leak what it had already fetched.
+     *
+     * `manager`'s URL modifier is only ever installed once every asset has
+     * resolved (success or the throw below) — an aborted call never installs
+     * a partial one, so `manager` is left exactly as it was if this rejects
+     * before that point.
+     */
+    signal?: AbortSignal;
+}
+interface UrdfSceneResources {
+    /**
+     * The robot's URDF as raw text — `package://` URIs intact, not rewritten
+     * to asset URLs. Hand it straight to `URDFLoader.parse(urdfText)` once
+     * `setURLModifier` is installed (this method already installed it on
+     * `manager` before returning).
+     */
+    urdfText: string;
+    /**
+     * The same reference strings `assets.list()`'s `urdf.missing` reports.
+     *
+     * **Top-level only — not a `.dae`'s internal references (Kassandra-W7a
+     * review correction).** The cloud builds this list from the URDF text
+     * alone (`<mesh>`/`<texture>` `filename` attributes), which is the only
+     * place it can see without parsing every `.dae` a sync touches; it never
+     * has and never can include an internal `<init_from>` reference. An
+     * earlier version of this comment claimed both — wrong, and worth naming
+     * as a correction rather than silently widening the sentence, since a
+     * caller who trusted "both" to mean both would build a completeness check
+     * against a list that structurally cannot report the second half. A
+     * `.dae`-internal reference the sync could not resolve surfaces through
+     * the sync's own failure reporting instead, not here.
+     *
+     * Not thrown either way: an incomplete URDF still renders what it has
+     * (`urdfCompleteness`'s own contract), so the caller decides whether to
+     * warn, block, or ignore before calling `URDFLoader.parse(urdfText)`. A
+     * reference NOT in this list that still fails to load at render time is a
+     * different failure — the store answered but the fetch itself did not.
+     */
+    missing: string[];
+    /**
+     * Revokes every `blob:` URL this call created. Call once the scene has
+     * finished loading (success or failure) or on unmount — safe to call more
+     * than once.
+     *
+     * **Does not touch `manager`'s URL modifier (D7, Kassandra-W7a review).**
+     * An earlier version reset it to the identity function here, which
+     * silently reopened D4 the moment the same manager was used again — for a
+     * second robot, or for anything else — before a later `prepareUrdfScene`
+     * call happened to overwrite it. The installed modifier is left running,
+     * and with this call's map now empty it already refuses anything it would
+     * have owned and passes through anything it would not have, correctly,
+     * on its own.
+     */
+    dispose(): void;
+}
+interface AssetsApi {
+    /**
+     * Every asset a robot has, plus whether its URDF is complete (spec §4.6).
+     * `urdf.missing` names the `package://` URIs the sync could not resolve —
+     * the number alone ("2 Meshes fehlen") sends a developer looking through a
+     * workspace by hand, the URIs are what they can act on.
+     */
+    list(robotId: string): Promise<AssetListResponse>;
+    /** One asset's bytes by id — a mesh, or any asset directly, addressed the same way `createMeshLoader` reaches one internally. */
+    get(robotId: string, assetId: string): Promise<AssetBytes>;
+    /**
+     * The robot's URDF, with every `package://` mesh URI already rewritten to
+     * an absolute Fleetless asset URL — ready to hand straight to
+     * `URDFLoader.parse(xml)`. Decoded as UTF-8 text rather than left as
+     * bytes because every consumer needs it as a string for exactly that call.
+     */
+    urdf(robotId: string): Promise<string>;
+    /**
+     * The mesh callback for `urdf-loader` (spec §4.6): 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 `@fleetless/contracts` `assets.ts`), so every app would
+     * otherwise write this glue itself, and each one differently.
+     *
+     * Returns a function with `loadMeshCb`'s own signature — assign it
+     * directly:
+     *
+     * ```ts
+     * loader.loadMeshCb = client.assets.createMeshLoader(robotId, loader.defaultMeshLoader.bind(loader))
+     * ```
+     *
+     * `delegate` does the actual format-specific parsing (STL/OBJ/DAE/GLTF —
+     * `loader.defaultMeshLoader` already knows how); this method's own job is
+     * only what a plain loader cannot do: fetch `path` with the
+     * `Authorization` header, and hand the delegate something it can load
+     * without one. It does that by fetching the bytes itself, wrapping them
+     * in a `Blob`, and calling `delegate` with an object URL substituted for
+     * `path` — so the delegate never touches the network, and the object URL
+     * is revoked the moment `delegate` reports success or failure (or the
+     * timeout elapses), never left for the caller to remember.
+     *
+     * **Refuses, via `onComplete(null, err)`, if the `manager` it is handed
+     * already has `prepareUrdfScene`'s URL modifier installed** — the two
+     * read different URDF sources and combining them on one manager breaks
+     * one half or the other, never obviously (see `prepareUrdfScene`'s own
+     * doc comment). Checked at the point the mistake would actually manifest
+     * rather than left to a paragraph a developer might not read.
+     */
+    createMeshLoader(robotId: string, delegate: MeshLoaderDelegate, options?: CreateMeshLoaderOptions): MeshLoaderDelegate;
+    /**
+     * Authenticated loading for everything three.js fetches to render a
+     * textured robot — not only meshes (spec §4.6, W7a, D2). Installs
+     * `manager.setURLModifier` so **every** load `manager` oversees resolves
+     * to a pre-fetched `blob:` URL: a top-level `<mesh>`, a `<material>`'s
+     * `<texture>`, and an image a `.dae` references internally via
+     * `<init_from>` — three cases, one mechanism, because the browser never
+     * fetches an asset directly. Every network read goes through this SDK
+     * with the bearer token first; a `blob:` URL is document-local and dies
+     * with the page, so nothing about who may read what changes.
+     *
+     * ```ts
+     * const manager = new THREE.LoadingManager()
+     * const { urdfText, missing, dispose } = await client.assets.prepareUrdfScene(robotId, manager)
+     * const loader = new URDFLoader(manager)
+     * const robot = loader.parse(urdfText)
+     * scene.add(robot)
+     * // later, once the scene has finished loading (or on unmount):
+     * dispose()
+     * ```
+     *
+     * **Do not also install `createMeshLoader` on the same manager.** The two
+     * consume 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 comment said that, and Momus-W7a's review traced it
+     * and found it wrong.** What actually happens is asymmetric breakage,
+     * whichever URDF text the combination ends up parsing: paired with
+     * *this* method's raw text, `createMeshLoader` receives urdf-loader's
+     * `resolvePath()` output (`/pkg/rel`) rather than an absolute Fleetless
+     * URL and 404s every mesh, while textures still resolve; paired with
+     * `urdf()`'s rewritten text instead, meshes load and every texture 401s
+     * — `createMeshLoader` bypasses this method's URL modifier entirely for
+     * meshes (that's what `loadMeshCb` means), so there is no hook left for
+     * a texture. Either way a developer who combined them by accident would
+     * debug the wrong symptom, which is worse than the original (already
+     * wrong) warning being merely unhelpful.
+     *
+     * **Enforced, not only documented (Momus-W7a review, via the team
+     * lead).** `createMeshLoader`'s returned callback checks whether the
+     * `manager` it is handed already has this method's URL modifier
+     * installed and fails loudly via `onComplete(null, err)` before ever
+     * touching the network, rather than relying on a developer having read
+     * this paragraph. See `managersWithPreparedUrdfScene`.
+     *
+     * **Why raw bytes, not `urdf()`'s rewritten text.** Both `urdf-loader`'s
+     * default mesh loading and `ColladaLoader` compute the base path they use
+     * to resolve a `.dae`'s internal references (`LoaderUtils.extractUrlBase`)
+     * from the URL they were originally asked to load — *before*
+     * `manager.resolveURL()`/the URL modifier ever runs; the modifier only
+     * changes what bytes get fetched, never what further relative references
+     * resolve against. Feeding it `urdf()`'s already-rewritten
+     * `.../assets/<uuid>` text would compute a base of `.../assets/`, and
+     * `textures/skin.png` joined onto that would never match anything this
+     * method's map knows about. Raw `package://` text is what keeps the two
+     * in sync.
+     *
+     * **`urdf-loader` resolves `package://` itself, before any of this runs —
+     * a second resolution stage this method has to account for, found by
+     * Threepio-W7a running the recipe demo in a real browser rather than
+     * reading the source.** `URDFLoader.parse()`'s own `resolvePath()`
+     * rewrites `package://pkg/rel` using `this.packages` (default `''`) to
+     * `/pkg/rel` — a root-relative URL — and *that* is what reaches
+     * `loadMeshCb`/`ColladaLoader`/`manager.resolveURL()`, not the original
+     * string. So the modifier is registered under **two** keys per asset: the
+     * literal `package://` name (`asset.name`, for a caller who sets
+     * `loader.packages = (pkg) => \`package://\${pkg}\`` to reconstruct it,
+     * or a renderer that never went through `resolvePath()` at all) and the
+     * root-relative form `urdf-loader`'s own *default* `packages: ''`
+     * produces (`/pkg/rel`) — covering the common case with zero required
+     * caller configuration. A `.dae`'s internal `<init_from>` ref resolves the
+     * same way one level deeper: `ColladaLoader` computes its own working
+     * path from *its* `url` argument (already `/pkg/rel` by the time it gets
+     * there under the default), so the internal reference lands on
+     * `/pkg/textures/skin.png` — exactly the second key, derived the same
+     * way. A caller whose `loader.packages` does something else entirely
+     * (a custom map, not the default and not the reconstruction above) is
+     * outside what this method can predict — see the ownership rule below
+     * for what happens to that reference.
+     *
+     * **This method only claims what it owns (D4, revised after Argus-W7a's
+     * review) — not every unmapped reference.** `manager` is frequently the
+     * caller's 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. A first version refused everything
+     * unmapped, which silently emptied every one of those the moment a
+     * caller shared their manager. So the rule is narrower: 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; an unmapped one falls back to the
+     * normalized form (D5, below) and then to a shared, inert, page-local
+     * `blob:` URL — never the original string, so a hostile URDF naming an
+     * unsynced or off-namespace reference still cannot make three.js touch
+     * the network for it. Anything else — not in that namespace — is left
+     * completely alone, **except** an absolute `http(s)` URL, which is
+     * refused regardless of namespace: the one case this method cannot leave
+     * ambiguous, because a hostile URDF naming an attacker's host directly
+     * (bypassing `package://` entirely) is exactly what D4 exists to close,
+     * and three.js would otherwise fetch it for real, off-origin, the moment
+     * the direct and namespace checks both miss.
+     *
+     * **A `.dae`'s own internal reference gets a second-chance, normalized
+     * lookup (D5, Momus-W7a review, reproduced in a real browser).** three.js
+     * builds the request for one by plain string concatenation — no `..`/`.`
+     * collapsing — while `asset.name` carries the *normalized* tail
+     * (`@fleetless/contracts`' naming rule). So `../textures/skin.png` or
+     * `./textures/skin.png`, both ordinary exporter output, would otherwise
+     * miss the direct key even though the reference is entirely resolvable.
+     * Verified independently that the top-level `<mesh>`/`<texture>` case
+     * never needs this: `asset.name` there is the URDF's own `package://` URI
+     * verbatim and `resolvePath()` rewrites it by the same unnormalized
+     * concatenation on both sides, so the direct key already matches.
+     *
+     * **`dispose()` does not undo any of this (D7, Kassandra-W7a review).**
+     * See its own doc comment on `UrdfSceneResources`.
+     *
+     * **Pre-fetch is unavoidable**, not merely a choice: a URL modifier
+     * cannot be asynchronous, so every asset it might be asked for has to
+     * already be a `blob:` URL before `URDFLoader.parse` runs. Bounded by
+     * `options.concurrency` (default 6) and scoped to only `kind: 'mesh'` and
+     * `kind: 'texture'` assets — which is already "what the URDF references"
+     * (`@fleetless/contracts`' `rest.ts`: a re-sync reconciles, so assets the
+     * current URDF no longer references stop belonging to the robot), not an
+     * unbounded fetch of everything the robot has ever had.
+     */
+    prepareUrdfScene(robotId: string, manager: UrdfSceneManager, options?: PrepareUrdfSceneOptions): Promise<UrdfSceneResources>;
+}
+
+/**
+ * What is kept between calls to stay logged in: exactly the wire shape
+ * `sessionTokens` returns, no derived fields. Refresh is reactive (a call
+ * that meets an expired access token refreshes and retries) rather than
+ * proactive, so there is no `expires_at` to compute or drift out of sync.
+ */
+type StoredSession = SessionTokens;
+/**
+ * Where the SDK keeps a session. A developer implements this to persist a
+ * login (localStorage, a cookie, a native keystore) — the SDK itself never
+ * assumes a browser, or any storage, exists.
+ */
+interface TokenStore {
+    load(): StoredSession | null | Promise<StoredSession | null>;
+    save(session: StoredSession | null): void | Promise<void>;
+}
+/** The default store: works out of the box, forgets the session on reload. */
+declare class InMemoryTokenStore implements TokenStore {
+    #private;
+    load(): StoredSession | null;
+    save(session: StoredSession | null): void;
+}
+
+/** `beginHostedLogin()`'s input (spec §3.4, §17, W7b). */
+interface BeginHostedLoginOptions {
+    /**
+     * The opaque `client_id` issued when the developer registered this app's
+     * OAuth client (console, App Settings). **Never `appIdentifier`** — they
+     * are deliberately different identifiers (`contracts/src/oauth.ts`,
+     * `oauthClient`'s doc comment: "the `client_id` on the wire — opaque, and
+     * not the app identifier").
+     */
+    clientId: string;
+    /**
+     * Must be registered, byte-for-byte, as one of that client's
+     * `redirect_uris` — matching at the server is exact-string, never a
+     * prefix (`contracts/src/oauth.ts`, `redirectUri`'s doc comment).
+     */
+    redirectUri: string;
+    scope?: string;
+    /**
+     * RFC 8707 audience binding (register row, W7b→W7c): the resource this
+     * session's token should be usable against — an MCP endpoint
+     * (`/mcp/<app>`, W7c) or another audience-checking resource this
+     * deployment validates. **Omit it for an ordinary app login.** A token
+     * with no `resource` carries no `aud` and works unrestricted against this
+     * app's own REST surface exactly as it always has; that path is
+     * unaffected by this field's existence. Only a caller that is itself
+     * going to present the token to an audience-checking resource needs to
+     * ask for one — and must ask for the *right* one, because `/mcp/<app>`
+     * refuses a token whose `aud` names a different app exactly as hard as it
+     * refuses a token with none at all.
+     */
+    resource?: string;
+}
+/** What `beginHostedLogin()` returns — nothing here has touched the network yet. */
+interface HostedLoginRequest {
+    /** Send the end user's browser here to start the hosted login page. */
+    url: string;
+    /**
+     * Persist this alongside `codeVerifier` before navigating away, and pass
+     * both back into `completeHostedLogin`. **This SDK does not persist them
+     * for you.** The redirect back to `redirectUri` is a fresh page load for a
+     * browser app — nothing kept in this SDK's own memory survives it (the
+     * same reasoning `client.ts` states for `TokenStore`: "the SDK itself
+     * never assumes a browser, or any storage, exists"). An in-memory default
+     * here would not be merely suboptimal, it would be broken for the primary
+     * use case while looking like it worked for anything that never actually
+     * navigates away. `sessionStorage`, a signed cookie, or a plain variable
+     * (a popup flow that never truly navigates) are all valid — that choice is
+     * the caller's.
+     */
+    state: string;
+    codeVerifier: string;
+}
+/** `completeHostedLogin()`'s input — the redirect back, plus what `beginHostedLogin` returned for this same attempt. */
+interface CompleteHostedLoginOptions {
+    /** The `code` query parameter from the redirect back to `redirectUri`. */
+    code: string;
+    /** The `state` query parameter from that same redirect. */
+    state: string;
+    /**
+     * The `state` this attempt's `beginHostedLogin` returned. Checked against
+     * `state` above **before any network call** — RFC 6749 §10.12's whole
+     * point is that a caller must not complete an authorization response it
+     * did not itself request.
+     */
+    expectedState: string;
+    /** The `codeVerifier` this attempt's `beginHostedLogin` returned. */
+    codeVerifier: string;
+    clientId: string;
+    /** Must be the exact same string passed to `beginHostedLogin`. */
+    redirectUri: string;
+    /**
+     * Must be the exact same string passed to `beginHostedLogin`, if any.
+     * Resending it here is not what binds the audience — the server already
+     * bound `resource` to the authorization code at `/oauth/authorize` and
+     * mints `aud` from that stored value regardless of what this call sends —
+     * but RFC 8707 §2 expects a client to name the resource at both steps,
+     * and the cloud rejects a *mismatched* resend outright (`invalid_target`).
+     * Omit it here exactly when it was omitted at `beginHostedLogin`.
+     */
+    resource?: string;
+}
+interface AuthApi {
+    /** Exchanges email + password, and the client's configured app identifier, for a session. */
+    login(email: string, password: string): Promise<void>;
+    /**
+     * Starts the hosted login flow (spec §3.4, §17, W7b): a Fleetless-served
+     * login page an app's end user is redirected to, with optional
+     * per-app IdP federation. Builds the `/oauth/authorize` URL (Authorization
+     * Code + PKCE, S256 only — OAuth 2.1 removes `plain`) and generates the
+     * `state`/`codeVerifier` PKCE and CSRF protection need. **Makes no network
+     * call** — everything here is local, so nothing about the app, the
+     * client, or the redirect URI is validated until the browser actually
+     * reaches `/oauth/authorize`.
+     *
+     * Async only because computing the S256 `code_challenge` needs
+     * `crypto.subtle.digest`, which the Web Crypto API only ever offers as a
+     * promise — there is no synchronous digest to call instead.
+     */
+    beginHostedLogin(options: BeginHostedLoginOptions): Promise<HostedLoginRequest>;
+    /**
+     * Completes the hosted login flow: checks `state` against `expectedState`
+     * (before any network call — see `CompleteHostedLoginOptions.expectedState`),
+     * exchanges `code` for tokens at `/oauth/token`, and stores them via the
+     * same `tokenStore` `login()` uses.
+     *
+     * **Two distinct refusals before that check, not one.** An empty
+     * `expectedState` throws `no_hosted_login_attempt` — nothing was
+     * persisted for this attempt (a different tab, a restored session,
+     * cleared storage), not necessarily an attack. Only once `expectedState`
+     * is actually present does a mismatch (or a missing `state` on the
+     * callback itself) throw `state_mismatch`. The two are told apart on
+     * purpose: they call for different remedies, and collapsing them would
+     * tell a developer debugging an ordinary storage gap that their app is
+     * under attack.
+     *
+     * Once past that check and the exchange completes, `me()`, `logout()`,
+     * `changePassword()` and silent refresh all behave identically afterwards,
+     * regardless of which flow the session started from. That is the actual
+     * content of §3.4's *"Beide Wege enden im selben Fleetless-Token"*: not
+     * merely that the bytes match, but that every existing code path treats
+     * the result the same way.
+     *
+     * The wire response is RFC 6749 §5.1's envelope (`token_type`, optional
+     * `scope`), not `sessionTokens` — this method normalizes one into the
+     * other before storing. **Refresh needs no separate handling**: the cloud
+     * mints these tokens through the same session mechanism `/api/client/login`
+     * uses (same `refresh_tokens` row, same rotation), so the existing silent
+     * refresh (`/api/client/refresh`) already works for a hosted-login
+     * session — nothing about the origin of a session is tracked or needs to
+     * be.
+     *
+     * Throws with the OAuth error code as `.code` (e.g. `invalid_grant` for an
+     * expired or already-used `code`) if the exchange itself fails — a
+     * different vocabulary from every other method on this interface, because
+     * `/oauth/token` answers in RFC 6749 §5.2's shape, not `apiError`.
+     *
+     * **Makes exactly one request to `/oauth/token` — never retried, no
+     * timeout-and-resend, no internal concurrency of its own.** Stated
+     * because the constraint that matters here is not this method's, it is
+     * the caller's: **never call this a second time for the same `code`
+     * while a first call is still in flight** (a plain "the first attempt
+     * looked like it timed out, so retry" is exactly the shape this warns
+     * against — it is not a defect in this method, since this method itself
+     * has nothing that could ever cause that). André's decision, 2026-08-18:
+     * the platform treats a second presentation of an authorization code as
+     * theft and revokes the whole token family it belongs to, deliberately,
+     * even though a plain double-submission looks identical on the wire —
+     * because the blast radius is bounded (only a caller already holding the
+     * correct `code_verifier` and `client_id` can trigger it, so a merely
+     * *sniffed* code cannot lock anyone out) and the alternative is a
+     * narrower defence against a real theft.
+     *
+     * **What actually happens if two requests race (measured, Argus-W7c):**
+     * one of the two receives `200` with a refresh token that the server has
+     * already revoked. The access token in that same response keeps working
+     * normally for the rest of its short TTL — nothing about the race is
+     * visible yet. The failure surfaces at this session's **first silent
+     * refresh**, as `token_revoked`, potentially many minutes after the race
+     * that actually caused it and with nothing in that later error pointing
+     * back to a retry that "worked". If your own framework, an HTTP client
+     * wrapper, or a user's impatient double-click can cause this method to
+     * be invoked twice concurrently for the same redirect, guard against
+     * that at the call site — a simple in-flight flag or disabling the
+     * triggering control is enough, since there is only ever one legitimate
+     * exchange per authorization code.
+     */
+    completeHostedLogin(options: CompleteHostedLoginOptions): Promise<void>;
+    /**
+     * Ends the session: revokes the whole refresh-token family server-side
+     * (a stolen refresh token stops working immediately) and closes this
+     * client's live realtime connection, if it has one. Then clears the
+     * local store. Never rejects and always clears the store, even if the
+     * server call fails: a user who presses "log out" must end up logged out
+     * locally regardless of the network. `revoked` reports whether the
+     * server-side revoke actually happened — `false` means the refresh
+     * family may still be alive server-side even though this client has
+     * forgotten it; an app that cares (a kiosk, a shared workstation) can
+     * warn the user or retry, one that doesn't can ignore it.
+     *
+     * **What this does not do:** invalidate the access token already issued.
+     * Access-token checks are stateless (a signed JWT, verified without a
+     * server-side lookup) — logout has nothing to flip on that token, only
+     * on the refresh family behind it. 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. This is a deliberate
+     * boundary of the stateless-JWT design (the same one that lets a role
+     * change, a block, or a membership removal take effect on the very next
+     * request without a fresh token), not a bug — but a kiosk or shared
+     * workstation needs to know that number.
+     */
+    logout(): Promise<{
+        revoked: boolean;
+    }>;
+    /** Who the caller turned out to be, without decoding a token client-side. */
+    me(): Promise<ClientIdentity>;
+    /**
+     * Starts self-registration into this app's pool (spec §3.2, W6c) — the
+     * second of the pool's two entry paths, alongside a console invitation.
+     * Sets the password here; `confirmRegistration` below only ever sees a
+     * token.
+     *
+     * **This does not log the caller in — there is no session yet.** A domain
+     * filter says *which* domains may register, never *whether the caller
+     * owns the address*, so minting a session here 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. So this mails a confirmation link and waits;
+     * `confirmRegistration(token)` is what proves the address and returns a
+     * session, the same two-step shape as `requestPasswordReset` /
+     * `confirmPasswordReset` below.
+     *
+     * **Resolves identically for an address that is new and one that already
+     * has an account** — same account-enumeration reasoning as
+     * `requestPasswordReset`. `mail` in the resolved value describes this
+     * deployment's mail configuration, not the address, so it is safe to
+     * read — but note that a deployment with no SMTP (`mail:
+     * 'not_configured'`) cannot complete a self-registration at all: unlike
+     * an invitation, where a developer can hand the link over directly, the
+     * confirmation link has no other channel.
+     *
+     * **The role is not yours to choose.** There is no `role` parameter: the
+     * app's own `selfRegistration.role_id` decides it (§3.2 — a pool member
+     * has exactly one role per app), and a signature that accepted one would
+     * be offering a choice the platform has to refuse anyway.
+     *
+     * **Fails the same way whether self-registration is off or the address's
+     * domain is not permitted.** Those two refusals are deliberately
+     * indistinguishable, for the same reason as above: telling them apart
+     * would let a caller probe configuration that is not theirs to see. Do
+     * not build a UI that tries to tell "this app doesn't allow sign-ups"
+     * apart from "your email domain isn't allowed" from the error alone.
+     *
+     * Behind the same limiter as `login` (`rate_limited`, W6c) — creating a
+     * row is the cheapest attack this platform has to defend against, so
+     * expect this to be throttled first under load, not last.
+     */
+    register(email: string, password: string): Promise<ClientRegisterResponse>;
+    /**
+     * Spends a self-registration confirmation token and returns the new
+     * session — the counterpart to `register` above. Stores the session
+     * exactly like `login`, so a caller who has just confirmed is not then
+     * told to log in separately.
+     *
+     * The token is single-use and expires; using it twice, or too late,
+     * answers `token_spent` either way, same as `confirmPasswordReset` below.
+     */
+    confirmRegistration(token: string): Promise<void>;
+    /**
+     * Changes the current end user's password (spec §3, W6c).
+     *
+     * `currentPassword` is required by the server even though the session
+     * already proves identity — it is what stops a stolen *session* from
+     * becoming a stolen *account* (see `passwordChangeRequest` in
+     * `@fleetless/contracts`).
+     *
+     * **Every other session of this identity is revoked on success, and this
+     * call's own session is re-issued, not left alone.** `passwordChangeRequest`
+     * carries nothing that identifies the caller's own refresh family, so the
+     * server cannot spare one token out of the family it just revoked — it
+     * revokes all of them and hands back a fresh pair, which this method
+     * stores exactly like `login` does. Skipping that store would leave the
+     * caller holding tokens the server has already revoked, working only
+     * until the access token expires and then silently logged out —
+     * indistinguishable from the change having failed, which is the one
+     * outcome this route exists to prevent. A user with other tabs or
+     * devices logged in will see *those* signed out the moment this
+     * resolves; if your app does not already make that consequence visible
+     * before they confirm, they will find out from a support ticket instead
+     * of from you.
+     */
+    changePassword(currentPassword: string, newPassword: string): Promise<void>;
+    /**
+     * Requests a password-reset link for `email` (spec §3, W6c) — sent by
+     * mail; the console-issued link is the primary path, this is the
+     * self-service one.
+     *
+     * **Resolves the same way whether or not `email` belongs to an account,
+     * and always did — this is not a bug to work around.** It is the one
+     * unauthenticated route in this SDK where revealing existence would be an
+     * account-enumeration oracle (see `passwordResetRequest`'s doc comment in
+     * `@fleetless/contracts`). There is nothing in this method's return value
+     * or its error codes that distinguishes "sent" from "no such account" —
+     * do not build a UI branch for "no such account" here, because there is
+     * nothing to branch on, on purpose.
+     */
+    requestPasswordReset(email: string): Promise<void>;
+    /**
+     * Completes a password reset using the token from the emailed link (spec
+     * §3, W6c).
+     *
+     * The token is single-use and expires; using it twice, or too late,
+     * answers `token_spent` either way — deliberately one code for both (see
+     * `ERROR_CODES` in `@fleetless/contracts`): telling them apart would tell
+     * a stranger whether a token ever existed, and the recovery is the same
+     * regardless — request a new link. Succeeding revokes every session of
+     * that identity, the same as `changePassword` — a forgotten password is
+     * one of the two states where somebody else may be holding a session.
+     */
+    confirmPasswordReset(token: string, newPassword: string): Promise<void>;
+}
+
+/**
+ * The snapshot's metadata alone, without the bytes (spec §10). All fields
+ * are `null` together when nothing has been captured yet for this camera —
+ * a fresh configuration before the first `snapshot_interval_ms` elapses, say
+ * — which is a state, not a failure: the wire answers it with
+ * `no_snapshot_yet`, and both `snapshot`/`snapshotMeta` absorb that code
+ * here rather than throw it, so a caller checks `age_ms === null` instead of
+ * wrapping every poll in a try/catch for something that is not exceptional.
+ *
+ * `age_ms` is **always** the cloud's own figure, never recomputed client-side
+ * as `Date.now() - timestamp_ms`: the cloud is the one clock that knows how
+ * long it has actually held the frame, and recomputing would reintroduce the
+ * viewer's own clock skew as a source of lying about freshness (see
+ * `SNAPSHOT_HEADERS`'s doc comment in `@fleetless/contracts`).
+ */
+interface CameraSnapshotMeta {
+    mime: string | null;
+    width: number | null;
+    height: number | null;
+    /** The bridge's capture time (§6.3). */
+    timestamp_ms: number | null;
+    age_ms: number | null;
+}
+/** One snapshot read: the image bytes plus everything needed to state how old they are (spec §10). */
+interface CameraSnapshot extends CameraSnapshotMeta {
+    image: Uint8Array | null;
+}
+/**
+ * What a LiveKit client needs to join, plus the means to leave (spec §10,
+ * §14.3: "Kamera (Snapshot-URL + LiveKit-Track-Handle)"). Hand `url`/`token`
+ * straight to a LiveKit client SDK (e.g. `Room.connect(url, token)`) — this
+ * SDK stops there on purpose: no video widget, no teleop-style helper
+ * (§14.3 keeps it thin).
+ */
+interface CameraLiveSession {
+    /**
+     * This viewer's own hold (W6b) — what `release()` releases, and the only
+     * thing distinguishing this session from every other tab of the same
+     * identity watching the same camera. Not previously addressable: a `DELETE`
+     * with no id released **all** of this identity's holds on the slug, so one
+     * tab closing stopped the robot for every other tab too. See `release()`'s
+     * doc comment for what changed and what did not.
+     */
+    session_id: string;
+    url: string;
+    room: string;
+    token: string;
+    /**
+     * When this token can no longer be used to **join** — not when an
+     * already-joined session ends. LiveKit checks a token at connect time
+     * only, so a `Room` that joined before this timestamp keeps streaming
+     * past it untouched; this field bounds how long an unused token sits
+     * around, nothing more.
+     *
+     * It is **not** a backstop for a forgotten `release()`, a crash, or a
+     * `kill -9` after joining: what ends an already-joined session is
+     * `release()` plus disconnecting the `Room`, the cloud noticing (via its
+     * own reconciliation against LiveKit's actual room participants) that
+     * this viewer is gone, or revocation kicking the participant outright.
+     * Do not design around `expires_at` as if it were any of those.
+     */
+    expires_at: string;
+    /**
+     * Tells the cloud this viewer no longer wants to hold the camera live —
+     * **this** hold, addressed by `session_id` (W6b), and no other tab's.
+     *
+     * Before W6b, `DELETE` carried no id and released every hold this identity
+     * had on the slug — so one tab's `release()` (or its unmount cleanup)
+     * stopped the robot out from under every other tab of the same logged-in
+     * user, which kept rendering a frozen frame because a LiveKit token is
+     * checked at join and never again. Each `CameraLiveSession` now releases
+     * only the hold it itself took.
+     *
+     * **This alone does not stop the stream.** The cloud makes LiveKit room
+     * participation the authoritative refcount, not this call — precisely
+     * because a closing tab cannot be relied on to make it. `release()` is a
+     * courteous fast path; the robot actually stops publishing once every
+     * viewer's LiveKit `Room` has disconnected, which the SFU notices on its
+     * own with no cooperation required. **Always pair this with disconnecting
+     * the `Room` you connected with `url`/`token`** — see the README's
+     * Cameras section for the paired cleanup pattern; a `release()` that ran
+     * alone while the `Room` stayed connected would stop nothing.
+     *
+     * Safe to call more than once (only the first call does anything) and
+     * never rejects — this is a courtesy notification, not the thing that
+     * actually stops the stream (see above), so there is nothing a caller
+     * could usefully do with a rejection here. That also makes this safe to
+     * use directly as e.g. a React effect's cleanup return value, including
+     * from `beforeunload`, where a call that could throw would be a liability.
+     *
+     * **A failed DELETE here is not observable anywhere** — not as a
+     * rejection, not as a realtime event, not as a field on this object. This
+     * is a deliberate decision, not an oversight (W6b review): the only
+     * consumer of that information would be code deciding whether to retry,
+     * and the backstop this comment already describes — the cloud's own
+     * LiveKit-participation reconciliation — makes a retry unnecessary for
+     * correctness. If a future caller needs to know "did my release actually
+     * reach the cloud" (telemetry, say), that is a new, additive signal to
+     * design, not a change to this method's contract.
+     */
+    release(): Promise<void>;
+}
+interface CamerasApi {
+    /** Every camera exposed on this robot (spec §11.2's per-robot descriptor list, extended to the camera kind). */
+    list(robotId: string): Promise<CameraDescriptor[]>;
+    /**
+     * The current snapshot: image bytes plus its age. Independent of `live` —
+     * a snapshot keeps updating on `snapshot_interval_ms` whether or not
+     * anyone is watching live (§10), and keeps being served, with a growing
+     * age, even while the bridge is offline.
+     */
+    snapshot(robotId: string, slug: string): Promise<CameraSnapshot>;
+    /**
+     * The snapshot's metadata alone — for polling "is there a newer frame
+     * yet?" without re-downloading the image on every check. Prefer this over
+     * `snapshot` for a view that only needs to show an age (e.g. "updated 2s
+     * ago") and fetches pixels on demand.
+     */
+    snapshotMeta(robotId: string, slug: string): Promise<CameraSnapshotMeta>;
+    /**
+     * Takes a refcounted hold on this camera's live stream (spec §10): the
+     * first `live()` on a slug starts the robot publishing, the last viewer
+     * leaving stops it. Deliberately not deduplicated locally across multiple
+     * `live()` calls for the same `(robotId, slug)` — unlike a datapoint
+     * subscription, each call needs its own distinct LiveKit participant, so
+     * a local counter here would just be the same shared-count bug
+     * `slug-subscriptions.ts` fixed, self-inflicted on a resource the cloud
+     * already counts correctly.
+     */
+    live(robotId: string, slug: string): Promise<CameraLiveSession>;
+}
+
+interface DatapointSubscriptionHandlers {
+    /** Called with the current value on subscribe, then again on every change. */
+    onEvent(event: DatapointEvent): void;
+    /** Called once if the subscription is refused (§11.5: e.g. `forbidden`, `unknown_datapoint`). */
+    onError?(error: FleetlessError): void;
+}
+interface DatapointSubscription {
+    /** Stops the subscription and, if the channel is currently connected, tells the server. */
+    unsubscribe(): void;
+}
+/**
+ * Window aggregation for `history` (spec §8). `window` and `agg` always
+ * travel together on the wire — the cloud refuses one without the other
+ * rather than defaulting either, since a silently chosen aggregation is a
+ * chart that lies quietly — so they live in one object here instead of two
+ * independent optional fields a caller could set only one of. The same
+ * reasoning as `cameraSource` being a discriminated union rather than
+ * optional fields: make the impossible combination unrepresentable, not
+ * merely rejected.
+ */
+interface HistoryAggregation {
+    /** Bucket width, e.g. `10s`, `1m`. */
+    window: string;
+    agg: 'min' | 'max' | 'avg';
+    /** A numeric field inside an object value, e.g. `pose.x` (§4.4 paths). Only meaningful when the datapoint's own value is not itself a number. */
+    field?: string;
+}
+interface HistoryOptions {
+    /**
+     * `now-30s` / `now-5m` / `now-1h`, or absolute unix milliseconds — as a
+     * **string** either way, exactly as the wire query expects it. The SDK
+     * does not accept a `Date` or a `number` and stringify it for you: that
+     * would be a convenience that quietly decides which of the two forms you
+     * meant, and the next person reading the wire traffic would not know
+     * which of us made that call.
+     */
+    from: string;
+    /** Same two forms as `from`. Defaults to now. */
+    to?: string;
+    limit?: number;
+    /** Present: the result is aggregated buckets. Absent: raw samples. */
+    aggregate?: HistoryAggregation;
+}
+interface DatapointsApi {
+    get(robotId: string, slug: string): Promise<DatapointValue>;
+    /**
+     * Subscribes over the realtime channel. Reconnect and re-authentication
+     * are handled by the shared `RealtimeChannel`; this resends its
+     * `subscribe` frame after every (re)connect, so a network drop is
+     * invisible to the caller beyond a gap in events.
+     *
+     * Reference-counted per `(robotId, slug)`: two subscriptions to the same
+     * pair share one wire subscription. Unsubscribing one never affects the
+     * other — the `unsubscribe` frame is sent only when the last subscriber
+     * on that pair goes away. This matters in practice: two widgets showing
+     * the same battery value, or a component mounted twice under React
+     * StrictMode, both subscribe to the same key. The count itself lives in
+     * `slug-subscriptions.ts`, shared with `actions.subscribe`/`services.call`
+     * — a slug is one namespace across kinds, and so is its subscription.
+     */
+    subscribe(robotId: string, slug: string, handlers: DatapointSubscriptionHandlers): DatapointSubscription;
+    /**
+     * Reads recorded history for a `retention: true` datapoint (spec §8) over
+     * REST — no realtime channel involved, the same way `cameras.snapshot`
+     * isn't. Returns a **discriminated result**: passing `aggregate` gets you
+     * back `HistoryBucketsResponse` (`kind: 'buckets'`), leaving it out gets
+     * you `HistorySamplesResponse` (`kind: 'samples'`) — two overloads so a
+     * caller who already knows which one they asked for isn't forced to
+     * narrow something they determined themselves. `kind` still carries the
+     * same information on both, so code that holds the result dynamically
+     * (e.g. read from a variable typed as the union) can still branch on it.
+     *
+     * **Rejects, does not silently empty out, two specific refusals** —
+     * unlike `cameras.snapshot`'s absorption of `no_snapshot_yet` into a null
+     * read, these two must reach the caller as thrown `FleetlessError`s:
+     * - `not_recorded` — the slug exists and is granted, but is configured
+     *   live-only. An empty result here would look exactly like "recorded,
+     *   but nothing in this window", and the two need opposite fixes: turn
+     *   recording on, versus look at a different range.
+     * - `not_aggregatable` — `aggregate` was given for a value that isn't a
+     *   number and no numeric `aggregate.field` was named.
+     */
+    history(robotId: string, slug: string, options: HistoryOptions & {
+        aggregate: HistoryAggregation;
+    }): Promise<HistoryBucketsResponse>;
+    history(robotId: string, slug: string, options: HistoryOptions & {
+        aggregate?: undefined;
+    }): Promise<HistorySamplesResponse>;
+}
+
+interface JobsApi {
+    /**
+     * Every job the platform currently believes this robot has — `GET
+     * /api/robots/:id/jobs` (W6b, contracts `robotJobsResponse` doc comment).
+     *
+     * `actions.subscribe`/`services.call` and `GET /jobs/:slug` (the per-slug
+     * route those build on) all require already knowing the slug. That is not
+     * always true: a reconnecting bridge 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,
+     * which is exactly what this method is for (register row 2k) — an app
+     * developer had no way to reach them before this.
+     *
+     * At most one entry per slug: the current job there, exactly what a
+     * per-slug read would answer for that slug. Not a history endpoint.
+     * Grant-filtered same as `cameras.list`/`datapoints` — an end user or
+     * server key sees only jobs on slugs their role grants; a developer
+     * session sees every job on the robot. Never empty-vs-missing ambiguity:
+     * a robot doing nothing resolves `[]`.
+     *
+     * **Ordered newest first by `started_at`, with `job.seq` as the
+     * tiebreaker** (`started_at` alone is not a total order — two jobs minted
+     * in the same millisecond used to sort arbitrarily, differently on each
+     * query). But for an **adopted** job, `started_at` is adoption time, not
+     * when it actually started on the robot — the cloud only learns of it at
+     * `hello`, having never minted it, and has no other honest value to put
+     * there. So this is 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 (contracts `robotJobsResponse` doc
+     * comment).
+     */
+    list(robotId: string): Promise<Job[]>;
+}
+
+interface PublishersApi {
+    /**
+     * Publishes one message to a publisher (spec §4.2, §6.4).
+     *
+     * This is a plain method call — there is deliberately no deadman switch,
+     * rate governor or "takt" helper here (spec §14.3). The bridge's own
+     * `timeout_ms` failsafe is the platform's safety primitive: if messages
+     * stop arriving — including because this process crashed — the bridge
+     * publishes the configured failsafe message itself. That does **not**
+     * mean the SDK protects a caller who stops calling `publish` on purpose
+     * without stopping cleanly (e.g. no repeated call at a safe rate): the
+     * safety pattern for *how often* and *when* to publish belongs in the
+     * app, not here. See the README's "No teleop helpers" section before
+     * building a publisher-driven control loop.
+     *
+     * Rejects `publisher_busy` while a different user is publishing and has
+     * not been quiet for `quiet_timeout_ms` yet (§6.4) — whoever publishes
+     * holds the publisher implicitly exclusive.
+     */
+    publish(robotId: string, slug: string, message: Record<string, unknown>, options?: SendCommandOptions): Promise<void>;
+}
+
+interface ServicesApi {
+    /**
+     * Calls a service and resolves with its result (spec §4.2, §11.3). A
+     * service call is a job underneath — the same `job_id` exchange and
+     * disconnect survival as an action (§6.1: "an action goal or a service
+     * call") — but that is deliberately invisible here: the caller gets a
+     * plain `Promise<result>`, matching the REST `serviceCallResponse` shape's
+     * developer experience. There is nothing to subscribe to for a service —
+     * no feedback, no progress, no cancel — so this call already waits for
+     * the terminal state internally.
+     *
+     * `options.patienceMs` bounds the **whole wait** for a service call (W6b)
+     * — unlike an action, where it bounds acceptance only — because a service
+     * has no further state to observe once it settles; the platform gives up
+     * on the ROS call itself after this long.
+     *
+     * `options.timeoutMs` bounds this SDK's own local wait for the WHOLE
+     * call — the ack that a job was created, plus however much of the
+     * budget is left for it to then reach a terminal state (D10) — not two
+     * separate `timeoutMs`-length windows back to back. A caller who sets
+     * `timeoutMs: 5000` is bounding total latency at ~5s, not ~10s; the
+     * number means what it says, once, for the whole call.
+     *
+     * It is also **not independent** of `patienceMs` (D3a): left unset, it
+     * is derived from `patienceMs` so this SDK's local clock cannot fire
+     * before the platform's own deadline has even been reached. Setting
+     * both, with `timeoutMs` shorter than `patienceMs`, throws
+     * `invalid_option` synchronously rather than letting the two race — see
+     * `resolveLocalWaitMs` in `commands.ts` for the full reasoning.
+     */
+    call(robotId: string, slug: string, params: Record<string, unknown>, options?: InvokeOptions): Promise<unknown>;
+}
+
+interface FleetlessClientOptions {
+    /** Base URL of the Fleetless REST API, e.g. `https://api.fleetless.dev`. */
+    apiUrl: string;
+    /** The app's identifier (the slug shown in the console), sent on every login. */
+    appIdentifier: string;
+    /**
+     * Where refresh/access tokens are kept between calls. Defaults to an
+     * in-memory store — pass your own (localStorage, a cookie, a native
+     * keystore) to persist a session across reloads. The SDK never assumes a
+     * browser exists.
+     */
+    tokenStore?: TokenStore;
+    /**
+     * A server key (`flk_...`) for server-side callers with full app rights.
+     * Mutually exclusive with `tokenStore`-based login: a client constructed
+     * with a server key never calls `auth.login`/`auth.logout`.
+     */
+    serverKey?: string;
+    /** Injectable for tests, or a non-global `fetch` implementation. */
+    fetch?: typeof fetch;
+    /** Injectable for tests, or a non-global `WebSocket` implementation. */
+    WebSocket?: typeof WebSocket;
+    /** Defaults to `apiUrl` with http(s) swapped for ws(s) and `/realtime` appended. */
+    realtimeUrl?: string;
+}
+interface FleetlessClientConfig {
+    readonly apiUrl: string;
+    readonly appIdentifier: string;
+    readonly realtimeUrl: string;
+}
+interface FleetlessClient {
+    readonly config: FleetlessClientConfig;
+    readonly auth: AuthApi;
+    readonly datapoints: DatapointsApi;
+    readonly actions: ActionsApi;
+    readonly services: ServicesApi;
+    readonly publishers: PublishersApi;
+    readonly cameras: CamerasApi;
+    /**
+     * Robot-wide job reads that do not fit under `actions`/`services` because
+     * they are not addressed by slug — see `JobsApi.list`.
+     */
+    readonly jobs: JobsApi;
+    /** URDF + mesh reads (spec §4.6) — list/get/urdf, plus the `urdf-loader` mesh callback. */
+    readonly assets: AssetsApi;
+    /**
+     * Closes the realtime channel and stops it from reconnecting. Safe to
+     * call whether or not any subscription was ever made, and safe to call
+     * more than once. A Node script (the exact use case `serverKey` is for)
+     * that never calls this after subscribing will not exit on its own — an
+     * open WebSocket keeps the event loop alive. `auth.logout()` calls this
+     * automatically; call it yourself too if the process should exit without
+     * logging out (e.g. a server-side caller shutting down).
+     */
+    close(): void;
+}
+declare function createClient(options: FleetlessClientOptions): FleetlessClient;
+
+export { type ActionsApi, type Asset, type AssetBytes, type AssetListResponse, type AssetsApi, type AuthApi, type BeginHostedLoginOptions, type BusyDetails, type CameraDescriptor, type CameraLiveSession, type CameraSnapshot, type CameraSnapshotMeta, type CamerasApi, type ClientIdentity, type ClientRegisterResponse, type CompleteHostedLoginOptions, type CreateMeshLoaderOptions, type DatapointEvent, type DatapointSubscription, type DatapointSubscriptionHandlers, type DatapointValue, type DatapointsApi, type FleetlessClient, type FleetlessClientConfig, type FleetlessClientOptions, FleetlessError, type FleetlessErrorCode, type FleetlessErrorOptions, type HistoryAggregation, type HistoryBucketsResponse, type HistoryOptions, type HistorySamplesResponse, type HostedLoginRequest, InMemoryTokenStore, type Job, type JobEvent, type JobState, type JobSubscription, type JobSubscriptionHandlers, type JobsApi, type MailStatus, type MeshLoaderDelegate, type ParameterInvalidDetails, type ParameterViolation, type PrepareUrdfSceneOptions, type PublishersApi, type RateLimitDetails, SDK_ERROR_CODES, type SdkErrorCode, type SendCommandOptions, type ServicesApi, type StoredSession, type TokenStore, type UrdfCompleteness, type UrdfSceneManager, type UrdfSceneResources, createClient, parameterInvalidDetails };