@fleetless/sdk 3.0.2 → 3.1.0

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to `@fleetless/sdk`. The format follows Keep a Changelog; th
 
 ## [Unreleased]
 
+## [3.1.0] — 2026-09-17
+
+### Added
+
+- **`client.robots`** — `list()` answers the robots the caller reaches, with bridge state and published version; `describe(robotId)` answers the datasheet: every granted datapoint, action, service, publisher and camera with unit, decimals and parameter JSON Schema, plus the `action_history` and `assets` capabilities. The same rows and the same sheet the MCP tools `robots_list` and `robot_describe` answer, from the same server code. Needs a cloud that serves contracts 1.1.0.
+- **`client.jobs.history(robotId, options?)`** — the run history the reference described since 3.0.0 and the package never shipped. Filters `slug`, `state`, `kind`, `limit`, `beforeSeq`, `fromMs`, `toMs`; page until `next_cursor` is `null`.
+
+### Changed
+
+- Re-pinned to `@fleetless/contracts` 1.1.0. `ClientRobotListItem`, `McpRobotDatasheet`, `McpExposure`, `McpCapabilities`, `JobRun` and `JobRunListResponse` are re-exported.
+
+## [3.0.3] — 2026-09-16
+
+- Published from GitHub Actions by npm trusted publishing: no publish token exists anywhere, and every version from this one on carries a provenance attestation linking it to the commit and the run that built it. `npm audit signatures` checks it.
+
+- **The README is a lobby now, not the reference.** What Fleetless is, what this package does, one snippet, and links into docs.fleetless.dev; the seven walkthroughs it carried are the SDK reference's job. The four doc comments and the one runtime error message that sent a developer to a README section point at the SDK reference instead, and the test that resolved those pointers now refuses any new one.
+- `RELEASING.md` no longer ships in the package; the published `CONTRIBUTING.md` points at it without a link.
+- The prose guard treats a path into the company-site repository the way it treats every other sibling repository's path.
+
 ## [3.0.2] — 2026-09-07
 
 No API change, and one documentation example that now compiles. The guard

package/CONTRIBUTING.md

@@ -1,8 +1,8 @@
 # Contributing to `@fleetless/sdk`
 
-This package is the TypeScript client for the Fleetless API. It is what a
-developer's own application calls, so a change here reaches every app built on
-it, and a change to what a method *sends* reaches the platform as well.
+This is the TypeScript client for the Fleetless API — the thing a developer's
+app calls directly. Change a method here and every app built on it feels it;
+change what a method *sends* and the platform feels it too.
 
 ## Setup
 
