@byline/host-tanstack-start 4.18.0 → 5.0.0

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

@@ -1,3 +1,4 @@
+import { withEditableRevision } from '../editable-revision.js'
 /**
  * This Source Code is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -131,7 +132,7 @@ export const getCollectionDocuments = createServerFn({ method: 'GET' })
     const hasRelations = Object.keys(populateMap).length > 0
     const populate: PopulateSpec | undefined = hasRelations ? populateMap : undefined
 
-    const result = await handle.find({
+    const result = await handle.findForEdit({
       where: Object.keys(where).length > 0 ? where : undefined,
       sort: viewState.sort,
       locale: params.locale ?? 'en',
@@ -140,7 +141,6 @@ export const getCollectionDocuments = createServerFn({ method: 'GET' })
       select: params.fields,
       populate,
       depth: hasRelations ? 1 : undefined,
-      status: 'any',
       // Admin list: show the raw per-locale state (untranslated docs render
       // empty in the active locale's columns) rather than falling back to the
       // default locale. Consistent with the edit view; overrides the client's
@@ -205,5 +205,10 @@ export const getCollectionDocuments = createServerFn({ method: 'GET' })
       return serialised as unknown as ReturnType<typeof list.parse>
     }
 
-    return list.parse(serialised)
+    const parsed = list.parse(serialised)
+    const observations = new Map(result.docs.map((doc) => [doc.id, doc]))
+    return {
+      ...parsed,
+      docs: parsed.docs.map((doc) => withEditableRevision(doc, observations.get(doc.id))),
+    }
   })

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

@@ -1,3 +1,4 @@
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 /**
  * This Source Code is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -9,15 +10,7 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { getAdminRequestContext } from '@byline/client/server'
-import {
-  assertActorCanPerform,
-  ERR_NOT_FOUND,
-  ERR_VALIDATION,
-  generateKeyBetween,
-  generateNKeysBetween,
-  getLogger,
-  getServerConfig,
-} from '@byline/core'
+import { ERR_NOT_FOUND, getLogger, getServerConfig, reorderDocument } from '@byline/core'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
 
@@ -27,138 +20,53 @@ import { ensureCollection } from '../../integrations/api-utils.js'
 // One of `beforeDocumentId` / `afterDocumentId` should be provided — they
 // identify the neighbours the dragged row should land between. Either may
 // be null:
-//   - both null    → empty collection or "append-to-end" no-op (writes
-//                     a fresh key)
+//   - both null    → append to the end; retain the key if already there
 //   - beforeId set, afterId null   → append after `beforeId`
 //   - beforeId null, afterId set   → prepend before `afterId`
 //
-// Writes a single column on `byline_documents` and does NOT create a new
-// document version. Goes through the `collections.<path>.update` ability;
+// Updates ordering and any necessary sibling-key repairs in one guarded
+// transaction, without creating content versions. Uses `collections.<path>.update`;
 // reordering is metadata-level update, not a new ability slug.
 // ---------------------------------------------------------------------------
 
 export const reorderCollectionDocument = createServerFn({ method: 'POST' })
   .validator(
     (input: {
+      expectedRevision: number
       collection: string
       documentId: string
       beforeDocumentId?: string | null
       afterDocumentId?: string | null
     }) => input
   )
-  .handler(async ({ data: input }) => {
-    const { collection: path, documentId, beforeDocumentId, afterDocumentId } = input
-    const logger = getLogger()
-
-    const config = await ensureCollection(path)
-    if (!config) {
-      throw ERR_NOT_FOUND({
-        message: 'Collection not found',
-        details: { collectionPath: path },
-      }).log(logger)
-    }
-
-    if (config.definition.orderable !== true) {
-      throw ERR_VALIDATION({
-        message: `collection '${path}' is not orderable; set \`orderable: true\` on its collection definition to enable reordering`,
-        details: { collectionPath: path },
-      }).log(logger)
-    }
-
-    const requestContext = await getAdminRequestContext()
-    assertActorCanPerform(requestContext, config.definition, 'update')
-
-    const serverConfig = getServerConfig()
-    const collectionId = config.collection.id
-
-    // Read the whole collection in canonical display order. Small by design
-    // for orderable use cases (bios, FAQs, sections), so a full read is
-    // cheap — and it gives us a single, consistent snapshot to reason about
-    // both backfill and recovery in one pass.
-    const canonical = await serverConfig.db.queries.documents.getCanonicalDocumentOrder({
-      collection_id: collectionId,
-    })
-
-    // Detect pathological key state — duplicates or non-ascending runs of
-    // keyed rows. These can land in the DB from prior buggy code paths
-    // or interrupted writes; once present, `generateKeyBetween` throws
-    // with `a >= b`. When detected, re-key the entire collection in the
-    // editor's current visible order so subsequent operations work from
-    // a clean baseline.
-    let corrupted = false
-    {
-      const seen = new Set<string>()
-      let lastKey: string | null = null
-      for (const doc of canonical) {
-        if (doc.order_key == null) continue
-        if (seen.has(doc.order_key)) {
-          corrupted = true
-          break
-        }
-        if (lastKey != null && doc.order_key <= lastKey) {
-          corrupted = true
-          break
-        }
-        seen.add(doc.order_key)
-        lastKey = doc.order_key
+  .handler(
+    withDocumentMutationErrors(async ({ data: input }) => {
+      const { collection: path, documentId, beforeDocumentId, afterDocumentId } = input
+      const logger = getLogger()
+
+      const config = await ensureCollection(path)
+      if (!config) {
+        throw ERR_NOT_FOUND({
+          message: 'Collection not found',
+          details: { collectionPath: path },
+        }).log(logger)
       }
-    }
 
-    if (corrupted) {
-      const allKeys = generateNKeysBetween(null, null, canonical.length)
-      for (let i = 0; i < canonical.length; i++) {
-        await serverConfig.db.commands.documents.setOrderKey({
-          document_id: canonical[i]?.id,
-          order_key: allKeys[i]!,
-        })
-      }
-    } else {
-      // Happy path — backfill trailing NULLs after the largest existing
-      // key. After canonical sort the NULL rows are always contiguous at
-      // the tail (`NULLS LAST`).
-      const firstNullIdx = canonical.findIndex((d) => d.order_key == null)
-      if (firstNullIdx !== -1) {
-        const nullDocs = canonical.slice(firstNullIdx)
-        const lastExistingKey = firstNullIdx === 0 ? null : canonical[firstNullIdx - 1]?.order_key
-        const newKeys = generateNKeysBetween(lastExistingKey, null, nullDocs.length)
-        for (let i = 0; i < nullDocs.length; i++) {
-          await serverConfig.db.commands.documents.setOrderKey({
-            document_id: nullDocs[i]?.id,
-            order_key: newKeys[i]!,
-          })
-        }
-      }
-    }
-
-    // Keys are now clean — resolve neighbours and place the moved row.
-    const { left, right } = await serverConfig.db.queries.documents.getNeighborOrderKeys({
-      collection_id: collectionId,
-      before_document_id: beforeDocumentId ?? null,
-      after_document_id: afterDocumentId ?? null,
-    })
-
-    let newKey: string
-    try {
-      newKey = generateKeyBetween(left, right)
-    } catch (err) {
-      throw ERR_VALIDATION({
-        message: 'cannot generate order_key between supplied neighbors',
-        details: {
+      const serverConfig = getServerConfig()
+      const result = await reorderDocument(
+        {
+          db: serverConfig.db,
+          definition: config.definition,
+          collectionId: config.collection.id,
+          collectionVersion: config.collection.version,
           collectionPath: path,
-          documentId,
-          beforeDocumentId,
-          afterDocumentId,
-          left,
-          right,
-          cause: err instanceof Error ? err.message : String(err),
+          requestContext: await getAdminRequestContext(),
+          logger,
+          defaultLocale: serverConfig.i18n.content.defaultLocale,
+          slugifier: serverConfig.slugifier,
         },
-      }).log(logger)
-    }
-
-    await serverConfig.db.commands.documents.setOrderKey({
-      document_id: documentId,
-      order_key: newKey,
+        { documentId, expectedRevision: input.expectedRevision, beforeDocumentId, afterDocumentId }
+      )
+      return { status: 'ok' as const, ...result }
     })
-
-    return { status: 'ok' as const, orderKey: newKey }
-  })
+  )

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

@@ -1,3 +1,4 @@
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 /**
  * This Source Code is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -14,46 +15,60 @@ import type { DocumentLifecycleContext } from '@byline/core/services'
 import { restoreDocumentVersion as restoreDocumentVersionService } from '@byline/core/services'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
+import { toCommittedDocumentHookFailureResponse } from './save-outcome.js'
 
 // ---------------------------------------------------------------------------
 // Restore a historical document version as the new current version
 // ---------------------------------------------------------------------------
 
 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)
-    }
-
-    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 result = await restoreDocumentVersionService(ctx, {
-      documentId: id,
-      sourceVersionId: versionId,
-    })
+  .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(),
+      }
 
-    return {
-      status: 'ok' as const,
-      documentId: result.documentId,
-      documentVersionId: result.documentVersionId,
-      sourceVersionId: result.sourceVersionId,
-    }
-  })
+      try {
+        const result = await restoreDocumentVersionService(ctx, {
+          documentId: id,
+          expectedRevision: input.expectedRevision,
+          sourceVersionId: versionId,
+        })
+
+        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
+      }
+    })
+  )

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

@@ -0,0 +1,108 @@
+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 = {
+      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

@@ -0,0 +1,80 @@
+/**
+ * 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 { ERR_DOCUMENT_HOOK_COMMITTED, ErrorCodes } from '@byline/core'
+import { describe, expect, it } from 'vitest'
+
+import {
+  hasCommittedDocumentHookFailure,
+  toCommittedDocumentHookFailureResponse,
+} from './save-outcome.js'
+
+describe('collection save outcome transport', () => {
+  it('returns only allowlisted committed hook metadata', () => {
+    const error = ERR_DOCUMENT_HOOK_COMMITTED({
+      message: 'internal message',
+      cause: new Error('secret hook failure'),
+      details: {
+        phase: 'afterCreate',
+        documentId: 'doc-1',
+        documentVersionId: 'version-1',
+        revision: 2,
+        sideEffectCode: ErrorCodes.STORAGE,
+        privatePath: '/private/cache/key',
+      },
+    })
+
+    const response = toCommittedDocumentHookFailureResponse(error)
+
+    expect(response).toEqual({
+      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')
+    expect(JSON.stringify(response)).not.toContain('/private/cache/key')
+    expect(hasCommittedDocumentHookFailure(response)).toBe(true)
+  })
+
+  it('accepts the singleton afterSave phase exported by core', () => {
+    const response = toCommittedDocumentHookFailureResponse(
+      ERR_DOCUMENT_HOOK_COMMITTED({
+        message: 'singleton committed',
+        details: {
+          phase: 'afterSave',
+          documentId: 'doc-singleton',
+          documentVersionId: 'version-singleton',
+          revision: 2,
+          sideEffectCode: ErrorCodes.UNHANDLED,
+        },
+      })
+    )
+
+    expect(response?.sideEffectFailure).toEqual({
+      phase: 'afterSave',
+      code: ErrorCodes.UNHANDLED,
+    })
+  })
+
+  it('does not classify ordinary or malformed failures as committed', () => {
+    expect(toCommittedDocumentHookFailureResponse(new Error('write failed'))).toBeNull()
+    expect(
+      toCommittedDocumentHookFailureResponse({
+        code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+        message: 'missing ids',
+        details: {
+          phase: 'afterUpdate',
+          sideEffectCode: ErrorCodes.UNHANDLED,
+        },
+      })
+    ).toBeNull()
+    expect(hasCommittedDocumentHookFailure({ status: 'ok' })).toBe(false)
+  })
+})

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

@@ -0,0 +1,57 @@
+/**
+ * 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 {
+  type DocumentHookCommittedPhase,
+  type DocumentHookSideEffectCode,
+  getDocumentHookCommittedDetails,
+} from '@byline/core/services'
+
+export interface CollectionDocumentCommittedHookFailureResponse {
+  status: 'committed-hook-failed'
+  documentId: string
+  documentVersionId: string
+  revision: number
+  sideEffectFailure: {
+    phase: DocumentHookCommittedPhase
+    code: DocumentHookSideEffectCode
+  }
+}
+
+/**
+ * Convert only validated core committed-hook errors into safe wire data. Raw
+ * hook errors, messages, stack traces, and storage paths remain server-side.
+ */
+export function toCommittedDocumentHookFailureResponse(
+  error: unknown
+): CollectionDocumentCommittedHookFailureResponse | null {
+  const details = getDocumentHookCommittedDetails(error)
+  if (details == null) return null
+
+  return {
+    status: 'committed-hook-failed',
+    documentId: details.documentId,
+    documentVersionId: details.documentVersionId,
+    revision: details.revision,
+    sideEffectFailure: {
+      phase: details.phase,
+      code: details.sideEffectCode,
+    },
+  }
+}
+
+export function hasCommittedDocumentHookFailure(
+  result: unknown
+): result is CollectionDocumentCommittedHookFailureResponse {
+  return (
+    typeof result === 'object' &&
+    result != null &&
+    'status' in result &&
+    result.status === 'committed-hook-failed'
+  )
+}