@byline/host-tanstack-start 3.21.0 → 4.1.0

package/src/routes/sign-in-path.test.node.ts

@@ -0,0 +1,79 @@
+import { defineClientConfig } from '@byline/core'
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import {
+  configureSignInRoutePath,
+  createSignInRoutePathResolver,
+  getSignInRoutePath,
+} from './sign-in-path.js'
+
+describe('sign-in route configuration', () => {
+  beforeEach(() => {
+    defineClientConfig({
+      serverURL: 'http://localhost:3000',
+      routes: { signIn: '/staff/login/' },
+      collections: [],
+      admin: [],
+      i18n: {
+        interface: { defaultLocale: 'en', locales: [] },
+        content: { defaultLocale: 'en', locales: [] },
+      },
+    })
+  })
+
+  it('reads and normalizes routes.signIn', () => {
+    expect(getSignInRoutePath()).toBe('/staff/login')
+  })
+
+  it('allows a deprecated signInPath override when it matches canonical config', () => {
+    expect(configureSignInRoutePath('staff/login/')).toBe('/staff/login')
+  })
+
+  it('rejects an invalid or divergent deprecated override when resolved', () => {
+    expect(() => configureSignInRoutePath('/auth/login/')).toThrow(/must match routes\.signIn/)
+    expect(() => configureSignInRoutePath('/auth/../login')).toThrow(/routes\.signIn/)
+  })
+
+  it('validates an override against configured rather than default route trees', () => {
+    defineClientConfig({
+      serverURL: 'http://localhost:3000',
+      routes: { admin: '/cms', api: '/rpc', signIn: '/admin/login' },
+      collections: [],
+      admin: [],
+      i18n: {
+        interface: { defaultLocale: 'en', locales: [] },
+        content: { defaultLocale: 'en', locales: [] },
+      },
+    })
+
+    expect(configureSignInRoutePath('/admin/login/')).toBe('/admin/login')
+    expect(() => configureSignInRoutePath('/cms/login')).toThrow(/routes\.signIn/)
+  })
+
+  it('defers a deprecated override until parent beforeLoad config registration', () => {
+    defineClientConfig({
+      serverURL: 'http://localhost:3000',
+      routes: { signIn: '/old/login' },
+      collections: [],
+      admin: [],
+      i18n: {
+        interface: { defaultLocale: 'en', locales: [] },
+        content: { defaultLocale: 'en', locales: [] },
+      },
+    })
+    const resolveSignInPath = createSignInRoutePathResolver('/staff/login/')
+
+    defineClientConfig({
+      serverURL: 'http://localhost:3000',
+      routes: { signIn: '/staff/login' },
+      collections: [],
+      admin: [],
+      i18n: {
+        interface: { defaultLocale: 'en', locales: [] },
+        content: { defaultLocale: 'en', locales: [] },
+      },
+    })
+
+    expect(resolveSignInPath()).toBe('/staff/login')
+  })
+})

package/src/routes/sign-in-path.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 { getClientConfig, resolveRoutes } from '@byline/core'
+
+/** Read the canonical client-safe sign-in destination. */
+export function getSignInRoutePath(): string {
+  return getClientConfig().routes.signIn
+}
+
+/** @deprecated Configure `routes.signIn`; retained for route-factory input validation. */
+export function configureSignInRoutePath(legacyOverride?: string): string {
+  const routes = getClientConfig().routes
+  const configured = routes.signIn
+  if (legacyOverride === undefined) return configured
+
+  const normalizedOverride = resolveRoutes({ ...routes, signIn: legacyOverride }).signIn
+  if (normalizedOverride !== configured) {
+    throw new Error(
+      `createAdminLayoutRoute signInPath (${normalizedOverride}) must match routes.signIn (${configured})`
+    )
+  }
+  return configured
+}
+
+/** Defer deprecated override validation until the admin route's beforeLoad boundary. */
+export function createSignInRoutePathResolver(legacyOverride?: string): () => string {
+  return legacyOverride === undefined
+    ? getSignInRoutePath
+    : () => configureSignInRoutePath(legacyOverride)
+}

package/src/server-fns/admin-account/change-password.ts

