@forumone/throughline-publishing 0.3.4 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @forumone/throughline-publishing
 
+## 0.4.0
+
+### Minor Changes
+
+- d20f909: Bind an approval to the document's content rather than to its `updatedAt`.
+
+  `request_approval` stored `String(document['updatedAt'] ?? …)` as `targetVersion`,
+  and publishing's approval step recomputed the same expression at publish time. So
+  an approval was tied to a timestamp that moves on **every** save. An editor fixing
+  a typo between an approver opening the request and clicking approve invalidated the
+  approval — and the approver spent that time reading a version that no longer
+  existed.
+
+  Requiring re-approval after an edit is a defensible rule. Inheriting it from
+  whichever timestamp field happened to be nearby is not, and it is why **autosave
+  could not be turned on** anywhere the approvals plugin is installed: autosave moves
+  `updatedAt` every couple of seconds of typing, so a pending approval would be
+  invalidated continuously.
+
+  Both sides now call `documentContentHash(document)`, new in
+  `@forumone/throughline-core`. It hashes the document with the metadata that moves
+  without the content moving stripped at every level — `id`, `createdAt`,
+  `updatedAt`, `_status`, `__v`, `_id`, `globalType` — over keys in sorted order,
+  since blocks come back out of JSONB in no promised order. Array order is preserved,
+  because that is the order of the blocks on the page. `{ exclude }` adds
+  app-specific bookkeeping fields to the strip list.
+
+  The rule is now the one that was wanted all along: a save that changed nothing
+  keeps a granted approval, a save that changed something invalidates it, and an edit
+  that is reverted brings the approval back. That last one is why this is a content
+  hash rather than a version id — a version id moves whether or not the content did.
+
+  The two sides only agree because they load the document identically, with
+  `payload.findByID({ collection, id, draft: true })` at the config's default depth.
+  A populated relationship and a bare relationship id are different values and no
+  normalising makes them one, so a caller hashing a document fetched at some other
+  depth gets a hash that matches nothing. That is stated on the function.
+
+  **Approvals pending at upgrade must be re-requested.** Their `targetVersion` holds
+  an ISO timestamp; the publish step now computes a hash, so nothing matches and
+  those documents report `approval-required` until a fresh request is granted. No
+  migration is offered, because the old value cannot be converted — the content it
+  was granted against is not recoverable from a timestamp. Grant a moment for
+  in-flight requests to clear before upgrading, or expect approvers to be asked once
+  more.
+
+  Also exports `isDraftWrite` from `@forumone/throughline-publishing`. It is the
+  predicate the plugin's own trust boundary uses to tell a "Save draft" apart from
+  an unpublish, and it is unavailable to host code that needs the same answer: an
+  `afterChange` hook cannot work it out, because Payload sets `data._status =
+'draft'` on any `draft: true` update before the hooks run and `previousDoc` is the
+  latest _version_ rather than the live document. With autosave on, a host hook that
+  drops a cache or sends a notification fires every few seconds of typing unless it
+  asks this first.
+
+  Minor rather than patch on all three: `documentContentHash` and `isDraftWrite` are
+  new public API, and the stored meaning of `targetVersion` changes.
+
+### Patch Changes
+
+- Updated dependencies [d20f909]
+  - @forumone/throughline-core@0.3.0
+
 ## 0.3.4
 
 ### Patch Changes

package/dist/index.d.ts

