@fleetless/sdk 2.0.2 → 3.0.0

package/CHANGELOG.md

@@ -4,6 +4,114 @@ All notable changes to `@fleetless/sdk`. The format follows Keep a Changelog; th
 
 ## [Unreleased]
 
+## [3.0.0] — 2026-09-06
+
+Fleetless shows an app user **no page**. The developer's own UI owns every
+screen — login, registration, verification, invitation acceptance, password
+reset, the provider buttons, the MCP consent — and this release replaces the
+SDK's auth surface with the JSON API those screens call. The hosted,
+app-branded login and consent pages are gone from the platform, so they are
+gone from here.
+
+### Removed
+
+- **`auth.beginHostedLogin` and `auth.completeHostedLogin`**, with
+  `BeginHostedLoginOptions`, `HostedLoginRequest` and
+  `CompleteHostedLoginOptions`. The `/oauth/authorize` + `/oauth/token` flow
+  they drove no longer runs for app users. Use `auth.beginOidcLogin` and
+  `auth.completeOidcLogin` for federated sign-in, or `auth.login` for a
+  password.
+- **`client.grants`** (`GrantsApi`, `grants.list`, `grants.revoke`), with the
+  `ConsentGrantSummary` and `ConsentRevokeResponse` re-exports. The routes
+  behind it are gone. The MCP consents an app user can withdraw are now
+  `auth.listMcpGrants()` and `auth.revokeMcpGrant(clientId)`.
+- **`auth.passwordResetUrl()`**. It pointed at a Fleetless-served page that is
+  now the developer console's own, for Fleetless users rather than app users.
+  An app user's reset is `auth.requestPasswordReset` and
+  `auth.confirmPasswordReset`, in your own UI.
+- **`LogoutResult`**, and with it everything `logout()` used to report about
+  the identity provider behind a session. That apparatus belonged to the
+  hosted login, where Fleetless owned the browser; an app that wants to end a
+  provider session redirects there itself, knowing its own provider.
+- **`no_hosted_login_attempt`** from `SDK_ERROR_CODES`. The case it named —
+  nothing persisted for this attempt — still throws, as `state_mismatch`, and
+  the message still says which of the two happened.
+- `HttpClient.requestOAuth`, the SDK's only form-urlencoded call. Nothing
+  reaches `/oauth/token` from here any more.
+
+### Added
+
+- **Registration and verification**: `auth.register({ email, password,
+  displayName? })`, `auth.verifyEmail(token)`,
+  `auth.resendVerification(email)`.
+- **Recovery and invitations**: `auth.requestPasswordReset(email)`,
+  `auth.confirmPasswordReset(token, newPassword)`,
+  `auth.acceptInvitation({ token, password, displayName? })`. Every one of
+  these that spends a mailed token stores the session it answers with, so a
+  person is not asked to sign in again immediately after proving they can read
+  the mail.
+- **Federated sign-in, per app**: `auth.listProviders()` for the buttons,
+  `auth.beginOidcLogin({ slug, redirectUri })` to build the start URL with
+  PKCE, `auth.completeOidcLogin({ code, state, expectedState, codeVerifier })`
+  to trade the one-time code for a session, and
+  `auth.oidcErrorFromCallback(params)` to read a failed sign-in off the
+  redirect back as a `FleetlessError`. The SDK builds the URL and **never
+  navigates**; the app does.
+- **The MCP consent screen**: `auth.mcpInteraction(id)`,
+  `auth.approveMcpInteraction(id)`, `auth.denyMcpInteraction(id)`. Both
+  decisions answer where to send the browser, a denial included.
+- **The app user's own standing consents**: `auth.listMcpGrants()` and
+  `auth.revokeMcpGrant(clientId)`.
+- New option and result types: `RegisterOptions`, `AcceptInvitationOptions`,
+  `ProviderButton`, `BeginOidcLoginOptions`, `OidcLoginRequest`,
+  `CompleteOidcLoginOptions`, `McpInteractionDecision`. New wire re-exports:
+  `ClientMcpInteraction`, `McpConsentGrant`, `ClientOidcErrorCode`.
+
+### Changed
+
+- **`ClientIdentity` renamed two fields**: `kind: 'end_user'` is now
+  `'app_user'`, and `end_user_id` is now `app_user_id`. A rename rather than a
+  kept key, deliberately — the old subject was a member of the org's one pool,
+  the new one is a row belonging to exactly one app, and a consumer reading
+  `.end_user_id` would have typechecked while meaning something subtly
+  different.
+- **`logout()` resolves with `void`**, not a `LogoutResult`. It still never
+  rejects and still always clears the local store.
+- **A `serverKey` client refuses session methods with a `FleetlessError` whose
+  code is `invalid_option`**, where it used to throw a bare `Error` a caller
+  could only catch by message. `me()`, `listProviders()`, `mcpInteraction()`
+  and `oidcErrorFromCallback()` still work on one: the first is what a server
+  key is for, the next two are reads the cloud answers without a credential,
+  and the last touches no network.
+- `state_mismatch` is now thrown by `completeOidcLogin`, before any request.
+- Pinned to `@fleetless/contracts` `48acd56`.
+
+### Verification
+
+- The `auth` and OIDC suites now drive the SDK's **default** `fetch` against a
+  real `node:http` server (`test/local-api.ts`) rather than a `vi.fn()`. Every
+  assertion about a path, a method, a header or a body is made against bytes
+  that actually left the process — which is what shows, for instance, that the
+  two MCP decisions send no `content-type` on their bodyless `POST`, a header
+  a fake `fetch` records as absent exactly as convincingly when it is wrong.
+
+## [2.1.0] — 2026-09-04
+
+### Added
+
+- `InvokeOptions` is exported — the type of `actions.invoke`'s options
+  argument, which a caller constructs and could not name.
+
+### Changed
+
+- Every exported member carries a doc comment; the generated SDK reference
+  on docs.fleetless.dev is rendered from them.
+- `InMemoryTokenStore` declares an explicit empty `constructor()`. It exists
+  only to carry a doc comment: TypeDoc reflects a synthesized constructor
+  for a class without one, and an undocumented member is what the reference
+  is built to have none of. Behaviour is unchanged — the class had an
+  implicit no-argument constructor before and has an explicit one now.
+
 ## [2.0.2] — 2026-09-04
 
 No code change; the published `dist/` is byte-identical to 2.0.0.

