@byline/host-tanstack-start 4.19.0 → 5.1.0

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

@@ -1,3 +1,11 @@
+/**
+ * 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 { createServerFn } from '@tanstack/react-start'
 
 import { getAdminRequestContext } from '@byline/client/server'
@@ -14,6 +22,8 @@ import { getLogger, withLogContext } from '@byline/core/logger'
 import { uploadField as coreUploadField } from '@byline/core/services'
 
 import { ensureDocumentResource } from '../../integrations/api-utils.js'
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 
 /**
  * Result of an upload through the host transport. The legacy top-level
@@ -25,6 +35,7 @@ export interface UploadFieldResult {
   /** Present when the upload endpoint created a document (createDocument=true, the default). */
   documentId?: string
   documentVersionId?: string
+  revision?: number
   storedFile: StoredFileValue
 }
 
@@ -148,89 +159,92 @@ function resolveUploadField(
  * without depending on TanStack Start server-function transport details.
  */
 export const uploadCollectionField = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMiddleware])
   .validator(parseUploadFormData)
-  .handler(async ({ data }) => {
-    const { collectionPath, shouldCreateDocument, fieldName, file, fields } = data
-    const logger = getLogger()
+  .handler(
+    withDocumentMutationErrors(async ({ data }) => {
+      const { collectionPath, shouldCreateDocument, fieldName, file, fields } = data
+      const logger = getLogger()
 
-    return withLogContext(
-      { domain: 'api', module: 'upload', function: 'uploadCollectionField' },
-      async () => {
-        // Upload is the one field transport shared by both document-resource
-        // kinds. The core service selects the kind-aware ability and rejects
-        // singleton document creation before hooks or storage; the admin form
-        // always requests the field-only branch (`createDocument=false`).
-        const config = await ensureDocumentResource(collectionPath)
-        if (config == null) {
-          throw ERR_NOT_FOUND(
-            {
-              message: 'Document resource not found.',
-              details: { collectionPath },
-            },
-            uploadCollectionField
-          ).log(logger)
-        }
+      return withLogContext(
+        { domain: 'api', module: 'upload', function: 'uploadCollectionField' },
+        async () => {
+          // Upload is the one field transport shared by both document-resource
+          // kinds. The core service selects the kind-aware ability and rejects
+          // singleton document creation before hooks or storage; the admin form
+          // always requests the field-only branch (`createDocument=false`).
+          const config = await ensureDocumentResource(collectionPath)
+          if (config == null) {
+            throw ERR_NOT_FOUND(
+              {
+                message: 'Document resource not found.',
+                details: { collectionPath },
+              },
+              uploadCollectionField
+            ).log(logger)
+          }
 
-        const serverConfig = getServerConfig()
-        const targetField = resolveUploadField(config.definition, collectionPath, fieldName)
-        // Per-field storage routing falls through to the site-wide default.
-        const storage = targetField.upload?.storage ?? serverConfig.storage
-        if (!storage) {
-          throw new Error(
-            `No storage provider configured for field '${targetField.name}' on collection ` +
-              `'${collectionPath}'. Set either field.upload.storage or the site-wide ` +
-              'ServerConfig.storage.'
-          )
-        }
+          const serverConfig = getServerConfig()
+          const targetField = resolveUploadField(config.definition, collectionPath, fieldName)
+          // Per-field storage routing falls through to the site-wide default.
+          const storage = targetField.upload?.storage ?? serverConfig.storage
+          if (!storage) {
+            throw new Error(
+              `No storage provider configured for field '${targetField.name}' on collection ` +
+                `'${collectionPath}'. Set either field.upload.storage or the site-wide ` +
+                'ServerConfig.storage.'
+            )
+          }
 
-        let buffer: Buffer
-        try {
-          buffer = Buffer.from(await file.arrayBuffer())
-        } catch (err: unknown) {
-          logger.error({ err, collectionPath }, 'failed to read file buffer')
-          throw new Error('Failed to read uploaded file.')
-        }
+          let buffer: Buffer
+          try {
+            buffer = Buffer.from(await file.arrayBuffer())
+          } catch (err: unknown) {
+            logger.error({ err, collectionPath }, 'failed to read file buffer')
+            throw new Error('Failed to read uploaded file.')
+          }
 
-        const ctx: FieldUploadContext = {
-          db: serverConfig.db,
-          definition: config.definition,
-          collectionId: config.collection.id,
-          collectionVersion: config.collection.version,
-          collectionPath,
-          fieldName: targetField.name,
-          storage,
-          logger,
-          defaultLocale: serverConfig.i18n.content.defaultLocale,
-          slugifier: serverConfig.slugifier,
-          filenameSlugifier: serverConfig.uploads?.filenameSlugifier,
-          requestContext: await getAdminRequestContext(),
-          imageProcessor: {
-            extractMeta: extractImageMeta,
-            isBypassMimeType,
-            generateVariants: ({ buffer, mimeType, storedFile, storage, upload, logger }) =>
-              generateImageVariants(
-                buffer,
-                mimeType,
-                storedFile,
-                storage,
-                upload.sizes ?? [],
-                logger
-              ),
-          },
-        }
+          const ctx: FieldUploadContext = {
+            db: serverConfig.db,
+            definition: config.definition,
+            collectionId: config.collection.id,
+            collectionVersion: config.collection.version,
+            collectionPath,
+            fieldName: targetField.name,
+            storage,
+            logger,
+            defaultLocale: serverConfig.i18n.content.defaultLocale,
+            slugifier: serverConfig.slugifier,
+            filenameSlugifier: serverConfig.uploads?.filenameSlugifier,
+            requestContext: await getAdminRequestContext(),
+            imageProcessor: {
+              extractMeta: extractImageMeta,
+              isBypassMimeType,
+              generateVariants: ({ buffer, mimeType, storedFile, storage, upload, logger }) =>
+                generateImageVariants(
+                  buffer,
+                  mimeType,
+                  storedFile,
+                  storage,
+                  upload.sizes ?? [],
+                  logger
+                ),
+            },
+          }
 
-        return coreUploadField(ctx, {
-          buffer,
-          originalFilename: file.name || 'upload',
-          mimeType: file.type || 'application/octet-stream',
-          fileSize: file.size,
-          fields,
-          shouldCreateDocument,
-          locale: serverConfig.i18n.content.defaultLocale,
-        })
-      }
-    )
-  })
+          return coreUploadField(ctx, {
+            buffer,
+            originalFilename: file.name || 'upload',
+            mimeType: file.type || 'application/octet-stream',
+            fileSize: file.size,
+            fields,
+            shouldCreateDocument,
+            locale: serverConfig.i18n.content.defaultLocale,
+          })
+        }
+      )
+    })
+  )
 
 /**
  * Upload a file to an upload-enabled collection.

package/src/server-fns/document-mutation-errors.ts

@@ -0,0 +1,67 @@
+import {
+  BylineError,
+  ErrorCodes,
+  getDocumentRevisionValidationDetails,
+  getDocumentStaleDetails,
+  getLockConflictDetails,
+} from '@byline/core'
+import { getDocumentHookCommittedDetails } from '@byline/core/services'
+
+import { committedTreeReceipt } from './structural-receipt.js'
+
+/** Error subclasses lose custom properties in the server-function serializer.
+ * Throw only validated plain data for document failures; never transport causes,
+ * SQL, hook messages or an unverified current revision. */
+export function documentMutationError(error: unknown): unknown {
+  const stale = getDocumentStaleDetails(error)
+  if (stale)
+    return {
+      code: ErrorCodes.DOCUMENT_STALE,
+      message: 'This document has changed. Reload before making changes.',
+      details: stale,
+    }
+  const validation = getDocumentRevisionValidationDetails(error)
+  if (validation)
+    return {
+      code: ErrorCodes.VALIDATION,
+      message: 'Reload this document before making changes.',
+      details: validation,
+    }
+  const lock = getLockConflictDetails(error)
+  if (lock)
+    return {
+      code: ErrorCodes.LOCK_CONFLICT,
+      message:
+        'This change could not be saved because another operation was using the document. Reload before trying again.',
+      details: lock,
+    }
+  const tree = committedTreeReceipt(error)
+  if (tree)
+    return {
+      code: ErrorCodes.TREE_HOOK_COMMITTED,
+      message: 'The structure was saved, but a follow-up action failed.',
+      details: tree,
+    }
+  const committed = getDocumentHookCommittedDetails(error)
+  if (committed)
+    return {
+      code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+      message: 'The document was saved, but a follow-up action failed.',
+      details: committed,
+    }
+  if (error instanceof BylineError && error.code === ErrorCodes.NOT_FOUND)
+    return { code: ErrorCodes.NOT_FOUND, message: 'This document is no longer available.' }
+  return error
+}
+
+export function withDocumentMutationErrors<T, R>(
+  handler: (input: T) => Promise<R>
+): (input: T) => Promise<R> {
+  return async (input) => {
+    try {
+      return await handler(input)
+    } catch (error) {
+      throw documentMutationError(error)
+    }
+  }
+}

