@versionone/agility-sdk 1.0.0-alpha.0 → 1.0.0-alpha.2

package/README.md

@@ -44,7 +44,7 @@ npm test
   - `assets.sendGuarded` - a batch as a compare-and-set on each asset's ChangeDate; changed assets come back `skipped`
   - `attachments.list` / `page` / `info` / `get` / `add` / `put` / `remove` / `url` - files attached to an asset: metadata on the Attachment asset, bytes through attachment.img; `page` adds the total and whether more pages follow; `get`'s `contentType` is the type the server sent the bytes with; `add` sends a small file inline (Base64, one request) and a large one in two steps (create, then upload), and a failed upload throws `AttachmentUploadError` naming the empty attachment it left
   - `embeddedImages.upload` / `url` / `normalize` - images in rich text: upload returns the `<img src>` URL; `normalize` rewrites `embedded.img` references to this instance's URL. They cannot be deleted
-  - `batch.run` / `batch.reversible` - preview, snapshot, (confirm,) send guarded, and a receipt with a reverse batch. Undo (`batch.reversible`) reactivates a closed asset before deleting it, and a second command on one asset is sent as a second guarded pass. `confirm` sees the touched assets' names; aliased updates/executes are sent as written with `guard: false`; a failure after the send throws `BatchRecordError` carrying the receipt
+  - `batch.run` / `batch.reversible` - preview, snapshot, (confirm,) send guarded, and a receipt with a reverse batch. Undo (`batch.reversible`) reactivates a closed asset before deleting it, and a second command on one asset is sent as a second guarded pass. The reverse uses only operations the type has in meta (a created Conversation, which has no `Delete`, is a note), and undoing an `Inactivate` or `QuickClose` reopens the descendants that close cascaded to (`receipt.openDescendants`, `receipt.cascaded`), parent first. A command the server reports as failed lands in `receipt.failed`, not `skipped`. `confirm` sees the touched assets' names; aliased updates/executes are sent as written with `guard: false`; a failure after the send throws `BatchRecordError` carrying the receipt
 - `TypeCache` - one instance's loaded type definitions, shared by many clients (`new AgilityApiClient(config, { types })`): a server that builds a client per user fetches each type once
 - `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
 - `ApiError` - typed API error; `CommandFailureError` - an api/asset batch in which commands failed (`failures` by index, plus the `response`)
@@ -71,15 +71,33 @@ 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.
 
 ```bash
