@byline/host-tanstack-start 4.19.0 → 5.0.0

package/src/server-fns/collections/scheduled-publication.ts

@@ -1,3 +1,4 @@
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 /**
  * This Source Code is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -66,6 +67,7 @@ export type SerializedDocumentPublishSchedule = Omit<
 }
 
 export interface ScheduledPublicationListItem extends SerializedDocumentPublishSchedule {
+  revision: number
   collectionPath: string
   collectionLabel: string
   documentPath: string | null
@@ -137,49 +139,75 @@ async function scheduledPublicationRuntime(): Promise<ScheduledPublicationRuntim
 
 /** Authenticated feature discovery for the admin shell and health warning. */
 export const getScheduledPublicationRuntime = createServerFn({ method: 'GET' }).handler(
-  async () => {
+  withDocumentMutationErrors(async () => {
     await getAdminRequestContext()
     return scheduledPublicationRuntime()
-  }
+  })
 )
 
 export const scheduleCollectionDocumentPublish = createServerFn({ method: 'POST' })
   .validator(
-    (input: { collection: string; id: string; publishAt: string; expectedVersionId: string }) =>
-      input
+    (input: {
+      expectedRevision: number
+      collection: string
+      id: string
+      publishAt: string
+      expectedVersionId: string
+    }) => input
+  )
+  .handler(
+    withDocumentMutationErrors(async ({ data }) => {
+      assertFeatureEnabled()
+      const schedule = await getAdminBylineClient()
+        .collection(data.collection)
+        .schedulePublish(data.id, {
+          publishAt: data.publishAt,
+          expectedRevision: data.expectedRevision,
+          expectedVersionId: data.expectedVersionId,
+        })
+      return { ...serializeSchedule(schedule), revision: schedule.revision }
+    })
   )
-  .handler(async ({ data }) => {
-    assertFeatureEnabled()
-    const schedule = await getAdminBylineClient()
-      .collection(data.collection)
-      .schedulePublish(data.id, {
-        publishAt: data.publishAt,
-        expectedVersionId: data.expectedVersionId,
-      })
-    return serializeSchedule(schedule)
-  })
 
 export const confirmCollectionDocumentScheduledPublish = createServerFn({ method: 'POST' })
-  .validator((input: { collection: string; id: string; expectedVersionId: string }) => input)
-  .handler(async ({ data }) => {
-    assertFeatureEnabled()
-    const schedule = await getAdminBylineClient()
-      .collection(data.collection)
-      .confirmScheduledPublish(data.id, { expectedVersionId: data.expectedVersionId })
-    return serializeSchedule(schedule)
-  })
+  .validator(
+    (input: {
+      expectedRevision: number
+      collection: string
+      id: string
+      expectedVersionId: string
+    }) => input
+  )
+  .handler(
+    withDocumentMutationErrors(async ({ data }) => {
+      assertFeatureEnabled()
+      const schedule = await getAdminBylineClient()
+        .collection(data.collection)
+        .confirmScheduledPublish(data.id, {
+          expectedRevision: data.expectedRevision,
+          expectedVersionId: data.expectedVersionId,
+        })
+      return { ...serializeSchedule(schedule), revision: schedule.revision }
+    })
+  )
 
 export const cancelCollectionDocumentScheduledPublish = createServerFn({ method: 'POST' })
-  .validator((input: { collection: string; id: string }) => input)
-  .handler(async ({ data }) => {
-    assertFeatureEnabled()
-    const schedule = await getAdminBylineClient()
-      .collection(data.collection)
-      .cancelScheduledPublish(data.id)
-    return schedule == null
-      ? { status: 'not_found' as const }
-      : { status: 'cancelled' as const, schedule: serializeSchedule(schedule) }
-  })
+  .validator((input: { expectedRevision: number; collection: string; id: string }) => input)
+  .handler(
+    withDocumentMutationErrors(async ({ data }) => {
+      assertFeatureEnabled()
+      const schedule = await getAdminBylineClient()
+        .collection(data.collection)
+        .cancelScheduledPublish(data.id, { expectedRevision: data.expectedRevision })
+      return schedule.schedule == null
+        ? { status: 'not_found' as const, revision: schedule.revision }
+        : {
+            status: 'cancelled' as const,
+            schedule: serializeSchedule(schedule.schedule),
+            revision: schedule.revision,
+          }
+    })
+  )
 
 export const listScheduledPublications = createServerFn({ method: 'GET' })
   .validator(
@@ -190,87 +218,86 @@ export const listScheduledPublications = createServerFn({ method: 'GET' })
       pageSize?: number
     }) => input
   )