package/src/server-fns/document-mutation-transport.test.node.ts

@@ -0,0 +1,211 @@
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+
+import {
+  ERR_CONFLICT,
+  ERR_DOCUMENT_HOOK_COMMITTED,
+  ERR_DOCUMENT_STALE,
+  ERR_LOCK_CONFLICT,
+  ERR_NOT_FOUND,
+  ERR_TREE_HOOK_COMMITTED,
+  ERR_VALIDATION,
+  getDocumentRevisionValidationDetails,
+  getDocumentStaleDetails,
+  getLockConflictDetails,
+} from '@byline/core'
+import { getDocumentHookCommittedDetails } from '@byline/core/services'
+import { beforeAll, describe, expect, it, vi } from 'vitest'
+
+import { documentMutationError, withDocumentMutationErrors } from './document-mutation-errors.js'
+
+// Exercise the installed Start HTTP handler and its real Seroval protocol. Only
+// manifest lookup and request-local response state are supplied by this harness;
+// the production application's compiled actions are covered by browser tests.
+const require = createRequire(import.meta.url)
+const startRequire = createRequire(require.resolve('@tanstack/react-start/package.json'))
+const serverPackage = startRequire.resolve('@tanstack/start-server-core/package.json')
+const esm = join(dirname(serverPackage), 'src')
+const serverRequire = createRequire(serverPackage)
+let handler: (input: { request: Request; context: object; serverFnId: string }) => Promise<Response>
+let seroval: {
+  toJSONAsync(value: unknown): Promise<unknown>
+  fromCrossJSON(value: unknown, options: object): unknown
+}
+let runWithStartContext: (context: object, fn: () => Promise<Response>) => Promise<Response>
+let action: (input: { data: unknown }) => Promise<unknown>
+
+beforeAll(async () => {
+  vi.doMock(join(esm, 'getServerFnById.ts'), () => ({ getServerFnById: async () => action }))
+  vi.doMock(join(esm, 'request-response.ts'), () => ({
+    getResponse: () => ({ status: 200, headers: new Headers() }),
+  }))
+  handler = (await import(join(esm, 'server-functions-handler.ts'))).handleServerAction
+  seroval = await import(serverRequire.resolve('seroval'))
+  runWithStartContext = (
+    await import(
+      join(
+        dirname(serverRequire.resolve('@tanstack/start-storage-context/package.json')),
+        'dist/esm/index.js'
+      )
+    )
+  ).runWithStartContext
+})
+
+async function roundTrip(data: unknown, operation: (data: unknown) => Promise<unknown>) {
+  const guarded = withDocumentMutationErrors(operation)
+  action = async ({ data }) => {
+    try {
+      return { result: await guarded(data) }
+    } catch (error) {
+      return { error }
+    }
+  }
+  const request = new Request('http://localhost/_serverFn/document-mutation', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-tsr-serverFn': 'true' },
+    body: JSON.stringify(await seroval.toJSONAsync({ data })),
+  })
+  const response = await runWithStartContext(
+    {
+      request,
+      startOptions: {},
+      contextAfterGlobalMiddlewares: {},
+      executedRequestMiddlewares: new Set(),
+      handlerType: 'serverFn',
+      getRouter: () => {
+        throw new Error('Router not used')
+      },
+    },
+    () => handler({ request, context: {}, serverFnId: 'document-mutation' })
+  )
+  const wire = await response.text()
+  const decoded = seroval.fromCrossJSON(JSON.parse(wire), {})
+  if (typeof decoded !== 'object' || decoded === null) throw new Error('Expected wire envelope')
+  return {
+    value: { error: Reflect.get(decoded, 'error'), result: Reflect.get(decoded, 'result') },
+    wire,
+  }
+}
+
+const staleCases = [
+  { reason: 'revision_mismatch', documentId: 'doc', expectedRevision: 1, currentRevision: 2 },
+  {
+    reason: 'version_parent_mismatch',
+    documentId: 'doc',
+    previousVersionId: 'old',
+    currentVersionId: 'new',
+  },
+  {
+    reason: 'singleton_slot_changed',
+    singletonPath: 'settings',
+    expectedState: 'empty',
+    currentState: 'document',
+  },
+] as const
+
+describe('document failures over Start HTTP serialization', () => {
+  for (const details of staleCases) {
+    it(`retains ${details.reason} and excludes diagnostics`, async () => {
+      const { value, wire } = await roundTrip({}, async () => {
+        throw ERR_DOCUMENT_STALE({
+          message: 'private driver detail',
+          details,
+          cause: new Error('SELECT secret'),
+          logExtra: { private: true },
+        })
+      })
+      expect(getDocumentStaleDetails(value.error)).toEqual(details)
+      expect(wire).not.toMatch(/private driver|SELECT secret|logExtra/)
+    })
+  }
+  for (const reason of ['missing_document_revision', 'invalid_document_revision'] as const) {
+    it(`retains reload-required validation: ${reason}`, async () => {
+      const { value } = await roundTrip({}, async () => {
+        throw ERR_VALIDATION({ message: 'internal', details: { reason } })
+      })
+      expect(getDocumentRevisionValidationDetails(value.error)).toEqual({ reason })
+      expect(getDocumentStaleDetails(value.error)).toBeNull()
+    })
+  }
+  it('retains a confirmed rollback without relabelling it stale', async () => {
+    const details = { reason: 'lock_conflict', rolledBack: true, retryable: true }
+    const { value, wire } = await roundTrip({}, async () => {
+      throw ERR_LOCK_CONFLICT({
+        message: 'driver message',
+        details,
+        cause: new Error('SQL private'),
+      })
+    })
+    expect(getLockConflictDetails(value.error)).toEqual(details)
+    expect(getDocumentStaleDetails(value.error)).toBeNull()
+    expect(wire).not.toMatch(/driver message|SQL private/)
+  })
+  it('keeps committed hook warnings separate and preserves their committed revision', async () => {
+    const details = {
+      phase: 'afterUpdate',
+      documentId: 'doc',
+      documentVersionId: 'version',
+      revision: 3,
+      sideEffectCode: 'ERR_UNHANDLED',
+    }
+    const { value, wire } = await roundTrip({}, async () => {
+      throw ERR_DOCUMENT_HOOK_COMMITTED({
+        message: 'private hook failure',
+        details,
+        cause: new Error('secret hook'),
+      })
+    })
+    expect(getDocumentHookCommittedDetails(value.error)).toEqual(details)
+    expect(getDocumentStaleDetails(value.error)).toBeNull()
+    expect(getLockConflictDetails(value.error)).toBeNull()
+    expect(wire).not.toMatch(/private hook failure|secret hook/)
+  })
+  it('round-trips safe integer observations and receipts as numbers', async () => {
+    const { value } = await roundTrip(
+      { expectedRevision: Number.MAX_SAFE_INTEGER - 1 },
+      async (data) => {
+        expect(data).toEqual({ expectedRevision: Number.MAX_SAFE_INTEGER - 1 })
+        return { documentId: 'doc', revision: Number.MAX_SAFE_INTEGER }
+      }
+    )
+    expect(value.result).toEqual({ documentId: 'doc', revision: Number.MAX_SAFE_INTEGER })
+  })
+  it('does not classify unrelated or malformed conflicts by message', () => {
+    const conflict = ERR_CONFLICT({ message: 'This document has changed.' })
+    expect(documentMutationError(conflict)).toBe(conflict)
+    const malformed = { code: 'ERR_DOCUMENT_STALE', details: { reason: 'revision_mismatch' } }
+    expect(documentMutationError(malformed)).toBe(malformed)
+  })
+})
+
+it('transports the authorized structural receipt on committed tree hook failure without diagnostics', async () => {
+  const receipt = {
+    documentId: 'doc',
+    revision: 3,
+    affectedDocuments: [{ documentId: 'allowed-sibling', revision: 4 }],
+    scheduledPublicationsNeedReconfirmation: true,
+  }
+  const { value, wire } = await roundTrip({}, async () => {
+    throw ERR_TREE_HOOK_COMMITTED({
+      message: 'private hook diagnostics',
+      cause: new Error('SQL secret'),
+      details: { ...receipt, change: 'reorder', affectedDocumentIds: ['private'], internal: true },
+    })
+  })
+  expect(value.error).toEqual({
+    code: 'ERR_TREE_HOOK_COMMITTED',
+    message: 'The structure was saved, but a follow-up action failed.',
+    details: receipt,
+  })
+  expect(wire).not.toMatch(/private|SQL secret|internal/)
+})
+it('transports unavailable-document errors without provider details', async () => {
+  const { value, wire } = await roundTrip({}, async () => {
+    throw ERR_NOT_FOUND({ message: 'private unavailable reason', details: { internal: true } })
+  })
+  expect(value.error).toEqual({
+    code: 'ERR_NOT_FOUND',
+    message: 'This document is no longer available.',
+  })
+  expect(wire).not.toMatch(/private|internal/)
+})

