@open-mercato/core 0.6.8-develop.6987.1.02f619470c → 0.6.8-develop.6993.1.3fc50f3409

package/src/modules/data_sync/AGENTS.md

@@ -104,6 +104,7 @@ interface DataSyncAdapter {
   streamExport?(entityType: string, cursor: string | null, config: SyncConfig): AsyncIterable<ExportBatch>
   getInitialCursor?(entityType: string): Promise<string | null>
   getMapping?(entityType: string): Promise<FieldMapping[]>
+  persistsSharedCursor?(entityType: string): boolean
   validateConnection?(credentials: Record<string, unknown>): Promise<{ valid: boolean; message?: string }>
 }
 ```
@@ -124,7 +125,9 @@ If the sync provider needs bootstrap credentials, mappings, locales, channels, o
 
 `pending` → `running` → `completed` | `failed` | `cancelled`
 
-- **Cursor persistence**: After each batch, cursor is saved to `SyncCursor`
+- **Cursor persistence**: After each batch, the cursor is saved on the run row and mirrored into the shared `SyncCursor` row
+- **Shared cursor opt-out**: An adapter returning `persistsSharedCursor(entityType) === false` keeps that entity type's cursor on the run row only — use it for whole-table backfills whose cursor is one run's scan state, not a durable log position. Those entity types resolve an incremental start position from the most recent run (`resolveResumeCursor`) instead of the shared row, and from `null` when that run completed
+- **Resetting an opt-out**: A reset flow that deletes the shared `SyncCursor` row MUST also call `syncRunService.resetResumePosition(integrationId, entityType, direction, scope)`. An opted-out entity type has no shared row to delete, so deleting only that leaves the resume position on the last interrupted run and the next incremental run re-imports just the tail of the walk it was reset against. The call is a no-op when nothing is interrupted, so make it unconditionally
 - **Resume**: Retry reads the last successful cursor, resumes from there
 - **Progress**: Linked to `ProgressJob` via `progressJobId` for `ProgressTopBar` display
 - **Cancellation**: Via `progressService.isCancellationRequested()`

package/src/modules/data_sync/api/run.ts

@@ -10,6 +10,7 @@ import type { SyncRunService } from '../lib/sync-run-service'
 import { runSyncSchema } from '../data/validators'
 import { startDataSyncRun } from '../lib/start-run'
 import { getDataSyncAdapter } from '../lib/adapter-registry'
+import { resolveStartCursor } from '../lib/start-cursor'
 import {
   runCrudMutationGuardAfterSuccess,
   validateCrudMutationGuard,
@@ -109,7 +110,14 @@ export async function POST(req: Request) {
 
     const cursor = parsed.data.fullSync
       ? null
-      : await syncRunService.resolveCursor(parsed.data.integrationId, parsed.data.entityType, parsed.data.direction, scope)
+      : await resolveStartCursor({
+        syncRunService,
+        adapter,
+        integrationId: parsed.data.integrationId,
+        entityType: parsed.data.entityType,
+        direction: parsed.data.direction,
+        scope,
+      })
 
     const { run, progressJob } = await startDataSyncRun({
       syncRunService,

package/src/modules/data_sync/api/runs/[id]/retry.ts

@@ -8,6 +8,7 @@ import type { ProgressService } from '../../../../progress/lib/progressService'
 import type { SyncRunService } from '../../../lib/sync-run-service'
 import { retrySyncSchema } from '../../../data/validators'
 import { startDataSyncRun } from '../../../lib/start-run'
+import { resolveAdapterForIntegration, resolveStartCursor } from '../../../lib/start-cursor'
 import {
   runCrudMutationGuardAfterSuccess,
   validateCrudMutationGuard,
@@ -89,7 +90,14 @@ export async function POST(req: Request, ctx: { params?: Promise<{ id?: string }
 
   const cursor = parsedBody.data.fromBeginning
     ? null
-    : previous.cursor ?? await syncRunService.resolveCursor(previous.integrationId, previous.entityType, previous.direction, scope)
+    : previous.cursor ?? await resolveStartCursor({
+      syncRunService,
+      adapter: resolveAdapterForIntegration(previous.integrationId),
+      integrationId: previous.integrationId,
+      entityType: previous.entityType,
+      direction: previous.direction,
+      scope,
+    })
 
   const { run, progressJob } = await startDataSyncRun({
     syncRunService,

package/src/modules/data_sync/lib/adapter-registry.ts

@@ -1,3 +1,4 @@
+import { getIntegration } from '@open-mercato/shared/modules/integrations/types'
 import type { DataSyncAdapter } from './adapter'
 
 const DATA_SYNC_ADAPTER_REGISTRY_KEY = Symbol.for('@open-mercato/data-sync/adapter-registry')
@@ -25,3 +26,17 @@ export function getDataSyncAdapter(providerKey: string): DataSyncAdapter | undef
 export function getAllDataSyncAdapters(): DataSyncAdapter[] {
   return Array.from(getAdapterRegistry().values())
 }
+
+export function resolveProviderKey(integrationId: string): string {
+  return getIntegration(integrationId)?.providerKey ?? integrationId
+}
+
+/**
+ * The adapter serving an integration. Single source of truth on purpose: the
+ * engine uses it to decide whether to WRITE the shared cursor row and the start
+ * paths use it to decide whether to READ one, and those two decisions must agree
+ * for every integration or an opted-out entity type silently resumes wrong.
+ */
+export function resolveAdapterForIntegration(integrationId: string): DataSyncAdapter | null {
+  return getDataSyncAdapter(resolveProviderKey(integrationId)) ?? null
+}

package/src/modules/data_sync/lib/adapter.ts

@@ -124,6 +124,24 @@ export interface DataSyncAdapter {
    */
   streamImport?(input: StreamImportInput): AsyncIterable<ImportBatch>
   streamExport?(input: StreamExportInput): AsyncIterable<ExportBatch>
+  /**
+   * Whether the engine mirrors this entity type's cursor into the shared
+   * `sync_cursors` row — one row per (integration, entityType, direction,
+   * scope), overwritten by every run that commits a batch.
+   *
+   * Default `true`. Return `false` for an entity type whose cursor is a single
+   * run's scan state rather than a durable position in a log. The run row keeps
+   * `initialCursor` + `cursor` either way, so a redelivered job still resumes
+   * exactly; what goes away is two concurrent or consecutive runs of the same
+   * entity type silently redefining each other's start position.
+   *
+   * The distinction is a blast radius, not a preference: losing a log position
+   * means re-draining the whole change queue, while losing a table walk's
+   * position means re-walking a table the adapter already re-walks idempotently.
+   * The predicate is per entity type because one adapter commonly serves both
+   * kinds — an incremental feed and a whole-table backfill.
+   */
+  persistsSharedCursor?(entityType: string): boolean
   getInitialCursor?(input: { entityType: string; scope: TenantScope }): Promise<string | null>
   getMapping(input: { entityType: string; scope: TenantScope }): Promise<DataMapping>
   validateConnection?(input: {

package/src/modules/data_sync/lib/start-cursor.ts

@@ -0,0 +1,35 @@
+import type { DataSyncAdapter } from './adapter'
+import type { SyncRunService } from './sync-run-service'
+
+type SyncScope = {
+  organizationId: string
+  tenantId: string
+}
+
+export { resolveAdapterForIntegration } from './adapter-registry'
+
+export function persistsSharedCursor(adapter: DataSyncAdapter | null | undefined, entityType: string): boolean {
+  return adapter?.persistsSharedCursor?.(entityType) ?? true
+}
+
+/**
+ * Start position for a non-full run. Entity types that mirror their cursor into
+ * the shared `sync_cursors` row read it from there. Entity types whose adapter
+ * opted out never write that row, so reading it would silently turn every
+ * incremental run into a full one — they resume from their own last run
+ * instead.
+ */
+export async function resolveStartCursor(params: {
+  syncRunService: SyncRunService
+  adapter?: DataSyncAdapter | null
+  integrationId: string
+  entityType: string
+  direction: 'import' | 'export'
+  scope: SyncScope
+}): Promise<string | null> {
+  const { syncRunService, adapter, integrationId, entityType, direction, scope } = params
+  if (persistsSharedCursor(adapter, entityType)) {
+    return syncRunService.resolveCursor(integrationId, entityType, direction, scope)
+  }
+  return syncRunService.resolveResumeCursor(integrationId, entityType, direction, scope)
+}

package/src/modules/data_sync/lib/sync-engine.ts

@@ -8,7 +8,7 @@ import { STALE_JOB_TIMEOUT_SECONDS } from '../../progress/lib/progressService'
 import { refreshCoverageSnapshot } from '../../query_index/lib/coverage'
 import { emitDataSyncEvent } from '../events'
 import type { DataSyncAdapter, DataMapping, ExportBatch, ImportBatch } from './adapter'
-import { getDataSyncAdapter } from './adapter-registry'
+import { getDataSyncAdapter, resolveProviderKey } from './adapter-registry'
 import type { SyncRunService } from './sync-run-service'
 import { SyncRunOwnershipConflictError } from './sync-run-service'
 import { createLogger } from '@open-mercato/shared/lib/logger'
@@ -30,10 +30,6 @@ type EngineDeps = {
   progressService: ProgressService
 }
 
-function resolveProviderKey(integrationId: string): string {
-  return getIntegration(integrationId)?.providerKey ?? integrationId
-}
-
 function applyImportCounters(batch: ImportBatch): Pick<Required<SyncCounterDelta>, 'createdCount' | 'updatedCount' | 'skippedCount' | 'failedCount'> {
   let createdCount = 0
   let updatedCount = 0
@@ -486,6 +482,7 @@ export function createSyncEngine(deps: EngineDeps) {
         throw new Error(`No import adapter registered for provider ${providerKey}`)
       }
       const operationalTelemetry = adapter.operationalTelemetry === true
+      const persistSharedCursor = adapter.persistsSharedCursor?.(run.entityType) ?? true
 
       const credentials = await integrationCredentialsService.resolve(run.integrationId, scope)
       if (!credentials) {
@@ -575,7 +572,7 @@ export function createSyncEngine(deps: EngineDeps) {
             },
             batch.cursor,
             scope,
-            committedBatches,
+            { expectedBatchesCompleted: committedBatches, persistSharedCursor },
           )
           committedBatches += 1
 
@@ -650,6 +647,7 @@ export function createSyncEngine(deps: EngineDeps) {
         throw new Error(`No export adapter registered for provider ${providerKey}`)
       }
       const operationalTelemetry = adapter.operationalTelemetry === true
+      const persistSharedCursor = adapter.persistsSharedCursor?.(run.entityType) ?? true
 
       const credentials = await integrationCredentialsService.resolve(run.integrationId, scope)
       if (!credentials) {
@@ -739,7 +737,7 @@ export function createSyncEngine(deps: EngineDeps) {
             },
             batch.cursor,
             scope,
-            committedBatches,
+            { expectedBatchesCompleted: committedBatches, persistSharedCursor },
           )
           committedBatches += 1
           await updateProgress(run.progressJobId, processedCount, null, scope)

package/src/modules/data_sync/lib/sync-run-service.ts

@@ -26,6 +26,25 @@ type SyncScope = {
   tenantId: string
 }
 
+export type CursorCommitOptions = {
+  /**
+   * Mirror the committed cursor into the shared `sync_cursors` row. Defaults to
+   * `true`; the engine passes the adapter's `persistsSharedCursor(entityType)`
+   * verdict. `false` keeps the cursor on the run row alone.
+   */
+  persistSharedCursor?: boolean
+  /**
+   * Fences the write against a concurrent delivery: the run must still be
+   * `running` and still sit on this batch count, or the commit throws
+   * {@link SyncRunOwnershipConflictError} and rolls back. Omit to keep the
+   * unguarded write for callers outside the engine.
+   */
+  expectedBatchesCompleted?: number
+}
+
+/** {@link CursorCommitOptions} minus the fence, which `updateCursor` does not apply. */
+export type SharedCursorOption = Pick<CursorCommitOptions, 'persistSharedCursor'>
+
 /**
  * Raised when a batch commit loses the ownership compare-and-swap, meaning
  * another delivery of the same job advanced the run while this worker was
@@ -64,8 +83,15 @@ export function createSyncRunService(em: EntityManager) {
     )
   }
 
-  function applyCursorMutation(run: SyncRun, cursorRow: SyncCursor | null, cursor: string, scope: SyncScope): void {
+  function applyCursorMutation(
+    run: SyncRun,
+    cursorRow: SyncCursor | null,
+    cursor: string,
+    scope: SyncScope,
+    persistSharedCursor: boolean,
+  ): void {
     run.cursor = cursor
+    if (!persistSharedCursor) return
     if (cursorRow) {
       cursorRow.cursor = cursor
     } else {
@@ -230,25 +256,37 @@ export function createSyncRunService(em: EntityManager) {
      * @deprecated Use {@link commitBatchProgress}. This method advances the
      * cursor without the ownership fence, so a stale delivery can move the
      * cursor of a run another worker owns. Kept for external callers only.
+     *
+     * It still takes `persistSharedCursor` despite being deprecated: an external
+     * caller advancing the cursor of an opted-out entity type would otherwise
+     * create the very `sync_cursors` row the opt-out exists to avoid, and a
+     * later incremental run would read it as a start position. The deprecated
+     * path has to honour the opt-out for as long as it exists.
      */
-    async updateCursor(runId: string, cursor: string, scope: SyncScope): Promise<void> {
+    async updateCursor(runId: string, cursor: string, scope: SyncScope, options?: SharedCursorOption): Promise<void> {
       const run = await this.getRun(runId, scope)
       if (!run) return
-      const cursorRow = await resolveCursorRow(run, scope)
+      const persistSharedCursor = options?.persistSharedCursor ?? true
+      const cursorRow = persistSharedCursor ? await resolveCursorRow(run, scope) : null
       await withAtomicFlush(em, [
-        () => applyCursorMutation(run, cursorRow, cursor, scope),
+        () => applyCursorMutation(run, cursorRow, cursor, scope, persistSharedCursor),
       ], { transaction: true })
     },
 
     /**
      * Commits one batch's counters and cursor in a single transaction.
      *
-     * Passing `expectedBatchesCompleted` fences the write: the run must still be
-     * `running` and still sit on that batch count, or another delivery of the
-     * same BullMQ job owns the run and this commit throws
+     * Passing `options.expectedBatchesCompleted` fences the write: the run must
+     * still be `running` and still sit on that batch count, or another delivery
+     * of the same BullMQ job owns the run and this commit throws
      * `SyncRunOwnershipConflictError` and rolls back. Omitting it keeps the
      * legacy unguarded write for callers outside the engine.
      *
+     * `options.persistSharedCursor` is orthogonal to the fence: it decides
+     * whether the committed cursor is mirrored into the shared `sync_cursors`
+     * row, and the two compose freely — a fenced commit for an opted-out entity
+     * type advances the run row alone and still throws on a stale fence.
+     *
      * The fence token is `batchesCompleted` rather than `cursor` because it
      * advances by construction on every commit. A cursor is a free-form adapter
      * string that an adapter may legitimately repeat between batches — the
@@ -268,11 +306,13 @@ export function createSyncRunService(em: EntityManager) {
       delta: Partial<Pick<SyncRun, 'createdCount' | 'updatedCount' | 'skippedCount' | 'failedCount' | 'batchesCompleted'>>,
       cursor: string,
       scope: SyncScope,
-      expectedBatchesCompleted?: number,
+      options?: CursorCommitOptions,
     ): Promise<SyncRun | null> {
       const run = await this.getRun(runId, scope)
       if (!run) return null
-      const cursorRow = await resolveCursorRow(run, scope)
+      const { expectedBatchesCompleted } = options ?? {}
+      const persistSharedCursor = options?.persistSharedCursor ?? true
+      const cursorRow = persistSharedCursor ? await resolveCursorRow(run, scope) : null
       const claimRunOwnership = async () => {
         if ((delta.batchesCompleted ?? 0) < 1) {
           throw new Error(`[internal] A fenced commit for sync run ${runId} must advance batchesCompleted`)
@@ -301,7 +341,7 @@ export function createSyncRunService(em: EntityManager) {
           run.skippedCount += delta.skippedCount ?? 0
           run.failedCount += delta.failedCount ?? 0
           run.batchesCompleted += delta.batchesCompleted ?? 0
-          applyCursorMutation(run, cursorRow, cursor, scope)
+          applyCursorMutation(run, cursorRow, cursor, scope, persistSharedCursor)
         },
       ], { transaction: true })
       return run
@@ -324,6 +364,74 @@ export function createSyncRunService(em: EntityManager) {
       return row?.cursor ?? null
     },
 
+    /**
+     * Resume position for an entity type whose adapter opted out of the shared
+     * `sync_cursors` row: the cursor of the most recent run, unless that run
+     * reached `completed`. A finished walk resumes from `null` so the next run
+     * starts over rather than skipping everything an older interrupted run had
+     * already passed.
+     */
+    async resolveResumeCursor(integrationId: string, entityType: string, direction: 'import' | 'export', scope: SyncScope): Promise<string | null> {
+      const [run] = await findWithDecryption(
+        em,
+        SyncRun,
+        {
+          integrationId,
+          entityType,
+          direction,
+          organizationId: scope.organizationId,
+          tenantId: scope.tenantId,
+          deletedAt: null,
+        },
+        { orderBy: { createdAt: 'DESC' }, limit: 1 },
+        scope,
+      )
+      if (!run || run.status === 'completed') return null
+      return run.cursor ?? null
+    },
+
+    /**
+     * Clears the run-scoped resume position for an entity type, so the next
+     * non-`fullSync` run starts from the beginning. Returns how many runs were
+     * cleared.
+     *
+     * This is the opt-out's equivalent of deleting the shared `sync_cursors`
+     * row. An entity type whose adapter returns `false` from
+     * `persistsSharedCursor` has no such row, so a reset flow that only deletes
+     * `SyncCursor` would leave {@link resolveResumeCursor} returning the cursor
+     * of the interrupted run it just reset against — re-importing the tail of a
+     * walk instead of the whole thing. Reset flows MUST call this alongside
+     * their `SyncCursor` delete; it is a no-op when nothing is interrupted.
+     *
+     * The `status` filter here selects which rows to clear. It is deliberately
+     * NOT the read-side filter {@link resolveResumeCursor} avoids: that method
+     * reads the single most recent run whatever its status, precisely so an
+     * older interrupted run cannot outlive a later completed walk. Clearing
+     * every interrupted run is enough to start fresh either way — if the latest
+     * run was interrupted its cursor is now null, and if it completed the resume
+     * path already returns null.
+     */
+    async resetResumePosition(
+      integrationId: string,
+      entityType: string,
+      direction: 'import' | 'export',
+      scope: SyncScope,
+    ): Promise<number> {
+      return em.nativeUpdate(
+        SyncRun,
+        {
+          integrationId,
+          entityType,
+          direction,
+          status: { $ne: 'completed' },
+          organizationId: scope.organizationId,
+          tenantId: scope.tenantId,
+          deletedAt: null,
+        },
+        { cursor: null, updatedAt: new Date() },
+      )
+    },
+
     async findRunningOverlap(integrationId: string, entityType: string, direction: 'import' | 'export', scope: SyncScope): Promise<SyncRun | null> {
       const [run] = await findWithDecryption(
         em,

package/src/modules/data_sync/workers/sync-scheduled.ts

@@ -6,6 +6,7 @@ import type { ProgressService } from '../../progress/lib/progressService'
 import type { SyncRunService } from '../lib/sync-run-service'
 import { SyncSchedule } from '../data/entities'
 import { startDataSyncRun } from '../lib/start-run'
+import { resolveAdapterForIntegration, resolveStartCursor } from '../lib/start-cursor'
 
 type ScheduledSyncPayload = {
   scheduleId: string
@@ -65,12 +66,14 @@ export default async function handle(job: QueuedJob<ScheduledSyncPayload>, ctx:
 
   const cursor = schedule.fullSync
     ? null
-    : await syncRunService.resolveCursor(
-        schedule.integrationId,
-        schedule.entityType,
-        schedule.direction,
-        job.payload.scope,
-      )
+    : await resolveStartCursor({
+        syncRunService,
+        adapter: resolveAdapterForIntegration(schedule.integrationId),
+        integrationId: schedule.integrationId,
+        entityType: schedule.entityType,
+        direction: schedule.direction,
+        scope: job.payload.scope,
+      })
 
   schedule.lastRunAt = new Date()
   await em.flush()

package/src/modules/sales/api/channels/route.ts

@@ -38,7 +38,7 @@ const listSchema = z
   .passthrough()
 
 const routeMetadata = {
-  GET: { requireAuth: true, requireFeatures: ['sales.channels.manage'] },
+  GET: { requireAuth: true, requireFeatures: ['sales.channels.view'] },
   POST: { requireAuth: true, requireFeatures: ['sales.channels.manage'] },
   PUT: { requireAuth: true, requireFeatures: ['sales.channels.manage'] },
   DELETE: { requireAuth: true, requireFeatures: ['sales.channels.manage'] },

package/src/modules/sales/api/documents/factory.ts

@@ -4,8 +4,10 @@ import { splitCustomFieldPayload, extractAllCustomFieldEntries } from '@open-mer
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { E } from '#generated/entities.ids.generated'
+import type { EntityManager } from '@mikro-orm/postgresql'
 import type { SalesOrder, SalesQuote } from '../../data/entities'
-import { SalesDocumentTagAssignment } from '../../data/entities'
+import { SalesChannel, SalesDocumentTagAssignment } from '../../data/entities'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import {
   ORDER_PAYMENT_LEDGER_FIELDS,
   ORDER_PAYMENT_LEDGER_WARNING_CODE,
@@ -298,6 +300,62 @@ const attachTags = async (payload: any, ctx: any) => {
   })
 }
 
+// Liveness note: this hook runs BEFORE the CRUD list cache stores the payload, so `channelName`
+// and `channelCode` are embedded in the cached entry. What keeps them fresh is that the hook also
+// runs on the cache-HIT path (shared/lib/crud/factory.ts:1683) and reassigns both fields
+// unconditionally for every item carrying a channel id. Anything that later skips this hook on a
+// hit — the way `skipEnrichersOnCacheHit` does for record-pure enrichers — would start serving the
+// stale names baked into the entry.
+export const attachChannelNames = async (
+  payload: { items?: Array<Record<string, unknown>> },
+  ctx: CrudCtx,
+) => {
+  const items = Array.isArray(payload?.items) ? payload.items : []
+  if (!items.length) return
+  const channelIds = Array.from(
+    new Set(
+      items
+        .map((item) => (item && typeof item.channelId === 'string' ? item.channelId : null))
+        .filter((value): value is string => !!value)
+    )
+  )
+  if (!channelIds.length) return
+  const em = ctx?.container?.resolve ? (ctx.container.resolve('em') as EntityManager) : null
+  if (!em) return
+
+  const where: Record<string, unknown> = { id: { $in: channelIds } }
+  if (ctx?.auth?.tenantId) where.tenantId = ctx.auth.tenantId
+  const orgIds =
+    Array.isArray(ctx?.organizationIds) && ctx.organizationIds.length
+      ? ctx.organizationIds.filter((val: string | null) => !!val)
+      : ctx?.selectedOrganizationId
+        ? [ctx.selectedOrganizationId]
+        : []
+  if (orgIds.length) where.organizationId = { $in: orgIds }
+
+  // Only `name` and `code` are read. Without this projection the query loads the whole channel row,
+  // and `sales/encryption.ts` declares eight of its columns encrypted (contact email/phone, the
+  // address block) — so every documents-list request would decrypt PII it never renders, on the
+  // cache-hit path too.
+  const channels = await findWithDecryption(
+    em,
+    SalesChannel,
+    where,
+    { fields: ['id', 'name', 'code'] },
+    {
+      tenantId: ctx?.auth?.tenantId ?? null,
+      organizationId: ctx?.selectedOrganizationId ?? ctx?.auth?.orgId ?? null,
+    }
+  )
+  const byId = new Map(channels.map((channel) => [channel.id, channel]))
+  items.forEach((item) => {
+    if (!item || typeof item.channelId !== 'string') return
+    const channel = byId.get(item.channelId)
+    item.channelName = channel?.name ?? null
+    item.channelCode = channel?.code ?? null
+  })
+}
+
 async function ensureNumberEditPermission(
   ctx: CrudCtx,
   translate: (key: string, fallback?: string) => string
@@ -557,6 +615,7 @@ export function buildDocumentCrudOptions(binding: DocumentBinding) {
     hooks: {
       afterList: async (payload: any, ctx: CrudCtx) => {
         await attachTags(payload, { ...ctx, bindingKind: binding.kind })
+        await attachChannelNames(payload, ctx)
         if (binding.kind === 'order' && Array.isArray(payload?.items) && payload.items.length === 1) {
           const item = payload.items[0] as Record<string, unknown>
           const orderId = typeof item?.id === 'string' ? item.id : null
@@ -629,6 +688,8 @@ export function buildDocumentOpenApi(binding: DocumentBinding) {
     paymentMethodSnapshot: z.record(z.string(), z.unknown()).nullable().optional(),
     currencyCode: z.string().nullable(),
     channelId: z.string().uuid().nullable(),
+    channelName: z.string().nullable().optional(),
+    channelCode: z.string().nullable().optional(),
     organizationId: z.string().uuid().nullable(),
     tenantId: z.string().uuid().nullable(),
     validFrom: z.string().nullable().optional(),