@byline/host-tanstack-start 4.19.0 → 5.1.0

package/src/admin-shell/scheduled-publications/list.tsx

@@ -1,4 +1,7 @@
-'use client'
+import { DocumentMutationNotice } from '../document-mutation-notice.js'
+import { useDocumentMutationState } from '../document-mutation-state.js'
+
+;('use client')
 
 /**
  * This Source Code is subject to the terms of the Mozilla Public
@@ -60,6 +63,7 @@ export function ScheduledPublicationsView({ data }: { data: ScheduledPublication
     state?: 'armed' | 'needs_reconfirm'
     page?: number
   }
+  const mutation = useDocumentMutationState(undefined)
   const [cancelling, setCancelling] = useState<string | null>(null)
 
   const applySearch = (patch: Record<string, unknown>) => {
@@ -69,11 +73,13 @@ export function ScheduledPublicationsView({ data }: { data: ScheduledPublication
     })
   }
 
-  const cancel = async (collection: string, documentId: string) => {
+  const cancel = async (collection: string, documentId: string, expectedRevision: number) => {
+    if (mutation.blocked || cancelling) return
     setCancelling(documentId)
     try {
+      mutation.assertWritable()
       const result = await cancelCollectionDocumentScheduledPublish({
-        data: { collection, id: documentId },
+        data: { collection, id: documentId, expectedRevision },
       })
       const cancelled = result.status === 'cancelled'
       toastManager.add({
@@ -95,9 +101,10 @@ export function ScheduledPublicationsView({ data }: { data: ScheduledPublication
         search: location.search as Record<string, unknown>,
       })
     } catch (error) {
+      if (mutation.report(error)) return
       toastManager.add({
         title: t('scheduledPublication.toast.failedTitle'),
-        description: (error as Error).message,
+        description: t('documentConcurrency.failed'),
         data: { intent: 'danger', iconType: 'danger', icon: true, close: true },
       })
     } finally {
@@ -110,6 +117,7 @@ export function ScheduledPublicationsView({ data }: { data: ScheduledPublication
   return (
     <Section>
       <Container>
+        <DocumentMutationNotice issue={mutation.issue} />
         <div className={cx('byline-scheduled-list-head', styles.head)}>
           <h1 className={styles.title}>{t('scheduledPublication.list.title')}</h1>
           <p className={styles.intro}>{t('scheduledPublication.list.intro')}</p>
@@ -257,13 +265,15 @@ export function ScheduledPublicationsView({ data }: { data: ScheduledPublication
                           size="xs"
                           type="button"
                           intent="danger"
-                          disabled={cancelling === schedule.documentId}
+                          disabled={mutation.blocked || cancelling !== null}
                           // The column header already says Actions and the row
                           // is a schedule, so the short label carries here —
                           // unlike the editor's menu, where "Cancel schedule"
                           // has to distinguish itself from cancelling an edit.
                           aria-label={t('scheduledPublication.actions.cancel')}
-                          onClick={() => cancel(schedule.collectionPath, schedule.documentId)}
+                          onClick={() =>
+                            cancel(schedule.collectionPath, schedule.documentId, schedule.revision)
+                          }
                         >
                           {t('common.actions.cancel')}
                         </Button>

package/src/admin-shell/singletons/history.test.tsx

@@ -194,6 +194,7 @@ const data: VersionHistoryData = {
 }
 
 const currentDocument = {
+  revision: 7,
   id: 'document-settings',
   versionId: 'version-current',
   status: 'published',
@@ -266,7 +267,7 @@ describe('singleton version history', () => {
     await act(async () => confirm?.click())
 
     expect(mocks.restoreSingleton).toHaveBeenCalledWith({
-      data: { singleton: 'site-settings', versionId: 'version-old' },
+      data: { singleton: 'site-settings', versionId: 'version-old', expectedRevision: 7 },
     })
     expect(mocks.invalidate).toHaveBeenCalledTimes(1)
     expect(mocks.navigate).toHaveBeenLastCalledWith({
@@ -395,6 +396,7 @@ describe('singleton version history', () => {
 
     expect(mocks.restoreCollection).toHaveBeenCalledWith({
       data: {
+        expectedRevision: 7,
         collection: 'articles',
         id: 'document-article',
         versionId: 'version-old',

package/src/admin-shell/singletons/history.tsx

@@ -89,6 +89,7 @@ export function SingletonHistoryView({
       currentVersionId,
       actorLabel,
       restoreStatusLabel,
+      mutationsBlocked,
       openRestore,
     }) => (
       <>
@@ -106,6 +107,7 @@ export function SingletonHistoryView({
               variant="outlined"
               size="xs"
               intent="noeffect"
+              disabled={mutationsBlocked}
               onClick={openRestore}
               className={cx('byline-coll-history-restore-button', historyStyles.restoreButton)}
               title={t('collections.history.restoreButtonTitle', {
@@ -166,8 +168,14 @@ export function SingletonHistoryView({
               return historical as unknown as Record<string, unknown>
             }}
             onPageSizeChange={handlePageSizeChange}
-            restoreVersion={(versionId) =>
-              restoreSingletonVersion({ data: { singleton, versionId } })
+            restoreVersion={(versionId, expectedRevision) =>
+              restoreSingletonVersion({
+                data: {
+                  expectedRevision,
+                  singleton,
+                  versionId,
+                },
+              })
             }
             onRestoreComplete={async () => {
               await router.invalidate()

package/src/admin-shell/singletons/view.test.tsx

@@ -9,7 +9,12 @@
 import { act } from 'react'
 
 import { BylineFieldServicesProvider } from '@byline/admin/react'
-import { defineAdminConfig, defineSingleton, type SingletonDefinition } from '@byline/core'
+import {
+  defineAdminConfig,
+  defineSingleton,
+  ERR_DOCUMENT_STALE,
+  type SingletonDefinition,
+} from '@byline/core'
 import { adminTranslations } from '@byline/i18n/admin'
 import { I18nProvider } from '@byline/i18n/react'
 import { createRoot, type Root } from 'react-dom/client'
@@ -149,6 +154,7 @@ const locales = [
 const loadedDocument = {
   id: 'doc-settings',
   versionId: 'version-1',
+  revision: 7,
   path: '__singleton__/site-settings',
   status: 'draft',
   fields: { title: 'Loaded title', attachment: null },
@@ -233,13 +239,29 @@ function latestToastDescription(): string {
 beforeEach(() => {
   vi.clearAllMocks()
   mocks.guardStates.length = 0
-  mocks.update.mockResolvedValue({ versionId: 'version-next' })
-  mocks.changeStatus.mockResolvedValue({ newStatus: 'published' })
-  mocks.unpublish.mockResolvedValue({ archivedCount: 1 })
-  mocks.schedule.mockResolvedValue({ state: 'armed' })
-  mocks.confirmSchedule.mockResolvedValue({ state: 'armed' })
-  mocks.cancelSchedule.mockResolvedValue(null)
-  mocks.copyToLocale.mockResolvedValue({ versionId: 'version-next' })
+  mocks.update.mockResolvedValue({
+    documentId: 'doc-settings',
+    revision: 8,
+    versionId: 'version-next',
+  })
+  mocks.changeStatus.mockResolvedValue({
+    documentId: 'doc-settings',
+    revision: 8,
+    newStatus: 'published',
+  })
+  mocks.unpublish.mockResolvedValue({ documentId: 'doc-settings', revision: 8, archivedCount: 1 })
+  mocks.schedule.mockResolvedValue({ documentId: 'doc-settings', revision: 8, state: 'armed' })
+  mocks.confirmSchedule.mockResolvedValue({
+    documentId: 'doc-settings',
+    revision: 8,
+    state: 'armed',
+  })
+  mocks.cancelSchedule.mockResolvedValue({ schedule: null, revision: 8 })
+  mocks.copyToLocale.mockResolvedValue({
+    documentId: 'doc-settings',
+    revision: 8,
+    versionId: 'version-next',
+  })
 
   defineAdminConfig({
     routes: { admin: '/internal/cms' },
@@ -316,7 +338,7 @@ describe('SingletonView', () => {
     expect(container.querySelector('.byline-preview-link')).toBeNull()
   })
 
-  it('saves full data with the active locale and the correct optimistic version', async () => {
+  it('saves full data with the active locale and the observed revision or explicit empty slot', async () => {
     render(null, 'en')
     typeIntoTitle('First save')
     await submit()
@@ -326,7 +348,7 @@ describe('SingletonView', () => {
         singleton: 'site-settings',
         data: { title: 'First save', attachment: undefined },
         locale: 'en',
-        expectedVersionId: undefined,
+        expectedState: 'empty',
       },
     })
     expect(mocks.invalidate).toHaveBeenCalledTimes(1)
@@ -342,19 +364,28 @@ describe('SingletonView', () => {
         singleton: 'site-settings',
         data: { title: 'Second save', attachment: null },
         locale: 'fr',
-        expectedVersionId: 'version-1',
+        expectedRevision: 7,
       },
     })
     expect(mocks.invalidate).toHaveBeenCalledTimes(2)
   })
 
   it('distinguishes stale saves from a singleton missing on the server', async () => {
-    mocks.update.mockRejectedValueOnce({ code: 'ERR_CONFLICT' })
+    mocks.update.mockRejectedValueOnce(
+      ERR_DOCUMENT_STALE({
+        message: 'Test failure',
+        details: {
+          reason: 'revision_mismatch',
+          documentId: 'doc-settings',
+          expectedRevision: 7,
+          currentRevision: 8,
+        },
+      })
+    )
     render(loadedDocument)
     typeIntoTitle('Stale edit')
     await submit()
-    const conflict = latestToastDescription()
-    expect(conflict).toContain('Someone else saved this singleton first')
+    expect(container.textContent).toContain('This document has changed since you opened it.')
 
     act(() => root.unmount())
     root = createRoot(container)
@@ -362,13 +393,22 @@ describe('SingletonView', () => {
     render(loadedDocument)
     typeIntoTitle('Missing edit')
     await submit()
-    const notConfigured = latestToastDescription()
-    expect(notConfigured).toContain('not configured on the server')
-    expect(notConfigured).not.toBe(conflict)
+    expect(container.textContent).toContain('This document is no longer available.')
+    expect(container.textContent).not.toContain('This document has changed since you opened it.')
   })
 
   it('keeps a failed save dirty with the navigation guard active', async () => {
-    mocks.update.mockRejectedValueOnce({ code: 'ERR_CONFLICT' })
+    mocks.update.mockRejectedValueOnce(
+      ERR_DOCUMENT_STALE({
+        message: 'Test failure',
+        details: {
+          reason: 'revision_mismatch',
+          documentId: 'doc-settings',
+          expectedRevision: 7,
+          currentRevision: 8,
+        },
+      })
+    )
     render(loadedDocument)
     typeIntoTitle('Unsaved change')
     await submit()
@@ -383,6 +423,7 @@ describe('SingletonView', () => {
       status: 'committed-hook-failed',
       documentId: 'doc-settings',
       documentVersionId: 'version-next',
+      revision: 8,
       sideEffectFailure: { phase: 'afterSave', code: 'ERR_UNHANDLED' },
     })
     render(loadedDocument)

package/src/admin-shell/singletons/view.tsx

@@ -13,7 +13,6 @@ import { useRouter } from '@tanstack/react-router'
 import { FormRenderer } from '@byline/admin/react'
 import type { SingletonAdminConfig, SingletonDefinition } from '@byline/core'
 import {
-  ErrorCodes,
   getDefaultStatus,
   getWorkflow,
   getWorkflowStatuses,
@@ -38,6 +37,7 @@ import {
 } from '../../server-fns/singletons/index.js'
 import { useNavigate } from '../chrome/loose-router.js'
 import { useTanStackNavigationGuard } from '../collections/tanstack-navigation-guard.js'
+import { useDocumentMutationState } from '../document-mutation-state.js'
 import { SingletonViewMenu } from './view-menu.js'
 import type { ContentLocaleOption } from '../collections/view-menu.js'
 
@@ -47,16 +47,10 @@ type SingletonDocument = Record<string, any> & {
   fields: Record<string, any>
 }
 
-function errorCode(error: unknown): string | null {
-  return typeof (error as { code?: unknown })?.code === 'string'
-    ? (error as { code: string }).code
-    : null
-}
-
 export function SingletonView({
   singletonDefinition,
   adminConfig,
-  document,
+  document: loadedDocument,
   initialData,
   locale,
   contentLocales,
@@ -71,6 +65,8 @@ export function SingletonView({
   contentLocales: ReadonlyArray<ContentLocaleOption>
   defaultContentLocale: string
 }) {
+  const mutation = useDocumentMutationState(loadedDocument)
+  const document = mutation.document ?? null
   const router = useRouter()
   const navigate = useNavigate()
   const toastManager = useToastManager()
@@ -132,14 +128,18 @@ export function SingletonView({
 
   const handleSubmit = async ({ data }: { data: Record<string, any> }) => {
     try {
+      mutation.assertWritable()
       const result = await updateSingleton({
         data: {
           singleton: path,
           data,
           locale: locale ?? defaultContentLocale,
-          expectedVersionId: document?.versionId,
+          ...(document == null
+            ? { expectedState: 'empty' as const }
+            : { expectedRevision: mutation.expectedRevision() }),
         },
       })
+      mutation.adopt(result)
       if (document != null) notifyScheduleSuspended()
       if (hasCommittedDocumentHookFailure(result)) {
         notifyCommittedHookFailure()
@@ -152,13 +152,16 @@ export function SingletonView({
       }
       await reload()
     } catch (err) {
-      const code = errorCode(err)
-      const description =
-        code === ErrorCodes.CONFLICT
-          ? t('singletons.edit.conflictDescription')
-          : code === ErrorCodes.NOT_FOUND
-            ? t('singletons.edit.notConfiguredDescription')
-            : t('singletons.edit.updateFailedDescription', { label: label.toLowerCase() })
+      const handled = mutation.report(err)
+      if (handled === 'blocked') throw err
+      if (handled === 'committed') {
+        notifyCommittedHookFailure()
+        await reload()
+        return
+      }
+      const description = t('singletons.edit.updateFailedDescription', {
+        label: label.toLowerCase(),
+      })
       toast(t('singletons.edit.updateTitle', { label }), description, 'danger')
 
       // FormRenderer commits its clean baseline only when this promise
@@ -170,7 +173,11 @@ export function SingletonView({
 
   const handleStatusChange = async (status: string) => {
     try {
-      await changeSingletonStatus({ data: { singleton: path, status } })
+      mutation.assertWritable()
+      const result = await changeSingletonStatus({
+        data: { expectedRevision: mutation.expectedRevision(), singleton: path, status },
+      })
+      mutation.adopt(result)
       toast(
         t('collections.edit.statusUpdateTitle', { label }),
         t('collections.edit.statusChangedDescription', { status }),
@@ -178,9 +185,18 @@ export function SingletonView({
       )
       await reload()
     } catch (err) {
+      const handled = mutation.report(err)
+      if (handled === 'blocked') throw err
+      if (handled === 'committed') {
+        notifyCommittedHookFailure()
+        await reload()
+        return
+      }
       toast(
         t('collections.edit.statusUpdateTitle', { label }),
-        t('collections.edit.statusChangeFailedDescription', { message: (err as Error).message }),
+        t('collections.edit.statusChangeFailedDescription', {
+          message: t('documentConcurrency.failed'),
+        }),
         'danger'
       )
       throw err
@@ -189,7 +205,11 @@ export function SingletonView({
 
   const handleUnpublish = async () => {
     try {
-      await unpublishSingleton({ data: { singleton: path } })
+      mutation.assertWritable()
+      const result = await unpublishSingleton({
+        data: { expectedRevision: mutation.expectedRevision(), singleton: path },
+      })
+      mutation.adopt(result)
       toast(
         t('collections.edit.unpublishTitle', { label }),
         t('collections.edit.unpublishedDescription'),
@@ -197,9 +217,18 @@ export function SingletonView({
       )
       await reload()
     } catch (err) {
+      const handled = mutation.report(err)
+      if (handled === 'blocked') throw err
+      if (handled === 'committed') {
+        notifyCommittedHookFailure()
+        await reload()
+        return
+      }
       toast(
         t('collections.edit.unpublishTitle', { label }),
-        t('collections.edit.unpublishFailedDescription', { message: (err as Error).message }),
+        t('collections.edit.unpublishFailedDescription', {
+          message: t('documentConcurrency.failed'),
+        }),
         'danger'
       )
       throw err
@@ -214,14 +243,17 @@ export function SingletonView({
     overwrite: boolean
   }) => {
     try {
+      mutation.assertWritable()
       const result = await copySingletonToLocale({
         data: {
+          expectedRevision: mutation.expectedRevision(),
           singleton: path,
           sourceLocale: locale ?? defaultContentLocale,
           targetLocale,
           overwrite,
         },
       })
+      mutation.adopt(result)
       const sourceLocale = locale ?? defaultContentLocale
       const sourceLabel =
         contentLocales.find((entry) => entry.code === sourceLocale)?.label ?? sourceLocale
@@ -246,9 +278,16 @@ export function SingletonView({
         search: { locale: targetLocale },
       })
     } catch (err) {
+      const handled = mutation.report(err)
+      if (handled === 'blocked') throw err
+      if (handled === 'committed') {
+        notifyCommittedHookFailure()
+        await reload()
+        return
+      }
       toast(
         t('collections.edit.copyToLocaleTitle', { label }),
-        t('collections.edit.copyFailedDescription', { message: (err as Error).message }),
+        t('collections.edit.copyFailedDescription', { message: t('documentConcurrency.failed') }),
         'danger'
       )
       throw err
@@ -257,9 +296,16 @@ export function SingletonView({
 
   const handleSchedulePublication = async ({ publishAt }: { publishAt: string }) => {
     try {
-      await scheduleSingletonPublish({
-        data: { singleton: path, publishAt, expectedVersionId: String(document?.versionId) },
+      mutation.assertWritable()
+      const result = await scheduleSingletonPublish({
+        data: {
+          expectedRevision: mutation.expectedRevision(),
+          singleton: path,
+          publishAt,
+          expectedVersionId: String(document?.versionId),
+        },
       })
+      mutation.adopt(result)
       toast(
         t('scheduledPublication.toast.scheduledTitle'),
         t('scheduledPublication.toast.scheduledDescription'),
@@ -267,16 +313,29 @@ export function SingletonView({
       )
       await reload()
     } catch (err) {
-      toast(t('scheduledPublication.toast.failedTitle'), (err as Error).message, 'danger')
+      const handled = mutation.report(err)
+      if (handled === 'blocked') throw err
+      if (handled === 'committed') {
+        notifyCommittedHookFailure()
+        await reload()
+        return
+      }
+      toast(t('scheduledPublication.toast.failedTitle'), t('documentConcurrency.failed'), 'danger')
       throw err
     }
   }
 
   const handleConfirmScheduledPublication = async () => {
     try {
-      await confirmSingletonScheduledPublish({
-        data: { singleton: path, expectedVersionId: String(document?.versionId) },
+      mutation.assertWritable()
+      const result = await confirmSingletonScheduledPublish({
+        data: {
+          expectedRevision: mutation.expectedRevision(),
+          singleton: path,
+          expectedVersionId: String(document?.versionId),
+        },
       })
+      mutation.adopt(result)
       toast(
         t('scheduledPublication.toast.confirmedTitle'),
         t('scheduledPublication.toast.confirmedDescription'),
@@ -284,14 +343,25 @@ export function SingletonView({
       )
       await reload()
     } catch (err) {
-      toast(t('scheduledPublication.toast.failedTitle'), (err as Error).message, 'danger')
+      const handled = mutation.report(err)
+      if (handled === 'blocked') throw err
+      if (handled === 'committed') {
+        notifyCommittedHookFailure()
+        await reload()
+        return
+      }
+      toast(t('scheduledPublication.toast.failedTitle'), t('documentConcurrency.failed'), 'danger')
       throw err
     }
   }
 
   const handleCancelScheduledPublication = async () => {
     try {
-      await cancelSingletonScheduledPublish({ data: { singleton: path } })
+      mutation.assertWritable()
+      const result = await cancelSingletonScheduledPublish({
+        data: { expectedRevision: mutation.expectedRevision(), singleton: path },
+      })
+      mutation.adopt({ ...result, documentId: String(document?.id) })
       toast(
         t('scheduledPublication.toast.cancelledTitle'),
         t('scheduledPublication.toast.cancelledDescription'),
@@ -299,7 +369,14 @@ export function SingletonView({
       )
       await reload()
     } catch (err) {
-      toast(t('scheduledPublication.toast.failedTitle'), (err as Error).message, 'danger')
+      const handled = mutation.report(err)
+      if (handled === 'blocked') throw err
+      if (handled === 'committed') {
+        notifyCommittedHookFailure()
+        await reload()
+        return
+      }
+      toast(t('scheduledPublication.toast.failedTitle'), t('documentConcurrency.failed'), 'danger')
       throw err
     }
   }
@@ -308,6 +385,10 @@ export function SingletonView({
     <Section>
       <Container>
         <FormRenderer
+          mutationIssue={mutation.issue}
+          mutationsBlocked={mutation.blocked}
+          observedRevision={mutation.revision}
+          onMutationError={mutation.report}
           mode={document == null ? 'create' : 'edit'}
           fields={fields}
           onSubmit={handleSubmit}

package/src/integrations/byline-admin-services.ts

@@ -36,6 +36,7 @@ import {
 import { adminSignIn } from '../server-fns/auth/index.js'
 import { getCollectionDocumentVersion as serverGetCollectionDocumentVersion } from '../server-fns/collections/get.js'
 import { setAdminLocaleFn } from '../server-fns/i18n/index.js'
+import { acceptSession, coordinateAuthAction, notifySessionAction } from './session-coordination.js'
 
 /**
  * Diff helper adapter — the contract uses positional args; the underlying
@@ -62,7 +63,12 @@ const getCollectionDocumentVersion: BylineAdminServices['getCollectionDocumentVe
 
 export const bylineAdminServices: BylineAdminServices = {
   // Auth
-  adminSignIn,
+  adminSignIn: async (args) => {
+    const result = await coordinateAuthAction(() => adminSignIn(args))
+    acceptSession(result.sessionId)
+    notifySessionAction()
+    return result
+  },
 
   // Account self-service
   updateAccount,

package/src/integrations/byline-field-services.ts

@@ -44,12 +44,11 @@ const uploadField: UploadFieldFn = (collection, formData, createDocument) =>
   serverUploadField(collection, formData, createDocument)
 
 const placeTreeNode: PlaceTreeNodeFn = async (input) => {
-  const { orderKey } = await serverPlaceTreeNode({ data: input })
-  return { orderKey }
+  return serverPlaceTreeNode({ data: input })
 }
 
 const removeFromTree: RemoveFromTreeFn = async (input) => {
-  await serverRemoveFromTree({ data: input })
+  return serverRemoveFromTree({ data: input })
 }
 
 const getTreeAncestors: GetTreeAncestorsFn = (input) =>

package/src/integrations/client-ip.test.node.ts

@@ -0,0 +1,45 @@
+/**
+ * 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
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import { createClientIpResolver, normalizeClientIp } from './client-ip.js'
+
+describe('client IP trust boundary', () => {
+  it('ignores spoofed forwarding headers in direct mode', async () => {
+    const resolve = createClientIpResolver({ resolvePeerIp: () => '192.0.2.1' })
+    expect(
+      await resolve(
+        new Request('https://app.test', {
+          headers: { 'x-forwarded-for': '198.51.100.1', 'x-real-ip': '198.51.100.2' },
+        })
+      )
+    ).toBe('192.0.2.1')
+  })
+  it('uses only the configured proxy header and fails closed on absent/invalid values', async () => {
+    const resolve = createClientIpResolver({
+      trustedProxyHeader: 'x-byline-client-ip',
+      resolvePeerIp: () => '127.0.0.1',
+    })
+    for (const value of ['', '192.0.2.1, 192.0.2.2', 'garbage']) {
+      expect(
+        await resolve(new Request('https://app.test', { headers: { 'x-byline-client-ip': value } }))
+      ).toBeNull()
+    }
+    expect(
+      await resolve(
+        new Request('https://app.test', { headers: { 'x-byline-client-ip': '2001:0db8::1' } })
+      )
+    ).toBe('2001:db8::1')
+  })
+  it('normalizes equivalent IP representations', () => {
+    expect(normalizeClientIp('::ffff:192.0.2.1')).toBe('192.0.2.1')
+    expect(normalizeClientIp('::ffff:c000:201')).toBe('192.0.2.1')
+    expect(normalizeClientIp('fe80::1%en0')).toBeNull()
+  })
+})