@@ -9,8 +9,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { type AccountResponse, changeAccountPasswordCommand } from '@byline/admin/admin-account'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 export interface ChangeAccountPasswordInput {

package/src/server-fns/admin-account/get.ts

@@ -9,8 +9,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { type AccountResponse, getAccountCommand } from '@byline/admin/admin-account'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 /**

package/src/server-fns/admin-account/update.ts

@@ -9,8 +9,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { type AccountResponse, updateAccountCommand } from '@byline/admin/admin-account'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 export interface UpdateAccountInput {

package/src/server-fns/admin-activity/get.ts

@@ -10,9 +10,9 @@ import { createServerFn } from '@tanstack/react-start'
 
 import { assertAdminActor } from '@byline/admin'
 import { ADMIN_ACTIVITY_ABILITIES } from '@byline/admin/admin-activity'
+import { getAdminRequestContext } from '@byline/client/server'
 import { ERR_AUDIT_UNSUPPORTED, getLogger, getServerConfig } from '@byline/core'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { type ActorLabelMap, resolveActorLabels } from '../collections/actors.js'
 import type { AuditLogEntryDto } from '../collections/audit.js'
 

package/src/server-fns/admin-permissions/get-role-abilities.ts

@@ -12,8 +12,8 @@ import {
   type GetRoleAbilitiesResponse,
   getRoleAbilitiesCommand,
 } from '@byline/admin/admin-permissions'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 export const getRoleAbilities = createServerFn({ method: 'GET' })

package/src/server-fns/admin-permissions/list-registered.ts

@@ -12,8 +12,8 @@ import {
   type ListRegisteredAbilitiesResponse,
   listRegisteredAbilitiesCommand,
 } from '@byline/admin/admin-permissions'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 /**

package/src/server-fns/admin-permissions/set-role-abilities.ts

@@ -12,8 +12,8 @@ import {
   type SetRoleAbilitiesResponse,
   setRoleAbilitiesCommand,
 } from '@byline/admin/admin-permissions'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 export interface SetRoleAbilitiesInput {

package/src/server-fns/admin-permissions/who-has.ts

@@ -9,8 +9,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { type WhoHasAbilityResponse, whoHasAbilityCommand } from '@byline/admin/admin-permissions'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 export const whoHasAbility = createServerFn({ method: 'GET' })

package/src/server-fns/admin-roles/create.ts

@@ -9,8 +9,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { type AdminRoleResponse, createAdminRoleCommand } from '@byline/admin/admin-roles'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 export interface CreateAdminRoleInput {

package/src/server-fns/admin-roles/delete.ts

@@ -9,8 +9,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { deleteAdminRoleCommand } from '@byline/admin/admin-roles'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 // Return shape mirrors `OkResponse` from `@byline/admin/admin-users`.

package/src/server-fns/admin-roles/get.ts

@@ -9,8 +9,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { type AdminRoleResponse, getAdminRoleCommand } from '@byline/admin/admin-roles'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 export const getAdminRole = createServerFn({ method: 'GET' })

package/src/server-fns/admin-roles/list.ts

@@ -9,8 +9,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { type AdminRoleListResponse, listAdminRolesCommand } from '@byline/admin/admin-roles'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 /**

package/src/server-fns/admin-roles/reorder.ts

@@ -9,8 +9,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { reorderAdminRolesCommand } from '@byline/admin/admin-roles'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 export const reorderAdminRoles = createServerFn({ method: 'POST' })

package/src/server-fns/admin-roles/update.ts

@@ -9,8 +9,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { type AdminRoleResponse, updateAdminRoleCommand } from '@byline/admin/admin-roles'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 export interface UpdateAdminRoleInput {

package/src/server-fns/admin-users/create.ts

@@ -9,8 +9,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { type AdminUserResponse, createAdminUserCommand } from '@byline/admin/admin-users'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 export interface CreateAdminUserInput {

package/src/server-fns/admin-users/delete.ts

@@ -9,8 +9,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { deleteAdminUserCommand, type OkResponse } from '@byline/admin/admin-users'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 export const deleteAdminUser = createServerFn({ method: 'POST' })

package/src/server-fns/admin-users/disable.ts

@@ -9,8 +9,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { disableAdminUserCommand, type OkResponse } from '@byline/admin/admin-users'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 // No UI affordance yet — paired with `enable.ts`, both ship ahead of the

package/src/server-fns/admin-users/enable.ts

@@ -9,8 +9,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { enableAdminUserCommand, type OkResponse } from '@byline/admin/admin-users'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 // No UI affordance yet — paired with `disable.ts`, both ship ahead of the

package/src/server-fns/admin-users/get-user-roles.ts

@@ -9,8 +9,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { getRolesForUserCommand, type UserRolesResponse } from '@byline/admin/admin-roles'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 export const getUserRoles = createServerFn({ method: 'GET' })

package/src/server-fns/admin-users/get.ts

@@ -9,8 +9,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { type AdminUserResponse, getAdminUserCommand } from '@byline/admin/admin-users'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 export const getAdminUser = createServerFn({ method: 'GET' })

package/src/server-fns/admin-users/list.ts

@@ -13,8 +13,8 @@ import {
   type AdminUserListResponse,
   listAdminUsersCommand,
 } from '@byline/admin/admin-users'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 export interface ListAdminUsersInput {

package/src/server-fns/admin-users/set-password.ts

@@ -9,8 +9,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { type AdminUserResponse, setAdminUserPasswordCommand } from '@byline/admin/admin-users'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 export interface SetAdminUserPasswordInput {

package/src/server-fns/admin-users/set-user-roles.ts

@@ -9,8 +9,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { setRolesForUserCommand, type UserRolesResponse } from '@byline/admin/admin-roles'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 export interface SetUserRolesInput {

package/src/server-fns/admin-users/update.ts

@@ -9,8 +9,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { type AdminUserResponse, updateAdminUserCommand } from '@byline/admin/admin-users'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 export interface UpdateAdminUserInput {

package/src/server-fns/ai/execute.ts

@@ -24,8 +24,7 @@ import type { ExecuteInstructionOptions, ExecuteInstructionParams } from '@bylin
 // Server-only execute API — kept on the `/server` subpath so the browser
 // barrel for `@byline/ai` stays free of pino + the provider SDKs.
 import { executeInstruction, executeInstructionStreaming } from '@byline/ai/server'
-
-import { getAdminRequestContext } from '../../auth/auth-context.js'
+import { getAdminRequestContext } from '@byline/client/server'
 
 /**
  * Wire shape — the same as `ExecuteInstruction` minus the in-process-only

package/src/server-fns/auth/current-user.ts

@@ -21,8 +21,8 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { type Actor, AuthError } from '@byline/auth'
+import { getAdminRequestContext } from '@byline/client/server'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 
 export interface CurrentAdminUser {

package/src/server-fns/auth/sign-in.ts

@@ -20,9 +20,9 @@
 import { createServerFn } from '@tanstack/react-start'
 import { getRequestHeader } from '@tanstack/react-start/server'
 
+import { setSessionCookies } from '@byline/client/server'
 import { getServerConfig } from '@byline/core'
 
-import { setSessionCookies } from '../../auth/auth-cookies.js'
 import { readAdminLocaleCookie } from '../../i18n/locale-cookie.js'
 import { bylineCore } from '../../integrations/byline-core.js'
 

package/src/server-fns/auth/sign-out.ts

@@ -23,11 +23,13 @@
 
 import { createServerFn } from '@tanstack/react-start'
 
+import {
+  clearPreviewCookie,
+  clearSessionCookies,
+  readRefreshTokenCookie,
+} from '@byline/client/server'
 import { getServerConfig } from '@byline/core'
 
-import { clearSessionCookies, readRefreshTokenCookie } from '../../auth/auth-cookies.js'
-import { clearPreviewCookie } from '../../auth/preview-cookies.js'
-
 export const adminSignOut = createServerFn({ method: 'POST' }).handler(async () => {
   const provider = getServerConfig().sessionProvider
   const refreshToken = readRefreshTokenCookie()

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

@@ -8,10 +8,10 @@
 
 import { createServerFn } from '@tanstack/react-start'
 
+import { getAdminBylineClient } from '@byline/client/server'
 import { ERR_NOT_FOUND, getLogger } from '@byline/core'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
-import { getAdminBylineClient } from '../../integrations/byline-client.js'
 import { type ActorLabelMap, resolveActorLabels } from './actors.js'
 
 // ---------------------------------------------------------------------------

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

@@ -8,11 +8,11 @@
 
 import { createServerFn } from '@tanstack/react-start'
 
+import { getAdminRequestContext } from '@byline/client/server'
 import { ERR_NOT_FOUND, getLogger, getServerConfig } from '@byline/core'
 import type { CopyToLocaleResult, DocumentLifecycleContext } from '@byline/core/services'
 import { copyToLocale } from '@byline/core/services'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { ensureCollection } from '../../integrations/api-utils.js'
 
 // ---------------------------------------------------------------------------

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

@@ -8,11 +8,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 { createDocument } from '@byline/core/services'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { ensureCollection } from '../../integrations/api-utils.js'
 
 // ---------------------------------------------------------------------------

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

@@ -8,11 +8,11 @@
 
 import { createServerFn } from '@tanstack/react-start'
 
+import { getAdminRequestContext } from '@byline/client/server'
 import { ERR_NOT_FOUND, getLogger, getServerConfig } from '@byline/core'
 import type { DeleteLocaleResult, DocumentLifecycleContext } from '@byline/core/services'
 import { deleteLocale } from '@byline/core/services'
 
-import { getAdminRequestContext } from '../../auth/auth-context.js'
 import { ensureCollection } from '../../integrations/api-utils.js'
 
 // ---------------------------------------------------------------------------

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

@@ -0,0 +1,72 @@
+/**
+ * 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 { DeleteDocumentResult, DeleteDocumentSideEffectPhase } from '@byline/core'
+import { describe, expect, it } from 'vitest'
+
+import { hasDeleteSideEffectFailures, toDeleteDocumentResponse } from './delete-outcome.js'
+
+describe('delete outcome transport and admin interpretation', () => {
+  it('returns only allowlisted phase/code data for a committed warning', () => {
+    // Simulate malformed runtime data from an older or compromised source. The
+    // core type rejects this shape, but the transport still sanitizes it.
+    const unsafeResult = {
+      deletedVersionCount: 2,
+      outcome: 'committed-with-side-effect-failures',
+      sideEffectFailures: [
+        { phase: 'afterDelete', message: 'secret hook details', code: 'ERR_SEARCH' },
+        { phase: 'storageCleanup', message: 'private/path.pdf', code: 'ERR_STORAGE' },
+        {
+          phase: 'internalOnly' as DeleteDocumentSideEffectPhase,
+          message: 'internal phase details',
+          code: 'ERR_INTERNAL',
+        },
+      ],
+    } as unknown as DeleteDocumentResult
+    const response = toDeleteDocumentResponse(unsafeResult)
+
+    expect(response).toEqual({
+      status: 'ok',
+      deletedVersionCount: 2,
+      outcome: 'committed-with-side-effect-failures',
+      sideEffectFailures: [
+        { phase: 'afterDelete', code: 'ERR_UNHANDLED' },
+        { phase: 'storageCleanup', code: 'ERR_STORAGE' },
+        { phase: 'unknown', code: 'ERR_UNHANDLED' },
+      ],
+    })
+    expect(JSON.parse(JSON.stringify(response))).toEqual(response)
+    expect(JSON.stringify(response)).not.toContain('secret hook details')
+    expect(JSON.stringify(response)).not.toContain('private/path.pdf')
+    expect(JSON.stringify(response)).not.toContain('internal phase details')
+    expect(hasDeleteSideEffectFailures(response)).toBe(true)
+  })
+
+  it('preserves the committed success discriminant and empty failures', () => {
+    const response = toDeleteDocumentResponse({
+      deletedVersionCount: 2,
+      outcome: 'committed',
+      sideEffectFailures: [],
+    })
+
+    expect(response).toEqual({
+      status: 'ok',
+      deletedVersionCount: 2,
+      outcome: 'committed',
+      sideEffectFailures: [],
+    })
+    expect(hasDeleteSideEffectFailures(response)).toBe(false)
+  })
+
+  it('classifies only committed side-effect failures as an admin warning', () => {
+    expect(hasDeleteSideEffectFailures({ outcome: 'committed' })).toBe(false)
+    expect(hasDeleteSideEffectFailures({ outcome: 'committed-with-side-effect-failures' })).toBe(
+      true
+    )
+  })
+})

package/src/server-fns/collections/delete-outcome.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 type {
+  DeleteDocumentResult,
+  DeleteDocumentSideEffectCode,
+  DeleteDocumentSideEffectPhase,
+} from '@byline/core'
+import { ErrorCodes } from '@byline/core'
+
+export type DeleteDocumentPublicSideEffectPhase = DeleteDocumentSideEffectPhase | 'unknown'
+export type DeleteDocumentPublicSideEffectCode = DeleteDocumentSideEffectCode
+
+export interface DeleteDocumentPublicSideEffectFailure {
+  phase: DeleteDocumentPublicSideEffectPhase
+  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[],
+      ]
+    }
+
+function sanitizePhase(phase: DeleteDocumentSideEffectPhase): DeleteDocumentPublicSideEffectPhase {
+  if (phase === 'storageCleanup' || phase === 'afterTreeChange' || phase === 'afterDelete') {
+    return phase
+  }
+  return 'unknown'
+}
+
+function sanitizeCode(code: string): DeleteDocumentPublicSideEffectCode {
+  return code === ErrorCodes.STORAGE ? ErrorCodes.STORAGE : ErrorCodes.UNHANDLED
+}
+
+function sanitizeFailure({
+  phase,
+  code,
+}: {
+  phase: DeleteDocumentSideEffectPhase
+  code: string
+}): DeleteDocumentPublicSideEffectFailure {
+  return { phase: sanitizePhase(phase), code: sanitizeCode(code) }
+}
+
+export function toDeleteDocumentResponse(result: DeleteDocumentResult): DeleteDocumentResponse {
+  if (result.outcome === 'committed') {
+    return { status: 'ok', ...result }
+  }
+
+  const [firstFailure, ...remainingFailures] = result.sideEffectFailures
+  return {
+    status: 'ok',
+    deletedVersionCount: result.deletedVersionCount,
+    outcome: result.outcome,
+    sideEffectFailures: [sanitizeFailure(firstFailure), ...remainingFailures.map(sanitizeFailure)],
+  }
+}
+
+export function hasDeleteSideEffectFailures(
+  result: Pick<DeleteDocumentResult, 'outcome'>
+): boolean {
+  return result.outcome === 'committed-with-side-effect-failures'
+}