@byline/host-tanstack-start 4.17.0 → 4.19.0

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

@@ -10,10 +10,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
@@ -59,13 +60,20 @@ export const createCollectionDocument = createServerFn({ method: 'POST' })
       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).

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

@@ -14,6 +14,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
@@ -31,29 +35,39 @@ import { ensureCollection } from '../../integrations/api-utils.js'
  */
 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)
-    }
+  .handler(
+    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, locale })
+      } catch (error) {
+        const committedFailure = toCommittedDocumentHookFailureResponse(error)
+        if (committedFailure != null) return committedFailure
+        throw error
+      }
+    }
+  )

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

@@ -14,6 +14,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
@@ -32,29 +36,39 @@ import { ensureCollection } from '../../integrations/api-utils.js'
  */
 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)
-    }
+  .handler(
+    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 })
+      } catch (error) {
+        const committedFailure = toCommittedDocumentHookFailureResponse(error)
+        if (committedFailure != null) return committedFailure
+        throw error
+      }
+    }
+  )

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'

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

@@ -14,6 +14,7 @@ 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
@@ -45,15 +46,21 @@ export const restoreDocumentVersion = createServerFn({ method: 'POST' })
       requestContext: await getAdminRequestContext(),
     }
 
-    const result = await restoreDocumentVersionService(ctx, {
-      documentId: id,
-      sourceVersionId: versionId,
-    })
+    try {
+      const result = await restoreDocumentVersionService(ctx, {
+        documentId: id,
+        sourceVersionId: versionId,
+      })
 
-    return {
-      status: 'ok' as const,
-      documentId: result.documentId,
-      documentVersionId: result.documentVersionId,
-      sourceVersionId: result.sourceVersionId,
+      return {
+        status: 'ok' as const,
+        documentId: result.documentId,
+        documentVersionId: result.documentVersionId,
+        sourceVersionId: result.sourceVersionId,
+      }
+    } catch (error) {
+      const committedFailure = toCommittedDocumentHookFailureResponse(error)
+      if (committedFailure != null) return committedFailure
+      throw error
     }
   })

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

