@fleetless/sdk 3.0.2 → 3.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fleetless/sdk",
-  "version": "3.0.2",
-  "description": "The official TypeScript SDK for Fleetless client apps \u2014 a ROS 2 robot as a REST and realtime API, cameras, jobs, and the app's own user accounts, federated sign-in and MCP consent.",
+  "version": "3.1.0",
+  "description": "The official TypeScript SDK for Fleetless client apps — a ROS 2 robot as a REST and realtime API, cameras, jobs, and the app's own user accounts, federated sign-in and MCP consent.",
   "license": "MIT",
   "author": {
     "name": "Dehne Robotik GmbH",
@@ -9,6 +9,10 @@
     "url": "https://dehne-robotik.de"
   },
   "homepage": "https://docs.fleetless.dev/reference/sdk/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fleetless/sdk"
+  },
   "bugs": {
     "email": "hello@fleetless.dev"
   },
@@ -51,8 +55,7 @@
     "CHANGELOG.md",
     "SECURITY.md",
     "CONTRIBUTING.md",
-    "CODE_OF_CONDUCT.md",
-    "RELEASING.md"
+    "CODE_OF_CONDUCT.md"
   ],
   "engines": {
     "node": ">=20"
@@ -61,6 +64,7 @@
   "scripts": {
     "build": "tsup && node scripts/stamp-dist.mjs",
     "prepare": "tsup && node scripts/stamp-dist.mjs",
+    "prepublishOnly": "node scripts/refuse-manual-publish.mjs",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:pack": "node scripts/verify-published-types.mjs",
@@ -72,7 +76,7 @@
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@fleetless/contracts": "1.0.5",
+    "@fleetless/contracts": "1.1.0",
     "@types/node": "^22.20.1",
     "tsup": "^8.3.0",
     "typedoc": "0.28.20",

package/RELEASING.md

@@ -1,195 +0,0 @@
-# Releasing `@fleetless/sdk`
-
-Maintainer notes: the development setup, the checks, and the release
-procedure. This file is not part of the published package.
-
-**CI runs on GitLab; the repository will mirror to GitHub.** The pipeline
-that verifies and publishes this package lives on an internal GitLab instance,
-and that is the only thing that publishes to npm. The public repository does not
-exist yet; when it does it is a mirror, where issues and pull requests arrive
-and no check runs. A contributor's pull request is verified by a maintainer
-running the same commands locally — see
-[CONTRIBUTING.md](CONTRIBUTING.md), which says so to the contributor as well.
-
-A mirror pushes what it is given, so **everything in a commit becomes public
-the moment it is pushed**, including the commit message and every file the
-branch touched.
-## Development setup
-
-Node 22 via `nvm`, and pnpm through corepack:
-
-```sh
-nvm use 22
-corepack enable
-pnpm install
-```
-
-**That install needs nothing private.** `@fleetless/contracts` — the source
-of truth for every wire type this SDK reads or writes — is a devDependency on
-the public npm package, pinned to an exact version. It used to be a private
-`git+ssh://` URL that only somebody with GitLab group access could install;
-that is over. The published SDK is unaffected either way: `tsup` inlines
-contracts' types into `dist/`, so a consumer of `@fleetless/sdk` never
-resolves it.
-
-Never redefine a shape the SDK sends to or reads from the API. Import it from
-`@fleetless/contracts` instead.
-
-## Checks
-
-| Command | What it does |
-|---|---|
-| `pnpm typecheck` | `tsc --noEmit` over the package. |
-| `pnpm test` | vitest. Most suites drive a fake `fetch` and a fake WebSocket; the three auth suites drive the SDK's own default `fetch` against a real `node:http` server (`test/local-api.ts`). No cloud needed. |
-| `pnpm build` | tsup into `dist/` — ESM, CJS and `.d.ts`. |
-| `pnpm run test:pack` | `npm pack`s the tarball, installs it into a bare project with nothing but `typescript`, and typechecks and runs real usage against it. This is what catches a `dist/index.d.ts` that still imports from `@fleetless/contracts` — a devDependency, so a consumer of the SDK never installs it. |
-
-Two further scripts check the built package against a **running** cloud
-(`./infra/dev.sh` in the umbrella repo). Each one runs against `dist/`, not
-`src/`, so run `pnpm build` first, and each fails by name on a missing
-variable rather than defaulting quietly.
-
-- `pnpm run verify:live` — a `busy` refusal carrying the job that is already
-  running, `command_outcome_unknown` and its documented recovery, a
-  `parameter_invalid` naming the flat key, job-id-addressed cancel, and
-  per-session camera release. Needs `FLEETLESS_API_URL` (or `API`),
-  `APP_IDENTIFIER`, `EMAIL`, `PASSWORD`, `ROBOT_ID`, `ACTION_SLUG`,
-  `SERVICE_SLUG`, `CAMERA_SLUG`, and two optional identities:
-  - `SECOND_EMAIL` — a second, distinct **app user** with the same role,
-    without which the busy check only proves that a second request is refused,
-    not that a different user's is.
-  - `OBSERVER_EMAIL` — a **third** app user, and the one whose password check
-    [6] rotates and restores. Leave it unset and the round trip runs on
-    `EMAIL`, the identity every other check in the file signs in as; the
-    script says so out loud when that happens. `infra/seed-dev.mjs --env`
-    exports all three.
-
-  Since 3.0.0 it also drives the client auth API as check [6]: `listProviders`
-  without a session, `login`, `me` (kind, app, role, address), `logout`, the
-  `changePassword` round trip with its restore, and the reset acknowledgement
-  compared byte for byte across a known and an unknown address. What it does
-  **not** drive is anything needing a mailed token — `register`,
-  `verifyEmail`, `acceptInvitation`, `confirmPasswordReset` — or the federated
-  and MCP-consent flows. Those are `infra/browser/app-auth-check.mjs`'s
-  subject, which reads maildev and drives a real Keycloak.
-- `pnpm run verify:history` — a relative range and its absolute equivalent
-  returning the same samples, aggregation matching arithmetic done here from
-  the raw rows, and the `not_recorded` / `not_aggregatable` refusals. Needs
-  `FLEETLESS_API_URL`, `APP_IDENTIFIER`, `EMAIL`, `PASSWORD`, `ROBOT_ID`,
-  `RECORDED_NUMERIC_SLUG`, `LIVE_ONLY_SLUG`, and optionally
-  `NON_NUMERIC_RECORDED_SLUG`.
-(`verify:hosted-login` is gone. The hosted login flow it drove —
-`beginHostedLogin` / `completeHostedLogin` and the app OAuth client behind
-them — was removed in 3.0.0 along with the script and its `package.json`
-entry.)
-
-`infra/seed-dev.mjs --env` in the umbrella repo exports most of those
-variables for a freshly seeded world.
-
-## Commits
-
-[Conventional Commits](https://www.conventionalcommits.org/). English, for
-code, comments, commit messages and everything else that lands in the
-repository.
-
-## Releasing
-
-Every version on npm is published by this repository's GitLab pipeline from a
-release tag. `npm publish` by hand is retired.
-
-1. Add the version's entry to `CHANGELOG.md` and set `version` in
-   `package.json` to the same number.
-2. Commit (`chore(release): X.Y.Z`), push, and wait for the branch pipeline's
-   `verify` job to go green.
-3. `git tag vX.Y.Z && git push origin vX.Y.Z`. The tag pipeline runs `verify`
-   again and then `publish`.
-4. Check the registry yourself. The `publish` job already asserts the first
-   line; this is the independent look, and the second line is the one that
-   says which dist-tag moved.
-
-   ```sh
-   npm view @fleetless/sdk@X.Y.Z version   # answers X.Y.Z
-   npm view @fleetless/sdk dist-tags       # latest -> X.Y.Z, or next -> X.Y.Z
-   ```
-
-   Name the version. A bare `npm view @fleetless/sdk version` resolves the
-   `latest` dist-tag, so after a pre-release publish it answers the *previous*
-   stable release and reads as a publish that did not happen.
-
-A pre-release tag — `vX.Y.Z-beta.1`, `vX.Y.Z-rc.2` — publishes under the npm
-dist-tag `next` instead of `latest`. Nothing else about it differs, and it is
-exactly why step 4 names the version.
-
-**A red `publish` job does not mean nothing was published.** The job runs
-`npm publish` and then looks the version up on the registry for about two
-minutes; npm answers reads from a replica that lags a publish, so the lookup
-can time out on a version that did land. The job says so itself, and it is
-worth repeating here because a red pipeline invites exactly one reaction —
-press retry — and that reaction cannot work: npm refuses to publish over an
-existing version, so the retry ends in a 403 that reads like a broken
-pipeline rather than like a release that already happened.
-
-> publish may have succeeded; the registry has not served the version yet; do
-> NOT retry this job (npm refuses to republish a version) — check
-> `npm view @fleetless/sdk@$VERSION` by hand
-
-If the hand check answers the version, the release is done: move the dist-tag
-by hand if it is wrong (`npm dist-tag add @fleetless/sdk@X.Y.Z latest`) and
-leave the job red. If it answers nothing after several minutes, the publish
-genuinely did not land and the job can be retried.
-
-**A red `publish` job that ends in `npm error code EOTP` published nothing.**
-npm is asking for a one-time password, which a pipeline cannot supply: the
-token in `NPM_TOKEN` does not bypass two-factor authentication, or the
-package's *Publishing access* setting on npmjs.com disallows tokens. Fix the
-token (a granular access token created with *Bypass two-factor
-authentication*) or the package setting (*Require two-factor authentication
-or an automation token*), then retry the job — nothing reached the registry,
-so a retry is safe here — measured on a pipeline that hit it.
-
-**The pipeline refuses a tag whose version disagrees with `package.json`.**
-`scripts/verify-version-tag.mjs` is the one place that rule lives; `verify`
-runs it first on a tag pipeline, so a mistyped tag fails in seconds and
-`publish` never starts (measured: `verify-version-tag: tag v9.9.9 names
-9.9.9 but package.json says 1.0.0`, publish skipped).
-
-Removing that bad tag takes the API, not git. `v*` is a **protected** tag
-pattern, so a delete over git is refused by the server with nothing but
-`! [remote rejected] v9.9.9 (pre-receive hook declined)`:
-
-```sh
-git tag -d vX.Y.Z                                          # local
-glab api -X DELETE projects/37/repository/tags/vX.Y.Z      # remote
-```
-
-Then fix `package.json` and tag again.
-
-### The one-time setting
-
-It is already in place; it is written down because nothing in this repository
-would tell you it exists if it were removed.
-
-There used to be a second one — `fleetless/fleetless-sdk` on the job-token
-allow-list of `fleetless/fleetless-contracts`, so the pipeline could rewrite
-the private `git+ssh://` contracts URL to HTTPS with `CI_JOB_TOKEN`. Contracts
-is a public npm package now, the rewrite is gone from `.gitlab-ci.yml`, and
-the allow-list entry buys this project nothing. Removing it is safe; leaving
-it is harmless.
-
-- **`NPM_TOKEN` is a protected, masked CI variable on this project**, holding
-  an npm granular automation token with publish rights on `@fleetless/sdk`.
-  Protected means an unprotected ref receives an *empty* value rather than no
-  value, which is why the tag pattern `v*` is a protected tag and why the
-  `publish` job's first action is to refuse an empty `NPM_TOKEN` by name.
-
-  ```sh
-  glab api projects/37/protected_tags     # v*, create access: Maintainers
-  ```
-
-The token reaches npm through an `.npmrc` written in the job's working
-directory holding `//registry.npmjs.org/:_authToken=${NPM_TOKEN}` **literally**
-— npm expands the variable when it reads the file, so the secret itself never
-lands on disk, and `after_script` removes the file either way. It cannot be
-passed as an environment assignment instead: `NPM_CONFIG_//registry…` is not a
-valid shell identifier, so both `bash` and `dash` parse it as a command name.
-