@@ -14,12 +14,12 @@ corepack enable
 pnpm install
 ```
 
-There are no private dependencies. `pnpm install` works from a clean checkout
-with nothing but a network connection to the npm registry — the wire schemas
-come from `@fleetless/contracts`, which is a public package.
+No private dependencies — `pnpm install` needs nothing but a network
+connection to npm. The wire schemas come from `@fleetless/contracts`, a
+public package.
 
-`pnpm install` runs `prepare`, which builds `dist/`. Some of the checks below
-read the built bundle, so a fresh checkout is ready for them.
+`pnpm install` runs `prepare` and builds `dist/`. Some checks below read the
+built bundle, so a fresh checkout is already ready for them.
 
 ## The checks
 
@@ -32,94 +32,98 @@ read the built bundle, so a fresh checkout is ready for them.
 
 To run one test file, use `pnpm vitest run test/<name>.test.ts`.
 
-## The rule this repository is most serious about: a real server, not a mocked `fetch`
+## 🔌 The rule this repository is most serious about: a real server, not a mocked `fetch`
 
 **The auth suites drive the SDK's own default `fetch` against a real
-`node:http` server** (`test/local-api.ts`), and no `fetch` option is passed to
-`createClient` in them.
+`node:http` server** (`test/local-api.ts`) — no `fetch` option passed to
+`createClient`.
 
-That is not ceremony. A suite that passes its own `fetch` never enters the code
-that actually ships: `client.ts` resolves `globalThis.fetch.bind(globalThis)`,
-and every assertion about "what the SDK sends" becomes an assertion about what
-a `vi.fn()` was asked to pretend to send. The two most expensive defects this
-package has had were both invisible to a mocked `fetch` and both obvious to a
-socket:
+Not ceremony. A suite that supplies its own `fetch` never touches the code
+that ships: `client.ts` resolves `globalThis.fetch.bind(globalThis)`, so "what
+the SDK sends" becomes "what a `vi.fn()` agreed to pretend to send." This
+package's two most expensive defects were both invisible to a mocked `fetch`
+and both obvious to a socket:
 
 - `createClient` defaulted to a **detached** `globalThis.fetch`. A real
-  browser's `fetch` is a Web IDL method that throws "Illegal invocation" unless
-  its receiver is the global object. Node's undici does not enforce that check,
-  so every test passed and every browser failed on the first call.
-- A path segment shaped like `../../../admin` reached a real server as a
-  traversal, because the encoding was asserted against a double that never
-  parsed the URL.
+  browser's `fetch` is a Web IDL method and throws "Illegal invocation"
+  unless the receiver is the global object; Node's undici doesn't check.
+  Every test passed, every browser failed on the first call.
+- `../../../admin` reached a real server as a traversal — the encoding was
+  asserted against a double that never parsed the URL.
 
-So: **if your change is about what leaves the process, test it against
-`test/local-api.ts`.** A double is fine for testing branching, refcounting,
-timers and error mapping, and most of the suite uses one for exactly that.
+**If your change touches what leaves the process, test it against
+`test/local-api.ts`.** A double is fine for branching, refcounting, timers,
+error mapping — most of the suite uses one for exactly that.
 
-`test/client.test.ts` carries a test named for this property on its own, so
-that removing it is visible in a diff rather than silent.
+`test/client.test.ts` names a test for this property on its own, so removing
+it shows up in a diff instead of in production.
 
 ## Licence headers
 
-Every source file carries the SPDX header `// SPDX-License-Identifier: MIT` as
-its first line — a `#!` shebang is the only thing allowed above it.
-`test/license-headers.test.ts` asserts this over the whole set, and it takes
-that set from `git ls-files` rather than from a list of directories, so a file
-added anywhere in the repository is swept the day it exists.
+Every source file's first line is the SPDX header
+`// SPDX-License-Identifier: MIT` — only a `#!` shebang may sit above it.
+`test/license-headers.test.ts` checks the whole set, sourced from
+`git ls-files` rather than a list of directories, so a new file is swept the
+day it's added.
 
-## Nothing internal reaches the published bytes
+## 📦 Nothing internal reaches the published bytes
 
 `tsup` bundles `@fleetless/contracts` **into** `dist/index.js` and
-`dist/index.cjs`, doc comments and all, and it writes the path each inlined
-module came from as a comment beside it. A comment written for the people who
-build this is therefore a comment an editor shows to somebody who installed it —
-and for four published versions that included German paragraphs, internal
-defect ids and an internal hostname, none of which appeared anywhere in this
-repository's source.
+`dist/index.cjs` — doc comments and all — and writes the source path of each
+inlined module as a comment beside it. A comment meant for the people who
+build this is therefore a comment an editor shows to whoever installed it.
+Four published versions did exactly that: German paragraphs, internal defect
+ids, an internal hostname — none of it in this repository's source.
 
-Write a comment as what the code does for a caller. Never as how the behaviour
-was found, on which machine, under which internal ticket, or in which language
-the team happened to be thinking that day.
+Write a comment for what the code does for a caller, not for how the
+behaviour was found, on which machine, under which ticket, or in which
+language the team happened to be thinking that day.
 