package/src/server-fns/editable-revision.test.node.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest'
+
+import { withEditableRevision } from './editable-revision.js'
+
+describe('editable response revision binding', () => {
+  const observed = { id: 'document', versionId: 'current', revision: 7 }
+  it('restores only the source revision without changing populated targets', () => {
+    const related = { id: 'related', versionId: 'published', fields: {} }
+    expect(
+      withEditableRevision({ id: 'document', versionId: 'current', fields: { related } }, observed)
+    ).toEqual({ id: 'document', versionId: 'current', revision: 7, fields: { related } })
+    expect(related).not.toHaveProperty('revision')
+  })
+  it.each([
+    { id: 'document', versionId: 'historical' },
+    { id: 'another-document', versionId: 'current' },
+  ])('rejects a transferred observation: %o', (document) => {
+    expect(() => withEditableRevision(document, observed)).toThrow('source observation')
+  })
+  it('rejects a row removed from the editable result', () => {
+    expect(() => withEditableRevision(observed, undefined)).toThrow('source observation')
+  })
+})

package/src/server-fns/editable-revision.ts

@@ -0,0 +1,18 @@
+import { ERR_DATABASE, isDocumentRevision } from '@byline/core'
+
+/** Restore metadata stripped by schema parsing only onto the exact source version.
+ * Never attach by array position: filtering/reordering must not transfer tokens. */
+export function withEditableRevision<T extends object>(
+  document: T,
+  observation: { id: string; versionId: string; revision: number } | undefined
+): T & { revision: number } {
+  if (
+    !observation ||
+    !isDocumentRevision(observation.revision) ||
+    Reflect.get(document, 'id') !== observation.id ||
+    Reflect.get(document, 'versionId') !== observation.versionId
+  ) {
+    throw ERR_DATABASE({ message: 'Editable response no longer matches its source observation' })
+  }
+  return { ...document, revision: observation.revision }
+}