@@ -0,0 +1,77 @@
+/**
+ * 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',
+        sideEffectCode: ErrorCodes.STORAGE,
+        privatePath: '/private/cache/key',
+      },
+    })
+
+    const response = toCommittedDocumentHookFailureResponse(error)
+
+    expect(response).toEqual({
+      status: 'committed-hook-failed',
+      documentId: 'doc-1',
+      documentVersionId: 'version-1',
+      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',
+          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,55 @@
+/**
+ * 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
+  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,
+    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'
+  )
+}

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

@@ -11,10 +11,14 @@ import { createServerFn } from '@tanstack/react-start'
 import { getAdminRequestContext } from '@byline/client/server'
 import { ERR_NOT_FOUND, getLogger, getServerConfig } from '@byline/core'
 import type { DocumentPatch } from '@byline/core/patches'
-import type { DocumentLifecycleContext } from '@byline/core/services'
+import type {
+  DocumentLifecycleContext,
+  UpdateDocumentWithPatchesResult,
+} from '@byline/core/services'
 import { updateDocumentSystemFields, updateDocumentWithPatches } from '@byline/core/services'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
+import { toCommittedDocumentHookFailureResponse } from './save-outcome.js'
 
 // ---------------------------------------------------------------------------
 // Apply patches (patch-based update — creates a new immutable version)
@@ -59,14 +63,25 @@ export const updateCollectionDocumentWithPatches = createServerFn({ method: 'POS
       requestContext: await getAdminRequestContext(),
     }
 
-    await updateDocumentWithPatches(ctx, {
-      documentId: id,
-      patches,
-      documentVersionId: versionId,
-      locale: locale ?? serverConfig.i18n.content.defaultLocale,
-    })
+    let result: UpdateDocumentWithPatchesResult
+    try {
+      result = await updateDocumentWithPatches(ctx, {
+        documentId: id,
+        patches,
+        documentVersionId: versionId,
+        locale: locale ?? serverConfig.i18n.content.defaultLocale,
+      })
+    } catch (error) {
+      const committedFailure = toCommittedDocumentHookFailureResponse(error)
+      if (committedFailure != null) return committedFailure
+      throw error
+    }
 
-    return { status: 'ok' as const }
+    return {
+      status: 'ok' as const,
+      documentId: result.documentId,
+      documentVersionId: result.documentVersionId,
+    }
   })
 
 // ---------------------------------------------------------------------------

package/src/server-fns/singletons/copy-to-locale.ts

@@ -10,6 +10,7 @@ import { createServerFn } from '@tanstack/react-start'
 
 import { getAdminBylineClient } from '@byline/client/server'
 
+import { toCommittedDocumentHookFailureResponse } from '../collections/save-outcome.js'
 import { serialise } from '../serialise.js'
 
 export const copySingletonToLocale = createServerFn({ method: 'POST' })
@@ -21,12 +22,18 @@ export const copySingletonToLocale = createServerFn({ method: 'POST' })
       overwrite?: boolean
     }) => input
   )
-  .handler(async ({ data }) =>
-    serialise(
-      await getAdminBylineClient().singleton(data.singleton).copyToLocale({
-        sourceLocale: data.sourceLocale,
-        targetLocale: data.targetLocale,
-        overwrite: data.overwrite,
-      })
-    )
-  )
+  .handler(async ({ data }) => {
+    try {
+      return serialise(
+        await getAdminBylineClient().singleton(data.singleton).copyToLocale({
+          sourceLocale: data.sourceLocale,
+          targetLocale: data.targetLocale,
+          overwrite: data.overwrite,
+        })
+      )
+    } catch (error) {
+      const committedFailure = toCommittedDocumentHookFailureResponse(error)
+      if (committedFailure != null) return committedFailure
+      throw error
+    }
+  })

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

@@ -10,10 +10,19 @@ import { createServerFn } from '@tanstack/react-start'
 
 import { getAdminBylineClient } from '@byline/client/server'
 
+import { toCommittedDocumentHookFailureResponse } from '../collections/save-outcome.js'
 import { serialise } from '../serialise.js'
 
 export const restoreSingletonVersion = createServerFn({ method: 'POST' })
   .validator((input: { singleton: string; versionId: string }) => input)
-  .handler(async ({ data }) =>
-    serialise(await getAdminBylineClient().singleton(data.singleton).restoreVersion(data.versionId))
-  )
+  .handler(async ({ data }) => {
+    try {
+      return serialise(
+        await getAdminBylineClient().singleton(data.singleton).restoreVersion(data.versionId)
+      )
+    } catch (error) {
+      const committedFailure = toCommittedDocumentHookFailureResponse(error)
+      if (committedFailure != null) return committedFailure
+      throw error
+    }
+  })

package/src/server-fns/singletons/singletons.test.node.ts

@@ -6,6 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 
+import { ERR_DOCUMENT_HOOK_COMMITTED, ErrorCodes } from '@byline/core'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 const mocks = vi.hoisted(() => ({
@@ -233,6 +234,39 @@ describe('singleton server functions', () => {
     )
   })
 
+  it.each([
+    ['update', updateSingleton, { singleton: 'site-settings', data: { title: 'Changed' } }],
+    [
+      'copyToLocale',
+      copySingletonToLocale,
+      { singleton: 'site-settings', sourceLocale: 'en', targetLocale: 'fr' },
+    ],
+    [
+      'restoreVersion',
+      restoreSingletonVersion,
+      { singleton: 'site-settings', versionId: 'version-1' },
+    ],
+  ] as const)('returns a committed hook outcome for %s', async (method, serverFunction, input) => {
+    handle[method].mockRejectedValueOnce(
+      ERR_DOCUMENT_HOOK_COMMITTED({
+        message: 'write committed',
+        details: {
+          phase: 'afterSave',
+          documentId: 'doc-settings',
+          documentVersionId: 'version-next',
+          sideEffectCode: ErrorCodes.UNHANDLED,
+        },
+      })
+    )
+
+    await expect(invoke(serverFunction, input)).resolves.toEqual({
+      status: 'committed-hook-failed',
+      documentId: 'doc-settings',
+      documentVersionId: 'version-next',
+      sideEffectFailure: { phase: 'afterSave', code: ErrorCodes.UNHANDLED },
+    })
+  })
+
   it('preserves authentication failures from the handle', async () => {
     const error = { code: 'ERR_UNAUTHENTICATED', message: 'sign in required' }
     handle.get.mockRejectedValueOnce(error)

package/src/server-fns/singletons/update.ts

@@ -10,6 +10,7 @@ import { createServerFn } from '@tanstack/react-start'
 
 import { getAdminBylineClient } from '@byline/client/server'
 
+import { toCommittedDocumentHookFailureResponse } from '../collections/save-outcome.js'
 import { serialise } from '../serialise.js'
 
 export interface UpdateSingletonInput {
@@ -23,9 +24,15 @@ export const updateSingleton = createServerFn({ method: 'POST' })
   .validator((input: UpdateSingletonInput) => input)
   .handler(async ({ data }) => {
     const { singleton, data: fields, locale, expectedVersionId } = data
-    const result = await getAdminBylineClient().singleton(singleton).update(fields, {
-      locale,
-      expectedVersionId,
-    })
-    return serialise(result)
+    try {
+      const result = await getAdminBylineClient().singleton(singleton).update(fields, {
+        locale,
+        expectedVersionId,
+      })
+      return serialise(result)
+    } catch (error) {
+      const committedFailure = toCommittedDocumentHookFailureResponse(error)
+      if (committedFailure != null) return committedFailure
+      throw error
+    }
   })