@byline/host-tanstack-start 4.18.0 → 5.0.0

package/src/server-fns/collections/copy-to-locale.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,6 +15,10 @@ import type { CopyToLocaleResult, DocumentLifecycleContext } from '@byline/core/
 import { copyToLocale } from '@byline/core/services'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
+import {
+  type CollectionDocumentCommittedHookFailureResponse,
+  toCommittedDocumentHookFailureResponse,
+} from './save-outcome.js'
 
 // ---------------------------------------------------------------------------
 // Copy document content from one locale into another
@@ -31,6 +36,7 @@ import { ensureCollection } from '../../integrations/api-utils.js'
 export const copyDocumentToLocale = createServerFn({ method: 'POST' })
   .validator(
     (input: {
+      expectedRevision: number
       collection: string
       id: string
       sourceLocale: string
@@ -38,34 +44,47 @@ export const copyDocumentToLocale = createServerFn({ method: 'POST' })
       overwrite: boolean
     }) => input
   )
-  .handler(async ({ data: input }): Promise<CopyToLocaleResult> => {
-    const { collection: path, id, sourceLocale, targetLocale, overwrite } = input
-    const logger = getLogger()
-    const config = await ensureCollection(path)
-    if (!config) {
-      throw ERR_NOT_FOUND({
-        message: 'Collection not found',
-        details: { collectionPath: path },
-      }).log(logger)
-    }
+  .handler(
+    withDocumentMutationErrors(
+      async ({
+        data: input,
+      }): Promise<CopyToLocaleResult | CollectionDocumentCommittedHookFailureResponse> => {
+        const { collection: path, id, sourceLocale, targetLocale, overwrite } = 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(),
+        }
 
-    return copyToLocale(ctx, {
-      documentId: id,
-      sourceLocale,
-      targetLocale,
-      overwrite,
-    })
-  })
+        try {
+          return await copyToLocale(ctx, {
+            documentId: id,
+            expectedRevision: input.expectedRevision,
+            sourceLocale,
+            targetLocale,
+            overwrite,
+          })
+        } catch (error) {
+          const committedFailure = toCommittedDocumentHookFailureResponse(error)
+          if (committedFailure != null) return committedFailure
+          throw error
+        }
+      }
+    )
+  )

package/src/server-fns/collections/create.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
@@ -10,10 +11,11 @@ import { createServerFn } from '@tanstack/react-start'
 
 import { getAdminRequestContext } from '@byline/client/server'
 import { ERR_NOT_FOUND, getLogger, getServerConfig } from '@byline/core'
-import type { DocumentLifecycleContext } from '@byline/core/services'
+import type { CreateDocumentResult, DocumentLifecycleContext } from '@byline/core/services'
 import { createDocument } from '@byline/core/services'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
+import { toCommittedDocumentHookFailureResponse } from './save-outcome.js'
 
 // ---------------------------------------------------------------------------
 // Create document
@@ -29,49 +31,59 @@ export const createCollectionDocument = createServerFn({ method: 'POST' })
       availableLocales?: string[]
     }) => input
   )
-  .handler(async ({ data: input }) => {
-    const {
-      collection: path,
-      data: documentData,
-      locale,
-      path: explicitPath,
-      availableLocales,
-    } = input
-    const logger = getLogger()
-    const config = await ensureCollection(path)
-    if (!config) {
-      throw ERR_NOT_FOUND({
-        message: 'Collection not found',
-        details: { collectionPath: path },
-      }).log(logger)
-    }
+  .handler(
+    withDocumentMutationErrors(async ({ data: input }) => {
+      const {
+        collection: path,
+        data: documentData,
+        locale,
+        path: explicitPath,
+        availableLocales,
+      } = 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(),
+      }
 
-    const result = await createDocument(ctx, {
-      data: structuredClone(documentData),
-      status: documentData.status,
-      locale: locale ?? serverConfig.i18n.content.defaultLocale,
-      path: explicitPath,
-      availableLocales,
-    })
+      let result: CreateDocumentResult
+      try {
+        result = await createDocument(ctx, {
+          data: structuredClone(documentData),
+          status: documentData.status,
+          locale: locale ?? serverConfig.i18n.content.defaultLocale,
+          path: explicitPath,
+          availableLocales,
+        })
+      } catch (error) {
+        const committedFailure = toCommittedDocumentHookFailureResponse(error)
+        if (committedFailure != null) return committedFailure
+        throw error
+      }
 
-    // The new document's id is returned so the create view can navigate
-    // straight to the edit view (create → edit).
-    return {
-      status: 'ok' as const,
-      documentId: result.documentId,
-      documentVersionId: result.documentVersionId,
-    }
-  })
+      // The new document's id is returned so the create view can navigate
+      // straight to the edit view (create → edit).
+      return {
+        status: 'ok' as const,
+        documentId: result.documentId,
+        documentVersionId: result.documentVersionId,
+        revision: result.revision,
+      }
+    })
+  )