package/README.md

@@ -9,8 +9,8 @@ The official TypeScript SDK for apps built on [Fleetless](https://fleetless.dev)
 which exposes a ROS 2 robot as a hosted REST and realtime API — exactly the
 topics, services and actions a developer chose to publish, under stable slugs,
 behind roles. The SDK covers all of it: datapoints (read, subscribe, recorded
-history), actions, services, publishers, cameras, jobs, assets and URDF, the
-hosted login, and an end user's own consent grants. It is framework-agnostic,
+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 20 or newer, and
 server-side with a server key instead of a user session.
@@ -40,11 +40,13 @@ server-side with a server key instead of a user session.
   `cameras.live` takes a refcounted hold: the first viewer starts the robot
   publishing, the last one leaving stops it. You get a LiveKit room URL and
   token to hand to the LiveKit client of your choice.
-- **Hosted login, so your app never handles a password.** OAuth 2.1
-  Authorization Code with PKCE (S256 only). `beginHostedLogin` makes no network
-  call at all, and `completeHostedLogin` checks `state` before it exchanges
-  anything. Federation to a customer's identity provider happens on the hosted
-  page, not in your code.
+- **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
@@ -56,8 +58,10 @@ server-side with a server key instead of a user session.
 npm i @fleetless/sdk
 ```
 
-You need an app identifier and an end user's credentials from the
-[Fleetless Console](https://console.fleetless.dev).
+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.
 
 ```ts checked
 import { createClient } from '@fleetless/sdk'
@@ -98,44 +102,106 @@ 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.
 
-### Hosted login
+### Your own sign-in UI
 
-Redirect the end user to the Fleetless-hosted login page instead of collecting
-a password yourself. Register the OAuth client in the console first, under
-**App Settings → OAuth clients**; its `client_id` is not your `appIdentifier`.
+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
-// 1. Build the URL. No network call happens here.
-const request = await client.auth.beginHostedLogin({
-  clientId: 'oauth-client-id-from-the-console',
+// 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',
 })
-
-// A redirect is a fresh page load, so persist these two yourself.
 sessionStorage.setItem('fleetless_state', request.state)
 sessionStorage.setItem('fleetless_code_verifier', request.codeVerifier)
-window.location.href = request.url
-
-// 2. On the callback page. The callback can legitimately carry ?error=...
-//    instead of a code, so check for that first.
-const params = new URLSearchParams(window.location.search)
-const expectedState = sessionStorage.getItem('fleetless_state')
-const codeVerifier = sessionStorage.getItem('fleetless_code_verifier')
-
-if (!params.has('error') && expectedState && codeVerifier) {
-  await client.auth.completeHostedLogin({
+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,
-    codeVerifier,
-    clientId: 'oauth-client-id-from-the-console',
-    redirectUri: 'https://your-app.example.com/callback',
+    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(). Never call completeHostedLogin twice for the same code.
+  // 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.
+
+### The MCP consent screen
+
+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)
+```
+
 ### Running a job
 
 An action is a job with a lifecycle. `invoke` resolves as soon as the job
@@ -184,30 +250,6 @@ await room.disconnect()
 await session.release()
 ```
 
-## Migrating from 1.0.0
-
-2.0.0 is a breaking release. `CHANGELOG.md` carries the complete inventory —
-established by diffing the published 1.0.0 tarball's types against this one's,
-not read off the commit log. The breaks, one line each:
-
-- `auth.register()` and `auth.confirmRegistration()` are gone with no
-  successor; a group grows by invitation (see [Account recovery](https://docs.fleetless.dev/reference/sdk/#account-recovery) in the SDK reference).
-- `auth.requestPasswordReset()` and `auth.confirmPasswordReset()` are gone.
-  Link the user to `auth.passwordResetUrl()` instead.
-- The types `MailStatus` and `ClientRegisterResponse` went with them.
-- The error code `not_a_member` is gone — a compile break for an exhaustive
-  `switch` on `error.code`.
-- `CameraDescriptor.snapshot_interval_ms` is now `snapshot_interval_seconds`.
-  **Read that twice:** it is a rename *and* a unit change, so renaming the
-  property and nothing else leaves you with a number a thousand times too
-  small.
-- `UrdfCompleteness.missing` and `UrdfSceneResources.missing` are no longer
-  `string[]` but `{ uri, element }[]`, so a missing texture is no longer
-  reported as a missing mesh. For the old shape: `missing.map((m) => m.uri)`.
-
-Nothing else was removed or re-typed. `auth.logout()`'s result grew a field and
-gained a name (`LogoutResult`); `.revoked` is unchanged.
-
 ## Documentation and help
 
 - **[SDK reference](https://docs.fleetless.dev/reference/sdk/)** — every method,
@@ -216,8 +258,12 @@ gained a name (`LogoutResult`); `.revoked` is unchanged.
   robot that has never connected to a value in your app.
 - **[REST and realtime API](https://docs.fleetless.dev/reference/api/)** — the
   wire surface underneath this package.
-- **[Hosted login recipe](https://docs.fleetless.dev/recipes/hosted-login/)** —
-  the full walkthrough, including every error the callback can carry.
+- **[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.
+- **[Identity](https://docs.fleetless.dev/reference/identity/)** — the two
+  identity spaces, the federation rules, and what each refusal licenses your
+  UI to claim.
 - **[CHANGELOG.md](CHANGELOG.md)** — what changed in each version.
 - Questions, bug reports and feature requests: hello@fleetless.dev.