@open-mercato/core 0.6.6-develop.6229.1.ebe6706732 → 0.6.6-develop.6245.1.2be3b151f8

package/src/modules/integrations/backend/integrations/bundle/[id]/page.tsx

@@ -38,6 +38,7 @@ type BundleIntegration = {
   description?: string
   category?: string
   isEnabled: boolean
+  state?: { updatedAt?: string | null }
 }
 
 type BundleDetail = {
@@ -56,6 +57,7 @@ type BundleDetail = {
   bundleIntegrations: BundleIntegration[]
   state: { isEnabled: boolean }
   hasCredentials: boolean
+  credentialsUpdatedAt?: string | null
 }
 
 type BundleConfigPageProps = {
@@ -86,6 +88,7 @@ export default function BundleConfigPage({ params }: BundleConfigPageProps) {
   const [error, setError] = React.useState<string | null>(null)
   const [isNotFound, setIsNotFound] = React.useState(false)
   const [credValues, setCredValues] = React.useState<Record<string, unknown>>({})
+  const [credentialsUpdatedAt, setCredentialsUpdatedAt] = React.useState<string | null>(null)
   const [isSavingCreds, setIsSavingCreds] = React.useState(false)
   const [togglingIds, setTogglingIds] = React.useState<Set<string>>(new Set())
 
@@ -131,11 +134,14 @@ export default function BundleConfigPage({ params }: BundleConfigPageProps) {
     }
     setDetail(call.result)
 
-    const credCall = await apiCall<{ credentials: Record<string, unknown> }>(
+    const credCall = await apiCall<{ credentials: Record<string, unknown>; updatedAt?: string | null }>(
       `/api/integrations/${encodeURIComponent(currentBundleId)}/credentials`,
       undefined,
       { fallback: null },
     )
+    if (credCall.ok && credCall.result) {
+      setCredentialsUpdatedAt(credCall.result.updatedAt ?? null)
+    }
     if (credCall.ok && credCall.result?.credentials) {
       const next = { ...credCall.result.credentials }
       if (currentBundleId === 'storage_s3') {
@@ -168,9 +174,8 @@ export default function BundleConfigPage({ params }: BundleConfigPageProps) {
           bundleId: currentBundleId,
           retryLastMutation,
         },
-        // TODO(#2373-B): thread updatedAt — integration detail/state response does not expose a record version yet
         operation: () => withScopedApiRequestHeaders(
-          buildOptimisticLockHeader(undefined),
+          buildOptimisticLockHeader(credentialsUpdatedAt),
           () => apiCall(`/api/integrations/${encodeURIComponent(currentBundleId)}/credentials`, {
             method: 'PUT',
             headers: { 'Content-Type': 'application/json' },
@@ -180,6 +185,7 @@ export default function BundleConfigPage({ params }: BundleConfigPageProps) {
       })
       if (call.ok) {
         flash(t('integrations.detail.credentials.saved'), 'success')
+        await load()
       } else {
         flash(t('integrations.detail.credentials.saveError'), 'error')
       }
@@ -188,9 +194,9 @@ export default function BundleConfigPage({ params }: BundleConfigPageProps) {
     } finally {
       setIsSavingCreds(false)
     }
-  }, [resolveCurrentBundleId, runMutation, mutationContextId, retryLastMutation, credValues, t])
+  }, [resolveCurrentBundleId, runMutation, mutationContextId, retryLastMutation, credValues, credentialsUpdatedAt, load, t])
 
-  const handleToggle = React.useCallback(async (integrationId: string, enabled: boolean) => {
+  const handleToggle = React.useCallback(async (integrationId: string, enabled: boolean, updatedAt?: string | null) => {
     setTogglingIds((prev) => new Set(prev).add(integrationId))
     try {
       const call = await runMutation({
@@ -204,10 +210,9 @@ export default function BundleConfigPage({ params }: BundleConfigPageProps) {
           integrationId,
           retryLastMutation,
         },
-        // TODO(#2373-B): thread updatedAt — integration detail/state response does not expose a record version yet
         operation: () => withScopedApiRequestHeaders(
-          buildOptimisticLockHeader(undefined),
-          () => apiCall(`/api/integrations/${encodeURIComponent(integrationId)}/state`, {
+          buildOptimisticLockHeader(updatedAt),
+          () => apiCall<{ updatedAt?: string | null }>(`/api/integrations/${encodeURIComponent(integrationId)}/state`, {
             method: 'PUT',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({ isEnabled: enabled }),
@@ -215,12 +220,15 @@ export default function BundleConfigPage({ params }: BundleConfigPageProps) {
         ),
       })
       if (call.ok) {
+        const nextUpdatedAt = call.result?.updatedAt ?? null
         setDetail((prev) => {
           if (!prev) return prev
           return {
             ...prev,
             bundleIntegrations: prev.bundleIntegrations.map((item) =>
-              item.id === integrationId ? { ...item, isEnabled: enabled } : item,
+              item.id === integrationId
+                ? { ...item, isEnabled: enabled, state: { updatedAt: nextUpdatedAt ?? item.state?.updatedAt ?? null } }
+                : item,
             ),
           }
         })
@@ -237,7 +245,7 @@ export default function BundleConfigPage({ params }: BundleConfigPageProps) {
   const handleBulkToggle = React.useCallback(async (enabled: boolean) => {
     if (!detail) return
     const targets = detail.bundleIntegrations.filter((item) => item.isEnabled !== enabled)
-    await Promise.all(targets.map((item) => handleToggle(item.id, enabled)))
+    await Promise.all(targets.map((item) => handleToggle(item.id, enabled, item.state?.updatedAt)))
   }, [detail, handleToggle])
 
   if (isLoading) return <Page><PageBody><LoadingMessage label={t('integrations.bundle.title')} /></PageBody></Page>
@@ -368,7 +376,7 @@ export default function BundleConfigPage({ params }: BundleConfigPageProps) {
                     <Switch
                       checked={item.isEnabled}
                       disabled={togglingIds.has(item.id)}
-                      onCheckedChange={(checked) => void handleToggle(item.id, checked)}
+                      onCheckedChange={(checked) => void handleToggle(item.id, checked, item.state?.updatedAt)}
                     />
                   </div>
                 </div>

package/src/modules/integrations/backend/integrations/page.tsx

@@ -45,7 +45,7 @@ type IntegrationItem = {
   hasCredentials: boolean
   healthStatus: 'healthy' | 'degraded' | 'unhealthy' | 'unconfigured'
   analytics: IntegrationAnalytics
-  updatedAt?: string | null
+  stateUpdatedAt?: string | null
 }
 
 type BundleItem = {
@@ -220,7 +220,7 @@ export default function IntegrationsMarketplacePage() {
         },
         operation: () => withScopedApiRequestHeaders(
           buildOptimisticLockHeader(updatedAt),
-          () => apiCall(`/api/integrations/${encodeURIComponent(integrationId)}/state`, {
+          () => apiCall<{ updatedAt?: string | null }>(`/api/integrations/${encodeURIComponent(integrationId)}/state`, {
             method: 'PUT',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({ isEnabled: enabled }),
@@ -231,12 +231,15 @@ export default function IntegrationsMarketplacePage() {
       if (!call.ok) {
         flash(t('integrations.detail.stateError'), 'error')
       } else {
+        const nextUpdatedAt = call.result?.updatedAt ?? null
         setData((prev) => {
           if (!prev) return prev
           return {
             ...prev,
             items: prev.items.map((item) =>
-              item.id === integrationId ? { ...item, isEnabled: enabled } : item,
+              item.id === integrationId
+                ? { ...item, isEnabled: enabled, stateUpdatedAt: nextUpdatedAt ?? item.stateUpdatedAt }
+                : item,
             ),
           }
         })
@@ -465,7 +468,7 @@ export default function IntegrationsMarketplacePage() {
                         <Switch
                           checked={item.isEnabled}
                           disabled={togglingIds.has(item.id)}
-                          onCheckedChange={(checked) => void handleToggle(item.id, checked, item.updatedAt)}
+                          onCheckedChange={(checked) => void handleToggle(item.id, checked, item.stateUpdatedAt)}
                           className="shrink-0"
                         />
                       </div>
@@ -503,7 +506,7 @@ export default function IntegrationsMarketplacePage() {
                       <Switch
                         checked={item.isEnabled}
                         disabled={togglingIds.has(item.id)}
-                        onCheckedChange={(checked) => void handleToggle(item.id, checked)}
+                        onCheckedChange={(checked) => void handleToggle(item.id, checked, item.stateUpdatedAt)}
                         className="shrink-0"
                       />
                     </div>

package/src/modules/integrations/data/entities.ts

@@ -85,7 +85,7 @@ export class IntegrationCredentials {
   @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
   createdAt: Date = new Date()
 
-  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  @Property({ name: 'updated_at', type: Date, onCreate: () => new Date(), onUpdate: () => new Date() })
   updatedAt: Date = new Date()
 
   @Property({ name: 'deleted_at', type: Date, nullable: true })
@@ -132,7 +132,7 @@ export class IntegrationState {
   @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
   createdAt: Date = new Date()
 
-  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  @Property({ name: 'updated_at', type: Date, onCreate: () => new Date(), onUpdate: () => new Date() })
   updatedAt: Date = new Date()
 
   @Property({ name: 'deleted_at', type: Date, nullable: true })

package/src/modules/integrations/lib/credentials-service.ts

@@ -184,6 +184,41 @@ export function createCredentialsService(em: EntityManager) {
       return decryptCredentialsBlob(row.credentials, scope)
     },
 
+    async getRowUpdatedAt(integrationId: string, scope: IntegrationScope): Promise<Date | null> {
+      let row = await findOneWithDecryption(
+        em,
+        IntegrationCredentials,
+        buildCredentialsFilter(integrationId, scope),
+        undefined,
+        scope,
+      )
+      if (!row && scope.userId) {
+        row = await findOneWithDecryption(
+          em,
+          IntegrationCredentials,
+          buildCredentialsFilter(integrationId, { ...scope, userId: null }),
+          undefined,
+          scope,
+        )
+      }
+      return row?.updatedAt ?? null
+    },
+
+    /**
+     * Resolve the persisted `updated_at` version for the credentials a caller
+     * would read via {@link resolve} (direct row first, then the bundle
+     * fallthrough). Returns `null` when no credentials row exists yet — the
+     * optimistic-lock guard treats a missing current version as "no conflict".
+     */
+    async resolveUpdatedAt(integrationId: string, scope: IntegrationScope): Promise<Date | null> {
+      const direct = await this.getRowUpdatedAt(integrationId, scope)
+      if (direct) return direct
+
+      const definition = getIntegration(integrationId)
+      if (!definition?.bundleId) return null
+      return this.getRowUpdatedAt(definition.bundleId, scope)
+    },
+
     async resolve(integrationId: string, scope: IntegrationScope): Promise<Record<string, unknown> | null> {
       const direct = await this.getRaw(integrationId, scope)
       if (direct) return direct

package/src/modules/integrations/lib/state-service.ts

@@ -11,6 +11,7 @@ export type ResolvedIntegrationState = {
   lastHealthCheckedAt: Date | null
   lastHealthLatencyMs: number | null
   enabledAt: Date | null
+  updatedAt: Date | null
 }
 
 export function createIntegrationStateService(em: EntityManager) {
@@ -25,6 +26,7 @@ export function createIntegrationStateService(em: EntityManager) {
       lastHealthCheckedAt: null,
       lastHealthLatencyMs: null,
       enabledAt: null,
+      updatedAt: null,
     }
   }
 
@@ -56,6 +58,7 @@ export function createIntegrationStateService(em: EntityManager) {
         lastHealthCheckedAt: state?.lastHealthCheckedAt ?? null,
         lastHealthLatencyMs: state?.lastHealthLatencyMs ?? null,
         enabledAt: state?.enabledAt ?? null,
+        updatedAt: state?.updatedAt ?? null,
       }
     },
 

package/src/modules/notifications/lib/notificationService.ts

@@ -1,6 +1,6 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { type Kysely, sql } from 'kysely'
-import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { CrudHttpError, conflict } from '@open-mercato/shared/lib/crud/errors'
 import { Notification, type NotificationStatus } from '../data/entities'
 import type { CreateNotificationInput, CreateBatchNotificationInput, CreateRoleNotificationInput, CreateFeatureNotificationInput, ExecuteActionInput } from '../data/validators'
 import type { NotificationPollData } from '@open-mercato/shared/modules/notifications/types'
@@ -448,6 +448,57 @@ export function createNotificationService(deps: NotificationServiceDeps): Notifi
         throw new Error('Action not found')
       }
 
+      // Reject an already-actioned notification before dispatching the command,
+      // so a retry or double-click cannot re-run the side effect.
+      if (notification.status === 'actioned') {
+        throw conflict('Notification action already executed')
+      }
+
+      const actionedAt = new Date()
+      const previousStatus = notification.status
+      const previousActionedAt = notification.actionedAt ?? null
+      const previousActionTaken = notification.actionTaken ?? null
+
+      // Atomically claim the notification so only one concurrent request can run
+      // the side-effecting command. The conditional UPDATE matches only while the
+      // notification has not been actioned yet; a losing request updates 0 rows.
+      const claimResult = (await getDb(em)
+        .updateTable('notifications' as any)
+        .set({
+          status: 'actioned',
+          actioned_at: actionedAt,
+          action_taken: input.actionId,
+        } as any)
+        .where('id' as any, '=', notification.id)
+        .where('recipient_user_id' as any, '=', ctx.userId as any)
+        .where('tenant_id' as any, '=', ctx.tenantId)
+        .where('status' as any, '!=', 'actioned')
+        .executeTakeFirst()) as { numUpdatedRows?: bigint | number } | undefined
+
+      if (Number(claimResult?.numUpdatedRows ?? 0) === 0) {
+        throw conflict('Notification action already executed')
+      }
+
+      // The claim is provisional: if the side-effecting command fails, the action
+      // never actually completed, so release the claim to its prior state. This
+      // lets the user retry the action instead of the notification being locked as
+      // `actioned` forever. Only release while we still own the claim
+      // (status = 'actioned'), so a concurrent winner's state is never clobbered.
+      const releaseClaim = async () => {
+        await getDb(em)
+          .updateTable('notifications' as any)
+          .set({
+            status: previousStatus,
+            actioned_at: previousActionedAt,
+            action_taken: previousActionTaken,
+          } as any)
+          .where('id' as any, '=', notification.id)
+          .where('recipient_user_id' as any, '=', ctx.userId as any)
+          .where('tenant_id' as any, '=', ctx.tenantId)
+          .where('status' as any, '=', 'actioned')
+          .executeTakeFirst()
+      }
+
       let result: unknown = null
 
       if (action.commandId && commandBus && container) {
@@ -469,21 +520,33 @@ export function createNotificationService(deps: NotificationServiceDeps): Notifi
           organizationIds: ctx.organizationId ? [ctx.organizationId] : null,
         }
 
-        const commandResult = await commandBus.execute(action.commandId, {
-          input: commandInput,
-          ctx: commandCtx,
-          metadata: {
-            tenantId: ctx.tenantId,
-            organizationId: ctx.organizationId,
-            resourceKind: 'notifications',
-          },
-        })
+        let commandResult: { result: unknown }
+        try {
+          commandResult = await commandBus.execute(action.commandId, {
+            input: commandInput,
+            ctx: commandCtx,
+            metadata: {
+              tenantId: ctx.tenantId,
+              organizationId: ctx.organizationId,
+              resourceKind: 'notifications',
+            },
+          })
+        } catch (err) {
+          // Never let a rollback failure mask the original command error — the
+          // caller needs the real failure to decide whether to retry.
+          try {
+            await releaseClaim()
+          } catch (releaseErr) {
+            debug('failed to release notification action claim', releaseErr)
+          }
+          throw err
+        }
 
         result = commandResult.result
       }
 
       notification.status = 'actioned'
-      notification.actionedAt = new Date()
+      notification.actionedAt = actionedAt
       notification.actionTaken = input.actionId
       notification.actionResult = result as Record<string, unknown>
 

package/src/modules/payment_gateways/api/status/route.ts

@@ -1,13 +1,21 @@
 import { NextResponse } from 'next/server'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
 import { getStatusSchema } from '../../data/validators'
 import type { PaymentGatewayService } from '../../lib/gateway-service'
 import { paymentGatewaysTag } from '../openapi'
 
+const gatewayTransactionResourceKind = 'payment_gateways:gateway_transaction'
+
 export const metadata = {
   path: '/payment_gateways/status',
   GET: { requireAuth: true, requireFeatures: ['payment_gateways.view'] },
+  POST: { requireAuth: true, requireFeatures: ['payment_gateways.manage'] },
 }
 
 export async function GET(req: Request) {
@@ -36,8 +44,81 @@ export async function GET(req: Request) {
       return NextResponse.json({ error: 'Transaction not found' }, { status: 404 })
     }
 
+    return NextResponse.json({
+      transactionId: transaction.id,
+      paymentId: transaction.paymentId,
+      providerKey: transaction.providerKey,
+      sessionId: transaction.providerSessionId,
+      status: transaction.unifiedStatus,
+      gatewayStatus: transaction.gatewayStatus,
+      amount: Number(transaction.amount),
+      amountReceived: null,
+      currencyCode: transaction.currencyCode,
+      redirectUrl: transaction.redirectUrl,
+      createdAt: transaction.createdAt.toISOString(),
+      updatedAt: transaction.updatedAt.toISOString(),
+    })
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : 'Failed to get status'
+    return NextResponse.json({ error: message }, { status: 500 })
+  }
+}
+
+export async function POST(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const payload = await readJsonSafe<unknown>(req)
+  const parsed = getStatusSchema.safeParse(payload)
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid payload', details: parsed.error.flatten() }, { status: 422 })
+  }
+
+  const container = await createRequestContainer()
+  const service = container.resolve('paymentGatewayService') as PaymentGatewayService
+  const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
+  const actorUserId = auth.userId ?? auth.sub
+  const { transactionId } = parsed.data
+
+  try {
+    const transaction = await service.findTransaction(transactionId, scope)
+    if (!transaction) {
+      return NextResponse.json({ error: 'Transaction not found' }, { status: 404 })
+    }
+
+    const guardResult = await validateCrudMutationGuard(container, {
+      tenantId: auth.tenantId,
+      organizationId: scope.organizationId,
+      userId: actorUserId,
+      resourceKind: gatewayTransactionResourceKind,
+      resourceId: transactionId,
+      operation: 'custom',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: parsed.data,
+    })
+    if (guardResult && !guardResult.ok) {
+      return NextResponse.json(guardResult.body, { status: guardResult.status })
+    }
+
     const status = await service.getPaymentStatus(transactionId, scope)
 
+    if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(container, {
+        tenantId: auth.tenantId,
+        organizationId: scope.organizationId,
+        userId: actorUserId,
+        resourceKind: gatewayTransactionResourceKind,
+        resourceId: transactionId,
+        operation: 'custom',
+        requestMethod: req.method,
+        requestHeaders: req.headers,
+        metadata: guardResult.metadata ?? null,
+      })
+    }
+
     return NextResponse.json({
       transactionId: transaction.id,
       paymentId: transaction.paymentId,
@@ -53,23 +134,34 @@ export async function GET(req: Request) {
       updatedAt: transaction.updatedAt.toISOString(),
     })
   } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : 'Failed to get status'
-    return NextResponse.json({ error: message }, { status: 500 })
+    const message = err instanceof Error ? err.message : 'Failed to refresh status'
+    return NextResponse.json({ error: message }, { status: 502 })
   }
 }
 
 export const openApi = {
   tags: [paymentGatewaysTag],
-  summary: 'Get payment transaction status',
+  summary: 'Payment transaction status',
   methods: {
     GET: {
-      summary: 'Get transaction status',
+      summary: 'Get stored transaction status',
       tags: [paymentGatewaysTag],
       responses: [
-        { status: 200, description: 'Transaction status' },
+        { status: 200, description: 'Stored transaction status' },
         { status: 400, description: 'Missing or malformed transactionId' },
         { status: 404, description: 'Transaction not found' },
       ],
     },
+    POST: {
+      summary: 'Refresh transaction status from the provider',
+      tags: [paymentGatewaysTag],
+      responses: [
+        { status: 200, description: 'Refreshed transaction status' },
+        { status: 401, description: 'Unauthorized' },
+        { status: 404, description: 'Transaction not found' },
+        { status: 422, description: 'Missing or malformed payload' },
+        { status: 502, description: 'Gateway provider error' },
+      ],
+    },
   },
 }

package/src/modules/payment_gateways/backend/payment-gateways/page.tsx

@@ -290,19 +290,35 @@ export default function PaymentTransactionsPage() {
   const handleRefreshStatus = React.useCallback(async () => {
     if (!selectedId) return
     setIsRefreshingStatus(true)
-    const call = await apiCall(`/api/payment_gateways/status?transactionId=${encodeURIComponent(selectedId)}`, undefined, { fallback: null })
-    if (!call.ok) {
-      flash(t('payment_gateways.transactions.error.refreshStatus', 'Failed to refresh transaction status'), 'error')
+    try {
+      await runMutation({
+        operation: async () => {
+          await apiCallOrThrow('/api/payment_gateways/status', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ transactionId: selectedId }),
+          })
+        },
+        context: {
+          entityType: 'payment_gateways:gateway_transaction',
+          entityId: selectedId,
+        },
+        mutationPayload: { transactionId: selectedId },
+      })
+      await Promise.all([
+        loadRows(),
+        loadDetail(selectedId),
+      ])
+      flash(t('payment_gateways.transactions.success.refreshStatus', 'Transaction status refreshed'), 'success')
+    } catch (error) {
+      const message = error instanceof Error && error.message
+        ? error.message
+        : t('payment_gateways.transactions.error.refreshStatus', 'Failed to refresh transaction status')
+      flash(message, 'error')
+    } finally {
       setIsRefreshingStatus(false)
-      return
     }
-    await Promise.all([
-      loadRows(),
-      loadDetail(selectedId),
-    ])
-    flash(t('payment_gateways.transactions.success.refreshStatus', 'Transaction status refreshed'), 'success')
-    setIsRefreshingStatus(false)
-  }, [loadDetail, loadRows, selectedId, t])
+  }, [loadDetail, loadRows, runMutation, selectedId, t])
 
   const handleCapturePayment = React.useCallback(async () => {
     if (!selectedId) return

package/src/modules/sales/backend/sales/channels/offers/page.tsx

@@ -14,6 +14,7 @@ import { readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato
 import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { deleteCrud } from '@open-mercato/ui/backend/utils/crud'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { mapOfferRow, renderOfferPriceSummary, type OfferRow } from '@open-mercato/core/modules/sales/components/channels/offerTableUtils'
@@ -26,9 +27,27 @@ type OffersResponse = {
 
 const PAGE_SIZE = 25
 
+const SAVE_CONTEXT_ID = 'sales-channel-offers-list'
+
 export default function SalesChannelOffersListPage() {
   const t = useT()
   const router = useRouter()
+  const { runMutation, retryLastMutation } = useGuardedMutation<{
+    formId: string
+    resourceKind: string
+    retryLastMutation: () => Promise<boolean>
+  }>({
+    contextId: SAVE_CONTEXT_ID,
+    blockedMessage: t('ui.forms.flash.saveBlocked', 'Save blocked by validation'),
+  })
+  const mutationContext = React.useMemo(
+    () => ({
+      formId: SAVE_CONTEXT_ID,
+      resourceKind: 'sales.channels.offers',
+      retryLastMutation,
+    }),
+    [retryLastMutation],
+  )
   const scopeVersion = useOrganizationScopeVersion()
   const channelOptionsRef = React.useRef<Map<string, FilterOption>>(new Map())
   const [rows, setRows] = React.useState<OfferRow[]>([])
@@ -282,19 +301,24 @@ export default function SalesChannelOffersListPage() {
 
   const handleDelete = React.useCallback(async (row: OfferRow) => {
     try {
-      await withScopedApiRequestHeaders(
-        buildOptimisticLockHeader(row.updatedAt),
-        () => deleteCrud('catalog/offers', row.id, {
-          errorMessage: t('sales.channels.offers.errors.delete', 'Failed to delete offer.'),
-        }),
-      )
+      await runMutation({
+        operation: () =>
+          withScopedApiRequestHeaders(
+            buildOptimisticLockHeader(row.updatedAt),
+            () => deleteCrud('catalog/offers', row.id, {
+              errorMessage: t('sales.channels.offers.errors.delete', 'Failed to delete offer.'),
+            }),
+          ),
+        context: mutationContext,
+        mutationPayload: { action: 'delete', id: row.id },
+      })
       flash(t('sales.channels.offers.messages.deleted', 'Offer deleted.'), 'success')
       handleRefresh()
     } catch (err) {
       if (surfaceRecordConflict(err, t)) { handleRefresh(); return }
       console.error('sales.channels.offers.delete', err)
     }
-  }, [handleRefresh, t])
+  }, [handleRefresh, mutationContext, runMutation, t])
 
   const tableTitle = (
     <div className="flex flex-col gap-1">