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

package/CHANGELOG.md

@@ -0,0 +1,171 @@
+# Changelog
+
+## 1.0.0-alpha.5 (unreleased)
+
+### Added
+
+- **Conditional schema reads** (agility-rooms D1/D3). 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 rooms' 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.
+  (gh-v1: 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
+  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
+  small.)
+
+## 1.0.0-alpha.4 — what the three adoptions asked for
+
+### Added
+
+- **Two narrow rest-1 paths** (agility-rooms): `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, {
+  ctx })` reads `New/<Type>?ctx=`: what the type's initializer fills in
+  for a context (a Timebox's next name and dates, schedule, state and
+  owner; a Story's carry-over from a Request), translated like a row,
+  without an `_oid`. Neither sends attribute values: rest-1 still carries
+  no update path.
+- **`client.fields`**: `describe(type, scope)` joins what a form needs —
+  the attributes the server requires on a create (meta), the ones the
+  product shows for the type in that scope (`api/visibleFields`, custom
+  fields included once configured), and the scope's scheme's important
+  fields with whether they are enforced at close; `visible(types,
+  scopes)` and `visibleByAsset(oid)` are the endpoints alone. New wire
+  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).
+- **`Outcome.requestId`**: the server's id for a batch, worth logging
+  (slack bot). 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.
+
+### Fixed
+
+- `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).
+- `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
+  after a failure needs `retries` above its default of 0; the deprecation
+  notes on `queryV1` and `assets.query` say where each endpoint is.
+
+### Migration note (from alpha.3's read path)
+
+- A rejected query through `client.query` is an `ApiError` with kind
+  `invalid` and code `QUERY_REJECTED`; `message` holds the server's
+  sentences and `details` its whole error document. A formatter that
+  printed `details` for api/asset's `CommandFailureError` now prints a JSON
+  document; print `message`.
+
+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.
+
+## 1.0.0-alpha.3 — the breaking batch (plan 005, step 2)
+
+### Breaking
+
+- **`client.assets.send` answers an `Outcome`, not the api/asset envelope.**
+  `created`, `modified`, `operated` (momentless OIDs), `failures` (by index,
+  each with its parsed `violation`), `queryResults` (one slot per query
+  command, `null` where it failed), `durationSeconds`. Migration:
+  `res.assetsCreated.oidTokens` → `res.created`;
+  `res.commandFailures.count` → `res.failures.length`;
+  `res.queryResult.results[i]` → `res.queryResults[i]`. The wire module
+  `assetApi.send` still returns the envelope for a passthrough.
+  `CommandFailureError` gains `outcome` beside `response`.
+- **Every SDK error is an `ApiError` with a `kind`** (`auth`, `forbidden`,
+  `notFound`, `invalid`, `transient`, `aborted`, `commandFailure`,
+  `protocol`, `usage`, `unknown`). Mistakes caught before any request
+  (an unpaged read, an empty batch, a bad OID token or asset number) throw
+  `UsageError`, not `Error`/`TypeError`. `UnguardableError` is a
+  `UsageError`; `GuardedPassError`, `BatchSendError`, `BatchRecordError`
+  and `AttachmentUploadError` are `WrappedError`s carrying the cause's
+  kind. Migration: a `catch` on `TypeError` becomes `instanceof
+  UsageError`; a branch on `status === 401` can become `kind === "auth"`.
+- **rest-1 reads take a query's spelling**: `client.data.list(type, {
+  select, filter, … })`. `sel` and `where` still work this alpha
+  (deprecated) and go in the next.
+
+### Deprecated (removed in the next alpha)
+
+- `client.queryV1.query` / `.queries` → `client.query` / `client.queries`.
+- `client.assets.query` / `.queries` → `client.query` / `client.queries`
+  (or `client.queryPage` for a total).
+- `client.attachments.url`, `client.embeddedImages.url` →
+  `client.urls.attachment`, `client.urls.embeddedImage`.
+- rest-1 `sel` / `where` → `select` / `filter`.
+
+### Added
+
+- The generated model is refreshed from meta.v1 26.3.1.13 (it was a
+  0.0.0.0 dev build): `Workflow`, `TeamWorkflow` and `WorkflowTransition`
+  arrive, with `Status.AllowedStatusTransitions`,
+  `Status.WorkflowStatusTransitions`, `Role.AllowedStatusTransitions` and
+  `Team.TeamWorkflows`. Nothing was removed or changed.
+  `scripts/download-metamodel.mjs` now strips an instance's own
+  definitions and reports them, so a refresh is reviewable.
+- Reads on the client: `client.query`, `queries` (query.v1: read-only,
+  retried like a GET), `client.get(oid, select)`, `client.queryPage(q)`
+  (total and `more`, via api/asset), `client.pages(q, { limit })` and
+  `client.all(q, { limit })` (page by page up to a limit, default 1000),
+  `client.me()` (the member the credentials belong to).
+- Typed queries: a literal `from` completes `select` from the type's
+  attributes, and rows are typed by what was selected (`row.Name` a
+  string, `row.Nmae` a compile error, `Status.Name` unknown, an aggregate
+  a number). An OID as `from` types by its type. `from` still takes an
+  alias or an unknown type; variables and `query<Story>` work as before.
+- Custom list types (`Custom_<Name>`, the one custom asset type Agility
+  allows, a subtype of List) type as `CustomList`: List's attributes and
+  the type's own token as `AssetType`, as a `from` or as an OID. Custom
+  attributes (`Custom_…`) and the reciprocal side of a custom relation
+  (`ReciprocalOf_…`, which the server adds on the related type) are
+  accepted on every type as attribute values.
+- `client.urls.asset(oid)`: the asset's page (`assetdetail.v1?oid=`).
+- `parseViolation(message)` and `CommandFailureDetail.violation`: the
+  rule, attribute token and loc-2 tag of a validation failure.
+- `kindOf(status, code)`, `ErrorKind`, `UsageError`, `WrappedError`.
+
+## 1.0.0-alpha.2
+
+- Releases are staged with `npm stage publish` and approved by a
+  maintainer with 2FA.
+
+## 1.0.0-alpha.1
+
+- Batch reverse uses the type's operations and the close cascade; the
+  guard sends a second command on one asset as a second pass; Moment is
+  never a guard stamp.
+
+## 1.0.0-alpha.0
+
+- First publish: `AgilityApiClient`, wire modules for api/asset,
+  query.v1, rest-1 reads, meta.v1, loc-2.v1 and attachments; services for
+  schema, resolve, guard, batch, attachments and embedded images.

package/README.md

@@ -49,8 +49,10 @@ Changes between alphas are in `CHANGELOG.md`, each with its migration line.
   - `resolve.numbers` / `resolve.ref` - asset numbers and OID tokens to assets, in one request
   - `attachments.list` / `page` / `info` / `get` / `add` / `put` / `remove` - files attached to an asset; `add` sends a small file inline and a large one in two steps, and a failed upload throws `AttachmentUploadError` naming the empty attachment it left
   - `embeddedImages.upload` / `normalize` - images in rich text; they cannot be deleted
-  - `urls.asset` / `attachment` / `embeddedImage` - where a browser opens each
-  - `data.list` / `get` / `history` - rest-1 reads, for deleted assets and history; `meta.*` - meta.v1 raw; `schema` - the translated, cached view; `localize` - loc-2 labels for tags (a violation's `tag` is one)
+  - `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, 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
@@ -75,7 +77,11 @@ No registry package yet. Pin a commit: `npm install github:versionone/VersionOne
 Versions are published to npmjs by `.github/workflows/publish.yml` when a
 tag `v<version>` is pushed; the tag must equal `package.json`'s version. A
 prerelease (`1.0.0-alpha.0`, `-beta.N`, `-rc.N`) goes out on its own
-dist-tag (`alpha`, `beta`, `rc`), so `latest` is never a prerelease.
+dist-tag (`alpha`, `beta`, `rc`). Until `1.0.0`, a maintainer moves
+`latest` to the newest alpha by hand (`npm dist-tag add
+@versionone/agility-sdk@<version> latest`), so a bare `npm install` gets
+the current API rather than the first publish; from `1.0.0` on, `latest`
+is never a prerelease.
 
 ```bash
 npm version 1.0.0-alpha.2 --no-git-tag-version   # bump, commit, merge