package/src/server-fns/collections/delete-locale.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,6 +15,10 @@ import type { DeleteLocaleResult, DocumentLifecycleContext } from '@byline/core/
 import { deleteLocale } from '@byline/core/services'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
+import {
+  type CollectionDocumentCommittedHookFailureResponse,
+  toCommittedDocumentHookFailureResponse,
+} from './save-outcome.js'
 
 // ---------------------------------------------------------------------------
 // Delete one content locale's data from a document
@@ -30,30 +35,48 @@ import { ensureCollection } from '../../integrations/api-utils.js'
  * transport layer.
  */
 export const deleteDocumentLocale = createServerFn({ method: 'POST' })
-  .validator((input: { collection: string; id: string; locale: string }) => input)
-  .handler(async ({ data: input }): Promise<DeleteLocaleResult> => {
-    const { collection: path, id, locale } = input
-    const logger = getLogger()
-    const config = await ensureCollection(path)
-    if (!config) {
-      throw ERR_NOT_FOUND({
-        message: 'Collection not found',
-        details: { collectionPath: path },
-      }).log(logger)
-    }
+  .validator(
+    (input: { expectedRevision: number; collection: string; id: string; locale: string }) => input
+  )
+  .handler(
+    withDocumentMutationErrors(
+      async ({
+        data: input,
+      }): Promise<DeleteLocaleResult | CollectionDocumentCommittedHookFailureResponse> => {
+        const { collection: path, id, locale } = 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(),
+        }
 
-    return deleteLocale(ctx, { documentId: id, locale })
-  })
+        try {
+          return await deleteLocale(ctx, {
+            documentId: id,
+            expectedRevision: input.expectedRevision,
+            locale,
+          })
+        } catch (error) {
+          const committedFailure = toCommittedDocumentHookFailureResponse(error)
+          if (committedFailure != null) return committedFailure
+          throw error
+        }
+      }
+    )
+  )

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

