@fleetless/sdk 3.0.1 → 3.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/CHANGELOG.md +101 -10
  2. package/CONTRIBUTING.md +76 -70
  3. package/README.md +65 -319
  4. package/SECURITY.md +11 -11
  5. package/dist/index.cjs +44 -45
  6. package/dist/index.d.cts +80 -99
  7. package/dist/index.d.ts +80 -99
  8. package/dist/index.js +44 -45
  9. package/package.json +7 -6
package/CHANGELOG.md CHANGED
@@ -4,6 +4,81 @@ All notable changes to `@fleetless/sdk`. The format follows Keep a Changelog; th
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [3.0.3] — 2026-09-16
8
+
9
+ - 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.
10
+
11
+ - **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.
12
+ - `RELEASING.md` no longer ships in the package; the published `CONTRIBUTING.md` points at it without a link.
13
+ - The prose guard treats a path into the company-site repository the way it treats every other sibling repository's path.
14
+
15
+ ## [3.0.2] — 2026-09-07
16
+
17
+ No API change, and one documentation example that now compiles. The guard
18
+ that was supposed to prove 3.0.1 clean was **green over four internal
19
+ references still inside the published bundle**, so it was rebuilt around the
20
+ question rather than around three directory names.
21
+
22
+ ### Fixed
23
+
24
+ - **Four internal references in the published 3.0.1 bundle**, which the guard
25
+ could not see: an internal decision label in `dist/index.js` and
26
+ `dist/index.cjs`, and a sentence in both about how a defect class had been
27
+ found. Measured against the registry rather than against this tree — 3.0.1
28
+ scores 4, 3.0.2 scores 0, and 3.0.0 scores 423.
29
+ - **The README's error-handling example did not compile.** `details` is
30
+ `unknown` on `FleetlessError`, deliberately, and the block read fields off
31
+ it directly — two `TS2339`s in a TypeScript SDK's own README, in the block a
32
+ reader copies first. It now narrows before reading, and it is opted in to
33
+ the documentation type check so it cannot drift again.
34
+ - **`Node 20 or newer` was listed as a runtime for the whole SDK.** Node 20
35
+ has no global `WebSocket` — it is behind a flag there — so anything realtime
36
+ fails on it with the SDK's own `no_websocket`. The README names Node 22, and
37
+ says what to pass on Node 20 instead.
38
+ - **Everything published pointed at a public repository that does not exist
39
+ yet.** `repository`, `bugs.url`, the README, `CONTRIBUTING.md` and
40
+ `RELEASING.md` all named it, and its four relative links resolved to 404s on
41
+ the npm page. They point at the maintainer address until the repository is
42
+ opened.
43
+ - **`CONTRIBUTING.md` linked `RELEASING.md`, which the tarball did not
44
+ carry.** `RELEASING.md` ships now, and every relative link in every shipped
45
+ document is checked against the tarball's own entries.
46
+ - **Each published file declares exactly one licence.** The bundler inlines
47
+ `@fleetless/contracts`, which is Apache-2.0, and the declaration files
48
+ carried six of its SPDX identifiers below this package's MIT one. A licence
49
+ scan over `node_modules` reported Apache obligations for a package that
50
+ ships no Apache text. The inherited identifiers are stripped at build time.
51
+ - **A CI comment sent whoever was reading a red publish job to a README
52
+ section that does not exist**, and `RELEASING.md` told a maintainer the
53
+ suite runs against a fake `fetch` — which `CONTRIBUTING.md` devotes a
54
+ section to denying, and which is untrue of three of the nineteen suites.
55
+
56
+ ### Changed
57
+
58
+ - **The guard scans what becomes public, computed rather than named.** The
59
+ union of what `npm pack` reports, what `git ls-files` reports and a walk of
60
+ every directory in `files`. Ten tracked files were outside the previous
61
+ shape, two of them published bytes; one of those two had already carried an
62
+ internal host to the registry inside `devDependencies`.
63
+ - **Only the German scan strips anything**, and only URLs and single-token
64
+ code spans. Stripping links and backticks before every class made the six
65
+ shipped documents blind to an internal hostname inside a markdown link.
66
+ - **Eighteen detectors, each carrying its own two fixtures**, with a floor
67
+ over the count. Seven of the previous fifteen had no fixture proving they
68
+ could fire, and two could be deleted with the whole suite green.
69
+ - **The tarball guard asserts absence as well as presence**: nothing outside
70
+ `files`, no sourcemaps, no source. It reads every dependency section rather
71
+ than the runtime one alone, and runs the marker detectors over the packed
72
+ manifest.
73
+
74
+ ### Added
75
+
76
+ - **`test/readme-pointers.test.ts`**: every pointer from the code into the
77
+ README resolves to a heading that is there. That was the defect 3.0.1 fixed
78
+ and left unguarded, one of them inside a runtime error message.
79
+ - **`scripts/verify-commit-messages.mjs`**, wired into the verify job. A
80
+ commit message is public the moment it is pushed.
81
+
7
82
  ## [3.0.1] — 2026-09-07