-`test/published-prose.test.ts` enforces it over `dist/`, `src/`, `test/`,
-`scripts/` and the shipped markdown, and it will tell you which class of thing
-came back and on which line.
+`test/published-prose.test.ts` checks `dist/`, `src/`, `test/`, `scripts/`
+and the shipped markdown, and names which class of thing came back and on
+which line.
 
 ## Pull requests
 
-**The public repository is not open yet.** It will be, and this section
-describes how it will work then. Until it exists, send patches and questions to
-<hello@fleetless.dev>. Either way, raise anything that changes an existing
-method signature or what a method sends before you write it, so we can say what
-else has to move with it.
-
-**CI runs on GitLab.** This repository is mirrored from an internal GitLab
-instance, which is where the pipeline that verifies and publishes it lives. You
-will not see a check run on your GitHub pull request; a maintainer runs the
-same checks, and the result comes back as a review comment. Run
-`pnpm typecheck && pnpm test && pnpm run test:pack` yourself before you open the
-pull request and you will have seen everything CI would tell you.
+**The public repository is not open yet.** It will be — this section
+describes how it works once it is. Until then, send patches and questions to
+<hello@fleetless.dev>. Either way: raise anything that changes an existing
+method signature or what a method sends *before* you write it, so we can
+tell you what else has to move with it.
+
+**CI runs on GitHub Actions**, in this repository
+(`.github/workflows/verify.yml`) — the suite, on every push and every pull
+request. `release.yml` publishes on a release tag and calls that same file
+first, so a release is never checked by a different pipeline than a push.
+
+**Your pull request is verified, a fork's included** — the same suite, the
+same file. GitHub holds a first-time contributor's first run until a
+maintainer approves it, so the checks can sit idle for a while before they
+start; that is the queue, not a failure. The run reads the code and nothing
+else: it is granted `contents: read`, no secret is available to it, and
+publishing lives in a workflow a pull request cannot trigger. Running
+`pnpm typecheck && pnpm test && pnpm run test:pack` yourself first still
+saves you a round trip — it is everything `verify` will tell you.
 
 ## The CLA
 
-The first pull request you open will ask you to sign a Contributor Licence
-Agreement. It grants Dehne Robotik GmbH the right to license your contribution
-under terms other than MIT in future — that is the whole of what it is for, and
-it is why the project can relicense its own code later without having to find
-every past contributor. It does not take your copyright away and it does not
-stop you from using your own contribution however you like.
+Your first pull request will ask you to sign a Contributor Licence Agreement.
+It grants Dehne Robotik GmbH the right to license your contribution under
+terms other than MIT later — that's the whole point, and why the project can
+relicense without hunting down every past contributor. It doesn't take your
+copyright, and it doesn't stop you from using your own contribution however
+you like.
 
 ## Commit messages
 
 [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/):
-`feat:`, `fix:`, `docs:`, `chore:`, `ci:`, `refactor:`, `test:`. A change that
-alters an existing method's signature or what it sends is a breaking change;
-say so with a `!` and a `BREAKING CHANGE:` footer, because it decides the next
+`feat:`, `fix:`, `docs:`, `chore:`, `ci:`, `refactor:`, `test:`. Changing an
+existing method's signature or what it sends is breaking — mark it with a
+`!` and a `BREAKING CHANGE:` footer, since that's what decides the next
 version number.
 
-Everything in this repository is written in **English** — code, comments,
-commit messages, documentation.
+Everything here is written in **English** — code, comments, commit messages,
+documentation.
 
 ## Code of conduct
 
@@ -127,5 +131,6 @@ By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## Releasing (maintainers)
 
-See [RELEASING.md](RELEASING.md). The pipeline publishes; `npm publish` from a
-working tree is not how a version gets to the registry.
+See RELEASING.md in the repository — it is not part of the published
+package. The `release` workflow publishes; `npm publish` from a working tree
+is not how a version gets to the registry.