@byline/host-tanstack-start 4.19.0 → 5.1.0

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

@@ -14,6 +14,8 @@ import type { DocumentLifecycleContext } from '@byline/core/services'
 import { restoreDocumentVersion as restoreDocumentVersionService } from '@byline/core/services'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 import { toCommittedDocumentHookFailureResponse } from './save-outcome.js'
 
 // ---------------------------------------------------------------------------
@@ -21,46 +23,54 @@ import { toCommittedDocumentHookFailureResponse } from './save-outcome.js'
 // ---------------------------------------------------------------------------
 
 export const restoreDocumentVersion = createServerFn({ method: 'POST' })
-  .validator((input: { collection: string; id: string; versionId: string }) => input)
-  .handler(async ({ data: input }) => {
-    const { collection: path, id, versionId } = input
-    const logger = getLogger()
-    const config = await ensureCollection(path)
-    if (!config) {
-      throw ERR_NOT_FOUND({
-        message: 'Collection not found',
-        details: { collectionPath: path },
-      }).log(logger)
-    }
+  .middleware([adminSessionMiddleware])
+  .validator(
+    (input: { expectedRevision: number; collection: string; id: string; versionId: string }) =>
+      input
+  )
+  .handler(
+    withDocumentMutationErrors(async ({ data: input }) => {
+      const { collection: path, id, versionId } = input
+      const logger = getLogger()
+      const config = await ensureCollection(path)
+      if (!config) {
+        throw ERR_NOT_FOUND({
+          message: 'Collection not found',
+          details: { collectionPath: path },
+        }).log(logger)
+      }
 
-    const serverConfig = getServerConfig()
-    const ctx: DocumentLifecycleContext = {
-      db: serverConfig.db,
-      definition: config.definition,
-      collectionId: config.collection.id,
-      collectionVersion: config.collection.version,
-      collectionPath: path,
-      logger,
-      defaultLocale: serverConfig.i18n.content.defaultLocale,
-      slugifier: serverConfig.slugifier,
-      requestContext: await getAdminRequestContext(),
-    }
+      const serverConfig = getServerConfig()
+      const ctx: DocumentLifecycleContext = {
+        db: serverConfig.db,
+        definition: config.definition,
+        collectionId: config.collection.id,
+        collectionVersion: config.collection.version,
+        collectionPath: path,
+        logger,
+        defaultLocale: serverConfig.i18n.content.defaultLocale,
+        slugifier: serverConfig.slugifier,
+        requestContext: await getAdminRequestContext(),
+      }
 
-    try {
-      const result = await restoreDocumentVersionService(ctx, {
-        documentId: id,
-        sourceVersionId: versionId,
-      })
+      try {
+        const result = await restoreDocumentVersionService(ctx, {
+          documentId: id,
+          expectedRevision: input.expectedRevision,
+          sourceVersionId: versionId,
+        })
 
-      return {
-        status: 'ok' as const,
-        documentId: result.documentId,
-        documentVersionId: result.documentVersionId,
-        sourceVersionId: result.sourceVersionId,
+        return {
+          status: 'ok' as const,
+          documentId: result.documentId,
+          revision: result.revision,
+          documentVersionId: result.documentVersionId,
+          sourceVersionId: result.sourceVersionId,
+        }
+      } catch (error) {
+        const committedFailure = toCommittedDocumentHookFailureResponse(error)
+        if (committedFailure != null) return committedFailure
+        throw error
       }
-    } catch (error) {
-      const committedFailure = toCommittedDocumentHookFailureResponse(error)
-      if (committedFailure != null) return committedFailure
-      throw error
-    }
-  })
+    })
+  )

package/src/server-fns/collections/revision-input.test.node.ts

@@ -0,0 +1,122 @@
+/**
+ * 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
+ */
+
+// Handler-level tests isolate transport; session-middleware tests exercise the real pre-handler boundary.
+vi.mock('../../integrations/session-middleware.js', () => ({ adminSessionMiddleware: {} }))
+
+import { createSuperAdminContext } from '@byline/auth'
+import {
+  defineCollection,
+  defineServerConfig,
+  getDocumentRevisionValidationDetails,
+} from '@byline/core'
+import { defineLogger } from '@byline/core/logger'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { testAdapter } from '../../../../core/src/storage/db-adapter.test-helper.js'
+
+const fixtures = vi.hoisted(() => ({ ensureCollection: vi.fn(), getAdminRequestContext: vi.fn() }))
+// Simulate only the compiler's binding of a validator to a handler. These are
+// the real exported host handlers and core services, not mocked lifecycle calls.
+vi.mock('@tanstack/react-start', () => ({
+  createServerFn: () => {
+    let validate = (value: unknown) => value
+    const chain = {
+      middleware() {
+        return chain
+      },
+      validator(fn: (value: unknown) => unknown) {
+        validate = fn
+        return chain
+      },
+      handler(fn: (args: { data: unknown }) => Promise<unknown>) {
+        return (args: { data: unknown }) => fn({ data: validate(args.data) })
+      },
+    }
+    return chain
+  },
+}))
+vi.mock('../../integrations/api-utils.js', () => ({ ensureCollection: fixtures.ensureCollection }))
+vi.mock('@byline/client/server', () => ({
+  getAdminRequestContext: fixtures.getAdminRequestContext,
+}))
+
+import { deleteDocument } from './delete.js'
+import { unpublishDocument, updateDocumentStatus } from './status.js'
+import {
+  updateCollectionDocumentSystemFields,
+  updateCollectionDocumentWithPatches,
+} from './update.js'
+
+const write = vi.fn((): never => {
+  throw new Error('Unexpected document write')
+})
+beforeEach(() => {
+  vi.clearAllMocks()
+  const silent = () => {}
+  defineLogger({
+    log: silent,
+    fatal: silent,
+    error: silent,
+    warn: silent,
+    info: silent,
+    debug: silent,
+    trace: silent,
+    silent,
+  })
+  const definition = defineCollection({
+    path: 'pages',
+    labels: { singular: 'Page', plural: 'Pages' },
+    fields: [],
+  })
+  fixtures.ensureCollection.mockResolvedValue({
+    definition,
+    collection: { id: 'collection', version: 1 },
+  })
+  fixtures.getAdminRequestContext.mockResolvedValue(createSuperAdminContext({ id: 'editor' }))
+  defineServerConfig({
+    collections: [definition],
+    db: testAdapter({ withTransaction: write }),
+    i18n: {
+      admin: { defaultLocale: 'en', locales: [] },
+      content: { defaultLocale: 'en', locales: ['en'] },
+    },
+  })
+})
+
+const operations = [
+  ['save', updateCollectionDocumentWithPatches, { patches: [] }],
+  ['metadata', updateCollectionDocumentSystemFields, { path: 'changed' }],
+  ['status', updateDocumentStatus, { status: 'published' }],
+  ['unpublish', unpublishDocument, {}],
+  ['delete', deleteDocument, {}],
+] as const
+
+describe('raw host revision inputs', () => {
+  for (const [name, operation, extra] of operations) {
+    for (const revision of [undefined, null, '1', 0, -1, 1.5, Number.MAX_SAFE_INTEGER + 1]) {
+      it(`${name} rejects ${String(revision)} without writing`, async () => {
+        const data = {
+          collection: 'pages',
+          id: 'document',
+          ...extra,
+          ...(revision === undefined ? {} : { expectedRevision: revision }),
+        }
+        const error = await Reflect.apply(operation, undefined, [{ data }]).catch(
+          (error: unknown) => error
+        )
+        expect(error).toMatchObject({ code: 'ERR_VALIDATION' })
+        expect(getDocumentRevisionValidationDetails(error)).toEqual({
+          reason:
+            revision === undefined ? 'missing_document_revision' : 'invalid_document_revision',
+        })
+        expect(write).not.toHaveBeenCalled()
+      })
+    }
+  }
+})

package/src/server-fns/collections/save-outcome.test.node.ts

@@ -23,6 +23,7 @@ describe('collection save outcome transport', () => {
         phase: 'afterCreate',
         documentId: 'doc-1',
         documentVersionId: 'version-1',
+        revision: 2,
         sideEffectCode: ErrorCodes.STORAGE,
         privatePath: '/private/cache/key',
       },
@@ -34,6 +35,7 @@ describe('collection save outcome transport', () => {
       status: 'committed-hook-failed',
       documentId: 'doc-1',
       documentVersionId: 'version-1',
+      revision: 2,
       sideEffectFailure: { phase: 'afterCreate', code: 'ERR_STORAGE' },
     })
     expect(JSON.stringify(response)).not.toContain('secret hook failure')
@@ -49,6 +51,7 @@ describe('collection save outcome transport', () => {
           phase: 'afterSave',
           documentId: 'doc-singleton',
           documentVersionId: 'version-singleton',
+          revision: 2,
           sideEffectCode: ErrorCodes.UNHANDLED,
         },
       })

package/src/server-fns/collections/save-outcome.ts

@@ -16,6 +16,7 @@ export interface CollectionDocumentCommittedHookFailureResponse {
   status: 'committed-hook-failed'
   documentId: string
   documentVersionId: string
+  revision: number
   sideEffectFailure: {
     phase: DocumentHookCommittedPhase
     code: DocumentHookSideEffectCode
@@ -36,6 +37,7 @@ export function toCommittedDocumentHookFailureResponse(
     status: 'committed-hook-failed',
     documentId: details.documentId,
     documentVersionId: details.documentVersionId,
+    revision: details.revision,
     sideEffectFailure: {
       phase: details.phase,
       code: details.sideEffectCode,

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

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

package/src/server-fns/collections/set-list-view-preference.ts

@@ -27,6 +27,7 @@ import { ERR_NOT_FOUND, getLogger } from '@byline/core'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
 import { bylineCore } from '../../integrations/byline-core.js'
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
 
 export interface SetListViewPreferenceInput {
   collection: string
@@ -38,6 +39,7 @@ export interface SetListViewPreferenceInput {
 }
 
 export const setListViewPreference = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMiddleware])
   .validator((input: SetListViewPreferenceInput) => input)
   .handler(async ({ data }) => {
     // Scopes are keyed by collection path — refuse to mint rows for

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

@@ -11,6 +11,7 @@ import { createServerFn } from '@tanstack/react-start'
 import { getAdminBylineClient } from '@byline/client/server'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
 
 // ---------------------------------------------------------------------------
 // Shared types
@@ -26,6 +27,7 @@ export interface CollectionStatusCount {
 // ---------------------------------------------------------------------------
 
 const getCollectionStatsFn = createServerFn({ method: 'GET' })
+  .middleware([adminSessionMiddleware])
   .validator((input: { collection: string }) => input)
   .handler(async ({ data }) => {
     const config = await ensureCollection(data.collection)