8
83
 
9
84
  No API change. This release exists because **3.0.0 published internal material
@@ -18,17 +93,33 @@ without it.
18
93
  comment beside it. In 3.0.0 those paths encoded a `git+ssh://` dependency
19
94
  specifier, so an internal hostname appeared **48 times** across the two
20
95
  bundles; the inlined comments carried German paragraphs and internal defect
21
- ids with them. Measured over the published tarballs, the same seventeen
22
- detectors over `dist/`:
23
-
24
- | | 3.0.0 | 3.0.1 |
25
- |---|---|---|
26
- | internal host or workspace name | 49 | 0 |
96
+ ids with them.
97
+
98
+ The table this entry first carried cited "the same seventeen detectors",
99
+ while the entry below it said the guard had fifteen classes and the guard
100
+ itself asserted fifteen. No seventeen-detector artefact ever existed, so
101
+ the numbers could not be reproduced from anything shipped. They are
102
+ replaced here by a measurement of the two **published tarballs** with the
103
+ guard as rebuilt in 3.0.2, which is a thing a reader can run:
104
+
105
+ | class | 3.0.0 | 3.0.1 |
106
+ |---|---:|---:|
107
+ | terse schedule label | 134 | 0 |
27
108
  | German prose | 58 | 0 |
28
- | internal wave labels | 134 | 0 |
29
- | internal decision labels | 42 | 0 |
30
- | internal defect ids | 14 | 0 |
31
- | every other class | 62 | 0 |
109
+ | internal host or workspace name | 49 | 0 |
110
+ | internal decision label | 44 | **2** |
111
+ | a reference to this package rather than the reader's | 30 | 0 |
112
+ | internal review codename | 28 | 0 |
113
+ | a reference to a document the reader does not have | 26 | 0 |
114
+ | longer schedule label | 16 | 0 |
115
+ | how the behaviour was found | 16 | **2** |
116
+ | internal defect id | 14 | 0 |
117
+ | internal feature id | 4 | 0 |
118
+ | the reference robot by name | 4 | 0 |
119
+ | **total** | **423** | **4** |
120
+
121
+ The four remaining in 3.0.1 are the subject of 3.0.2 below. They are here
122
+ rather than in that entry because this is the entry that claimed zero.
32
123
 
33
124
  None of it appeared in this repository's own source, which is why no sweep of
34
125
  the source had found it. The fix is the contracts pin — `@fleetless/contracts`
package/CONTRIBUTING.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # Contributing to `@fleetless/sdk`
2
2
 
3
- This package is the TypeScript client for the Fleetless API. It is what a
4
- developer's own application calls, so a change here reaches every app built on
5
- it, and a change to what a method *sends* reaches the platform as well.
3
+ This is the TypeScript client for the Fleetless API — the thing a developer's
4
+ app calls directly. Change a method here and every app built on it feels it;
5
+ change what a method *sends* and the platform feels it too.
6
6
 
7
7
  ## Setup
8
8
 
@@ -14,12 +14,12 @@ corepack enable
14
14
  pnpm install