-npm version 1.0.0-alpha.1 --no-git-tag-version   # bump, commit, merge
-git tag v1.0.0-alpha.1 && git push origin v1.0.0-alpha.1
+npm version 1.0.0-alpha.2 --no-git-tag-version   # bump, commit, merge
+git tag v1.0.0-alpha.2 && git push origin v1.0.0-alpha.2
 ```
 
+The workflow does not publish directly: it runs `npm stage publish`, which
+puts the version in the registry where nobody can install it yet, and prints
+its stage ID in the run's summary. A maintainer then approves it with 2FA,
+which is what publishes it:
+
+```bash
+npm stage view <stage-id>      # what was staged
+npm stage approve <stage-id>   # publish it (asks for 2FA)
+npm stage reject <stage-id>    # discard it
+```
+
+or approves it on the package's page on npmjs. `npm stage` needs npm
+11.15.0 or later.
+
 Authentication is npm trusted publishing: on npmjs, the package's settings
-link this repository and `publish.yml`, and no token is stored. A package
-must exist before it can be linked, so the very first version is published
-once by hand by an `@versionone` org member (`npm publish --access public
---tag alpha` from a clean checkout of the tagged commit), then linked.
+link this repository, `publish.yml` and the GitHub environment `npm`, with
+the `npm stage publish` permission (leave plain `npm publish` off, as npm
+recommends), and no token is stored. A trusted-publisher link expires; an
+expired one must be deleted and created again, and until then the workflow
+fails with `ENEEDAUTH`. The `npm` environment (repository settings) requires
+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
 

package/dist/index.cjs

@@ -889,9 +889,46 @@ async function snapshot(transport, described) {
   }
   return before;
 }
-var INVERSE = { Inactivate: "Reactivate", Reactivate: "Inactivate", Delete: "Undelete", Undelete: "Delete" };
-function reverseOf(described, before, done) {
+var INVERSE = { Inactivate: "Reactivate", QuickClose: "Reactivate", Reactivate: "Inactivate", Delete: "Undelete", Undelete: "Delete" };
+var CASCADING = /* @__PURE__ */ new Set(["Inactivate", "QuickClose"]);
+var CASCADE_DEPTH = 8;
+async function openDescendantsOf(transport, schema, roots) {
+  const out = {};
+  const rootOf = new Map(roots.map((r) => [momentless(r), momentless(r)]));
+  const seen = new Set(rootOf.keys());
+  let frontier = [...rootOf.keys()];
+  for (let depth = 0; depth < CASCADE_DEPTH && frontier.length; depth += 1) {
+    const children = /* @__PURE__ */ new Map();
+    for (const [type, list3] of byType(frontier)) {
+      await schema.load(type);
+      if (!schema.attribute(type, "Children")) continue;
+      for (const part of chunks(list3)) {
+        const rows = await query(transport, { from: type, select: ["Children"], filter: ["ID=$oids"], with: { $oids: part }, page: { size: part.length, start: 0 } });
+        for (const r of rows) {
+          const parent = momentless(r._oid);
+          for (const c of [].concat(plain(r.Children) ?? [])) {
+            const child = momentless(String(c));
+            if (seen.has(child)) continue;
+            seen.add(child);
+            children.set(child, rootOf.get(parent));
+          }
+        }
+      }
+    }
+    const states = children.size ? await statesOf(transport, [...children.keys()]) : {};
+    frontier = [];
+    for (const [child, root] of children) {
+      if (states[child] === void 0 || isClosed(states[child])) continue;
+      rootOf.set(child, root);
+      (out[root] ??= []).push(child);
+      frontier.push(child);
+    }
+  }
+  return out;
+}
+function reverseOf(described, before, done, context = {}) {
   const commands = [], notes = [];
+  const cannot = (oid, op) => context.canOperate?.(typeOfOid(oid), op) === false;
   const modified = new Set(done.modified.map(momentless)), operated = new Set(done.operated.map(momentless));
   for (const u of described.updates) {
     if (!modified.has(u.oid)) continue;
@@ -916,10 +953,32 @@ function reverseOf(described, before, done) {
   for (const e of described.executes) {
     if (!operated.has(e.oid)) continue;
     const inverse = INVERSE[e.op];
-    if (inverse) commands.push({ from: e.oid, execute: inverse });
-    else notes.push(`${e.oid}: ${e.op} has no known inverse (was ${String(before[e.oid]?.AssetState ?? "?")})`);
+    if (!inverse) {
+      notes.push(`${e.oid}: ${e.op} has no known inverse (was ${String(before[e.oid]?.AssetState ?? "?")})`);
+      continue;
+    }
+    if (cannot(e.oid, inverse)) {
+      notes.push(`${e.oid}: ${typeOfOid(e.oid)} has no ${inverse} operation, so its ${e.op} is not reversed`);
+      continue;
+    }
+    commands.push({ from: e.oid, execute: inverse });
+    if (!CASCADING.has(e.op)) continue;
+    const open = context.openDescendants?.[e.oid] ?? [];
+    const closed = context.cascaded ? context.cascaded[e.oid] ?? [] : void 0;
+    if (closed === void 0) {
+      if (open.length) notes.push(`${e.oid}: ${e.op} may also have closed ${open.length} open descendant${open.length === 1 ? "" : "s"} (${open.join(", ")}); they could not be read back, so they are not reopened`);
+      continue;
+    }
+    for (const d of closed) {
+      if (cannot(d, "Reactivate")) notes.push(`${d}: closed with ${e.oid}, but ${typeOfOid(d)} has no Reactivate operation`);
+      else commands.push({ from: d, execute: "Reactivate" });
+    }
+    if (closed.length) notes.push(`${e.oid}: ${e.op} also closed ${closed.join(", ")}; reopened after it`);
+  }
+  for (const oid of [...done.created].reverse().map(momentless)) {
+    if (cannot(oid, "Delete")) notes.push(`${oid}: ${typeOfOid(oid)} has no Delete operation, so it is not deleted${typeOfOid(oid) === "Conversation" ? " (the server removes a Conversation once its last Expression is deleted)" : ""}`);
+    else commands.push({ from: oid, execute: "Delete" });
   }
-  for (const oid of [...done.created].reverse()) commands.push({ from: momentless(oid), execute: "Delete" });
   for (const d of described.deferred ?? []) notes.push(`command ${d.index} (${d.alias}): an aliased ${d.kind} of ${d.from}, sent as written with no snapshot; not reversed`);
   if (commands.length) notes.unshift("restores the state recorded at snapshotAt; anything that changed between then and sentAt is not reflected, and a scalar restored to null is cleared, not unset");
   return { commands, notes };
@@ -954,12 +1013,14 @@ async function runBatch(transport, schema, commands, options = {}) {
   const described = describe(commands, projected);
   const touched = touchedBy(projected);
   const names = await namesOf(transport, schema, touched, noteFailure);
-  const receipt = { receipt: 1, request: commands, previewedAt, preview: projected, described, names: Object.fromEntries(names), before: {}, sent: false, guarded: false, created: [], touched: [], after: {}, skipped: [], reverse: { commands: [], notes: [] }, notes };
+  const receipt = { receipt: 1, request: commands, previewedAt, preview: projected, described, names: Object.fromEntries(names), before: {}, sent: false, guarded: false, created: [], touched: [], after: {}, skipped: [], failed: [], openDescendants: {}, cascaded: {}, reverse: { commands: [], notes: [] }, notes };
   const nothing = !described.creates.length && !described.updates.length && !described.executes.length && !described.queries.length && !described.deferred.length;
   if (nothing) return receipt;
   for (const d of described.deferred) notes.push(`command ${d.index} (${d.alias}): an aliased ${d.kind}, which preview does not expand; sent as written, not snapshotted, not reversible`);
   receipt.snapshotAt = now();
   receipt.before = await snapshot(transport, described);
+  const closing = described.executes.filter((e) => CASCADING.has(e.op)).map((e) => e.oid);
+  if (closing.length) receipt.openDescendants = await openDescendantsOf(transport, schema, closing);
   if (options.dryRun) return receipt;
   if (options.confirm && !await options.confirm(receipt)) return receipt;
   let unstamped = [];
@@ -991,13 +1052,29 @@ async function runBatch(transport, schema, commands, options = {}) {
   const unnamed = { number: null, name: null };
   receipt.created = done.created.map((oid, i) => ({ alias: described.creates[i]?.alias ?? null, type: described.creates[i]?.type ?? typeOfOid(oid), oid, ...unnamed }));
   receipt.touched = hit.map((oid) => ({ oid, ...names.get(oid) ?? unnamed }));
-  receipt.skipped = useGuard ? [.../* @__PURE__ */ new Set([...unstamped, ...touched.filter((oid) => !hit.includes(oid))])] : [];
-  receipt.reverse = reverseOf(described, receipt.before, done);
+  const sentAs = receipt.sentCommands ?? [];
+  const oidOfSent = (i) => {
+    const body = i === null ? void 0 : sentAs[i] ? bodyOf3(sentAs[i]) : void 0;
+    const id = body?.with?.$oid ?? body?.from;
+    return typeof id === "string" && id.includes(":") ? momentless(id) : null;
+  };
+  receipt.failed = [...new Set(done.failures.map((f) => oidOfSent(f.index)).filter((oid) => !!oid && touched.includes(oid) && !hit.includes(oid)))];
+  receipt.skipped = useGuard ? [.../* @__PURE__ */ new Set([...unstamped, ...touched.filter((oid) => !hit.includes(oid) && !receipt.failed.includes(oid))])] : [];
+  for (const type of new Set([...done.created, ...hit].map((oid) => typeOfOid(momentless(oid))))) await schema.load(type).catch(() => null);
+  const canOperate = (type, op) => schema.canOperate(type, op);
+  const operatedNow = new Set(done.operated.map(momentless));
+  const closed = Object.keys(receipt.openDescendants).filter((oid) => operatedNow.has(oid) && receipt.openDescendants[oid].length);
+  receipt.reverse = reverseOf(described, receipt.before, done, { openDescendants: receipt.openDescendants, cascaded: closed.length ? void 0 : {}, canOperate });
   try {
+    if (closed.length) {
+      const states = await statesOf(transport, closed.flatMap((oid) => receipt.openDescendants[oid]));
+      receipt.cascaded = Object.fromEntries(closed.map((oid) => [oid, receipt.openDescendants[oid].filter((d) => isClosed(states[d]))]));
+      receipt.reverse = reverseOf(described, receipt.before, done, { openDescendants: receipt.openDescendants, cascaded: receipt.cascaded, canOperate });
+    }
     const more = await namesOf(transport, schema, [...done.created, ...hit.filter((oid) => !names.has(oid))], noteFailure);
     receipt.created = receipt.created.map((c) => ({ ...c, ...more.get(c.oid) ?? unnamed }));
     receipt.touched = receipt.touched.map((t) => names.has(t.oid) ? t : { ...t, ...more.get(t.oid) ?? unnamed });
-    const all = [...done.created, ...hit];
+    const all = [.../* @__PURE__ */ new Set([...done.created, ...hit, ...Object.values(receipt.cascaded).flat()])];
     receipt.after = all.length ? await stampsOf(transport, all) : {};
   } catch (error) {
     throw new BatchRecordError(error, receipt);
@@ -1161,7 +1238,8 @@ function toAssetType(doc) {
     ...doc.DefaultOrderBy ? { DefaultOrderBy: doc.DefaultOrderBy.tokenref } : {},
     ...doc.DefaultDisplayBy ? { DefaultDisplayBy: doc.DefaultDisplayBy.tokenref } : {},
     ...doc.ShortName ? { ShortName: doc.ShortName.tokenref } : {},
-    Attributes: Object.fromEntries(Object.entries(doc.Attributes ?? {}).map(([key, value]) => [key, toAttributeDefinition(value)]))
+    Attributes: Object.fromEntries(Object.entries(doc.Attributes ?? {}).map(([key, value]) => [key, toAttributeDefinition(value)])),
+    ...doc.Operations ? { Operations: Object.keys(doc.Operations).map((token) => token.slice(token.indexOf(".") + 1)) } : {}
   };
 }
 function toMetamodel(doc) {
@@ -1225,6 +1303,15 @@ var Schema = class _Schema {
   attribute(type, name) {
     return attributeOf(this, type, name);
   }
+  /**
+   * Can the type do this operation (Delete, Reactivate, …)? Undefined when
+   * the type is not loaded or its definition carries no operations, so a
+   * caller can tell "no" from "don't know".
+   */
+  canOperate(type, op) {
+    const t = this.assetType(type);
+    return t?.Operations ? t.Operations.includes(op) : void 0;
+  }
   /** The tokens loaded so far. */
   get loaded() {
     return [...this.types.entries()].filter(([, t]) => t !== null).map(([token]) => token);