package/dist/index.cjs

@@ -42,7 +42,9 @@ __export(index_exports, {
   attachment: () => attachment_exports,
   createFetchTransport: () => createFetchTransport,
   describeBatch: () => describe,
+  fields: () => fields_exports,
   guard: () => guard,
+  importantName: () => importantName,
   isAssetNumber: () => isAssetNumber,
   isOidToken: () => isOidToken,
   kindOf: () => kindOf,
@@ -183,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 {
@@ -229,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) {
@@ -247,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;
@@ -455,24 +475,29 @@ 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;
   const rule = parts[1], rest = parts.slice(2).filter((p) => p !== "");
   if (rest[0] === "AttributeDefinition" && rest[1] && rest[2]) return { rule, attribute: `${rest[2]}.${rest[1]}`, tag: rest.join("'") };
   const token = rest.length === 1 && /^[A-Za-z][A-Za-z0-9_]*\.[A-Za-z][A-Za-z0-9_]*$/.test(rest[0]) ? rest[0] : null;
-  return { rule, attribute: token, tag: rest.length ? rest.join("'") : null };
+  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 {
+    requestId: typeof response.requestId === "string" && response.requestId ? response.requestId : null,
     created: (response.assetsCreated?.oidTokens ?? []).map(momentless),
     modified: (response.assetsModified?.oidTokens ?? []).map(momentless),
     operated: (response.assetsOperatedOn?.oidTokens ?? []).map(momentless),
@@ -481,13 +506,14 @@ function outcomeOf(response) {
     durationSeconds: typeof response.durationSeconds === "number" ? response.durationSeconds : null
   };
 }
-var emptyOutcome = () => ({ created: [], modified: [], operated: [], failures: [], queryResults: [], durationSeconds: null });
+var emptyOutcome = () => ({ requestId: null, created: [], modified: [], operated: [], failures: [], queryResults: [], durationSeconds: null });
 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;
   return into;
 }
@@ -1168,6 +1194,65 @@ async function reversible(transport, receipt, options = {}) {
   return { commands, drifted, reactivated };
 }
 
+// src/wire/fields.ts
+var fields_exports = {};
+__export(fields_exports, {
+  visibleFields: () => visibleFields,
+  visibleFieldsByAsset: () => visibleFieldsByAsset
+});
+async function visibleFields(transport, types, scopes) {
+  if (!types.length) return {};
+  const params = [...scopes.map((s) => `scopeOid=${encodeURIComponent(momentless(s))}`), ...types.map((t) => `assetTypeToken=${encodeURIComponent(t)}`)].join("&");
+  const answer = await transport.request({ method: "GET", path: `/api/visibleFields?${params}`, responseType: "json" });
+  if (!Array.isArray(answer)) throw new ApiError("api/visibleFields did not answer a list", 200, "BAD_RESPONSE", answer);
+  const out = {};
+  for (const entry of answer) if (entry && typeof entry.assetType === "string") out[entry.assetType] = Array.isArray(entry.fields) ? entry.fields.filter((f) => typeof f === "string") : [];
+  return out;
+}
+async function visibleFieldsByAsset(transport, oid) {
+  const answer = await transport.request({ method: "GET", path: "/api/visibleFieldsByAsset", query: { oidToken: momentless(oid) }, responseType: "json" });
+  if (!Array.isArray(answer)) throw new ApiError("api/visibleFieldsByAsset did not answer a list", 200, "BAD_RESPONSE", answer);
+  return answer.filter((f) => typeof f === "string");
+}
+
+// src/services/fields.ts
+async function lineage(schema, type) {
+  const out = [];
+  for (let t = type; t && !out.includes(t); ) {
+    out.push(t);
+    const def = await schema.load(t);
+    t = def?.Base;
+  }
+  return out;
+}
+function importantName(token, types) {
+  const dot = token.indexOf(".");
+  if (dot < 0) return token;
+  return types.includes(token.slice(0, dot)) ? token.slice(dot + 1) : null;
+}
+async function describe2(transport, schema, type, scope) {
+  const scopeOid = momentless(scope);
+  const types = await lineage(schema, type);
+  const definition = await schema.load(type);
+  const required = definition ? Object.values(definition.Attributes).filter((a) => a.IsRequired && !a.IsReadOnly).map((a) => a.Name).sort() : [];
+  const [visible, [row]] = await Promise.all([
+    visibleFields(transport, [type], [scopeOid]),
+    query(transport, { from: "Scope", select: [{ from: "Scheme", select: ["ImportantFields", "IsRequiredAtClose"] }], filter: ["ID=$scope"], with: { $scope: scopeOid }, page: { size: 1, start: 0 } }, { lookup: schema })
+  ]);
+  const scheme = row?.Scheme ?? null;
+  const tokens = Array.isArray(scheme?.ImportantFields) ? scheme.ImportantFields.filter((t) => typeof t === "string") : [];
+  const important = [...new Set(tokens.map((t) => importantName(t, types)).filter((n) => !!n))].sort();
+  return {
+    type,
+    scope: scopeOid,
+    scheme: scheme ? momentless(scheme._oid) : null,
+    required,
+    visible: visible[type] ?? [],
+    important,
+    requiredAtClose: scheme?.IsRequiredAtClose === true
+  };
+}
+
 // src/types/asset.ts
 var ASSET_STATE_CODES = { Future: 0, Active: 64, Closed: 128, Dead: 192, Template: 200, OldBrokenDownStory: 208, Deprecated: 254, Deleted: 255 };
 var STATE_OF_CODE = Object.fromEntries(Object.entries(ASSET_STATE_CODES).map(([name, code]) => [code, name]));
@@ -1260,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
@@ -1308,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")`);
@@ -1325,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();
@@ -1389,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) => {
@@ -1399,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,
@@ -1459,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`);
@@ -1493,6 +1632,8 @@ __export(rest1_exports, {
   history: () => history,
   list: () => list2,
   momentless: () => momentless,
+  operate: () => operate,
+  template: () => template,
   toQuery: () => toQuery
 });
 var toRef = (doc) => ({ _oid: momentless(doc.idref) });
@@ -1547,6 +1688,19 @@ async function get2(transport, oid, select) {
   const doc = await transport.request({ method: "GET", path: `/rest-1.v1/Data/${encodeURIComponent(type)}/${encodeURIComponent(id)}`, query: { sel: select?.join(",") }, responseType: "json" });
   return fromAssetDocument(doc);
 }
+async function operate(transport, oid, op) {
+  const [type, id] = momentless(oid).split(":");
+  if (!type || !id) throw new UsageError(`"${oid}" is not an OID token (Story:1234)`);
+  const doc = await transport.request({ method: "POST", path: `/rest-1.v1/Data/${encodeURIComponent(type)}/${encodeURIComponent(id)}`, query: { op }, responseType: "json" });
+  if (!doc || typeof doc.id !== "string" || !doc.id) throw new ApiError(`rest-1 ${op} on ${oid} did not answer with an asset`, 200, "BAD_RESPONSE", doc);
+  const moment = doc.id.split(":")[2] ?? null;
+  return { oid: momentless(doc.id), moment };
+}
+async function template(transport, type, options = {}) {
+  const doc = await transport.request({ method: "GET", path: `/rest-1.v1/New/${encodeURIComponent(type)}`, query: { ctx: options.ctx ? momentless(options.ctx) : void 0 }, responseType: "json" });
+  const { _oid: _ignored, ...values } = fromAssetDocument({ ...doc, id: doc.id || `${type}:0` });
+  return values;
+}
 var history = (transport, target, params) => {
   const [type, id] = target.split(":");
   const path = id ? `/rest-1.v1/Hist/${encodeURIComponent(type)}/${encodeURIComponent(id)}` : `/rest-1.v1/Hist/${encodeURIComponent(type)}`;
@@ -1629,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
@@ -1644,16 +1808,39 @@ var AgilityApiClient = class _AgilityApiClient {
     return localize(this.transport, tags, options);
   }
   /**
-   * rest-1.v1, for what query.v1 cannot do: deleted assets (`deleted:
-   * true`), one asset by OID without a page, and history (one row per
-   * moment). Parameters are spelled as a query's (`select`, `filter`).
+   * rest-1.v1, for what the other endpoints cannot do: deleted assets
+   * (`deleted: true`), one asset by OID without a page, history (one row
+   * per moment), a new asset's template (`template`: what the type's
+   * initializer fills in for a context — a Timebox's next name and dates,
+   * a Story's carry-over from a Request), and an operation's result
+   * (`operate`: api/asset performs a Copy but never says what it made;
+   * rest-1 answers the new OID). Parameters are spelled as a query's
+   * (`select`, `filter`).
    */
   data = {
     list: (type, params) => list2(this.transport, type, params),
     get: (oid, select) => get2(this.transport, oid, select),
-    history: (target, params) => history(this.transport, target, params)
+    history: (target, params) => history(this.transport, target, params),
+    template: (type, options) => template(this.transport, type, options),
+    operate: (oid, op) => operate(this.transport, oid, op)
   };
-  /** @deprecated since 1.0.0-alpha.3: `client.query` / `client.queries` read through query.v1. Removed in 1.0.0. */
+  /** Copy an asset (the server's Copy operation) and answer the copy's OID: the one thing api/asset's `execute: "Copy"` does not say. */
+  async copy(oid) {
+    return (await operate(this.transport, oid, "Copy")).oid;
+  }
+  /**
+   * What a form needs for an asset type in a scope: the attributes the
+   * server requires to create one (meta), the ones the product shows there
+   * (api/visibleFields, custom fields included once configured), and the
+   * scope's scheme's important fields and whether they are enforced at
+   * close. `visible` alone answers for several types and scopes at once.
+   */
+  fields = {
+    describe: (type, scope) => describe2(this.transport, this.schema, type, scope),
+    visible: (types, scopes) => visibleFields(this.transport, types, scopes),
+    visibleByAsset: (oid) => visibleFieldsByAsset(this.transport, oid)
+  };
+  /** @deprecated since 1.0.0-alpha.3: use `client.query` / `client.queries` (the same endpoint, query.v1; only the name moved). Removed in 1.0.0. */
   queryV1 = {
     query: (q) => this.query(q),
     queries: (qs) => this.queries(qs)
@@ -1685,7 +1872,7 @@ var AgilityApiClient = class _AgilityApiClient {
       await this.schema.ensureFor(commands);
       return sendGuarded(this.transport, commands, { ...options, lookup: this.schema });
     },
-    /** @deprecated since 1.0.0-alpha.3: use `client.query` (or `client.queryPage` for a total). Removed in 1.0.0. */
+    /** @deprecated since 1.0.0-alpha.3: use `client.query` (rows, through query.v1) or `client.queryPage` (rows and a total, through api/asset as this does). Removed in 1.0.0. */
     query: async (q) => {
       await this.schema.ensureFor([q]);
       return query(this.transport, q, { lookup: this.schema });
@@ -1745,8 +1932,19 @@ var AgilityApiClient = class _AgilityApiClient {
   };
   /** Where a browser opens things on this instance: an asset's page, an attachment's bytes, an embedded image. */
   urls = {
-    /** The asset's page: assetdetail.v1 redirects to the type's own detail page (live 2026-11-12). */
-    asset: (oid) => `${this.config.baseUrl.replace(/\/+$/, "")}/assetdetail.v1?oid=${momentless(oid)}`,
+    /**
+     * The asset's page, from an OID token or an asset Number (S-01001,
+     * what a person typed and what a message shows): assetdetail.v1
+     * resolves either and redirects to the type's own detail page; a signed-
+     * out reader lands there after logging in. Anything else is a UsageError.
+     */
+    asset: (ref) => {
+      const base = this.config.baseUrl.replace(/\/+$/, "");
+      const text = ref.trim();
+      if (isOidToken(text)) return `${base}/assetdetail.v1?oid=${momentless(text)}`;
+      if (isAssetNumber(text)) return `${base}/assetdetail.v1?Number=${encodeURIComponent(text)}`;
+      throw new UsageError(`"${ref}" is neither an OID token (Story:1234) nor an asset number (S-1234)`);
+    },
     attachment: (id) => attachmentUrl(this.config.baseUrl, id),
     embeddedImage: (id) => embeddedImageUrl(this.config.baseUrl, id)
   };
@@ -1775,7 +1973,9 @@ var AgilityApiClient = class _AgilityApiClient {
   attachment,
   createFetchTransport,
   describeBatch,
+  fields,
   guard,
+  importantName,
   isAssetNumber,
   isOidToken,
   kindOf,