15
15
  ```
16
16
 
17
- There are no private dependencies. `pnpm install` works from a clean checkout
18
- with nothing but a network connection to the npm registry — the wire schemas
19
- come from `@fleetless/contracts`, which is a public package.
17
+ No private dependencies — `pnpm install` needs nothing but a network
18
+ connection to npm. The wire schemas come from `@fleetless/contracts`, a
19
+ public package.
20
20
 
21
- `pnpm install` runs `prepare`, which builds `dist/`. Some of the checks below
22
- read the built bundle, so a fresh checkout is ready for them.
21
+ `pnpm install` runs `prepare` and builds `dist/`. Some checks below read the
22
+ built bundle, so a fresh checkout is already ready for them.
23
23
 
24
24
  ## The checks
25
25
 
@@ -32,93 +32,98 @@ read the built bundle, so a fresh checkout is ready for them.
32
32
 
33
33
  To run one test file, use `pnpm vitest run test/<name>.test.ts`.
34
34
 
35
- ## The rule this repository is most serious about: a real server, not a mocked `fetch`
35
+ ## 🔌 The rule this repository is most serious about: a real server, not a mocked `fetch`
36
36
 
37
37
  **The auth suites drive the SDK's own default `fetch` against a real
38
- `node:http` server** (`test/local-api.ts`), and no `fetch` option is passed to
39
- `createClient` in them.
38
+ `node:http` server** (`test/local-api.ts`) — no `fetch` option passed to
39
+ `createClient`.
40
40
 
41
- That is not ceremony. A suite that passes its own `fetch` never enters the code
42
- that actually ships: `client.ts` resolves `globalThis.fetch.bind(globalThis)`,
43
- and every assertion about "what the SDK sends" becomes an assertion about what
44
- a `vi.fn()` was asked to pretend to send. The two most expensive defects this
45
- package has had were both invisible to a mocked `fetch` and both obvious to a
46
- socket:
41
+ Not ceremony. A suite that supplies its own `fetch` never touches the code
42
+ that ships: `client.ts` resolves `globalThis.fetch.bind(globalThis)`, so "what
43
+ the SDK sends" becomes "what a `vi.fn()` agreed to pretend to send." This
44
+ package's two most expensive defects were both invisible to a mocked `fetch`
45
+ and both obvious to a socket:
47
46
 
48
47
  - `createClient` defaulted to a **detached** `globalThis.fetch`. A real
49
- browser's `fetch` is a Web IDL method that throws "Illegal invocation" unless
50
- its receiver is the global object. Node's undici does not enforce that check,
51
- so every test passed and every browser failed on the first call.
52
- - A path segment shaped like `../../../admin` reached a real server as a
53
- traversal, because the encoding was asserted against a double that never
54
- parsed the URL.
48
+ browser's `fetch` is a Web IDL method and throws "Illegal invocation"
49
+ unless the receiver is the global object; Node's undici doesn't check.
50
+ Every test passed, every browser failed on the first call.
51
+ - `../../../admin` reached a real server as a traversal — the encoding was
52
+ asserted against a double that never parsed the URL.
55
53
 
56
- So: **if your change is about what leaves the process, test it against
57
- `test/local-api.ts`.** A double is fine for testing branching, refcounting,
58
- timers and error mapping, and most of the suite uses one for exactly that.
54
+ **If your change touches what leaves the process, test it against
55
+ `test/local-api.ts`.** A double is fine for branching, refcounting, timers,
56
+ error mapping — most of the suite uses one for exactly that.
59
57
 
60
- `test/client.test.ts` carries a test named for this property on its own, so
61
- that removing it is visible in a diff rather than silent.
58
+ `test/client.test.ts` names a test for this property on its own, so removing
59
+ it shows up in a diff instead of in production.
62
60
 
63
61
  ## Licence headers
64
62
 
65
- Every source file carries the SPDX header `// SPDX-License-Identifier: MIT` as
66
- its first line — a `#!` shebang is the only thing allowed above it.
67
- `test/license-headers.test.ts` asserts this over the whole set, and it takes
68
- that set from `git ls-files` rather than from a list of directories, so a file
69
- added anywhere in the repository is swept the day it exists.
63
+ Every source file's first line is the SPDX header
64
+ `// SPDX-License-Identifier: MIT` — only a `#!` shebang may sit above it.
65
+ `test/license-headers.test.ts` checks the whole set, sourced from
66
+ `git ls-files` rather than a list of directories, so a new file is swept the
67
+ day it's added.
70
68
 
71
- ## Nothing internal reaches the published bytes
69
+ ## 📦 Nothing internal reaches the published bytes
72
70
 
73
71
  `tsup` bundles `@fleetless/contracts` **into** `dist/index.js` and
74
- `dist/index.cjs`, doc comments and all, and it writes the path each inlined
75
- module came from as a comment beside it. A comment written for the people who
76
- build this is therefore a comment an editor shows to somebody who installed it —
77
- and for four published versions that included German paragraphs, internal
78
- defect ids and an internal hostname, none of which appeared anywhere in this
79
- repository's source.
72
+ `dist/index.cjs` — doc comments and all — and writes the source path of each
73
+ inlined module as a comment beside it. A comment meant for the people who
74
+ build this is therefore a comment an editor shows to whoever installed it.
75
+ Four published versions did exactly that: German paragraphs, internal defect
76
+ ids, an internal hostname — none of it in this repository's source.
80
77
 
81
- Write a comment as what the code does for a caller. Never as how the behaviour
82
- was found, on which machine, under which internal ticket, or in which language
83
- the team happened to be thinking that day.
78
+ Write a comment for what the code does for a caller, not for how the
79
+ behaviour was found, on which machine, under which ticket, or in which
80
+ language the team happened to be thinking that day.
84
81
 