@@ -8,4 +8,21 @@ export type { PipelineContext, PipelineResult, PipelineStep, PipelineStepResult,
  */
 export { getPublishStatus, getPublishingService, publishDocument, unpublishDocument, } from './service.js';
 export type { DocumentActionArgs, PublishOutcome, PublishRequest, PublishStatusOutcome, PublishingActor, PublishingService, UnpublishOutcome, } from './service.js';
+/**
+ * Whether the update in flight on this document is a draft write — a "Save
+ * draft", or a tick of autosave — rather than one that changes what the
+ * public sees.
+ *
+ * `afterChange` cannot work this out for itself. Payload sets
+ * `data._status = 'draft'` on any `draft: true` update before the hooks
+ * run, and `previousDoc` is the latest *version* rather than the live
+ * document, so a draft save of a published page and an unpublish of it look
+ * the same from inside the hook. The publishing plugin already records the
+ * operation's real `draft` argument in `beforeOperation` for its own trust
+ * boundary; this exposes the same answer to host hooks.
+ *
+ * With autosave on, a host `afterChange` that drops a cache or sends a
+ * notification fires every few seconds of typing unless it asks this first.
+ */
+export { isDraftWrite } from './hooks/draft-writes.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAE9C,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,cAAc,CAAA;AAErB,YAAY,EACV,eAAe,EACf,cAAc,EACd,YAAY,EACZ,kBAAkB,GACnB,MAAM,qBAAqB,CAAA;AAE5B;;;;GAIG;AACH,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,GAClB,MAAM,cAAc,CAAA;AAErB,YAAY,EACV,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAE9C,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,cAAc,CAAA;AAErB,YAAY,EACV,eAAe,EACf,cAAc,EACd,YAAY,EACZ,kBAAkB,GACnB,MAAM,qBAAqB,CAAA;AAE5B;;;;GAIG;AACH,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,GAClB,MAAM,cAAc,CAAA;AAErB,YAAY,EACV,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,cAAc,CAAA;AAErB;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/index.js

@@ -5,4 +5,21 @@ export { publishingPlugin } from './plugin.js';
  * given user, with no API key and correct audit attribution.
  */
 export { getPublishStatus, getPublishingService, publishDocument, unpublishDocument, } from './service.js';
+/**
+ * Whether the update in flight on this document is a draft write — a "Save
+ * draft", or a tick of autosave — rather than one that changes what the
+ * public sees.
+ *
+ * `afterChange` cannot work this out for itself. Payload sets
+ * `data._status = 'draft'` on any `draft: true` update before the hooks
+ * run, and `previousDoc` is the latest *version* rather than the live
+ * document, so a draft save of a published page and an unpublish of it look
+ * the same from inside the hook. The publishing plugin already records the
+ * operation's real `draft` argument in `beforeOperation` for its own trust
+ * boundary; this exposes the same answer to host hooks.
+ *
+ * With autosave on, a host `afterChange` that drops a cache or sends a
+ * notification fires every few seconds of typing unless it asks this first.
+ */
+export { isDraftWrite } from './hooks/draft-writes.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAmB9C;;;;GAIG;AACH,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,GAClB,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAmB9C;;;;GAIG;AACH,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,GAClB,MAAM,cAAc,CAAA;AAYrB;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/pipeline/steps/approval.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"approval.d.ts","sourceRoot":"","sources":["../../../src/pipeline/steps/approval.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,eAErC,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,EAAE,YAoC1B,CAAA"}
+{"version":3,"file":"approval.d.ts","sourceRoot":"","sources":["../../../src/pipeline/steps/approval.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,eAErC,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,EAAE,YA+C1B,CAAA"}

package/dist/pipeline/steps/approval.js

@@ -1,3 +1,4 @@
+import { documentContentHash } from '@forumone/throughline-core';
 /**
  * Symbol the approvals plugin attaches its resolver under. Publishing's
  * approval step looks here when no resolver is supplied via options, which
@@ -29,7 +30,18 @@ export const approvalStep = async (ctx) => {
             suggestion: 'Register approvalsPlugin in your Payload config (it attaches the resolver automatically) or pass an explicit `approvalResolver` to publishingPlugin.',
         };
     }
-    const versionId = String(ctx.document['updatedAt'] ?? ctx.documentId);
+    /*
+    The approval binds to the document's content, not to its `updatedAt`. The
+    approvals plugin's `request_approval` computes this same hash, with this
+    same function, over a document loaded by the same `findByID` call — so an
+    approval granted on what an approver read still resolves after a save that
+    changed nothing, and does not resolve after one that changed something.
+  
+    Binding to `updatedAt` made that a property of a timestamp rather than a
+    rule: any save at all invalidated a pending approval, which is also why
+    autosave and approvals could not both be on. See #341.
+    */
+    const versionId = await documentContentHash(ctx.document);
     const approval = await resolver.getActiveApproval(ctx.collection.slug, ctx.documentId, versionId);
     if (!approval) {
         return {

package/dist/pipeline/steps/approval.js.map

@@ -1 +1 @@
-{"version":3,"file":"approval.js","sourceRoot":"","sources":["../../../src/pipeline/steps/approval.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC,GAAG,CACjD,0CAA0C,CAC3C,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,YAAY,GAAiB,KAAK,EAAE,GAAG,EAAE,EAAE;IACtD,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,CAEzC,CAAA;IACb,IAAI,CAAC,MAAM,EAAE,CAAC,kBAAkB,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;IAExD,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,gBAAgB,IAAI,uBAAuB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IACrF,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;YACL,IAAI,EAAE,KAAK;YACX,IAAI,EAAE,2BAA2B;YACjC,MAAM,EAAE,mEAAmE;YAC3E,UAAU,EACR,sJAAsJ;SACzJ,CAAA;IACH,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,CAAA;IACrE,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,iBAAiB,CAC/C,GAAG,CAAC,UAAU,CAAC,IAAI,EACnB,GAAG,CAAC,UAAU,EACd,SAAS,CACV,CAAA;IAED,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;YACL,IAAI,EAAE,KAAK;YACX,IAAI,EAAE,mBAAmB;YACzB,MAAM,EACJ,wFAAwF;YAC1F,UAAU,EACR,mFAAmF;SACtF,CAAA;IACH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;AACvB,CAAC,CAAA;AAED,SAAS,uBAAuB,CAAC,OAAe;IAC9C,MAAM,KAAK,GAAI,OAAmC,CAAC,yBAAyB,CAAC,CAAA;IAC7E,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAE,KAA0B,CAAC,CAAC,CAAC,SAAS,CAAA;AAC9F,CAAC"}
+{"version":3,"file":"approval.js","sourceRoot":"","sources":["../../../src/pipeline/steps/approval.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAIhE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC,GAAG,CACjD,0CAA0C,CAC3C,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,YAAY,GAAiB,KAAK,EAAE,GAAG,EAAE,EAAE;IACtD,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,CAEzC,CAAA;IACb,IAAI,CAAC,MAAM,EAAE,CAAC,kBAAkB,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;IAExD,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,gBAAgB,IAAI,uBAAuB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IACrF,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;YACL,IAAI,EAAE,KAAK;YACX,IAAI,EAAE,2BAA2B;YACjC,MAAM,EAAE,mEAAmE;YAC3E,UAAU,EACR,sJAAsJ;SACzJ,CAAA;IACH,CAAC;IAED;;;;;;;;;;MAUE;IACF,MAAM,SAAS,GAAG,MAAM,mBAAmB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IACzD,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,iBAAiB,CAC/C,GAAG,CAAC,UAAU,CAAC,IAAI,EACnB,GAAG,CAAC,UAAU,EACd,SAAS,CACV,CAAA;IAED,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;YACL,IAAI,EAAE,KAAK;YACX,IAAI,EAAE,mBAAmB;YACzB,MAAM,EACJ,wFAAwF;YAC1F,UAAU,EACR,mFAAmF;SACtF,CAAA;IACH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;AACvB,CAAC,CAAA;AAED,SAAS,uBAAuB,CAAC,OAAe;IAC9C,MAAM,KAAK,GAAI,OAAmC,CAAC,yBAAyB,CAAC,CAAA;IAC7E,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAE,KAA0B,CAAC,CAAC,CAAC,SAAS,CAAA;AAC9F,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forumone/throughline-publishing",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Policy-gated publishing server for Throughline. Wraps Payload's update operation with composition, accessibility, required-field, embargo, and approval gating.",
   "type": "module",
   "main": "./dist/index.js",
@@ -59,7 +59,7 @@
   },
   "dependencies": {
     "zod": "^3.23.0",
-    "@forumone/throughline-core": "0.2.2",
+    "@forumone/throughline-core": "0.3.0",
     "@forumone/throughline-plugin-contract": "0.2.1"
   },
   "devDependencies": {