-  .handler(async ({ data }) => {
-    assertFeatureEnabled()
-    if (data.states?.some((state) => state !== 'armed' && state !== 'needs_reconfirm') === true) {
-      throw ERR_VALIDATION({ message: 'state must be armed or needs_reconfirm' })
-    }
-    if (data.lastAuthorizedBy != null && !UUID_RE.test(data.lastAuthorizedBy)) {
-      throw ERR_VALIDATION({ message: 'lastAuthorizedBy must be a UUID' })
-    }
-    const core = bylineCore()
-    const page = data.page ?? 1
-    const pageSize = data.pageSize ?? 25
-    const requestContext = await getAdminRequestContext()
-    const result = await listDocumentPublishSchedules(core, requestContext, {
-      states: data.states,
-      lastAuthorizedBy: data.lastAuthorizedBy,
-      page,
-      pageSize,
-    })
-    const collections = new Map(
-      core.collections.map((definition) => {
-        const record = core.getCollectionRecord(definition.path)
-        return [record.collectionId, definition] as const
+  .handler(
+    withDocumentMutationErrors(async ({ data }) => {
+      assertFeatureEnabled()
+      if (data.states?.some((state) => state !== 'armed' && state !== 'needs_reconfirm') === true) {
+        throw ERR_VALIDATION({ message: 'state must be armed or needs_reconfirm' })
+      }
+      if (data.lastAuthorizedBy != null && !UUID_RE.test(data.lastAuthorizedBy)) {
+        throw ERR_VALIDATION({ message: 'lastAuthorizedBy must be a UUID' })
+      }
+      const core = bylineCore()
+      const page = data.page ?? 1
+      const pageSize = data.pageSize ?? 25
+      const requestContext = await getAdminRequestContext()
+      const result = await listDocumentPublishSchedules(core, requestContext, {
+        states: data.states,
+        lastAuthorizedBy: data.lastAuthorizedBy,
+        page,
+        pageSize,
       })
-    )
-    // Resolve authorizer names in one query for the whole page rather than one
-    // per row. `last_authorized_by` is deliberately not a foreign key — deleting
-    // an admin account must not revoke a schedule it authorized — so an id here
-    // may simply have no user row left, and the caller falls back to the id.
-    const authorizerIds = [
-      ...new Set(
-        result.schedules
-          .map((schedule) => schedule.lastAuthorizedBy)
-          .filter((id): id is string => id != null)
-      ),
-    ]
-    const authorizerNames = new Map<string, string>()
-    // `adminStore` is optional on core — an installation can run without the
-    // admin subsystem — so a missing store simply means no names to resolve and
-    // the column falls back to ids.
-    const adminUsers = core.adminStore?.adminUsers
-    if (authorizerIds.length > 0 && adminUsers != null) {
-      const users = await adminUsers.getByIds(authorizerIds)
-      for (const user of users) {
-        const fullName = [user.given_name, user.family_name].filter(Boolean).join(' ').trim()
-        authorizerNames.set(user.id, fullName.length > 0 ? fullName : user.email)
+      const collections = new Map(
+        core.collections.map((definition) => {
+          const record = core.getCollectionRecord(definition.path)
+          return [record.collectionId, definition] as const
+        })
+      )
+      // Resolve authorizer names in one query for the whole page rather than one
+      // per row. `last_authorized_by` is deliberately not a foreign key — deleting
+      // an admin account must not revoke a schedule it authorized — so an id here
+      // may simply have no user row left, and the caller falls back to the id.
+      const authorizerIds = [
+        ...new Set(
+          result.schedules
+            .map((schedule) => schedule.lastAuthorizedBy)
+            .filter((id): id is string => id != null)
+        ),
+      ]
+      const authorizerNames = new Map<string, string>()
+      // `adminStore` is optional on core — an installation can run without the
+      // admin subsystem — so a missing store simply means no names to resolve and
+      // the column falls back to ids.
+      const adminUsers = core.adminStore?.adminUsers
+      if (authorizerIds.length > 0 && adminUsers != null) {
+        const users = await adminUsers.getByIds(authorizerIds)
+        for (const user of users) {
+          const fullName = [user.given_name, user.family_name].filter(Boolean).join(' ').trim()
+          authorizerNames.set(user.id, fullName.length > 0 ? fullName : user.email)
+        }
       }
-    }
 
-    const schedules = await Promise.all(
-      result.schedules.map(async (schedule): Promise<ScheduledPublicationListItem> => {
-        const definition = collections.get(schedule.collectionId)
-        const documentPath = await core.db.queries.documents.getCurrentPath({
-          collection_id: schedule.collectionId,
-          document_id: schedule.documentId,
+      const schedules = await Promise.all(
+        result.schedules.map(async (schedule): Promise<ScheduledPublicationListItem> => {
+          const definition = collections.get(schedule.collectionId)
+          return {
+            ...serializeSchedule(schedule),
+            collectionPath: definition?.path ?? schedule.collectionId,
+            collectionLabel:
+              definition == null
+                ? schedule.collectionId
+                : isSingleton(definition)
+                  ? definition.label
+                  : definition.labels.plural,
+            documentPath: schedule.documentPath,
+            revision: schedule.revision,
+            lastAuthorizedByName:
+              schedule.lastAuthorizedBy == null
+                ? null
+                : (authorizerNames.get(schedule.lastAuthorizedBy) ?? null),
+          }
         })
-        return {
-          ...serializeSchedule(schedule),
-          collectionPath: definition?.path ?? schedule.collectionId,
-          collectionLabel:
-            definition == null
-              ? schedule.collectionId
-              : isSingleton(definition)
-                ? definition.label
-                : definition.labels.plural,
-          documentPath,
-          lastAuthorizedByName:
-            schedule.lastAuthorizedBy == null
-              ? null
-              : (authorizerNames.get(schedule.lastAuthorizedBy) ?? null),
-        }
-      })
-    )
+      )
 
-    return {
-      schedules,
-      meta: {
-        page,
-        pageSize,
-        total: result.total,
-        totalPages: Math.max(1, Math.ceil(result.total / pageSize)),
-      },
-      runtime: await scheduledPublicationRuntime(),
-    } satisfies ScheduledPublicationListResponse
-  })
+      return {
+        schedules,
+        meta: {
+          page,
+          pageSize,
+          total: result.total,
+          totalPages: Math.max(1, Math.ceil(result.total / pageSize)),
+        },
+        runtime: await scheduledPublicationRuntime(),
+      } satisfies ScheduledPublicationListResponse
+    })
+  )

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

@@ -1,3 +1,4 @@
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 /**
  * This Source Code is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -23,80 +24,101 @@ import { ensureCollection } from '../../integrations/api-utils.js'
 // ---------------------------------------------------------------------------
 
 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)
-    }
+  .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)
-    }
+  .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 })
+})