@versionone/agility-sdk 1.0.0-alpha.5 → 1.0.0-alpha.6

package/CHANGELOG.md

@@ -1,10 +1,26 @@
 # Changelog
 
-## 1.0.0-alpha.5 (unreleased)
+## 1.0.0-alpha.6
+
+- The generated model is refreshed from meta.v1 26.3.2.13 (was
+  26.3.1.13): no type, attribute, flag or operation changed between the
+  two; only the version stamp moved.
+
+### Breaking
+
+- **Node 22 or later** (`engines.node` is `>=22`, was `>=18`), and `dist`
+  is now built for Node 22+ (tsup's `target` was `node18`). Node 18
+  reached end of life in April 2025 and Node 20 in April 2026; neither
+  gets security fixes. CI tests the maintained LTS lines, 22, 24 and 26,
+  so a consumer on 18 or 20 was already untested. (The chat-bot consumer
+  runs 24 and the CLI consumer requires 22; the browser app consumer
+  does not run on Node.)
+
+## 1.0.0-alpha.5
 
 ### Added
 
-- **Conditional schema reads** (agility-rooms D1/D3). meta.v1 sends one
+- **Conditional schema reads** (for a browser app consumer). meta.v1 sends one
   strong ETag for the whole schema (`"26.3.1.13.<stamp>"`, the same on
   the document, a type and an attribute) and honours `If-None-Match` with
   a 304. `client.meta.read({ ifNoneMatch })` and `readType(token, {
@@ -13,7 +29,7 @@
   the smallest resource. `TypeCache.etag` remembers the tag the loaded
   types came with, and `client.schema.revalidate()` asks the server in
   one small read and drops the loaded types only when the tag moved —
-  what rooms' metamodel store does by hand. Transport: a request with
+  what a browser app's metamodel store does by hand. Transport: a request with
   `acceptNotModified` resolves to undefined on a 304 after `onResponse`
   sees it.
 
@@ -23,24 +39,28 @@
   defaults to 1, was 0): a GET, a query.v1 read or a guarded batch that
   says so, after a network failure or a 5xx, 150 ms later. A plain write
   is never resent, as before. Pass `retries: 0` for the old behaviour.
-  (gh-v1: the doc promised a retry the default never made.) A 429 counts
+  (a CLI consumer: the doc promised a retry the default never made.) A 429 counts
   as transient like a 5xx — the instance throttles per token — and a
   Retry-After is honoured when sent, up to 30 s.
 - **A rejected query's `details` are the exceptions alone**
   (`{ type, message }[]`, exported as `QueryRejection`), not query.v1's
-  whole error document; `message` is unchanged. (gh-v1: a formatter that
+  whole error document; `message` is unchanged. (a CLI consumer: a formatter that
   printed details printed a JSON document.)
 - **`CommandFailureDetail.echoed` is not enumerable**: still readable on
   every failure for a corrected resend, but a serialised failure (a
   receipt, a log line, a bot's result) carries index, message and
-  violation only. (slack bot, gh-v1: re-mapping failures to keep results
+  violation only. (chat-bot and CLI consumers: re-mapping failures to keep results
   small.)
+- **The committed `metamodel.json` names no instance**: every `href` is
+  spelled from `/meta.v1/` (`scripts/download-metamodel.mjs` rewrites
+  them on a pull). The generated types are unchanged; nothing in the SDK
+  reads an href.
 
 ## 1.0.0-alpha.4 — what the three adoptions asked for
 
 ### Added
 
-- **Two narrow rest-1 paths** (agility-rooms): `client.data.operate(oid,
+- **Two narrow rest-1 paths** (for a browser app consumer): `client.data.operate(oid,
   op)` runs an operation for its result — api/asset performs a Copy but
   reports only the source; rest-1 answers the copy's OID — and
   `client.copy(oid)` is that for Copy. `client.data.template(type, {
@@ -58,9 +78,9 @@
   module `fields`.
 - **`client.urls.asset` takes an asset Number** as well as an OID
   (`assetdetail.v1?Number=S-01001`): the readable form a CLI prints and a
-  chat message shows (gh-v1, slack bot).
+  chat message shows (a CLI consumer, a chat-bot consumer).
 - **`Outcome.requestId`**: the server's id for a batch, worth logging
-  (slack bot). Null for an outcome merged from several sends.
+  (a chat-bot consumer). Null for an outcome merged from several sends.
 - `outcomeOf` tolerating a partial envelope is now a stated contract
   with a test: consumers' fakes may send only the fields they need.
 
@@ -68,7 +88,7 @@
 
 - `parseViolation`: `tag` is null for the token spelling
   (`Violation'Invalid'Epic.Scope`); it was the token, which is not a loc-2
-  tag (gh-v1).
+  tag (a CLI consumer).
 - `CHANGELOG.md` ships in the npm package.
 - Doc notes: `kind: "usage"` means nothing was sent (status 0), so an
   error formatter should not blame the server; `client.query`'s resend
@@ -86,9 +106,9 @@
 Alpha releases may break between versions. Every breaking change is listed
 here with the one-line migration a consumer applies. A renamed export keeps
 its old name as a `@deprecated` alias for one alpha and is removed in the
-next; `1.0.0` follows agility-rooms' adoption, and semver after that.
+next; `1.0.0` follows the browser app consumer's adoption, and semver after that.
 
-## 1.0.0-alpha.3 — the breaking batch (plan 005, step 2)
+## 1.0.0-alpha.3 — the breaking batch
 
 ### Breaking
 

package/README.md

@@ -1,6 +1,6 @@
 # @versionone/agility-sdk
 
-TypeScript SDK for the Digital.ai Agility (formerly VersionOne) API. It works in Node (ESM or CommonJS) and the browser, ships its own types, and has no runtime dependencies.
+TypeScript SDK for the Digital.ai Agility (formerly VersionOne) API. It works in Node 22 or later (ESM or CommonJS) and the browser, ships its own types, and has no runtime dependencies.
 
 Not to be confused with `v1sdk`, the 2.x JavaScript SDK: this is a new API, not a compatible successor.
 
@@ -15,7 +15,7 @@ npm install @versionone/agility-sdk@alpha
 ```ts
 import { AgilityApiClient } from "@versionone/agility-sdk";
 
-const client = new AgilityApiClient({ baseUrl: "https://www14.v1host.com/v1sdktesting", accessToken: process.env.V1_ACCESS_TOKEN });
+const client = new AgilityApiClient({ baseUrl: "https://agility.example.com/MyInstance", accessToken: process.env.V1_ACCESS_TOKEN });
 const stories = await client.query({ from: "Story", select: ["Name", "Estimate"], page: { size: 10, start: 0 } });
 // stories[0].Estimate is a number | null; stories[0].Nmae does not compile
 ```
@@ -35,7 +35,7 @@ npm test
 - `npm run typecheck` - run TypeScript type checks
 - `npm run verify` - run typecheck + build + tests
 - `npm run test` - run unit tests
-- `npm run download:metamodel -- <baseAgilityUrl>` - refresh `metamodel.json` from an instance on the current release (instance-specific definitions stripped; `--raw` keeps them), then `npm run generate:types`. The cleanest source is a dev instance on a blank database (Core's gulp task for that); a hosted instance on the release gives the same file. The generated model is from meta.v1 **26.3.1.13** (hosted, 2026-11-12)
+- `npm run download:metamodel -- <baseAgilityUrl>` - refresh `metamodel.json` from an instance on the current release (instance-specific definitions stripped; `--raw` keeps them), then `npm run generate:types`. The cleanest source is a dev instance on a blank database (the product's dev tooling has a task for that); a hosted instance on the release gives the same file. The generated model is from meta.v1 **26.3.2.13** (hosted, 2026-11-14)
 
 ## Public API
 
@@ -112,6 +112,8 @@ an approval, so a pushed tag waits for a maintainer before it stages. A
 package must exist before it can be linked, so the very first version was
 published once by hand by an `@versionone` org member.
 
-## Before PR
+## Contributing
 
-- Run `npm run verify` to validate typecheck, build, and tests before opening a pull request.
+Run `npm run verify` (typecheck, build, tests) before opening a pull request.
+This repository is public: `CONTRIBUTING.md` says what may be committed
+here and where working plans and consumer hand-offs live instead.