@byline/host-tanstack-start 4.19.0 → 5.1.0

package/src/server-fns/singletons/change-status.ts

@@ -10,10 +10,19 @@ import { createServerFn } from '@tanstack/react-start'
 
 import { getAdminBylineClient } from '@byline/client/server'
 
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 import { serialise } from '../serialise.js'
 
 export const changeSingletonStatus = createServerFn({ method: 'POST' })
-  .validator((input: { singleton: string; status: string }) => input)
-  .handler(async ({ data }) =>
-    serialise(await getAdminBylineClient().singleton(data.singleton).changeStatus(data.status))
+  .middleware([adminSessionMiddleware])
+  .validator((input: { expectedRevision: number; singleton: string; status: string }) => input)
+  .handler(
+    withDocumentMutationErrors(async ({ data }) =>
+      serialise(
+        await getAdminBylineClient()
+          .singleton(data.singleton)
+          .changeStatus(data.status, { expectedRevision: data.expectedRevision })
+      )
+    )
   )

package/src/server-fns/singletons/confirm-scheduled-publish.ts

@@ -10,14 +10,22 @@ import { createServerFn } from '@tanstack/react-start'
 
 import { getAdminBylineClient } from '@byline/client/server'
 
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 import { serialise } from '../serialise.js'
 
 export const confirmSingletonScheduledPublish = createServerFn({ method: 'POST' })
-  .validator((input: { singleton: string; expectedVersionId: string }) => input)
-  .handler(async ({ data }) =>
-    serialise(
-      await getAdminBylineClient()
-        .singleton(data.singleton)
-        .confirmScheduledPublish({ expectedVersionId: data.expectedVersionId })
+  .middleware([adminSessionMiddleware])
+  .validator(
+    (input: { expectedRevision: number; singleton: string; expectedVersionId: string }) => input
+  )
+  .handler(
+    withDocumentMutationErrors(async ({ data }) =>
+      serialise(
+        await getAdminBylineClient().singleton(data.singleton).confirmScheduledPublish({
+          expectedRevision: data.expectedRevision,
+          expectedVersionId: data.expectedVersionId,
+        })
+      )
     )
   )

package/src/server-fns/singletons/copy-to-locale.ts

@@ -10,30 +10,37 @@ import { createServerFn } from '@tanstack/react-start'
 
 import { getAdminBylineClient } from '@byline/client/server'
 
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
 import { toCommittedDocumentHookFailureResponse } from '../collections/save-outcome.js'
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 import { serialise } from '../serialise.js'
 
 export const copySingletonToLocale = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMiddleware])
   .validator(
     (input: {
+      expectedRevision: number
       singleton: string
       sourceLocale: string
       targetLocale: string
       overwrite?: boolean
     }) => input
   )
-  .handler(async ({ data }) => {
-    try {
-      return serialise(
-        await getAdminBylineClient().singleton(data.singleton).copyToLocale({
-          sourceLocale: data.sourceLocale,
-          targetLocale: data.targetLocale,
-          overwrite: data.overwrite,
-        })
-      )
-    } catch (error) {
-      const committedFailure = toCommittedDocumentHookFailureResponse(error)
-      if (committedFailure != null) return committedFailure
-      throw error
-    }
-  })
+  .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/find-by-version.ts

@@ -10,9 +10,11 @@ import { createServerFn } from '@tanstack/react-start'
 
 import { getAdminBylineClient } from '@byline/client/server'
 
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
 import { serialise } from '../serialise.js'
 
 export const findSingletonByVersion = createServerFn({ method: 'GET' })
+  .middleware([adminSessionMiddleware])
   .validator((input: { singleton: string; versionId: string; locale?: string }) => input)
   .handler(async ({ data }) =>
     serialise(

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

@@ -10,9 +10,11 @@ import { createServerFn } from '@tanstack/react-start'
 
 import { getAdminBylineClient } from '@byline/client/server'
 
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
 import { serialise } from '../serialise.js'
 
 export const getSingletonScheduledPublish = createServerFn({ method: 'GET' })
+  .middleware([adminSessionMiddleware])
   .validator((input: { singleton: string }) => input)
   .handler(async ({ data }) =>
     serialise(await getAdminBylineClient().singleton(data.singleton).getScheduledPublish())

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

@@ -8,6 +8,7 @@
 
 import { createServerFn } from '@tanstack/react-start'
 
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
 import { readSingletonDocument } from '../singleton-document-read.js'
 
 export interface GetSingletonInput {
@@ -23,10 +24,11 @@ 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' })
+  .middleware([adminSessionMiddleware])
   .validator((input: GetSingletonInput) => input)
   .handler(async ({ data }) => readSingletonDocument(data))

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

@@ -10,6 +10,7 @@ import { createServerFn } from '@tanstack/react-start'
 
 import { getAdminBylineClient } from '@byline/client/server'
 
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
 import { type ActorLabelMap, resolveActorLabels } from '../actors.js'
 import { serialise } from '../serialise.js'
 
@@ -22,6 +23,7 @@ export interface SingletonHistorySearchParams {
 }
 
 export const getSingletonHistory = createServerFn({ method: 'GET' })
+  .middleware([adminSessionMiddleware])
   .validator((input: { singleton: string; params?: SingletonHistorySearchParams }) => input)
   .handler(async ({ data }) => {
     const params = data.params ?? {}

package/src/server-fns/singletons/restore-version.ts

@@ -10,19 +10,26 @@ import { createServerFn } from '@tanstack/react-start'
 
 import { getAdminBylineClient } from '@byline/client/server'
 
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
 import { toCommittedDocumentHookFailureResponse } from '../collections/save-outcome.js'
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 import { serialise } from '../serialise.js'
 
 export const restoreSingletonVersion = createServerFn({ method: 'POST' })
-  .validator((input: { singleton: string; versionId: string }) => input)
-  .handler(async ({ data }) => {
-    try {
-      return serialise(
-        await getAdminBylineClient().singleton(data.singleton).restoreVersion(data.versionId)
-      )
-    } catch (error) {
-      const committedFailure = toCommittedDocumentHookFailureResponse(error)
-      if (committedFailure != null) return committedFailure
-      throw error
-    }
-  })
+  .middleware([adminSessionMiddleware])
+  .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

@@ -10,15 +10,28 @@ import { createServerFn } from '@tanstack/react-start'
 
 import { getAdminBylineClient } from '@byline/client/server'
 
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 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,
-      })
+  .middleware([adminSessionMiddleware])
+  .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,7 +6,12 @@
  * Copyright (c) Infonomic Company Limited
  */
 
-import { ERR_DOCUMENT_HOOK_COMMITTED, ErrorCodes } from '@byline/core'
+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(() => ({
@@ -18,6 +23,9 @@ vi.mock('@tanstack/react-start', () => ({
   createServerFn: () => {
     let validate = (input: unknown) => input
     const chain = {
+      middleware() {
+        return chain
+      },
       validator(validator: (input: unknown) => unknown) {
         validate = validator
         return chain
@@ -51,13 +59,16 @@ import { scheduleSingletonPublish } from './schedule-publish.js'
 import { unpublishSingleton } from './unpublish.js'
 import { updateSingleton } from './update.js'
 
+// Handler-level tests isolate transport; session-middleware tests exercise the real pre-handler boundary.
+vi.mock('../../integrations/session-middleware.js', () => ({ adminSessionMiddleware: {} }))
+
 type ServerFunction = (options: { data: any }) => Promise<any>
 
 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(),
@@ -84,14 +95,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,
           },
@@ -105,23 +115,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 },
       },
       {
@@ -130,11 +140,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',
           },
         ],
@@ -143,15 +155,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' },
       },
       {
@@ -185,8 +197,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' },
       },
       {
@@ -194,18 +206,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)
 
@@ -219,18 +236,18 @@ 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 }
     )
   })
 
@@ -254,6 +271,7 @@ describe('singleton server functions', () => {
           phase: 'afterSave',
           documentId: 'doc-settings',
           documentVersionId: 'version-next',
+          revision: 8,
           sideEffectCode: ErrorCodes.UNHANDLED,
         },
       })
@@ -263,13 +281,14 @@ describe('singleton server functions', () => {
       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)
   })
@@ -301,9 +320,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)
 
@@ -314,9 +358,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

@@ -10,10 +10,19 @@ import { createServerFn } from '@tanstack/react-start'
 
 import { getAdminBylineClient } from '@byline/client/server'
 
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 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())
+  .middleware([adminSessionMiddleware])
+  .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

@@ -9,30 +9,37 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { getAdminBylineClient } from '@byline/client/server'
+import type { SingletonSavePrecondition } from '@byline/core'
 
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
 import { toCommittedDocumentHookFailureResponse } from '../collections/save-outcome.js'
+import { withDocumentMutationErrors } from '../document-mutation-errors.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' })
+  .middleware([adminSessionMiddleware])
   .validator((input: UpdateSingletonInput) => input)
-  .handler(async ({ data }) => {
-    const { singleton, data: fields, locale, expectedVersionId } = data
-    try {
-      const result = await getAdminBylineClient().singleton(singleton).update(fields, {
-        locale,
-        expectedVersionId,
-      })
-      return serialise(result)
-    } catch (error) {
-      const committedFailure = toCommittedDocumentHookFailureResponse(error)
-      if (committedFailure != null) return committedFailure
-      throw error
-    }
-  })
+  .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
+      }
+    })
+  )

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'))
+}