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

package/CHANGELOG.md

@@ -1,10 +1,66 @@
 # Changelog
 
+## 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** (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, {
+  ifNoneMatch })` answer `{ value, etag }`, or null without a download when
+  the tag still matches; `client.meta.etag()` reads the tag alone from
+  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 a browser app's metamodel store does by hand. Transport: a request with
+  `acceptNotModified` resolves to undefined on a 304 after `onResponse`
+  sees it.
+
+### Changed
+
+- **Idempotent requests are resent once by default** (`retries` now
+  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.
+  (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. (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. (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, {
@@ -22,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.
 
@@ -32,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
@@ -50,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
 
@@ -52,7 +52,7 @@ Changes between alphas are in `CHANGELOG.md`, each with its migration line.
   - `copy(oid)` - the Copy operation, answering the copy's OID (api/asset performs it but never says what it made); `data.operate(oid, op)` is the general form
   - `fields.describe(type, scope)` - what a form needs: required attributes (meta), the ones the product shows there (`api/visibleFields`, custom fields included), the scheme's important fields and whether they are enforced at close
   - `urls.asset(oidOrNumber)` / `attachment` / `embeddedImage` - where a browser opens each
-  - `data.list` / `get` / `history` / `template` - rest-1 reads: deleted assets, history, and a new asset's template for a context (`New/<Type>?ctx=`); `meta.*` - meta.v1 raw; `schema` - the translated, cached view; `localize` - loc-2 labels for tags (a violation's `tag` is one)
+  - `data.list` / `get` / `history` / `template` - rest-1 reads: deleted assets, history, and a new asset's template for a context (`New/<Type>?ctx=`); `meta.*` - meta.v1 raw, with conditional reads (`read` / `readType` with `ifNoneMatch`, `etag()`: meta.v1 sends one ETag for the whole schema); `schema` - the translated, cached view, `schema.revalidate()` drops it only when that tag moves; `localize` - loc-2 labels for tags (a violation's `tag` is one)
 - Errors: everything thrown is an `ApiError` with a `kind` (`auth`, `forbidden`, `notFound`, `invalid`, `transient`, `aborted`, `commandFailure`, `protocol`, `usage`, `unknown`). A mistake caught before any request is a `UsageError`
 - `TypeCache` - one instance's loaded type definitions, shared by many clients (`new AgilityApiClient(config, { types })`)
 - `createFetchTransport` - configurable HTTP transport: `credentials` for same-origin cookie auth, `onUnauthorized` to re-authenticate on a 401 (resends idempotent requests once), and a per-request `signal`; `client.withSignal(signal)` ties a whole client to one
@@ -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.

package/dist/index.cjs

@@ -185,10 +185,22 @@ function messageOf(data, status) {
   return `HTTP ${status}`;
 }
 var delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var MAX_RETRY_AFTER_MS = 3e4;
+function retryDelay(response, attempt) {
+  const header = response.headers.get("retry-after");
+  if (header) {
+    const seconds = Number(header);
+    const ms = Number.isFinite(seconds) ? seconds * 1e3 : Date.parse(header) - Date.now();
+    if (Number.isFinite(ms) && ms > MAX_RETRY_AFTER_MS) return null;
+    if (Number.isFinite(ms) && ms > 0) return ms;
+  }
+  return 150 * (attempt + 1);
+}
+var retriable = (status) => status === 429 || status >= 500;
 function createFetchTransport(config) {
   const fetchImpl = config.fetchImpl ?? fetch;
   const timeoutMs = config.timeoutMs ?? 6e4;
-  const retries = Math.max(0, config.retries ?? 0);
+  const retries = Math.max(0, config.retries ?? 1);
   const authorization = config.authorization ?? (config.accessToken ? `Bearer ${config.accessToken}` : void 0);
   const unauthorizedStatuses = config.unauthorizedStatuses ?? [401];
   return {
@@ -231,6 +243,10 @@ function createFetchTransport(config) {
             options.onResponse?.({ status: response.status, headers: response.headers });
             return await readBody(response, responseType);
           }
+          if (response.status === 304 && options.acceptNotModified) {
+            options.onResponse?.({ status: 304, headers: response.headers });
+            return void 0;
+          }
           const data = await readBody(response, responseType === "bytes" ? "text" : responseType === "json" ? "auto" : responseType);
           lastError = new ApiError(messageOf(data, response.status), response.status, void 0, data);
         } catch (error) {
@@ -249,8 +265,10 @@ function createFetchTransport(config) {
           }
           break;
         }
-        if (response.status >= 500 && attempt + 1 < attempts) {
-          await delay(150 * (attempt + 1));
+        if (retriable(response.status) && attempt + 1 < attempts) {
+          const wait = retryDelay(response, attempt);
+          if (wait === null) break;
+          await delay(wait);
           continue;
         }
         break;
@@ -457,6 +475,11 @@ function toNumber(value) {
   const n = typeof value === "string" && value.trim() !== "" ? Number(value) : NaN;
   return Number.isNaN(n) ? value : n;
 }
+function failureDetail(index, message, echoed) {
+  const detail = { index, message, violation: parseViolation(message) };
+  Object.defineProperty(detail, "echoed", { value: echoed, enumerable: false, writable: false });
+  return detail;
+}
 function parseViolation(message) {
   const parts = message.trim().split("'");
   if (parts[0] !== "Violation" || !parts[1]) return null;
@@ -466,12 +489,11 @@ function parseViolation(message) {
   return { rule, attribute: token, tag: !token && rest.length > 1 ? rest.join("'") : null };
 }
 function failuresOf(response) {
-  return (response.commandFailures?.commands ?? []).map(({ error, ...echoed }) => ({
-    index: typeof error === "object" && error && typeof error.sourceCommandIndex === "number" ? error.sourceCommandIndex : null,
-    message: typeof error === "string" ? error : error?.message || "command failed",
-    echoed,
-    violation: parseViolation(typeof error === "string" ? error : error?.message || "")
-  }));
+  return (response.commandFailures?.commands ?? []).map(({ error, ...echoed }) => failureDetail(
+    typeof error === "object" && error && typeof error.sourceCommandIndex === "number" ? error.sourceCommandIndex : null,
+    typeof error === "string" ? error : error?.message || "command failed",
+    echoed
+  ));
 }
 function outcomeOf(response) {
   return {
@@ -489,7 +511,7 @@ function mergeOutcome(into, done, offset) {
   into.created.push(...done.created);
   into.modified.push(...done.modified);
   into.operated.push(...done.operated);
-  into.failures.push(...done.failures.map((f) => ({ ...f, index: f.index === null ? null : f.index + offset })));
+  into.failures.push(...done.failures.map((f) => failureDetail(f.index === null ? null : f.index + offset, f.message, f.echoed)));
   into.queryResults.push(...done.queryResults);
   into.requestId = null;
   if (done.durationSeconds !== null) into.durationSeconds = (into.durationSeconds ?? 0) + done.durationSeconds;
@@ -1323,10 +1345,13 @@ async function resolveRef(transport, spec, options = {}) {
 // src/wire/meta.ts
 var meta_exports = {};
 __export(meta_exports, {
+  etag: () => etag,
   getAssetType: () => getAssetType,
   getAttributeDefinition: () => getAttributeDefinition,
   getMetamodel: () => getMetamodel,
   isMetamodelDocument: () => isMetamodelDocument,
+  readAssetType: () => readAssetType,
+  readMetamodel: () => readMetamodel,
   toAssetType: () => toAssetType,
   toAttributeDefinition: () => toAttributeDefinition,
   toMetamodel: () => toMetamodel
@@ -1371,12 +1396,36 @@ function toMetamodel(doc) {
 function isMetamodelDocument(value) {
   return !!value && typeof value === "object" && typeof value.Version === "string" && !!value.AssetTypes && typeof value.AssetTypes === "object";
 }
+var PROBE_PATH = "/meta.v1/BaseAsset/Name";
+async function conditional(transport, path, options) {
+  let etag2 = null, status = 200;
+  const onResponse = (r) => {
+    status = r.status;
+    etag2 = r.headers.get("etag");
+  };
+  const headers = options.ifNoneMatch ? { "if-none-match": options.ifNoneMatch } : void 0;
+  const doc = await transport.request({ method: "GET", path, headers, responseType: "json", onResponse, acceptNotModified: !!options.ifNoneMatch });
+  if (status === 304 || doc === void 0) return null;
+  return { value: doc, etag: etag2 };
+}
 async function getMetamodel(transport) {
   return toMetamodel(await transport.request({ method: "GET", path: "/meta.v1", responseType: "json" }));
 }
+async function readMetamodel(transport, options = {}) {
+  const read2 = await conditional(transport, "/meta.v1", options);
+  return read2 && { value: toMetamodel(read2.value), etag: read2.etag };
+}
 async function getAssetType(transport, token) {
   return toAssetType(await transport.request({ method: "GET", path: `/meta.v1/${encodeURIComponent(token)}`, responseType: "json" }));
 }
+async function readAssetType(transport, token, options = {}) {
+  const read2 = await conditional(transport, `/meta.v1/${encodeURIComponent(token)}`, options);
+  return read2 && { value: toAssetType(read2.value), etag: read2.etag };
+}
+async function etag(transport, options = {}) {
+  const read2 = await conditional(transport, PROBE_PATH, options);
+  return read2 ? read2.etag : options.ifNoneMatch ?? null;
+}
 async function getAttributeDefinition(transport, tokenref) {
   const [type, attribute] = tokenref.split(".");
   if (!type || !attribute) throw new UsageError(`"${tokenref}" is not an attribute token ("Story.Name")`);
@@ -1388,6 +1437,13 @@ var TypeCache = class _TypeCache {
   /** Loaded types; null records that the instance has no such type, so it is not asked for again. */
   types = /* @__PURE__ */ new Map();
   loading = /* @__PURE__ */ new Map();
+  /** The schema's tag the loaded types came with (meta.v1's ETag, one for the whole schema); null until a load, or for a seeded cache. */
+  etag = null;
+  /** Forget every loaded type (and the tag): the next query loads afresh. In-flight loads finish into the cache as before. */
+  clear() {
+    this.types.clear();
+    this.etag = null;
+  }
   /** A cache seeded from a metamodel document. */
   static fromMetamodel(metamodel) {
     const cache = new _TypeCache();
@@ -1452,7 +1508,10 @@ var Schema = class _Schema {
       this.types.set(token, null);
       return null;
     }
-    const request = getAssetType(this.transport, token).catch((error) => {
+    const request = readAssetType(this.transport, token).then((read2) => {
+      if (read2?.etag) this.cache.etag = read2.etag;
+      return read2 ? read2.value : null;
+    }).catch((error) => {
       if (error instanceof ApiError && error.status === 404) return null;
       throw error;
     }).then((type) => {
@@ -1462,6 +1521,23 @@ var Schema = class _Schema {
     this.loading.set(token, request);
     return request;
   }
+  /**
+   * Has the instance's schema changed since these types were loaded? One
+   * small conditional read of meta.v1. Unchanged: nothing happens.
+   * Changed (or never tagged, or the transport cannot see headers): the
+   * loaded types are dropped, so the next query loads them again, and the
+   * new tag is kept. Answers whether it changed and the current tag. A
+   * schema without a transport (seeded) never changes.
+   */
+  async revalidate() {
+    if (!this.transport) return { changed: false, etag: this.cache.etag };
+    const was = this.cache.etag;
+    const now2 = await etag(this.transport, { ifNoneMatch: was });
+    if (was && now2 === was) return { changed: false, etag: was };
+    this.cache.clear();
+    this.cache.etag = now2;
+    return { changed: true, etag: now2 };
+  }
   /**
    * Load whatever the queries in a batch need to have their rows translated:
    * the `from` types, then the types behind every relation hop and sub-select,
@@ -1522,8 +1598,8 @@ __export(queryV1_exports, {
 });
 function rejected(error) {
   const details = error.details;
-  const messages = (details?.exceptions ?? []).map((e) => e?.message).filter((m) => typeof m === "string" && !!m);
-  return messages.length ? new ApiError(messages.join("; "), error.status, "QUERY_REJECTED", error.details) : error;
+  const rejections = (details?.exceptions ?? []).filter((e) => e && typeof e.message === "string" && e.message).map((e) => ({ type: typeof e.type === "string" ? e.type : null, message: e.message }));
+  return rejections.length ? new ApiError(rejections.map((r) => r.message).join("; "), error.status, "QUERY_REJECTED", rejections) : error;
 }
 async function queries2(transport, qs, options = {}) {
   for (const q of qs) if (!q.page) throw new UsageError(`query of ${q.from} without a page: every query.v1 read must be bounded`);
@@ -1707,11 +1783,21 @@ var AgilityApiClient = class _AgilityApiClient {
     return row;
   }
   // ---- the endpoints behind the reads -----------------------------------------------
-  /** meta.v1: the instance's schema, raw. (The translated, cached view is `schema`.) */
+  /**
+   * meta.v1: the instance's schema, raw. (The translated, cached view is
+   * `schema`; `schema.revalidate()` drops it when the schema's tag moves.)
+   * `read` and `readType` are conditional: pass the tag a previous answer
+   * carried and an unchanged schema answers null without a download —
+   * meta.v1 sends one strong ETag for the whole schema. `etag()` reads that
+   * tag alone, from the smallest resource.
+   */
   meta = {
     metamodel: () => getMetamodel(this.transport),
+    read: (options) => readMetamodel(this.transport, options),
     assetType: (token) => getAssetType(this.transport, token),
-    attributeDefinition: (tokenref) => getAttributeDefinition(this.transport, tokenref)
+    readType: (token, options) => readAssetType(this.transport, token, options),
+    attributeDefinition: (tokenref) => getAttributeDefinition(this.transport, tokenref),
+    etag: (options) => etag(this.transport, options)
   };
   /**
    * loc-2.v1: labels for tags, in one request (meta's DisplayName values are