@fleetless/sdk 3.0.1 → 3.0.3

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: MIT
 import { z } from 'zod';
 
-// SPDX-License-Identifier: Apache-2.0
 
 /**
  * Jobs: one running unit of work on a robot — an action
@@ -234,7 +233,6 @@ declare const historyBucketsResponse: z.ZodObject<{
 }, z.core.$strip>;
 type HistoryBucketsResponse = z.infer<typeof historyBucketsResponse>;
 
-// SPDX-License-Identifier: Apache-2.0
 
 /**
  * One datapoint sample pushed to a subscriber. The current value arrives
@@ -250,7 +248,6 @@ declare const datapointEvent: z.ZodObject<{
 }, z.core.$strip>;
 type DatapointEvent = z.infer<typeof datapointEvent>;
 
-// SPDX-License-Identifier: Apache-2.0
 
 /**
  * Access plus refresh. The access token is short-lived; the
@@ -267,7 +264,6 @@ declare const sessionTokens: z.ZodObject<{
 }, z.core.$strip>;
 type SessionTokens = z.infer<typeof sessionTokens>;
 
-// SPDX-License-Identifier: Apache-2.0
 
 /**
  * **Why a federated sign-in ended without a session, in a code the app can
@@ -416,7 +412,6 @@ declare const clientIdentity: z.ZodObject<{
 }, z.core.$strip>;
 type ClientIdentity = z.infer<typeof clientIdentity>;
 
-// SPDX-License-Identifier: Apache-2.0
 
 declare const asset: z.ZodObject<{
     id: z.ZodUUID;
@@ -551,7 +546,6 @@ declare const assetListResponse: z.ZodObject<{
 }, z.core.$strip>;
 type AssetListResponse = z.infer<typeof assetListResponse>;
 
-// SPDX-License-Identifier: Apache-2.0
 
 /**
  * One violated parameter rule. `details` on the envelope stays `unknown` — codes
@@ -613,13 +607,13 @@ type ErrorCode = (typeof ERROR_CODES)[number];
  *   later on the same socket — nobody knows — but the caller cannot be made
  *   to wait forever for that.
  * - `command_outcome_unknown`: 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.
+ *   on purpose — the connection that carried the command was replaced by a
+ *   new one (a reconnect) before any reply arrived. The server, if it
+ *   answered at all, answered a socket that no longer exists, so 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`: 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
@@ -807,20 +801,19 @@ interface JobSubscriptionHandlers {
 interface JobSubscription {
     /**
      * Stops this subscription. The `unsubscribe` frame reaches the server only
-     * when this was the **last** holder of the robot and slug pair, and only if
-     * the channel is connected — subscriptions are reference-counted across
-     * kinds, so releasing this one while a second `actions.subscribe`, a
-     * `datapoints.subscribe` or an in-flight `services.call` still holds the
-     * same pair leaves that one's stream running untouched. Safe to call more
-     * than once.
+     * when this was the **last** holder of the robot/slug pair and the channel
+     * is connected — subscriptions are reference-counted across kinds, so a
+     * second `actions.subscribe`, `datapoints.subscribe` or in-flight
+     * `services.call` on the same pair keeps its stream running. Safe to call
+     * more than once.
      */
     unsubscribe(): void;
 }
 
 /**
  * Long-running work on a robot, reachable as `client.actions`. An action is
- * a ROS action the developer exposed under a slug: it is invoked, it runs
- * for as long as it runs, and it reports back while it does.
+ * a ROS action the developer exposed under a slug: it is invoked, runs as
+ * long as it runs, and reports back while it does.
  */
 interface ActionsApi {
     /**
@@ -828,7 +821,7 @@ interface ActionsApi {
      * — 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.
+     * `error.details.running` naming the running job.
      *
      * `options.patienceMs` bounds goal *acceptance* only — once a goal
      * is accepted this call has already resolved; the job then runs as long
@@ -1112,7 +1105,7 @@ interface AssetsApi {
      * **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. **It is not that every mesh gets fetched twice.**
+     * cloud-rewritten text. **Not a double-fetch.**
      * 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
@@ -1242,7 +1235,7 @@ interface TokenStore {
 /** The default store: works out of the box, forgets the session on reload. */
 declare class InMemoryTokenStore implements TokenStore {
     #private;
-    /** Creates an empty store. Nothing is loaded from anywhere — a client built with it starts logged out. */
+    /** Nothing is loaded from anywhere — a client built with it starts logged out. */
     constructor();
     /** Returns the session held in memory, or `null` if there is none. */
     load(): StoredSession | null;
@@ -1686,8 +1679,8 @@ interface CameraLiveSession {
      * 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
+     * the `Room` you connected with `url`/`token`** — see the Cameras
+     * section of the SDK reference 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
@@ -1698,14 +1691,12 @@ interface CameraLiveSession {
      * 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: 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.
+     * rejection, a realtime event, or a field on this object. Deliberate, not
+     * an oversight: the only consumer of that information would be code
+     * deciding whether to retry, and the reconciliation backstop described
+     * above already makes a retry unnecessary for correctness. A future need
+     * to know "did my release actually reach the cloud" (telemetry, say) is a
+     * new, additive signal to design, not a change to this method's contract.
      */
     release(): Promise<void>;
 }
@@ -1759,12 +1750,11 @@ interface DatapointSubscriptionHandlers {
 interface DatapointSubscription {
     /**
      * Stops this subscription. The `unsubscribe` frame reaches the server only
-     * when this was the **last** holder of the robot and slug pair, and only if
-     * the channel is connected — subscriptions are reference-counted across
-     * kinds, so releasing this one while a second `datapoints.subscribe`, an
-     * `actions.subscribe` or an in-flight `services.call` still holds the same
-     * pair leaves that one's stream running untouched. Safe to call more than
-     * once.
+     * when this was the **last** holder of the robot/slug pair and the channel
+     * is connected — subscriptions are reference-counted across kinds, so
+     * releasing this one while a `datapoints.subscribe`, `actions.subscribe` or
+     * in-flight `services.call` still holds the same pair leaves that one's
+     * stream running. Safe to call more than once.
      */
     unsubscribe(): void;
 }
@@ -1772,11 +1762,10 @@ interface DatapointSubscription {
  * Window aggregation for `datapoints.history`. `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.
+ * chart that lies quietly — so they live in one object instead of two
+ * optional fields a caller could set only one of. Same reasoning as
+ * `cameraSource`'s discriminated union: make the impossible combination
+ * unrepresentable, not merely rejected.
  */
 interface HistoryAggregation {
     /** Bucket width, e.g. `10s`, `1m`. */
@@ -1787,9 +1776,8 @@ interface HistoryAggregation {
     field?: string;
 }
 /**
- * The window `datapoints.history` reads, and whether it comes back as raw
- * samples or as aggregated buckets. `aggregate` is what decides which of
- * the two responses you get.
+ * The window `datapoints.history` reads. `aggregate` decides whether the
+ * response is raw samples or aggregated buckets.
  */
 interface HistoryOptions {
     /**
@@ -1829,9 +1817,9 @@ interface DatapointsApi {
      * 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. That count is shared with
+     * on that pair goes away. In practice: two widgets showing the same
+     * battery value, or a component mounted twice under React StrictMode,
+     * subscribe to the same key. That count is shared with
      * `actions.subscribe` and `services.call` — a slug is one namespace across
      * kinds, and so is its subscription.
      */
@@ -1844,10 +1832,9 @@ interface DatapointsApi {
      * reduced by `aggregate.agg`. Leave `aggregate` out and the other overload
      * gives you raw samples instead.
      *
-     * Two overloads rather than one union so a caller who already knows which
-     * they asked for isn't forced to narrow something they determined
-     * themselves. `kind` still carries the same information on both, so code
-     * holding the result dynamically can still branch on it.
+     * Two overloads rather than one union, so a caller who already knows which
+     * one they asked for isn't forced to narrow it. `kind` carries the same
+     * information either way, so dynamic code 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
@@ -1881,28 +1868,26 @@ interface DatapointsApi {
 }
 
 /**
- * Robot-wide job reads, reachable as `client.jobs`. Everything here is
- * addressed by robot rather than by slug, which is what `actions` and
- * `services` cannot do.
+ * Robot-wide job reads, reachable as `client.jobs` — addressed by robot,
+ * not slug, which `actions` and `services` cannot do.
  */
 interface JobsApi {
     /**
      * Every job the platform currently believes this robot has.
      *
-     * `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 — an app developer has no
-     * other way to reach them.
-     *
-     * 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 `[]`.
+     * `actions.subscribe`/`services.call` and `GET /jobs/:slug` — the per-slug
+     * route those build on — all require knowing the slug already. Two cases
+     * don't: a reconnecting bridge naming a job the cloud only *adopted*, and
+     * a config change leaving a job on a slug the published document no
+     * longer contains. Neither has a slug to give — this method is the only
+     * way an app developer reaches them.
+     *
+     * At most one entry per slug: the current job there, same as a per-slug
+     * read would answer. 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
@@ -1926,16 +1911,15 @@ interface PublishersApi {
     /**
      * Publishes one message to a publisher.
      *
-     * This is a plain method call — there is deliberately no deadman switch,
-     * rate governor or "takt" helper here. 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 "Publishers, and no teleop helpers"
-     * section before building a publisher-driven control loop.
+     * A plain method call — deliberately no deadman switch, rate governor or
+     * "takt" helper. The bridge's own `timeout_ms` failsafe is the platform's
+     * safety primitive: when messages stop arriving, crash included, the
+     * bridge publishes its configured failsafe message. That does **not**
+     * cover a caller who stops calling `publish` on purpose without stopping
+     * cleanly (e.g. no repeated call at a safe rate) — how often and when to
+     * publish is the app's pattern, not the SDK's. See the Publishers
+     * section of the SDK reference before building a
+     * publisher-driven control loop.
      *
      * Rejects `publisher_busy` while a different user is publishing and has
      * not been quiet for its configured quiet timeout yet — whoever publishes
@@ -1946,16 +1930,15 @@ interface PublishersApi {
 
 /**
  * Request/response calls to a robot, reachable as `client.services`. A
- * service answers once and is done, which is why this namespace has a
- * single method and nothing to subscribe to.
+ * service answers once and is done — one method, nothing to subscribe to.
  */
 interface ServicesApi {
     /**
      * Calls a service and resolves with its result. A service call is a job
      * underneath — the same `job_id` exchange and disconnect survival as an
      * action — 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 —
+     * plain `Promise<result>`, matching the REST `serviceCallResponse` shape.
+     * 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.
      *
@@ -1968,8 +1951,7 @@ interface ServicesApi {
      * call — the ack that a job was created, plus however much of the
      * budget is left for it to then reach a terminal state — 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.
+     * `timeoutMs: 5000` bounds total latency at ~5s, not ~10s.
      *
      * It is also **not independent** of `patienceMs`: left unset, it
      * is derived from `patienceMs` so this SDK's local clock cannot fire
@@ -1992,10 +1974,9 @@ interface FleetlessClientOptions {
     /** 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.
+     * Where refresh/access tokens live between calls. Defaults to in-memory —
+     * pass your own (localStorage, a cookie, a native keystore) to persist a
+     * session across reloads. The SDK never assumes a browser exists.
      */
     tokenStore?: TokenStore;
     /**
@@ -2057,13 +2038,13 @@ interface FleetlessClient {
     /** URDF and mesh reads — 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).
+     * Closes the realtime channel and stops it from reconnecting. Safe with
+     * no subscription ever made, and safe to call twice. 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 if the process should exit without logging out (e.g. a
+     * server-side shutdown).
      */
     close(): void;
 }