85
- `test/published-prose.test.ts` enforces it over `dist/`, `src/`, `test/`,
86
- `scripts/` and the shipped markdown, and it will tell you which class of thing
87
- came back and on which line.
82
+ `test/published-prose.test.ts` checks `dist/`, `src/`, `test/`, `scripts/`
83
+ and the shipped markdown, and names which class of thing came back and on
84
+ which line.
88
85
 
89
86
  ## Pull requests
90
87
 
91
- **Pull requests are welcome on GitHub**, at
92
- <https://github.com/fleetless/sdk>. Open an issue first for anything that
93
- changes an existing method signature or what a method sends, so we can say what
94
- else has to move with it.
95
-
96
- **CI runs on GitLab.** This repository is mirrored from an internal GitLab
97
- instance, which is where the pipeline that verifies and publishes it lives. You
98
- will not see a check run on your GitHub pull request; a maintainer runs the
99
- same checks, and the result comes back as a review comment. Run
100
- `pnpm typecheck && pnpm test && pnpm run test:pack` yourself before you open the
101
- pull request and you will have seen everything CI would tell you.
88
+ **The public repository is not open yet.** It will be — this section
89
+ describes how it works once it is. Until then, send patches and questions to
90
+ <hello@fleetless.dev>. Either way: raise anything that changes an existing
91
+ method signature or what a method sends *before* you write it, so we can
92
+ tell you what else has to move with it.
93
+
94
+ **CI runs on GitHub Actions**, in this repository
95
+ (`.github/workflows/verify.yml`) — the suite, on every push and every pull
96
+ request. `release.yml` publishes on a release tag and calls that same file
97
+ first, so a release is never checked by a different pipeline than a push.
98
+
99
+ **Your pull request is verified, a fork's included** — the same suite, the
100
+ same file. GitHub holds a first-time contributor's first run until a
101
+ maintainer approves it, so the checks can sit idle for a while before they
102
+ start; that is the queue, not a failure. The run reads the code and nothing
103
+ else: it is granted `contents: read`, no secret is available to it, and
104
+ publishing lives in a workflow a pull request cannot trigger. Running
105
+ `pnpm typecheck && pnpm test && pnpm run test:pack` yourself first still
106
+ saves you a round trip — it is everything `verify` will tell you.
102
107
 
103
108
  ## The CLA
104
109
 
105
- The first pull request you open will ask you to sign a Contributor Licence
106
- Agreement. It grants Dehne Robotik GmbH the right to license your contribution
107
- under terms other than MIT in future — that is the whole of what it is for, and
108
- it is why the project can relicense its own code later without having to find
109
- every past contributor. It does not take your copyright away and it does not
110
- stop you from using your own contribution however you like.
110
+ Your first pull request will ask you to sign a Contributor Licence Agreement.
111
+ It grants Dehne Robotik GmbH the right to license your contribution under
112
+ terms other than MIT later — that's the whole point, and why the project can
113
+ relicense without hunting down every past contributor. It doesn't take your
114
+ copyright, and it doesn't stop you from using your own contribution however
115
+ you like.
111
116
 
112
117
  ## Commit messages
113
118
 
114
119
  [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/):
115
- `feat:`, `fix:`, `docs:`, `chore:`, `ci:`, `refactor:`, `test:`. A change that
116
- alters an existing method's signature or what it sends is a breaking change;
117
- say so with a `!` and a `BREAKING CHANGE:` footer, because it decides the next
120
+ `feat:`, `fix:`, `docs:`, `chore:`, `ci:`, `refactor:`, `test:`. Changing an
121
+ existing method's signature or what it sends is breaking — mark it with a
122
+ `!` and a `BREAKING CHANGE:` footer, since that's what decides the next
118
123
  version number.
119
124
 
120
- Everything in this repository is written in **English** — code, comments,
121
- commit messages, documentation.
125
+ Everything here is written in **English** — code, comments, commit messages,
126
+ documentation.
122
127
 
123
128
  ## Code of conduct
124
129
 
@@ -126,5 +131,6 @@ By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
126
131
 
127
132
  ## Releasing (maintainers)
128
133
 
129
- See [RELEASING.md](RELEASING.md). The pipeline publishes; `npm publish` from a
130
- working tree is not how a version gets to the registry.
134
+ See RELEASING.md in the repository — it is not part of the published
135
+ package. The `release` workflow publishes; `npm publish` from a working tree
136
+ is not how a version gets to the registry.