@byline/host-tanstack-start 4.19.0 → 5.1.0

package/src/server-fns/collections/status.ts

@@ -17,86 +17,111 @@ import {
 } from '@byline/core/services'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 
 // ---------------------------------------------------------------------------
 // Change document workflow status
 // ---------------------------------------------------------------------------
 
 export const updateDocumentStatus = createServerFn({ method: 'POST' })
-  .validator((input: { collection: string; id: string; status: string }) => input)
-  .handler(async ({ data: input }) => {
-    const { collection: path, id, status: nextStatus } = input
-    const logger = getLogger()
-    const config = await ensureCollection(path)
-    if (!config) {
-      throw ERR_NOT_FOUND({
-        message: 'Collection not found',
-        details: { collectionPath: path },
-      }).log(logger)
-    }
+  .middleware([adminSessionMiddleware])
+  .validator(
+    (input: { expectedRevision: number; collection: string; id: string; status: string }) => input
+  )
+  .handler(
+    withDocumentMutationErrors(async ({ data: input }) => {
+      const { collection: path, id, status: nextStatus } = input
+      const logger = getLogger()
+      const config = await ensureCollection(path)
+      if (!config) {
+        throw ERR_NOT_FOUND({
+          message: 'Collection not found',
+          details: { collectionPath: path },
+        }).log(logger)
+      }
 
-    const serverConfig = getServerConfig()
-    const ctx: DocumentLifecycleContext = {
-      db: serverConfig.db,
-      definition: config.definition,
-      collectionId: config.collection.id,
-      collectionVersion: config.collection.version,
-      collectionPath: path,
-      logger,
-      defaultLocale: serverConfig.i18n.content.defaultLocale,
-      slugifier: serverConfig.slugifier,
-      requestContext: await getAdminRequestContext(),
-    }
+      const serverConfig = getServerConfig()
+      const ctx: DocumentLifecycleContext = {
+        db: serverConfig.db,
+        definition: config.definition,
+        collectionId: config.collection.id,
+        collectionVersion: config.collection.version,
+        collectionPath: path,
+        logger,
+        defaultLocale: serverConfig.i18n.content.defaultLocale,
+        slugifier: serverConfig.slugifier,
+        requestContext: await getAdminRequestContext(),
+      }
 
-    const result = await changeDocumentStatus(ctx, {
-      documentId: id,
-      nextStatus,
+      const result = await changeDocumentStatus(ctx, {
+        documentId: id,
+        expectedRevision: input.expectedRevision,
+        nextStatus,
+      })
+      return {
+        status: 'ok' as const,
+        documentId: result.documentId,
+        revision: result.revision,
+        previousStatus: result.previousStatus,
+        newStatus: result.newStatus,
+      }
     })
-    return {
-      status: 'ok' as const,
-      previousStatus: result.previousStatus,
-      newStatus: result.newStatus,
-    }
-  })
+  )
 
 // ---------------------------------------------------------------------------
 // Unpublish document (archive the live published version)
 // ---------------------------------------------------------------------------
 
 export const unpublishDocument = createServerFn({ method: 'POST' })
-  .validator((input: { collection: string; id: string }) => input)
-  .handler(async ({ data: input }) => {
-    const { collection: path, id } = input
-    const logger = getLogger()
-    const config = await ensureCollection(path)
-    if (!config) {
-      throw ERR_NOT_FOUND({
-        message: 'Collection not found',
-        details: { collectionPath: path },
-      }).log(logger)
-    }
+  .middleware([adminSessionMiddleware])
+  .validator((input: { expectedRevision: number; collection: string; id: string }) => input)
+  .handler(
+    withDocumentMutationErrors(async ({ data: input }) => {
+      const { collection: path, id } = input
+      const logger = getLogger()
+      const config = await ensureCollection(path)
+      if (!config) {
+        throw ERR_NOT_FOUND({
+          message: 'Collection not found',
+          details: { collectionPath: path },
+        }).log(logger)
+      }
 
-    const serverConfig = getServerConfig()
-    const ctx: DocumentLifecycleContext = {
-      db: serverConfig.db,
-      definition: config.definition,
-      collectionId: config.collection.id,
-      collectionVersion: config.collection.version,
-      collectionPath: path,
-      logger,
-      defaultLocale: serverConfig.i18n.content.defaultLocale,
-      slugifier: serverConfig.slugifier,
-      requestContext: await getAdminRequestContext(),
-    }
+      const serverConfig = getServerConfig()
+      const ctx: DocumentLifecycleContext = {
+        db: serverConfig.db,
+        definition: config.definition,
+        collectionId: config.collection.id,
+        collectionVersion: config.collection.version,
+        collectionPath: path,
+        logger,
+        defaultLocale: serverConfig.i18n.content.defaultLocale,
+        slugifier: serverConfig.slugifier,
+        requestContext: await getAdminRequestContext(),
+      }
 
-    const result = await unpublishDocumentService(ctx, { documentId: id })
+      const result = await unpublishDocumentService(ctx, {
+        documentId: id,
+        expectedRevision: input.expectedRevision,
+      })
 
-    if (result.archivedCount === 0) {
-      throw ERR_NOT_FOUND({
-        message: 'No published version found for this document',
-        details: { documentId: id, collectionPath: path },
-      }).log(logger)
-    }
+      if (result.archivedCount === 0) {
+        throw ERR_NOT_FOUND({
+          message: 'No published version found for this document',
+          details: {
+            documentId: id,
+            expectedRevision: input.expectedRevision,
+            collectionPath: path,
+          },
+        }).log(logger)
+      }
 
-    return { status: 'ok' as const, archivedCount: result.archivedCount }
-  })
+      return {
+        status: 'ok' as const,
+        documentId: result.documentId,
+        revision: result.revision,
+        archivedCount: result.archivedCount,
+      }
+    })
+  )

package/src/server-fns/collections/tree-mutation.test.node.ts

@@ -175,51 +175,109 @@ describe('admin tree mutations', () => {
     expect(controller.isMoving()).toBe(false)
   })
 
-  it('opts ordinary placement retries into lifecycle reconciliation', async () => {
+  const receipt = {
+    documentId: 'doc-1',
+    revision: 2,
+    affectedDocuments: [{ documentId: 'doc-1', revision: 2 }],
+    scheduledPublicationsNeedReconfirmation: false,
+  }
+
+  it('forwards each caller observation and requests reconciliation without retrying', async () => {
     const placeTreeNode = vi
-      .fn()
+      .fn<Parameters<typeof placeAdminTreeNode>[0]['placeTreeNode']>()
       .mockRejectedValueOnce(new Error('post-commit hook failed'))
-      .mockResolvedValue({ orderKey: 'key-1' })
-
-    const retry = () =>
-      placeAdminTreeNode({ placeTreeNode } as any, 'doc-1', {
+      .mockResolvedValue({ orderKey: 'key-1', ...receipt })
+    const handle = { placeTreeNode }
+    await expect(
+      placeAdminTreeNode(handle, 'doc-1', {
+        expectedRevision: 1,
         parentDocumentId: 'parent-1',
         beforeDocumentId: 'left-1',
       })
-
-    await expect(retry()).rejects.toThrow('post-commit hook failed')
-    await expect(retry()).resolves.toEqual({ orderKey: 'key-1' })
-
-    expect(placeTreeNode).toHaveBeenCalledTimes(2)
-    expect(placeTreeNode).toHaveBeenNthCalledWith(
-      2,
-      'doc-1',
-      expect.objectContaining({ reconcile: true })
-    )
+    ).rejects.toThrow('post-commit hook failed')
+    expect(placeTreeNode).toHaveBeenCalledTimes(1)
+    // A separate caller action carries its newly observed receipt, never an implicit retry.
+    await expect(
+      placeAdminTreeNode(handle, 'doc-1', {
+        expectedRevision: 2,
+        parentDocumentId: 'parent-1',
+        beforeDocumentId: 'left-1',
+      })
+    ).resolves.toEqual({ orderKey: 'key-1', ...receipt })
+    expect(placeTreeNode).toHaveBeenNthCalledWith(2, 'doc-1', {
+      expectedRevision: 2,
+      parentDocumentId: 'parent-1',
+      beforeDocumentId: 'left-1',
+      reconcile: true,
+    })
   })
 
-  it('opts ordinary removal retries into lifecycle reconciliation', async () => {
-    const removeFromTree = vi.fn().mockResolvedValue(undefined)
-
-    await removeAdminTreeNode({ removeFromTree } as any, 'doc-1')
-
-    expect(removeFromTree).toHaveBeenCalledWith('doc-1', { reconcile: true })
+  it('requests reconciliation for removal and preserves the caller revision', async () => {
+    const removeFromTree = vi
+      .fn<Parameters<typeof removeAdminTreeNode>[0]['removeFromTree']>()
+      .mockResolvedValue(receipt)
+    await expect(
+      removeAdminTreeNode({ removeFromTree }, 'doc-1', { expectedRevision: 1 })
+    ).resolves.toEqual(receipt)
+    expect(removeFromTree).toHaveBeenCalledWith('doc-1', { expectedRevision: 1, reconcile: true })
   })
 
   it('preserves an explicit reconciliation override', async () => {
-    const placeTreeNode = vi.fn().mockResolvedValue({ orderKey: 'key-1' })
-    const removeFromTree = vi.fn().mockResolvedValue(undefined)
-
-    await placeAdminTreeNode({ placeTreeNode } as any, 'doc-1', {
+    const placeTreeNode = vi
+      .fn<Parameters<typeof placeAdminTreeNode>[0]['placeTreeNode']>()
+      .mockResolvedValue({ orderKey: 'key-1', ...receipt })
+    const removeFromTree = vi
+      .fn<Parameters<typeof removeAdminTreeNode>[0]['removeFromTree']>()
+      .mockResolvedValue(receipt)
+    await placeAdminTreeNode({ placeTreeNode }, 'doc-1', {
+      expectedRevision: 1,
       parentDocumentId: null,
       reconcile: false,
     })
-    await removeAdminTreeNode({ removeFromTree } as any, 'doc-1', { reconcile: false })
-
+    await removeAdminTreeNode({ removeFromTree }, 'doc-1', {
+      expectedRevision: 2,
+      reconcile: false,
+    })
     expect(placeTreeNode).toHaveBeenCalledWith('doc-1', {
+      expectedRevision: 1,
       parentDocumentId: null,
       reconcile: false,
     })
-    expect(removeFromTree).toHaveBeenCalledWith('doc-1', { reconcile: false })
+    expect(removeFromTree).toHaveBeenCalledWith('doc-1', { expectedRevision: 2, reconcile: false })
   })
 })
+
+it('does not refresh or replace the observation after a typed stale tree move', async () => {
+  const error = {
+    code: 'ERR_DOCUMENT_STALE',
+    details: {
+      reason: 'revision_mismatch',
+      documentId: 'doc',
+      expectedRevision: 2,
+      currentRevision: 3,
+    },
+  }
+  const refresh = vi.fn()
+  const mutate = vi.fn().mockRejectedValue(error)
+  expect(await executeAdminTreeMove(mutate, refresh)).toEqual({ status: 'mutation-failed', error })
+  expect(mutate).toHaveBeenCalledTimes(1)
+  expect(refresh).not.toHaveBeenCalled()
+})
+
+it('retains the authorized schedule summary when refresh fails after a committed move', async () => {
+  const receipt = {
+    documentId: 'doc',
+    revision: 3,
+    affectedDocuments: [{ documentId: 'sibling', revision: 4 }],
+    scheduledPublicationsNeedReconfirmation: true,
+  }
+  const error = new Error('refresh unavailable')
+  expect(
+    await executeAdminTreeMove(
+      async () => receipt,
+      async () => {
+        throw error
+      }
+    )
+  ).toEqual({ status: 'refresh-failed', error, receipt })
+})

package/src/server-fns/collections/tree-mutation.ts

@@ -1,5 +1,14 @@
 import type { CollectionHandle, PlaceTreeNodeOptions, RemoveFromTreeOptions } from '@byline/client'
-import { ErrorCodes, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER } from '@byline/core'
+import {
+  ErrorCodes,
+  getDocumentRevisionValidationDetails,
+  getDocumentStaleDetails,
+  getLockConflictDetails,
+  TREE_HOOK_COMMITTED_MARKER,
+  TREE_PLACEMENT_STALE_MARKER,
+} from '@byline/core'
+
+import { structuralReceipt } from '../structural-receipt.js'
 
 function hasErrorCode(error: unknown, code: string): boolean {
   return (
@@ -27,11 +36,11 @@ export function isCommittedTreeHookFailure(error: unknown): boolean {
 }
 
 export type AdminTreeMoveOutcome =
-  | { status: 'ok' }
+  | { status: 'ok'; receipt?: ReturnType<typeof structuralReceipt> }
   | { status: 'suppressed' }
   | { status: 'mutation-failed'; error: unknown; refreshError?: unknown }
   | { status: 'committed-hook-failed'; error: unknown; refreshError?: unknown }
-  | { status: 'refresh-failed'; error: unknown }
+  | { status: 'refresh-failed'; error: unknown; receipt?: ReturnType<typeof structuralReceipt> }
 
 export interface AdminTreeMoveUiEffects {
   rollback: boolean
@@ -93,9 +102,17 @@ export async function executeAdminTreeMove(
   mutate: () => Promise<unknown>,
   refresh: () => Promise<unknown>
 ): Promise<AdminTreeMoveOutcome> {
+  let receipt: ReturnType<typeof structuralReceipt>
   try {
-    await mutate()
+    receipt = structuralReceipt(await mutate())
   } catch (error) {
+    if (
+      getDocumentStaleDetails(error) ||
+      getDocumentRevisionValidationDetails(error) ||
+      getLockConflictDetails(error) ||
+      hasErrorCode(error, ErrorCodes.NOT_FOUND)
+    )
+      return { status: 'mutation-failed', error }
     const status = isCommittedTreeHookFailure(error)
       ? ('committed-hook-failed' as const)
       : ('mutation-failed' as const)
@@ -109,9 +126,9 @@ export async function executeAdminTreeMove(
 
   try {
     await refresh()
-    return { status: 'ok' }
+    return { status: 'ok', ...(receipt ? { receipt } : {}) }
   } catch (error) {
-    return { status: 'refresh-failed', error }
+    return { status: 'refresh-failed', error, ...(receipt ? { receipt } : {}) }
   }
 }
 
@@ -140,24 +157,24 @@ export function createAdminTreeMoveController(): AdminTreeMoveController {
   }
 }
 
-/** Admin retries reconcile post-commit tree hooks unless explicitly disabled. */
+/** Request reconciliation for explicit caller actions; never retry or replace their revision. */
 export function placeAdminTreeNode(
   handle: Pick<CollectionHandle, 'placeTreeNode'>,
   documentId: string,
   options: PlaceTreeNodeOptions
-): Promise<{ orderKey: string }> {
+): ReturnType<CollectionHandle['placeTreeNode']> {
   return handle.placeTreeNode(documentId, {
     ...options,
     reconcile: options.reconcile ?? true,
   })
 }
 
-/** Admin retries reconcile post-commit tree hooks unless explicitly disabled. */
+/** Request reconciliation for explicit caller actions; never retry or replace their revision. */
 export function removeAdminTreeNode(
   handle: Pick<CollectionHandle, 'removeFromTree'>,
   documentId: string,
-  options: RemoveFromTreeOptions = {}
-): Promise<void> {
+  options: RemoveFromTreeOptions
+): ReturnType<CollectionHandle['removeFromTree']> {
   return handle.removeFromTree(documentId, {
     ...options,
     reconcile: options.reconcile ?? true,