@byline/core 3.0.2 → 3.1.0

package/dist/@types/collection-types.d.ts

@@ -323,6 +323,12 @@ export interface BeforeCreateContext {
  * Includes the `documentId` and `documentVersionId` returned by storage
  * so the hook can reference the persisted document.
  *
+ * `path` is the document's canonical (source-locale) routing path as
+ * written into `byline_document_paths` — the value a consumer needs to
+ * invalidate a cache key, purge a CDN URL, or fire a webhook against the
+ * specific document. (Resolved *after* `beforeCreate`, since that hook may
+ * mutate the source field that path derivation reads.)
+ *
  * `duplicate` mirrors `BeforeCreateContext.duplicate` — present only when
  * the create was triggered by `duplicateDocument`.
  */
@@ -331,6 +337,8 @@ export interface AfterCreateContext {
     collectionPath: string;
     documentId: string;
     documentVersionId: string;
+    /** The document's canonical (source-locale) routing path. */
+    path: string;
     duplicate?: {
         sourceDocumentId: string;
     };
@@ -371,6 +379,11 @@ export interface BeforeUpdateContext {
  * Includes the `documentId` and `documentVersionId` of the newly created
  * version so the hook can reference the persisted document.
  *
+ * `path` is the document's canonical (source-locale) routing path after the
+ * update — surfaced explicitly so cache-invalidation / CDN-purge / webhook
+ * hooks need not dig it out of `originalData`. (Previously available only
+ * implicitly via `originalData.path`.)
+ *
  * `restore` mirrors `BeforeUpdateContext.restore` — present only when the
  * update was triggered by restoring a historical version.
  * `copyToLocale` mirrors `BeforeUpdateContext.copyToLocale` — present only
@@ -382,6 +395,8 @@ export interface AfterUpdateContext {
     collectionPath: string;
     documentId: string;
     documentVersionId: string;
+    /** The document's canonical (source-locale) routing path. */
+    path: string;
     restore?: {
         sourceVersionId: string;
     };
@@ -396,37 +411,60 @@ export interface AfterUpdateContext {
 }
 /**
  * Context passed to `beforeStatusChange` / `afterStatusChange` hooks.
+ *
+ * `path` is the document's canonical (source-locale) routing path — present
+ * so a status-change hook (publish → purge CDN, archive → drop cache key) can
+ * act on the specific document/URL rather than invalidating the whole
+ * collection.
  */
 export interface StatusChangeContext {
     documentId: string;
     documentVersionId: string;
     collectionPath: string;
+    /** The document's canonical (source-locale) routing path. */
+    path: string;
     previousStatus: string;
     nextStatus: string;
 }
 /**
  * Context passed to `beforeUnpublish` hooks.
+ *
+ * `path` is the document's canonical (source-locale) routing path — present
+ * so an unpublish hook can target the specific document/URL.
  */
 export interface BeforeUnpublishContext {
     documentId: string;
     collectionPath: string;
+    /** The document's canonical (source-locale) routing path. */
+    path: string;
 }
 /**
  * Context passed to `afterUnpublish` hooks.
  *
  * `archivedCount` indicates how many published versions were archived.
+ *
+ * `path` is the document's canonical (source-locale) routing path — present
+ * so an unpublish hook can target the specific document/URL.
  */
 export interface AfterUnpublishContext {
     documentId: string;
     collectionPath: string;
+    /** The document's canonical (source-locale) routing path. */
+    path: string;
     archivedCount: number;
 }
 /**
- * Context passed to `beforeDelete` / `afterDelete` hooks (future).
+ * Context passed to `beforeDelete` / `afterDelete` hooks.
+ *
+ * `path` is the document's canonical (source-locale) routing path — present
+ * so a delete hook can purge the specific document/URL (cache key, CDN, search
+ * index) rather than the entire collection.
  */
 export interface DeleteContext {
     documentId: string;
     collectionPath: string;
+    /** The document's canonical (source-locale) routing path. */
+    path: string;
 }
 /**
  * Context passed to `beforeStore` hooks (configured on

package/dist/@types/db-types.d.ts

@@ -468,6 +468,21 @@ export interface IDocumentQueries {
         created_at: Date;
         updated_at: Date;
     } | null>;
+    /**
+     * Resolve a document's canonical (source-locale) routing path.
+     *
+     * Returns the `byline_document_paths` row for the document under its own
+     * `source_locale` anchor (falling back to the configured default content
+     * locale for rows predating `source_locale`). Narrow by design — used by
+     * the lifecycle to populate `path` on the status-change / unpublish hook
+     * contexts without widening `getCurrentVersionMetadata`.
+     *
+     * Returns `null` when the document has no path row (or does not exist).
+     */
+    getCurrentPath(params: {
+        collection_id: string;
+        document_id: string;
+    }): Promise<string | null>;
     getDocumentByPath(params: {
         collection_id: string;
         path: string;

package/dist/services/collection-bootstrap.test.node.js

@@ -59,6 +59,7 @@ function createMockDb(options) {
             documents: {
                 getDocumentById: vi.fn(fail),
                 getCurrentVersionMetadata: vi.fn(fail),
+                getCurrentPath: vi.fn(fail),
                 getDocumentByPath: vi.fn(fail),
                 getDocumentByVersion: vi.fn(fail),
                 getDocumentsByVersionIds: vi.fn(fail),
@@ -201,6 +202,7 @@ describe('ensureCollections', () => {
                 documents: {
                     getDocumentById: vi.fn(),
                     getCurrentVersionMetadata: vi.fn(),
+                    getCurrentPath: vi.fn(),
                     getDocumentByPath: vi.fn(),
                     getDocumentByVersion: vi.fn(),
                     getDocumentsByVersionIds: vi.fn(),

package/dist/services/discover-counter-groups.test.node.js

@@ -44,6 +44,7 @@ function makeAdapter(options) {
             documents: {
                 getDocumentById: vi.fn(fail),
                 getCurrentVersionMetadata: vi.fn(fail),
+                getCurrentPath: vi.fn(fail),
                 getDocumentByPath: vi.fn(fail),
                 getDocumentByVersion: vi.fn(fail),
                 getDocumentsByVersionIds: vi.fn(fail),

package/dist/services/document-lifecycle.js

@@ -255,6 +255,7 @@ export async function createDocument(ctx, params) {
             collectionPath,
             documentId,
             documentVersionId,
+            path: resolvedPath,
         });
         return { documentId, documentVersionId };
     });
@@ -340,6 +341,7 @@ export async function updateDocument(ctx, params) {
             collectionPath,
             documentId,
             documentVersionId,
+            path: pathForCommand ?? originalData.path,
         });
         return { documentId, documentVersionId };
     });
@@ -453,6 +455,7 @@ export async function updateDocumentWithPatches(ctx, params) {
             collectionPath,
             documentId,
             documentVersionId,
+            path: pathForCommand ?? originalData.path,
         });
         return { documentId, documentVersionId };
     });
@@ -514,10 +517,18 @@ export async function changeDocumentStatus(ctx, params) {
                 details: { currentStatus, nextStatus: params.nextStatus },
             }).log(ctx.logger);
         }
+        // Resolve the document's canonical path so the hooks can act on the
+        // specific document/URL (CDN purge, cache-key drop). Narrow lookup —
+        // getCurrentVersionMetadata deliberately omits the path subquery.
+        const path = (await ctx.db.queries.documents.getCurrentPath({
+            collection_id: collectionId,
+            document_id: params.documentId,
+        })) ?? '';
         const hookCtx = {
             documentId: params.documentId,
             documentVersionId,
             collectionPath,
+            path,
             previousStatus: currentStatus,
             nextStatus: params.nextStatus,
         };
@@ -550,7 +561,7 @@ export async function changeDocumentStatus(ctx, params) {
  */
 export async function unpublishDocument(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'unpublishDocument' }, async () => {
-        const { db, collectionPath, definition } = ctx;
+        const { db, collectionId, collectionPath, definition } = ctx;
         // Unpublish is a workflow transition out of `published` — reuse the
         // changeStatus gate rather than a separate ability.
         assertActorCanPerform(ctx.requestContext, collectionPath, 'changeStatus');
@@ -563,9 +574,16 @@ export async function unpublishDocument(ctx, params) {
             }).log(ctx.logger);
         }
         const hooks = definition.hooks;
+        // Resolve the document's canonical path so the hooks can target the
+        // specific document/URL (CDN purge, cache-key drop).
+        const path = (await db.queries.documents.getCurrentPath({
+            collection_id: collectionId,
+            document_id: params.documentId,
+        })) ?? '';
         await invokeHook(hooks?.beforeUnpublish, {
             documentId: params.documentId,
             collectionPath,
+            path,
         });
         const archivedCount = await db.commands.documents.archivePublishedVersions({
             document_id: params.documentId,
@@ -573,6 +591,7 @@ export async function unpublishDocument(ctx, params) {
         await invokeHook(hooks?.afterUnpublish, {
             documentId: params.documentId,
             collectionPath,
+            path,
             archivedCount,
         });
         return { archivedCount };
@@ -709,13 +728,15 @@ export async function restoreDocumentVersion(ctx, params) {
         });
         const documentId = extractDocumentId(result.document) || params.documentId;
         const documentVersionId = extractVersionId(result.document);
-        // 7. afterUpdate.
+        // 7. afterUpdate. Restore is path-sticky: the canonical path comes
+        //    from the current version's envelope (originalData), not the source.
         await invokeHook(hooks?.afterUpdate, {
             data: sourceFields,
             originalData,
             collectionPath,
             documentId,
             documentVersionId,
+            path: originalData.path ?? '',
             restore: restoreContext,
         });
         return {
@@ -797,6 +818,11 @@ export async function deleteDocument(ctx, params) {
         const hookCtx = {
             documentId: params.documentId,
             collectionPath,
+            // The current document was fetched above (reconstructed only for
+            // upload collections, but the envelope carries the locale-resolved
+            // `path` projection either way). Surface it so delete hooks can purge
+            // the specific document/URL.
+            path: latest.path ?? '',
         };
         // 2. beforeDelete hook.
         await invokeHook(hooks?.beforeDelete, hookCtx);
@@ -1041,6 +1067,7 @@ export async function duplicateDocument(ctx, params) {
             collectionPath,
             documentId: newDocumentId,
             documentVersionId: newDocumentVersionId,
+            path: finalPath,
             duplicate: duplicateMarker,
         });
         return {
@@ -1330,6 +1357,9 @@ export async function copyToLocale(ctx, params) {
             collectionPath,
             documentId: params.documentId,
             documentVersionId,
+            // Path is sticky and source-locale-anchored; copy-to-locale never
+            // touches it. Read it off the target envelope.
+            path: targetRecord.path ?? '',
             copyToLocale: copyToLocaleMarker,
         });
         return {
@@ -1436,6 +1466,9 @@ export async function deleteLocale(ctx, params) {
             collectionPath,
             documentId: params.documentId,
             documentVersionId: result.newVersionId,
+            // Path is sticky and source-locale-anchored; deleting a translation
+            // never touches it. Read it off the target envelope.
+            path: targetRecord.path ?? '',
             deleteLocale: deleteLocaleMarker,
         });
         return {

package/dist/services/document-lifecycle.test.node.js

@@ -35,6 +35,7 @@ function createMockDb() {
     const softDeleteDocument = vi.fn().mockResolvedValue(1);
     const getDocumentById = vi.fn().mockResolvedValue(null);
     const getCurrentVersionMetadata = vi.fn().mockResolvedValue(null);
+    const getCurrentPath = vi.fn().mockResolvedValue('current-path');
     const db = {
         commands: {
             collections: {
@@ -64,6 +65,7 @@ function createMockDb() {
             documents: {
                 getDocumentById,
                 getCurrentVersionMetadata,
+                getCurrentPath,
                 getDocumentByPath: vi.fn(),
                 getDocumentByVersion: vi.fn(),
                 getDocumentsByVersionIds: vi.fn(),
@@ -87,6 +89,7 @@ function createMockDb() {
         softDeleteDocument,
         getDocumentById,
         getCurrentVersionMetadata,
+        getCurrentPath,
     };
 }
 const noopLogger = {
@@ -165,6 +168,14 @@ describe('Document lifecycle service', () => {
                 documentVersionId: 'ver-1',
             }));
         });
+        it('afterCreate receives the resolved canonical path', async () => {
+            const afterCreate = vi.fn();
+            const { db } = createMockDb();
+            const definition = { ...minimalCollection, hooks: { afterCreate } };
+            const ctx = buildCtx(db, definition);
+            await createDocument(ctx, { data: { title: 'X' }, path: 'my-explicit-path' });
+            expect(afterCreate).toHaveBeenCalledWith(expect.objectContaining({ path: 'my-explicit-path' }));
+        });
         it('beforeCreate can mutate data before persistence', async () => {
             const { db, createDocumentVersion } = createMockDb();
             const definition = {
@@ -328,6 +339,36 @@ describe('Document lifecycle service', () => {
                 documentVersionId: 'ver-1',
             }));
         });
+        it('afterUpdate carries the sticky path forward when none is supplied', async () => {
+            const afterUpdate = vi.fn();
+            const { db, getDocumentById } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'prev-ver',
+                path: 'sticky-path',
+                fields: { title: 'Old' },
+            });
+            const definition = { ...minimalCollection, hooks: { afterUpdate } };
+            const ctx = buildCtx(db, definition);
+            await updateDocument(ctx, { documentId: 'doc-1', data: { title: 'New' } });
+            expect(afterUpdate).toHaveBeenCalledWith(expect.objectContaining({ path: 'sticky-path' }));
+        });
+        it('afterUpdate surfaces an explicitly-supplied path', async () => {
+            const afterUpdate = vi.fn();
+            const { db, getDocumentById } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'prev-ver',
+                path: 'sticky-path',
+                fields: { title: 'Old' },
+            });
+            const definition = { ...minimalCollection, hooks: { afterUpdate } };
+            const ctx = buildCtx(db, definition);
+            await updateDocument(ctx, {
+                documentId: 'doc-1',
+                data: { title: 'New' },
+                path: 'new-path',
+            });
+            expect(afterUpdate).toHaveBeenCalledWith(expect.objectContaining({ path: 'new-path' }));
+        });
         it('does not pass path to the storage primitive when no explicit path is supplied', async () => {
             const { db, getDocumentById, createDocumentVersion } = createMockDb();
             getDocumentById.mockResolvedValue({
@@ -641,7 +682,9 @@ describe('Document lifecycle service', () => {
                 nextStatus: 'published',
                 documentId: 'doc-1',
                 documentVersionId: 'ver-1',
+                path: 'current-path',
             }));
+            expect(hooks.afterStatusChange).toHaveBeenCalledWith(expect.objectContaining({ path: 'current-path' }));
         });
         it('does not invoke hooks when transition is invalid', async () => {
             const hooks = {
@@ -728,9 +771,11 @@ describe('Document lifecycle service', () => {
             const ctx = buildCtx(db, definition);
             await unpublishDocument(ctx, { documentId: 'doc-1' });
             expect(callOrder).toEqual(['before', 'archive', 'after']);
+            expect(hooks.beforeUnpublish).toHaveBeenCalledWith(expect.objectContaining({ documentId: 'doc-1', path: 'current-path' }));
             expect(hooks.afterUnpublish).toHaveBeenCalledWith(expect.objectContaining({
                 documentId: 'doc-1',
                 archivedCount: 2,
+                path: 'current-path',
             }));
         });
         it('works when no hooks are defined', async () => {
@@ -772,6 +817,27 @@ describe('Document lifecycle service', () => {
         });
     });
     // -----------------------------------------------------------------------
+    // deleteDocument
+    // -----------------------------------------------------------------------
+    describe('deleteDocument', () => {
+        it('invokes beforeDelete / afterDelete with the document path', async () => {
+            const beforeDelete = vi.fn();
+            const afterDelete = vi.fn();
+            const { db, getDocumentById } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'ver-1',
+                document_id: 'doc-1',
+                path: 'doc-to-delete',
+                fields: {},
+            });
+            const definition = { ...minimalCollection, hooks: { beforeDelete, afterDelete } };
+            const ctx = buildCtx(db, definition);
+            await deleteDocument(ctx, { documentId: 'doc-1' });
+            expect(beforeDelete).toHaveBeenCalledWith(expect.objectContaining({ documentId: 'doc-1', path: 'doc-to-delete' }));
+            expect(afterDelete).toHaveBeenCalledWith(expect.objectContaining({ documentId: 'doc-1', path: 'doc-to-delete' }));
+        });
+    });
+    // -----------------------------------------------------------------------
     // restoreDocumentVersion
     // -----------------------------------------------------------------------
     describe('restoreDocumentVersion', () => {
@@ -916,6 +982,8 @@ describe('Document lifecycle service', () => {
             expect(afterUpdate).toHaveBeenCalledWith(expect.objectContaining({
                 documentId: 'doc-1',
                 documentVersionId: 'ver-restored',
+                // Sticky path comes from the current version's envelope, not the source.
+                path: 'sticky-path',
                 restore: { sourceVersionId },
             }));
         });
@@ -1195,6 +1263,11 @@ describe('Document lifecycle service', () => {
             expect(afterCtx.duplicate).toEqual({ sourceDocumentId: 'doc-source' });
             expect(afterCtx.documentId).toBe('doc-new');
             expect(afterCtx.documentVersionId).toBe('ver-new');
+            // afterCreate carries the final path written for the duplicate — the
+            // same value handed to createDocumentVersion.
+            const writtenPath = mocks.createDocumentVersion.mock.calls[0]?.[0]?.path;
+            expect(typeof afterCtx.path).toBe('string');
+            expect(afterCtx.path).toBe(writtenPath);
         });
         it('enforces collections.<path>.create — rejects an admin actor missing the ability', async () => {
             const mocks = createMockDb();
@@ -1484,6 +1557,8 @@ describe('Document lifecycle service', () => {
                 sourceLocale: 'en',
                 targetLocale: 'fr',
             });
+            // Sticky path read off the target-locale envelope.
+            expect(afterUpdate.mock.calls[0]?.[0].path).toBe('hello');
         });
         it('enforces collections.<path>.update — rejects an admin actor missing the ability', async () => {
             const { mocks } = setupSourceTarget();

package/dist/services/field-upload.test.node.js

@@ -73,6 +73,7 @@ function createMockDb() {
             documents: {
                 getDocumentById: vi.fn(),
                 getCurrentVersionMetadata: vi.fn(),
+                getCurrentPath: vi.fn(),
                 getDocumentByPath: vi.fn(),
                 getDocumentByVersion: vi.fn(),
                 getDocumentsByVersionIds: vi.fn(),

package/dist/services/populate.test.node.js

@@ -161,6 +161,7 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
             documents: {
                 getDocumentById: vi.fn(),
                 getCurrentVersionMetadata: vi.fn(),
+                getCurrentPath: vi.fn(),
                 getDocumentByPath: vi.fn(),
                 getDocumentByVersion: vi.fn(),
                 getDocumentsByVersionIds: vi.fn(),

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "3.0.2"
+    "@byline/auth": "3.1.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",