@byline/host-tanstack-start 4.18.0 → 5.0.0

package/src/server-fns/singletons/copy-to-locale.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
@@ -10,23 +11,34 @@ import { createServerFn } from '@tanstack/react-start'
 
 import { getAdminBylineClient } from '@byline/client/server'
 
+import { toCommittedDocumentHookFailureResponse } from '../collections/save-outcome.js'
 import { serialise } from '../serialise.js'
 
 export const copySingletonToLocale = createServerFn({ method: 'POST' })
   .validator(
     (input: {
+      expectedRevision: number
       singleton: string
       sourceLocale: string
       targetLocale: string
       overwrite?: boolean
     }) => input
   )
-  .handler(async ({ data }) =>
-    serialise(
-      await getAdminBylineClient().singleton(data.singleton).copyToLocale({
-        sourceLocale: data.sourceLocale,
-        targetLocale: data.targetLocale,
-        overwrite: data.overwrite,
-      })
-    )
+  .handler(
+    withDocumentMutationErrors(async ({ data }) => {
+      try {
+        return serialise(
+          await getAdminBylineClient().singleton(data.singleton).copyToLocale({
+            expectedRevision: data.expectedRevision,
+            sourceLocale: data.sourceLocale,
+            targetLocale: data.targetLocale,
+            overwrite: data.overwrite,
+          })
+        )
+      } catch (error) {
+        const committedFailure = toCommittedDocumentHookFailureResponse(error)
+        if (committedFailure != null) return committedFailure
+        throw error
+      }
+    })
   )

package/src/server-fns/singletons/get.ts

@@ -23,9 +23,9 @@ export interface GetSingletonInput {
  * - this shared host layer owns lenient reads, raw missing-locale values,
  *   relation-summary population, transport serialization, and preservation of
  *   restore warnings and locale metadata;
- * - the route loader composes published-version metadata plus scheduled-
- *   publication enablement, capability, and schedule aliases because those
- *   require host-only database and actor context beyond the singleton handle.
+ * - the route loader composes the informational published-version badge, feature
+ *   enablement, capability, and schedule aliases. Schedule state itself comes
+ *   from the same editable snapshot as the source document.
  */
 export const getSingleton = createServerFn({ method: 'GET' })
   .validator((input: GetSingletonInput) => input)

package/src/server-fns/singletons/restore-version.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
@@ -10,10 +11,23 @@ import { createServerFn } from '@tanstack/react-start'
 
 import { getAdminBylineClient } from '@byline/client/server'
 
+import { toCommittedDocumentHookFailureResponse } from '../collections/save-outcome.js'
 import { serialise } from '../serialise.js'
 
 export const restoreSingletonVersion = createServerFn({ method: 'POST' })
-  .validator((input: { singleton: string; versionId: string }) => input)
-  .handler(async ({ data }) =>
-    serialise(await getAdminBylineClient().singleton(data.singleton).restoreVersion(data.versionId))
+  .validator((input: { expectedRevision: number; singleton: string; versionId: string }) => input)
+  .handler(
+    withDocumentMutationErrors(async ({ data }) => {
+      try {
+        return serialise(
+          await getAdminBylineClient()
+            .singleton(data.singleton)
+            .restoreVersion(data.versionId, { expectedRevision: data.expectedRevision })
+        )
+      } catch (error) {
+        const committedFailure = toCommittedDocumentHookFailureResponse(error)
+        if (committedFailure != null) return committedFailure
+        throw error
+      }
+    })
   )

package/src/server-fns/singletons/schedule-publish.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
@@ -13,12 +14,22 @@ import { getAdminBylineClient } from '@byline/client/server'
 import { serialise } from '../serialise.js'
 
 export const scheduleSingletonPublish = createServerFn({ method: 'POST' })
-  .validator((input: { singleton: string; publishAt: string; expectedVersionId: string }) => input)
-  .handler(async ({ data }) =>
-    serialise(
-      await getAdminBylineClient().singleton(data.singleton).schedulePublish({
-        publishAt: data.publishAt,
-        expectedVersionId: data.expectedVersionId,
-      })
+  .validator(
+    (input: {
+      expectedRevision: number
+      singleton: string
+      publishAt: string
+      expectedVersionId: string
+    }) => input
+  )
+  .handler(
+    withDocumentMutationErrors(async ({ data }) =>
+      serialise(
+        await getAdminBylineClient().singleton(data.singleton).schedulePublish({
+          publishAt: data.publishAt,
+          expectedRevision: data.expectedRevision,
+          expectedVersionId: data.expectedVersionId,
+        })
+      )
     )
   )

package/src/server-fns/singletons/singletons.test.node.ts

@@ -6,6 +6,12 @@
  * Copyright (c) Infonomic Company Limited
  */
 
+import {
+  ERR_DOCUMENT_HOOK_COMMITTED,
+  ERR_LOCK_CONFLICT,
+  ErrorCodes,
+  getLockConflictDetails,
+} from '@byline/core'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 const mocks = vi.hoisted(() => ({
@@ -56,7 +62,7 @@ const invoke = (serverFunction: unknown, data: Record<string, any>) =>
   (serverFunction as ServerFunction)({ data })
 
 const handle = {
-  get: vi.fn(),
+  getForEdit: vi.fn(),
   update: vi.fn(),
   changeStatus: vi.fn(),
   unpublish: vi.fn(),
@@ -83,14 +89,13 @@ describe('singleton server functions', () => {
     const cases = [
       {
         serverFunction: getSingleton,
-        method: 'get',
+        method: 'getForEdit',
         input: { singleton: 'site-settings', locale: 'fr' },
         args: [
           {
             locale: 'fr',
             populate: undefined,
             depth: undefined,
-            status: 'any',
             onMissingLocale: 'empty',
             lenient: true,
           },
@@ -104,23 +109,23 @@ describe('singleton server functions', () => {
           singleton: 'site-settings',
           data: { title: 'Changed' },
           locale: 'fr',
-          expectedVersionId: 'version-1',
+          expectedRevision: 7,
         },
-        args: [{ title: 'Changed' }, { locale: 'fr', expectedVersionId: 'version-1' }],
+        args: [{ title: 'Changed' }, { locale: 'fr', expectedRevision: 7 }],
         result: { versionId: 'version-2' },
       },
       {
         serverFunction: changeSingletonStatus,
         method: 'changeStatus',
-        input: { singleton: 'site-settings', status: 'published' },
-        args: ['published'],
+        input: { singleton: 'site-settings', status: 'published', expectedRevision: 7 },
+        args: ['published', { expectedRevision: 7 }],
         result: { newStatus: 'published' },
       },
       {
         serverFunction: unpublishSingleton,
         method: 'unpublish',
-        input: { singleton: 'site-settings' },
-        args: [],
+        input: { singleton: 'site-settings', expectedRevision: 7 },
+        args: [{ expectedRevision: 7 }],
         result: { archivedCount: 1 },
       },
       {
@@ -129,11 +134,13 @@ describe('singleton server functions', () => {
         input: {
           singleton: 'site-settings',
           publishAt: '2026-09-01T10:00:00Z',
+          expectedRevision: 7,
           expectedVersionId: 'version-2',
         },
         args: [
           {
             publishAt: '2026-09-01T10:00:00Z',
+            expectedRevision: 7,
             expectedVersionId: 'version-2',
           },
         ],
@@ -142,15 +149,15 @@ describe('singleton server functions', () => {
       {
         serverFunction: confirmSingletonScheduledPublish,
         method: 'confirmScheduledPublish',
-        input: { singleton: 'site-settings', expectedVersionId: 'version-3' },
-        args: [{ expectedVersionId: 'version-3' }],
+        input: { singleton: 'site-settings', expectedRevision: 7, expectedVersionId: 'version-3' },
+        args: [{ expectedRevision: 7, expectedVersionId: 'version-3' }],
         result: { state: 'armed' },
       },
       {
         serverFunction: cancelSingletonScheduledPublish,
         method: 'cancelScheduledPublish',
-        input: { singleton: 'site-settings' },
-        args: [],
+        input: { singleton: 'site-settings', expectedRevision: 7 },
+        args: [{ expectedRevision: 7 }],
         result: { state: 'cancelled' },
       },
       {
@@ -184,8 +191,8 @@ describe('singleton server functions', () => {
       {
         serverFunction: restoreSingletonVersion,
         method: 'restoreVersion',
-        input: { singleton: 'site-settings', versionId: 'version-1' },
-        args: ['version-1'],
+        input: { singleton: 'site-settings', versionId: 'version-1', expectedRevision: 7 },
+        args: ['version-1', { expectedRevision: 7 }],
         result: { versionId: 'version-4' },
       },
       {
@@ -193,18 +200,23 @@ describe('singleton server functions', () => {
         method: 'copyToLocale',
         input: {
           singleton: 'site-settings',
+          expectedRevision: 7,
           sourceLocale: 'en',
           targetLocale: 'fr',
           overwrite: true,
         },
-        args: [{ sourceLocale: 'en', targetLocale: 'fr', overwrite: true }],
+        args: [{ expectedRevision: 7, sourceLocale: 'en', targetLocale: 'fr', overwrite: true }],
         result: { versionId: 'version-5' },
       },
     ] as const
 
     for (const testCase of cases) {
       const method = handle[testCase.method]
-      method.mockResolvedValueOnce(testCase.result)
+      method.mockResolvedValueOnce(
+        testCase.method === 'getForEdit'
+          ? { state: 'document', document: testCase.result }
+          : testCase.result
+      )
 
       const result = await invoke(testCase.serverFunction, testCase.input)
 
@@ -218,24 +230,59 @@ describe('singleton server functions', () => {
     }
   })
 
-  it('forwards the optimistic version to update unchanged', async () => {
+  it('forwards the observed revision to update unchanged', async () => {
     handle.update.mockResolvedValueOnce({ versionId: 'version-next' })
 
     await invoke(updateSingleton, {
       singleton: 'site-settings',
       data: { title: 'Changed' },
-      expectedVersionId: 'version-current',
+      expectedRevision: 7,
     })
 
     expect(handle.update).toHaveBeenCalledWith(
       { title: 'Changed' },
-      { locale: undefined, expectedVersionId: 'version-current' }
+      { locale: undefined, expectedRevision: 7 }
     )
   })
 
+  it.each([
+    ['update', updateSingleton, { singleton: 'site-settings', data: { title: 'Changed' } }],
+    [
+      'copyToLocale',
+      copySingletonToLocale,
+      { singleton: 'site-settings', sourceLocale: 'en', targetLocale: 'fr' },
+    ],
+    [
+      'restoreVersion',
+      restoreSingletonVersion,
+      { singleton: 'site-settings', versionId: 'version-1' },
+    ],
+  ] as const)('returns a committed hook outcome for %s', async (method, serverFunction, input) => {
+    handle[method].mockRejectedValueOnce(
+      ERR_DOCUMENT_HOOK_COMMITTED({
+        message: 'write committed',
+        details: {
+          phase: 'afterSave',
+          documentId: 'doc-settings',
+          documentVersionId: 'version-next',
+          revision: 8,
+          sideEffectCode: ErrorCodes.UNHANDLED,
+        },
+      })
+    )
+
+    await expect(invoke(serverFunction, input)).resolves.toEqual({
+      status: 'committed-hook-failed',
+      documentId: 'doc-settings',
+      documentVersionId: 'version-next',
+      revision: 8,
+      sideEffectFailure: { phase: 'afterSave', code: ErrorCodes.UNHANDLED },
+    })
+  })
+
   it('preserves authentication failures from the handle', async () => {
     const error = { code: 'ERR_UNAUTHENTICATED', message: 'sign in required' }
-    handle.get.mockRejectedValueOnce(error)
+    handle.getForEdit.mockRejectedValueOnce(error)
 
     await expect(invoke(getSingleton, { singleton: 'site-settings' })).rejects.toBe(error)
   })
@@ -267,9 +314,34 @@ describe('singleton server functions', () => {
     expect(mocks.resolveActorLabels).toHaveBeenCalledWith([])
   })
 
+  it('preserves confirmed lock failures as safe wire data through the host', async () => {
+    const conflict = ERR_LOCK_CONFLICT({
+      message: 'private diagnostic',
+      cause: new Error('driver SQL'),
+    })
+    handle.update.mockRejectedValueOnce(conflict)
+    let received: unknown
+    try {
+      await invoke(updateSingleton, {
+        singleton: 'site-settings',
+        data: { title: 'Changed' },
+        expectedRevision: 6,
+      })
+    } catch (error) {
+      received = error
+    }
+    expect(received).not.toHaveProperty('cause')
+    expect(getLockConflictDetails(JSON.parse(JSON.stringify(received)))).toEqual({
+      reason: 'lock_conflict',
+      rolledBack: true,
+      retryable: true,
+    })
+    expect(handle.update).toHaveBeenCalledTimes(1)
+  })
+
   it('keeps missing-slot and stale-write failures distinguishable', async () => {
     const missing = { code: 'ERR_NOT_FOUND', message: 'slot is empty' }
-    const stale = { code: 'ERR_CONFLICT', message: 'version changed' }
+    const stale = { code: 'ERR_DOCUMENT_STALE', message: 'document changed' }
     handle.changeStatus.mockRejectedValueOnce(missing)
     handle.update.mockRejectedValueOnce(stale)
 
@@ -280,9 +352,9 @@ describe('singleton server functions', () => {
       invoke(updateSingleton, {
         singleton: 'site-settings',
         data: { title: 'Changed' },
-        expectedVersionId: 'stale',
+        expectedRevision: 6,
       })
-    ).rejects.toMatchObject({ code: 'ERR_CONFLICT' })
+    ).rejects.toMatchObject({ code: 'ERR_DOCUMENT_STALE' })
   })
 
   it('serialises schedule dates at the transport boundary', async () => {

package/src/server-fns/singletons/unpublish.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
@@ -13,7 +14,13 @@ import { getAdminBylineClient } from '@byline/client/server'
 import { serialise } from '../serialise.js'
 
 export const unpublishSingleton = createServerFn({ method: 'POST' })
-  .validator((input: { singleton: string }) => input)
-  .handler(async ({ data }) =>
-    serialise(await getAdminBylineClient().singleton(data.singleton).unpublish())
+  .validator((input: { expectedRevision: number; singleton: string }) => input)
+  .handler(
+    withDocumentMutationErrors(async ({ data }) =>
+      serialise(
+        await getAdminBylineClient()
+          .singleton(data.singleton)
+          .unpublish({ expectedRevision: data.expectedRevision })
+      )
+    )
   )

package/src/server-fns/singletons/update.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
@@ -9,23 +10,34 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { getAdminBylineClient } from '@byline/client/server'
+import type { SingletonSavePrecondition } from '@byline/core'
 
+import { toCommittedDocumentHookFailureResponse } from '../collections/save-outcome.js'
 import { serialise } from '../serialise.js'
 
-export interface UpdateSingletonInput {
+export type UpdateSingletonInput = SingletonSavePrecondition & {
   singleton: string
   data: Record<string, any>
   locale?: string
-  expectedVersionId?: string
 }
 
 export const updateSingleton = createServerFn({ method: 'POST' })
   .validator((input: UpdateSingletonInput) => input)
-  .handler(async ({ data }) => {
-    const { singleton, data: fields, locale, expectedVersionId } = data
-    const result = await getAdminBylineClient().singleton(singleton).update(fields, {
-      locale,
-      expectedVersionId,
+  .handler(
+    withDocumentMutationErrors(async ({ data }) => {
+      const { singleton, data: fields, locale, ...precondition } = data
+      try {
+        const result = await getAdminBylineClient()
+          .singleton(singleton)
+          .update(fields, {
+            locale,
+            ...precondition,
+          })
+        return serialise(result)
+      } catch (error) {
+        const committedFailure = toCommittedDocumentHookFailureResponse(error)
+        if (committedFailure != null) return committedFailure
+        throw error
+      }
     })
-    return serialise(result)
-  })
+  )

package/src/server-fns/structural-receipt.ts

@@ -0,0 +1,41 @@
+import { ErrorCodes, isDocumentRevision, type StructuralMutationReceipt } from '@byline/core'
+
+/** Copy only the authorized receipt fields emitted by the lifecycle service. */
+export function structuralReceipt(value: unknown): StructuralMutationReceipt | null {
+  if (typeof value !== 'object' || value === null) return null
+  const documentId = Reflect.get(value, 'documentId')
+  const revision = Reflect.get(value, 'revision')
+  const suspended = Reflect.get(value, 'scheduledPublicationsNeedReconfirmation')
+  const affected = Reflect.get(value, 'affectedDocuments')
+  if (
+    typeof documentId !== 'string' ||
+    !isDocumentRevision(revision) ||
+    typeof suspended !== 'boolean' ||
+    !Array.isArray(affected)
+  )
+    return null
+  const affectedDocuments = []
+  for (const row of affected) {
+    if (typeof row !== 'object' || row === null) return null
+    const id = Reflect.get(row, 'documentId')
+    const token = Reflect.get(row, 'revision')
+    if (typeof id !== 'string' || !isDocumentRevision(token)) return null
+    affectedDocuments.push({ documentId: id, revision: token })
+  }
+  return {
+    documentId,
+    revision,
+    affectedDocuments,
+    scheduledPublicationsNeedReconfirmation: suspended,
+  }
+}
+
+export function committedTreeReceipt(error: unknown): StructuralMutationReceipt | null {
+  if (
+    typeof error !== 'object' ||
+    error === null ||
+    Reflect.get(error, 'code') !== ErrorCodes.TREE_HOOK_COMMITTED
+  )
+    return null
+  return structuralReceipt(Reflect.get(error, 'details'))
+}