@fleetless/sdk 3.0.2 → 3.1.0

package/README.md

@@ -5,82 +5,51 @@
 [![license MIT](https://img.shields.io/npm/l/@fleetless/sdk)](LICENSE)
 [![node >=20](https://img.shields.io/node/v/@fleetless/sdk)](https://nodejs.org)
 
-The official TypeScript SDK for apps built on [Fleetless](https://fleetless.dev),
-which exposes a ROS 2 robot as a hosted REST and realtime API — exactly the
-topics, services and actions a developer chose to publish, under stable slugs,
-behind roles. The SDK covers all of it: datapoints (read, subscribe, recorded
-history), actions, services, publishers, cameras, jobs, assets and URDF, and
-the whole client auth API your own sign-in UI calls. It is framework-agnostic,
-ships ESM and CJS with its own types, and runs wherever a `fetch` and a
-`WebSocket` exist — a browser, a mobile webview, Node 22 or newer, and
-server-side with a server key instead of a user session. On Node 20 the REST
-half works as it stands, but there is no global `WebSocket` (it is behind
-`--experimental-websocket` there), so anything realtime needs one supplied:
-`createClient({ …, WebSocket: (await import('ws')).WebSocket })`, or the flag.
-Without it, `subscribe` calls `onError` with `no_websocket`.
+**Your robot, as an API. This is the client.**
 
-**The mental model in one paragraph.** A robot runs the Fleetless bridge, a
-ROS 2 node. In the [Fleetless Console](https://console.fleetless.dev) a
-developer picks which topics, services and actions that robot exposes and gives
-each one a stable `snake_case` slug and a role that may reach it. The cloud
-turns those into REST and realtime endpoints. This package is the client for
-those endpoints: you address a robot by its id and a capability by its slug,
-you sign your own users in against your own app's user directory, and you never
-see a ROS name, a topic type or a message definition. Renaming a node on the
-robot is invisible to your app; changing a slug is not.
+[Fleetless](https://fleetless.dev) turns a ROS 2 robot into a hosted REST and
+realtime API. The robot runs the Fleetless Bridge, and in the
+[Fleetless Console](https://console.fleetless.dev) a developer picks which
+topics, services, actions, publishers and cameras it exposes, each under a
+stable slug and behind a role. Your app talks to those slugs over HTTPS and
+never learns a ROS name, a topic type or a message definition.
 
-New here? The [getting-started guide](https://docs.fleetless.dev/getting-started/)
-goes from a robot that has never connected to a value on a page, and the
-[app-auth recipe](https://docs.fleetless.dev/recipes/app-auth/) is the
-walkthrough for every sign-in screen.
+This package is the official TypeScript client for that API. It handles the
+sessions, the reconnects, the subscriptions and the errors, so your code can
+get on with the part that is actually about your robot. Framework-agnostic,
+ESM and CJS, types included.
 
-## Why
-
-- **One connection, however many subscriptions.** Every datapoint and job
-  subscription shares a single authenticated WebSocket. It reconnects with
-  exponential backoff, re-authenticates, and resends its own subscribe frames,
-  so a dropped network shows up as a gap in events rather than as work for you.
-- **Subscriptions are reference-counted per robot and slug.** Two widgets on
-  the same battery value, or one component mounted twice under React
-  StrictMode, share one wire subscription. Unsubscribing one never cuts off the
-  other.
-- **Errors you branch on, not errors you parse.** Every refusal arrives as a
-  `FleetlessError` carrying a stable `code` — `busy`, `forbidden`,
-  `robot_offline`, `rate_limited` — plus the SDK's own codes for refusals that
-  never reached the network. `rate_limited` is surfaced with its
-  `retry_after_ms` and never retried behind your back.
-- **Publishers with a failsafe the robot enforces.** `publishers.publish` sends
-  one message and nothing else. If your app stops publishing — including
-  because it crashed — the bridge on the robot publishes the configured
-  failsafe message itself. The safety primitive lives on the robot, not in your
-  event loop.
-- **Cameras that cost nothing while nobody watches.** Snapshot bytes come with
-  the cloud's own `age_ms`, and keep being served while the robot is offline.
-  `cameras.live` takes a refcounted hold: the first viewer starts the robot
-  publishing, the last one leaving stops it. You get a LiveKit room URL and
-  token to hand to the LiveKit client of your choice.
-- **The whole auth surface, and every screen stays yours.** Fleetless renders
-  no page for an app user: registration with email verification, invitations,
-  password reset, single sign-on to one of the app's identity providers, and
-  the MCP consent screen are all methods on `client.auth`, called from a UI you
-  wrote. The federated flow runs its own PKCE (S256 only) against Fleetless;
-  `beginOidcLogin` makes no network call, and `completeOidcLogin` checks
-  `state` before it exchanges anything.
-- **A token store you control.** Implement two methods to keep a session in
-  `localStorage`, a cookie or a native keystore; the default keeps it in
-  memory. Refresh is silent and single-flight, so ten concurrent calls that
-  meet an expired access token share one refresh instead of firing ten.
+Fleetless is in closed beta. The waiting list is at
+<https://fleetless.dev/#waiting-list>.
 
-## Getting started
+## ✨ What you can do with it
+
+- **Find your robots** and read what your role lets you do on each — slugs,
+  units, parameter schemas — before you draw a screen.
+- **Read datapoints** once, subscribe to them live over one reconnecting
+  WebSocket, or query their recorded history.
+- **Run actions and call services** by slug, with feedback, progress and
+  results as they arrive.
+- **Publish messages** to a topic, behind a failsafe the robot enforces
+  itself the moment your app goes quiet.
+- **Show cameras**: a snapshot that is always there, or live video over
+  WebRTC that starts with the first viewer and stops with the last.
+- **Follow jobs**, sync assets, and render the robot's URDF with its meshes.
+- **Sign your users in** — registration, verification, invitations, password
+  reset, single sign-on and MCP consent — from screens that are entirely
+  yours. Fleetless renders no page for an app user.
+- **Branch on errors** instead of parsing them: every refusal is a
+  `FleetlessError` with a stable `code`.
+
+## 🚀 Getting started
 
 ```sh
 npm i @fleetless/sdk
 ```
 
-You need an app identifier and the credentials of an **app user** — an
-account inside that app, which the developer's team creates or invites from
-the [Fleetless Console](https://console.fleetless.dev). A console login is a
-Fleetless user, a different identity space, and will not sign in here.
+You need an app identifier and an **app user** of that app, both created in
+the console. A console login is a Fleetless user, a different identity space,
+and will not sign in here.
 
 ```ts checked
 import { createClient } from '@fleetless/sdk'
@@ -92,312 +61,65 @@ const client = createClient({
 
 await client.auth.login('user@example.com', 'correct-horse-battery')
 
-// Robot ids are UUIDs; the console shows the one you want.
-const robotId = '4f2c1a90-7b3e-4d51-9c86-0a1b2c3d4e5f'
+const robotId = '4f2c1a90-7b3e-4d51-9c86-0a1b2c3d4e5f' // the console shows it
 
 // One-shot read.
 const battery = await client.datapoints.get(robotId, 'battery_percentage')
 console.log(battery.value, battery.timestamp_ms)
 
-// Live updates. The current value arrives immediately, then every change.
+// Live updates: the current value first, then every change.
 const subscription = client.datapoints.subscribe(robotId, 'battery_percentage', {
-  onEvent(event) {
-    console.log(event.value, event.timestamp_ms)
-  },
-  onError(error) {
-    console.error(error.code, error.message)
-  },
+  onEvent: (event) => console.log(event.value, event.timestamp_ms),
+  onError: (error) => console.error(error.code, error.message),
 })
 
 // Later:
 subscription.unsubscribe()
 await client.auth.logout()
-// logout() already closes the realtime channel. Call close() yourself when a
-// process should exit without logging out — an open WebSocket keeps Node alive.
-client.close()
-```
-
-Slugs are the names you chose in the console, in `snake_case`
-(`[a-z][a-z0-9]*(_[a-z0-9]+)*`) — never the robot's internal ROS names, which
-is what makes renaming a node on the robot invisible to your app.
-
-### Your own sign-in UI
-
-Every screen an app user sees belongs to your app. These are the calls behind
-them; the full walkthrough, page by page, is the
-[app-auth recipe](https://docs.fleetless.dev/recipes/app-auth/).
-
-```ts
-// Registration. Resolves on 202 — which says a policy-allowed request was
-// accepted, NOT that an account was created. An address the app already knows
-// gets the identical answer with no mail sent, so the only honest thing to
-// render is a sentence about the mailbox.
-await client.auth.register({ email, password, displayName })
-
-// The page your app serves at the app's configured `verify_url`. Stores a
-// session, so nobody types a password right after reading their mail.
-await client.auth.verifyEmail(tokenFromTheLink)
-
-// Recovery. requestPasswordReset always resolves on 202, for a known address
-// and an unknown one alike.
-await client.auth.requestPasswordReset(email)
-await client.auth.confirmPasswordReset(tokenFromTheLink, newPassword)
-
-// The page your app serves at the app's configured `invite_url`.
-await client.auth.acceptInvitation({ token: tokenFromTheLink, password })
-```
-
-### Sign-in through an identity provider
-
-An app may carry any number of OpenID Connect providers, configured per app in
-the console. Your page draws the buttons; your app never talks to the provider.
-
-```ts
-// Draw the buttons. Only enabled providers are listed, slug and name only.
-const providers = await client.auth.listProviders()
-
-// 1. Build the URL. No network call: this generates the PKCE verifier and the
-//    state, and hands them back, because a redirect is a fresh page load.
-const request = await client.auth.beginOidcLogin({
-  slug: 'azure',
-  redirectUri: 'https://your-app.example.com/callback',
-})
-sessionStorage.setItem('fleetless_state', request.state)
-sessionStorage.setItem('fleetless_code_verifier', request.codeVerifier)
-window.location.assign(request.url)
-
-// 2. On the callback page. A refused sign-in redirects here with `error`
-//    rather than a code, so check for that first.
-const params = new URL(window.location.href).searchParams
-const failure = client.auth.oidcErrorFromCallback(params)
-if (failure) {
-  // A FleetlessError carrying the documented reason: no_access, email_taken,
-  // email_unverified, domain_not_allowed, registration_closed, and the rest.
-  showSignInProblem(failure)
-} else {
-  await client.auth.completeOidcLogin({
-    code: params.get('code') ?? '',
-    state: params.get('state') ?? '',
-    expectedState: sessionStorage.getItem('fleetless_state') ?? '',
-    codeVerifier: sessionStorage.getItem('fleetless_code_verifier') ?? '',
-  })
-  // From here on me(), logout() and silent refresh behave exactly as they do
-  // after login().
-}
 ```
 
-`completeOidcLogin` refuses before any network call, with `state_mismatch`,
-for a mismatch, a missing `state`, **and** an empty `expectedState` — that
-last case is checked first and explicitly, because two empty strings compare
-equal.
-
-One callback URL is registered at the provider,
-`https://api.fleetless.dev/api/client/oidc/callback`, the same for every app
-and every provider. It is not your `redirectUri`, which is a page in your app.
+`battery_percentage` is a slug you chose in the console, not a ROS topic.
+Rename the node on the robot and your app never notices. Rename the slug and
+it does.
 
-### The MCP consent screen
+The SDK runs wherever `fetch` and `WebSocket` exist: browsers, webviews,
+Node 22 and newer, or server-side with a server key instead of a user session.
+Node 20 does REST fine but ships no global `WebSocket`, so realtime there needs
+one passed in through the `WebSocket` option.
 
-Only if the app serves its own MCP endpoint. An authorization redirects the
-browser to a page your app serves, with an interaction id; your page signs the
-person in, shows them what is being asked, and answers.
-
-```ts
-// Sign the person in FIRST — `already_granted` is derived from the bearer,
-// and an anonymous read answers `false` for everybody.
-const interaction = await client.auth.mcpInteraction(interactionId)
-
-// `interaction.client_name` is a name the client typed about itself during an
-// unauthenticated registration. `client_name_verified` is the literal false;
-// render it as a claim, never as an identity. `scopes` is always empty: what a
-// session reaches is decided by the user's role, re-read on every call.
-const { redirectTo } = approved
-  ? await client.auth.approveMcpInteraction(interactionId)
-  : await client.auth.denyMcpInteraction(interactionId)
-window.location.assign(redirectTo) // a denial redirects too
-
-// A "connected apps" screen. Withdrawing stops the NEXT authorization; a
-// session already running keeps working for the rest of its 15 minutes.
-const grants = await client.auth.listMcpGrants()
-await client.auth.revokeMcpGrant(grants[0].client_id)
-```
-
-### Actions
-
-An action is a job with a lifecycle. `invoke` resolves as soon as the job
-exists; feedback, progress and the result arrive over `subscribe`.
-
-```ts
-const job = await client.actions.invoke(robotId, 'dock', { 'target_pose.position.x': 1.0 })
-
-const sub = client.actions.subscribe(robotId, 'dock', {
-  onJob(event) {
-    console.log(event.job.state, event.feedback, event.progress)
-    if (event.job.state === 'succeeded') console.log(event.job.result)
-  },
-  onError(error) {
-    console.error(error.code, error.message)
-  },
-})
-
-// Cancel the job you started, specifically — not whatever runs there by now.
-const cancelled = await client.actions.cancel(robotId, 'dock', job.id)
-sub.unsubscribe()
-```
+## 📚 Documentation
 
-`params` is flat, keyed by the parameter names the developer declared. A second
-`invoke` while one is still running is refused `busy`, with the running job on
-`error.details.running`. A service is the same machinery with a plain result:
-`await client.services.call(robotId, 'set_mode', { mode: 'autonomous' })`.
+Everything past this point lives at **[docs.fleetless.dev](https://docs.fleetless.dev)**.
 
-### Publishers, and no teleop helpers
-
-`publishers.publish` sends **one** message. There is no `startPublishing`, no
-rate helper, no joystick binding and no "hold this value" call, and that is a
-decision rather than a gap.
-
-The safety primitive lives on the robot. A publisher is configured with a
-`timeout_ms` and a failsafe message; if messages stop arriving — including
-because your process crashed, your tab closed, or the network went away — the
-bridge publishes the failsafe itself. Nothing in your event loop has to survive
-for that to happen.
-
-A helper here would move the appearance of that guarantee into a browser, where
-it is not true. So *how often* and *when* to publish is your application's
-decision, made where it can see the user's intent:
-
-```ts
-// A control loop is yours to write, and yours to stop. `speed` is your app's.
-const timer = setInterval(() => {
-  void client.publishers.publish(robotId, 'cmd_vel', { 'linear.x': speed })
-}, 100)
-
-// Stop publishing and let the robot's own failsafe take over.
-clearInterval(timer)
-```
-
-`publish` rejects `publisher_busy` while a different user holds the publisher
-and has not been quiet for its configured timeout.
-
-### Cameras
-
-```ts
-import { Room } from 'livekit-client' // your choice of LiveKit client
-
-// The snapshot is always there, independent of anyone watching live.
-const snap = await client.cameras.snapshot(robotId, 'camera_front')
-if (snap.image !== null) console.log(snap.mime, `${snap.age_ms}ms old`)
-
-// Live is on demand, and it costs you a release.
-const room = new Room()
-const session = await client.cameras.live(robotId, 'camera_front')
-await room.connect(session.url, session.token)
-
-// When you are done watching — both calls, together. Disconnecting the Room is
-// what actually stops the stream; release() is the courteous fast path.
-await room.disconnect()
-await session.release()
-```
-
-## Errors
-
-Every refusal arrives as a `FleetlessError` with a stable `code`. Branch on the
-code; never parse the message, which is written for a developer reading a
-console and may change.
-
-`error.details` is typed `unknown`, deliberately: it is whatever the server
-sent, and the SDK does not pretend to have validated it. Narrow it before you
-read a field. `BusyDetails` and `RateLimitDetails` are exported as types, and
-`parameterInvalidDetails` as a runtime schema you can `parse`.
-
-```ts checked
-import { createClient, FleetlessError } from '@fleetless/sdk'
-import type { BusyDetails, RateLimitDetails } from '@fleetless/sdk'
-
-declare function showRunning(job: BusyDetails['running'] | undefined): void
-declare function showOffline(): void
-declare function showNotAllowed(): void
-declare function showRetryLater(ms: number | undefined): void
-declare function showUnexpected(error: FleetlessError): void
-
-const client = createClient({ apiUrl: 'https://api.fleetless.dev', appIdentifier: 'warehouse_dash' })
-const robotId = '4f2c1a90-7b3e-4d51-9c86-0a1b2c3d4e5f'
-
-/** `details` is server-shaped: check the field is there before reading it. */
-const field = <T,>(details: unknown, key: string): T | undefined =>
-  typeof details === 'object' && details !== null && key in details
-    ? ((details as Record<string, unknown>)[key] as T)
-    : undefined
-
-try {
-  await client.actions.invoke(robotId, 'dock', {})
-} catch (error) {
-  if (!(error instanceof FleetlessError)) throw error
-  switch (error.code) {
-    case 'busy':          showRunning(field<BusyDetails['running']>(error.details, 'running')); break
-    case 'robot_offline': showOffline(); break
-    case 'forbidden':     showNotAllowed(); break
-    case 'rate_limited':  showRetryLater(field<RateLimitDetails['retry_after_ms']>(error.details, 'retry_after_ms')); break
-    default:              showUnexpected(error); break
-  }
-}
-```
-
-- **`rate_limited` is surfaced, never retried behind your back.** The SDK does
-  not sleep and re-send. `details.retry_after_ms` carries the wait the platform
-  asked for, when it sent one — read it defensively, since a refusal from an
-  intermediary may carry no `details` at all.
-- **The one retry the SDK does perform is `token_expired`**, and only once: it
-  refreshes the session and re-sends the same request. That refresh is
-  single-flight, so ten concurrent calls meeting an expired token share one.
-- **`command_outcome_unknown` is an honest answer, not a failure.** It means
-  the realtime connection cycled while a command was in flight and the SDK
-  cannot say whether the robot got it. Read the job back by slug through
-  `actions.subscribe` to find out.
-- Some codes never reach the network at all — `invalid_option`,
-  `state_mismatch`, `no_session`, `untrusted_absolute_url`. They are the SDK
-  refusing to send something rather than the platform refusing to accept it.
-
-## Documentation and help
-
-- **[SDK reference](https://docs.fleetless.dev/reference/sdk/)** — every method,
-  every option, and what each one deliberately does not do.
+- **[SDK reference](https://docs.fleetless.dev/reference/sdk/)** — every
+  method, every option, and what each one deliberately does not do.
 - **[Getting started](https://docs.fleetless.dev/getting-started/)** — from a
   robot that has never connected to a value in your app.
-- **[REST and realtime API](https://docs.fleetless.dev/reference/api/)** — the
-  wire surface underneath this package.
 - **[Your own login UI](https://docs.fleetless.dev/recipes/app-auth/)** — the
-  full walkthrough for every auth screen, and the mistakes that cost the most
-  time.
+  walkthrough for every sign-in screen.
 - **[Identity](https://docs.fleetless.dev/reference/identity/)** — the two
-  identity spaces, the federation rules, and what each refusal licenses your
-  UI to claim.
+  identity spaces, and what a refusal licenses your UI to claim.
+- **[REST and realtime API](https://docs.fleetless.dev/reference/api/)** —
+  the wire underneath this package.
 - **[CHANGELOG.md](CHANGELOG.md)** — what changed in each version.
-- Questions, bug reports and feature requests: hello@fleetless.dev.
 
-Fleetless is in closed beta. The waiting list is at
-<https://fleetless.dev/#waiting-list>.
+Questions, bug reports and feature requests: hello@fleetless.dev.
 
-## Reporting a security issue
+## 🔒 Reporting a security issue
 
-Email **security@fleetless.dev**. Please do not open a public issue for a
-security report. [SECURITY.md](SECURITY.md) says what is in scope here — how
-this package handles tokens, the PKCE verifier and the `state` value — and what
-belongs to the platform instead.
+Email **security@fleetless.dev** rather than opening a public issue.
+[SECURITY.md](SECURITY.md) says what is in scope for this package — tokens,
+the PKCE verifier, the `state` value — and what belongs to the platform.
 
-## Contributing
+## 🤝 Contributing
 
 The public repository is not open yet. Until it is, send patches and questions
-to <hello@fleetless.dev>. Read
-[CONTRIBUTING.md](CONTRIBUTING.md) first: it covers the setup, the checks, the
-Contributor Licence Agreement, and the one rule this repository is strict about
-— the auth suites drive the SDK's own `fetch` against a real `node:http`
-server rather than a double, because a mocked `fetch` cannot see the bugs that
-have actually shipped.
+to <hello@fleetless.dev>, after reading [CONTRIBUTING.md](CONTRIBUTING.md) for
+the setup, the checks and the Contributor Licence Agreement.
 
 By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
 
-## Maintainers
-
-Maintained by [Dehne Robotik GmbH](https://dehne-robotik.de).
+## 📜 Licence
 
-MIT licensed — see [LICENSE](LICENSE).
+MIT — see [LICENSE](LICENSE). Maintained by
+[Dehne Robotik GmbH](https://dehne-robotik.de).

package/SECURITY.md

@@ -18,7 +18,7 @@ released fix, we credit you by name unless you ask us not to.
 
 This repository is the TypeScript SDK that client applications use to talk to
 Fleetless. It runs **in your users' browsers and on your servers**, and it
-holds credentials while it does. That is where its security surface is.
+holds credentials while it does. That is its security surface.
 
 Specifically in scope:
 
@@ -39,14 +39,14 @@ them in memory only and writes them nowhere. A report is in scope if the SDK:
 - races its own silent refresh in a way that lets a stale or a foreign token
   be used.
 
-Choosing to persist tokens in `localStorage`, a cookie or a native keystore is
-your decision and its consequences are yours; a defect in how the SDK *hands*
-them to your store is ours.
+Where you persist tokens — `localStorage`, a cookie, a native keystore — is
+your decision and your risk. A defect in how the SDK *hands* them to your
+store is ours.
 
 ### PKCE and `state` in the federated sign-in flow
 
-`beginOidcLogin` generates a PKCE verifier and a `state` value and returns them
-to you, because a redirect is a fresh page load and the SDK has nowhere of its
+`beginOidcLogin` generates a PKCE verifier and a `state` value and hands them
+back to you: a redirect is a fresh page load, and the SDK has nowhere of its
 own to keep them. `completeOidcLogin` checks `state` before it exchanges
 anything.
 
@@ -58,7 +58,7 @@ equal; any path that reaches the token exchange without the check.
 
 **Where you store the verifier and the `state` between the two calls is your
 application's decision**, and this policy cannot cover it. The README shows
-`sessionStorage`, which is a reasonable default and not the only correct one.
+`sessionStorage`, a reasonable default and not the only correct one.
 
 ### The rest of the package
 
@@ -79,10 +79,10 @@ application's decision**, and this policy cannot cover it. The README shows
 **The Fleetless cloud is not in this repository.** A server that fails to
 enforce a permission, an authentication or authorisation flaw in the platform,
 a rate limit, a data leak from an API endpoint, anything about how a token is
-minted or validated — none of those live here, and none of them can be fixed by
-a change to this package. Report them to the same address; say which service
-you were looking at, and we will route it. What we cannot do is treat this
-repository's issue tracker as the place where they are tracked.
+minted or validated — none of that lives here, and none of it can be fixed by
+a change to this package. Report it to the same address, say which service you
+were looking at, and we will route it. We will not treat this repository's
+issue tracker as the place where it is tracked.
 
 Also out of scope here: the Fleetless console, the robot-side bridge, the
 `@fleetless/contracts` schemas (they have their own repository and their own