package/src/server-fns/i18n/set-locale.ts

@@ -25,7 +25,7 @@
  * switcher works on the sign-in surface — the DB write simply skips.
  */
 
-import { createServerFn } from '@tanstack/react-start'
+import { createMiddleware, createServerFn } from '@tanstack/react-start'
 
 import type { AccountResponse } from '@byline/admin/admin-account'
 import { setPreferredLocaleCommand } from '@byline/admin/admin-account'
@@ -34,6 +34,7 @@ import { getAdminRequestContext } from '@byline/client/server'
 
 import { clearAdminLocaleCookie, setAdminLocaleCookie } from '../../i18n/locale-cookie.js'
 import { bylineCore } from '../../integrations/byline-core.js'
+import { expectedSession } from '../../integrations/session-coordination.js'
 
 export interface SetAdminLocaleInput {
   /** BCP 47 tag, or `null` to clear the preference. */
@@ -53,9 +54,18 @@ export interface SetAdminLocaleResult {
   account: AccountResponse | null
 }
 
+const localeSession = createMiddleware({ type: 'function' }).client(({ next }) =>
+  next({
+    sendContext: {
+      expectedSessionId: expectedSession(),
+    },
+  })
+)
+
 export const setAdminLocaleFn = createServerFn({ method: 'POST' })
+  .middleware([localeSession])
   .validator((input: SetAdminLocaleInput) => input)
-  .handler(async ({ data }): Promise<SetAdminLocaleResult> => {
+  .handler(async ({ data, context: caller }): Promise<SetAdminLocaleResult> => {
     const core = bylineCore()
     const locales = core.config.i18n.admin.locales
 
@@ -87,6 +97,9 @@ export const setAdminLocaleFn = createServerFn({ method: 'POST' })
 
     try {
       const context = await getAdminRequestContext()
+      if (!caller.expectedSessionId || caller.expectedSessionId !== context.sessionId) {
+        return { ok: true as const, locale: data.locale, account: null }
+      }
       const account = await setPreferredLocaleCommand(
         context,
         { locale: data.locale },
@@ -94,7 +107,10 @@ export const setAdminLocaleFn = createServerFn({ method: 'POST' })
       )
       return { ok: true as const, locale: data.locale, account }
     } catch (err) {
-      if (err instanceof AuthError && err.code === AuthErrorCodes.UNAUTHENTICATED) {
+      if (
+        err instanceof AuthError &&
+        (err.code === AuthErrorCodes.UNAUTHENTICATED || err.code === AuthErrorCodes.ACCESS_EXPIRED)
+      ) {
         // Expected on the pre-auth path. Cookie already written.
         return { ok: true as const, locale: data.locale, account: null }
       }

package/src/server-fns/preview/disable.ts

@@ -18,7 +18,11 @@ import { createServerFn } from '@tanstack/react-start'
 
 import { clearPreviewCookie } from '@byline/client/server'
 
-export const disablePreviewModeFn = createServerFn({ method: 'POST' }).handler(async () => {
-  clearPreviewCookie()
-  return { status: 'ok' as const, preview: false as const }
-})
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
+
+export const disablePreviewModeFn = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMiddleware])
+  .handler(async () => {
+    clearPreviewCookie()
+    return { status: 'ok' as const, preview: false as const }
+  })

package/src/server-fns/preview/enable.ts

@@ -19,8 +19,12 @@ import { createServerFn } from '@tanstack/react-start'
 
 import { getAdminRequestContext, setPreviewCookie } from '@byline/client/server'
 
-export const enablePreviewModeFn = createServerFn({ method: 'POST' }).handler(async () => {
-  await getAdminRequestContext()
-  setPreviewCookie()
-  return { status: 'ok' as const, preview: true as const }
-})
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
+
+export const enablePreviewModeFn = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMiddleware])
+  .handler(async () => {
+    await getAdminRequestContext()
+    setPreviewCookie()
+    return { status: 'ok' as const, preview: true as const }
+  })

package/src/server-fns/singleton-document-read.ts

@@ -7,7 +7,7 @@
  */
 
 import { getAdminBylineClient } from '@byline/client/server'
-import { getCollectionDefinition } from '@byline/core'
+import { ERR_NOT_FOUND, getCollectionDefinition } from '@byline/core'
 
 import { resolveAdminDocumentRead } from './admin-document-presentation.js'
 import { serialise } from './serialise.js'
@@ -27,6 +27,10 @@ export interface SingletonDocumentReadInput {
  */
 export async function readSingletonDocument(data: SingletonDocumentReadInput) {
   const handle = getAdminBylineClient().singleton(data.singleton)
-  const { options } = resolveAdminDocumentRead(getCollectionDefinition(data.singleton), data)
-  return serialise(await handle.get(options))
+  const {
+    options: { status: _status, ...options },
+  } = resolveAdminDocumentRead(getCollectionDefinition(data.singleton), data)
+  const snapshot = await handle.getForEdit(options)
+  if (snapshot == null) throw ERR_NOT_FOUND({ message: 'Singleton document is unavailable' })
+  return snapshot.state === 'empty' ? null : serialise(snapshot.document)
 }

package/src/server-fns/singletons/cancel-scheduled-publish.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 cancelSingletonScheduledPublish = createServerFn({ method: 'POST' })
-  .validator((input: { singleton: string }) => input)
-  .handler(async ({ data }) =>
-    serialise(await getAdminBylineClient().singleton(data.singleton).cancelScheduledPublish())
+  .middleware([adminSessionMiddleware])
+  .validator((input: { expectedRevision: number; singleton: string }) => input)
+  .handler(
+    withDocumentMutationErrors(async ({ data }) =>
+      serialise(
+        await getAdminBylineClient()
+          .singleton(data.singleton)
+          .cancelScheduledPublish({ expectedRevision: data.expectedRevision })
+      )
+    )
   )