@@ -16,6 +16,10 @@ describe('delete outcome transport and admin interpretation', () => {
     // Simulate malformed runtime data from an older or compromised source. The
     // core type rejects this shape, but the transport still sanitizes it.
     const unsafeResult = {
+      documentId: 'doc-1',
+      revision: 2,
+      affectedDocuments: [{ documentId: 'child', revision: 3 }],
+      scheduledPublicationsNeedReconfirmation: true,
       deletedVersionCount: 2,
       outcome: 'committed-with-side-effect-failures',
       sideEffectFailures: [
@@ -36,6 +40,10 @@ describe('delete outcome transport and admin interpretation', () => {
 
     expect(response).toEqual({
       status: 'ok',
+      documentId: 'doc-1',
+      revision: 2,
+      affectedDocuments: [{ documentId: 'child', revision: 3 }],
+      scheduledPublicationsNeedReconfirmation: true,
       deletedVersionCount: 2,
       outcome: 'committed-with-side-effect-failures',
       sideEffectFailures: [
@@ -53,6 +61,10 @@ describe('delete outcome transport and admin interpretation', () => {
 
   it('preserves the committed success discriminant and empty failures', () => {
     const response = toDeleteDocumentResponse({
+      documentId: 'doc-1',
+      revision: 2,
+      affectedDocuments: [{ documentId: 'child', revision: 3 }],
+      scheduledPublicationsNeedReconfirmation: true,
       deletedVersionCount: 2,
       outcome: 'committed',
       sideEffectFailures: [],
@@ -60,6 +72,10 @@ describe('delete outcome transport and admin interpretation', () => {
 
     expect(response).toEqual({
       status: 'ok',
+      documentId: 'doc-1',
+      revision: 2,
+      affectedDocuments: [{ documentId: 'child', revision: 3 }],
+      scheduledPublicationsNeedReconfirmation: true,
       deletedVersionCount: 2,
       outcome: 'committed',
       sideEffectFailures: [],

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

@@ -10,6 +10,7 @@ import type {
   DeleteDocumentResult,
   DeleteDocumentSideEffectCode,
   DeleteDocumentSideEffectPhase,
+  StructuralMutationReceipt,
 } from '@byline/core'
 import { ErrorCodes } from '@byline/core'
 
@@ -21,22 +22,28 @@ export interface DeleteDocumentPublicSideEffectFailure {
   code: DeleteDocumentPublicSideEffectCode
 }
 
-export type DeleteDocumentResponse =
-  | {
-      status: 'ok'
-      deletedVersionCount: number
-      outcome: 'committed'
-      sideEffectFailures: []
-    }
-  | {
-      status: 'ok'
-      deletedVersionCount: number
-      outcome: 'committed-with-side-effect-failures'
-      sideEffectFailures: [
-        DeleteDocumentPublicSideEffectFailure,
-        ...DeleteDocumentPublicSideEffectFailure[],
-      ]
-    }
+export type DeleteDocumentResponse = StructuralMutationReceipt &
+  (
+    | {
+        status: 'ok'
+        documentId: string
+        revision: number
+        deletedVersionCount: number
+        outcome: 'committed'
+        sideEffectFailures: []
+      }
+    | {
+        status: 'ok'
+        documentId: string
+        revision: number
+        deletedVersionCount: number
+        outcome: 'committed-with-side-effect-failures'
+        sideEffectFailures: [
+          DeleteDocumentPublicSideEffectFailure,
+          ...DeleteDocumentPublicSideEffectFailure[],
+        ]
+      }
+  )
 
 function sanitizePhase(phase: DeleteDocumentSideEffectPhase): DeleteDocumentPublicSideEffectPhase {
   if (phase === 'afterTreeChange' || phase === 'afterDelete') {
@@ -67,6 +74,10 @@ export function toDeleteDocumentResponse(result: DeleteDocumentResult): DeleteDo
   const [firstFailure, ...remainingFailures] = result.sideEffectFailures
   return {
     status: 'ok',
+    documentId: result.documentId,
+    revision: result.revision,
+    affectedDocuments: result.affectedDocuments,
+    scheduledPublicationsNeedReconfirmation: result.scheduledPublicationsNeedReconfirmation,
     deletedVersionCount: result.deletedVersionCount,
     outcome: result.outcome,
     sideEffectFailures: [sanitizeFailure(firstFailure), ...remainingFailures.map(sanitizeFailure)],

package/src/server-fns/collections/delete.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
@@ -21,43 +22,48 @@ import { toDeleteDocumentResponse } from './delete-outcome.js'
 // ---------------------------------------------------------------------------
 
 export const deleteDocument = createServerFn({ method: 'POST' })
-  .validator((input: { collection: string; id: string }) => input)
-  .handler(async ({ data: input }) => {
-    const { collection: path, id } = input
-    const logger = getLogger()
-    const config = await ensureCollection(path)
-    if (!config) {
-      throw ERR_NOT_FOUND({
-        message: 'Collection not found',
-        details: { collectionPath: path },
-      }).log(logger)
-    }
+  .validator((input: { expectedRevision: number; collection: string; id: string }) => input)
+  .handler(
+    withDocumentMutationErrors(async ({ data: input }) => {
+      const { collection: path, id } = 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()
-    // Resolve the storage provider so the lifecycle service can clean up
-    // uploaded files and variants on deletion. With per-field upload
-    // config, a collection may have one (or more) image/file fields with
-    // their own storage. The delete path needs *a* provider; we pick the
-    // first upload-capable field's, falling back to the site-wide
-    // default. Multi-storage collections are out of scope today —
-    // deletion routes everything through one provider, which is fine
-    // when all upload fields target the same backend (the common case).
-    const firstUploadField = getUploadFields(config.definition)[0]
-    const storage = firstUploadField?.upload?.storage ?? serverConfig.storage
-    const db = serverConfig.db
-    const ctx: DocumentLifecycleContext = {
-      db,
-      definition: config.definition,
-      collectionId: config.collection.id,
-      collectionVersion: config.collection.version,
-      collectionPath: path,
-      ...(storage ? { storage } : {}),
-      logger,
-      defaultLocale: serverConfig.i18n.content.defaultLocale,
-      slugifier: serverConfig.slugifier,
-      requestContext: await getAdminRequestContext(),
-    }
+      const serverConfig = getServerConfig()
+      // Resolve the storage provider so the lifecycle service can clean up
+      // uploaded files and variants on deletion. With per-field upload
+      // config, a collection may have one (or more) image/file fields with
+      // their own storage. The delete path needs *a* provider; we pick the
+      // first upload-capable field's, falling back to the site-wide
+      // default. Multi-storage collections are out of scope today —
+      // deletion routes everything through one provider, which is fine
+      // when all upload fields target the same backend (the common case).
+      const firstUploadField = getUploadFields(config.definition)[0]
+      const storage = firstUploadField?.upload?.storage ?? serverConfig.storage
+      const db = serverConfig.db
+      const ctx: DocumentLifecycleContext = {
+        db,
+        definition: config.definition,
+        collectionId: config.collection.id,
+        collectionVersion: config.collection.version,
+        collectionPath: path,
+        ...(storage ? { storage } : {}),
+        logger,
+        defaultLocale: serverConfig.i18n.content.defaultLocale,
+        slugifier: serverConfig.slugifier,
+        requestContext: await getAdminRequestContext(),
+      }
 
-    const result = await deleteDocumentService(ctx, { documentId: id })
-    return toDeleteDocumentResponse(result)
-  })
+      const result = await deleteDocumentService(ctx, {
+        documentId: id,
+        expectedRevision: input.expectedRevision,
+      })
+      return toDeleteDocumentResponse(result)
+    })
+  )

package/src/server-fns/collections/duplicate.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,6 +15,10 @@ import type { DocumentLifecycleContext, DuplicateDocumentResult } from '@byline/
 import { duplicateDocument } from '@byline/core/services'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
+import {
+  type CollectionDocumentCommittedHookFailureResponse,
+  toCommittedDocumentHookFailureResponse,
+} from './save-outcome.js'
 
 // ---------------------------------------------------------------------------
 // Duplicate document
@@ -31,30 +36,45 @@ import { ensureCollection } from '../../integrations/api-utils.js'
  * TanStack Start's transport layer for the client to branch on.
  */
 export const duplicateCollectionDocument = createServerFn({ method: 'POST' })
-  .validator((input: { collection: string; id: string }) => input)
-  .handler(async ({ data: input }): Promise<DuplicateDocumentResult> => {
-    const { collection: path, id: sourceDocumentId } = input
-    const logger = getLogger()
-    const config = await ensureCollection(path)
-    if (!config) {
-      throw ERR_NOT_FOUND({
-        message: 'Collection not found',
-        details: { collectionPath: path },
-      }).log(logger)
-    }
+  .validator((input: { expectedRevision: number; collection: string; id: string }) => input)
+  .handler(
+    withDocumentMutationErrors(
+      async ({
+        data: input,
+      }): Promise<DuplicateDocumentResult | CollectionDocumentCommittedHookFailureResponse> => {
+        const { collection: path, id: sourceDocumentId } = 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(),
+        }
 
-    return duplicateDocument(ctx, { sourceDocumentId })
-  })
+        try {
+          return await duplicateDocument(ctx, {
+            sourceDocumentId,
+            expectedRevision: input.expectedRevision,
+          })
+        } catch (error) {
+          const committedFailure = toCommittedDocumentHookFailureResponse(error)
+          if (committedFailure != null) return committedFailure
+          throw error
+        }
+      }
+    )
+  )

package/src/server-fns/collections/get.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
@@ -51,13 +52,16 @@ const getDocumentFn = createServerFn({ method: 'GET' })
     const client = getAdminBylineClient()
     const handle = client.collection(path)
 
-    const { options: readOptions, populatedTree } = resolveAdminDocumentRead(config.definition, {
+    const {
+      options: { status: _status, ...readOptions },
+      populatedTree,
+    } = resolveAdminDocumentRead(config.definition, {
       locale,
       depth,
       populateRelations,
     })
 
-    const document = await handle.findById(id, {
+    const document = await handle.findByIdForEdit(id, {
       ...readOptions,
     })
 
@@ -141,13 +145,13 @@ const getDocumentFn = createServerFn({ method: 'GET' })
         actor?.hasAbility(documentAbilityKey(config.definition, 'changeStatus')) === true &&
         actor.hasAbility(documentAbilityKey(config.definition, 'publish'))
       if (canSchedulePublication) {
-        scheduledPublish = await handle.getScheduledPublish(id)
+        scheduledPublish = document.scheduledPublication
       }
     }
     const serializedSchedule = scheduledPublish == null ? null : serialise(scheduledPublish)
 
     return {
-      ...(parsed as Record<string, any>),
+      ...withEditableRevision(parsed, document),
       _publishedVersion: publishedVersion,
       ...(restoreWarnings && restoreWarnings.length > 0
         ? { _restoreWarnings: restoreWarnings }

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

@@ -18,6 +18,7 @@ export * from './list'
 export * from './reindex'
 export * from './reorder'
 export * from './restore-version'
+export * from './save-outcome'
 export * from './scheduled-publication'
 export * from './set-list-view-preference'
 export * from './stats'