@open-mercato/core 0.6.6-develop.6198.1.0822f97cc6 → 0.6.6-develop.6204.1.30b1f58642

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

@@ -18,6 +18,7 @@ import {
 import { Spinner } from '@open-mercato/ui/primitives/spinner'
 import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
 import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import type { CredentialFieldType, IntegrationCredentialField } from '@open-mercato/shared/modules/integrations/types'
@@ -88,6 +89,14 @@ export default function BundleConfigPage({ params }: BundleConfigPageProps) {
   const [isSavingCreds, setIsSavingCreds] = React.useState(false)
   const [togglingIds, setTogglingIds] = React.useState<Set<string>>(new Set())
 
+  const mutationContextId = React.useMemo(
+    () => `integrations.bundle:${bundleId ?? 'unknown'}`,
+    [bundleId],
+  )
+  const { runMutation, retryLastMutation } = useGuardedMutation<Record<string, unknown>>({
+    contextId: mutationContextId,
+  })
+
   const resolveCurrentBundleId = React.useCallback(() => {
     return bundleId ?? (
       typeof window !== 'undefined'
@@ -147,49 +156,83 @@ export default function BundleConfigPage({ params }: BundleConfigPageProps) {
     const currentBundleId = resolveCurrentBundleId()
     if (!currentBundleId) return
     setIsSavingCreds(true)
-    // TODO(#2373-B): thread updatedAt — integration detail/state response does not expose a record version yet
-    const call = await withScopedApiRequestHeaders(
-      buildOptimisticLockHeader(undefined),
-      () => apiCall(`/api/integrations/${encodeURIComponent(currentBundleId)}/credentials`, {
-        method: 'PUT',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ credentials: credValues }),
-      }, { fallback: null }),
-    )
-    if (call.ok) {
-      flash(t('integrations.detail.credentials.saved'), 'success')
-    } else {
+    try {
+      const call = await runMutation({
+        mutationPayload: { bundleId: currentBundleId, credentials: credValues },
+        context: {
+          formId: mutationContextId,
+          operation: 'update',
+          actionId: 'save-credentials',
+          resourceKind: 'integrations.bundle',
+          resourceId: currentBundleId,
+          bundleId: currentBundleId,
+          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(currentBundleId)}/credentials`, {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ credentials: credValues }),
+          }, { fallback: null }),
+        ),
+      })
+      if (call.ok) {
+        flash(t('integrations.detail.credentials.saved'), 'success')
+      } else {
+        flash(t('integrations.detail.credentials.saveError'), 'error')
+      }
+    } catch {
       flash(t('integrations.detail.credentials.saveError'), 'error')
+    } finally {
+      setIsSavingCreds(false)
     }
-    setIsSavingCreds(false)
-  }, [resolveCurrentBundleId, credValues, t])
+  }, [resolveCurrentBundleId, runMutation, mutationContextId, retryLastMutation, credValues, t])
 
   const handleToggle = React.useCallback(async (integrationId: string, enabled: boolean) => {
     setTogglingIds((prev) => new Set(prev).add(integrationId))
-    // TODO(#2373-B): thread updatedAt — integration detail/state response does not expose a record version yet
-    const call = await withScopedApiRequestHeaders(
-      buildOptimisticLockHeader(undefined),
-      () => apiCall(`/api/integrations/${encodeURIComponent(integrationId)}/state`, {
-        method: 'PUT',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ isEnabled: enabled }),
-      }, { fallback: null }),
-    )
-    if (call.ok) {
-      setDetail((prev) => {
-        if (!prev) return prev
-        return {
-          ...prev,
-          bundleIntegrations: prev.bundleIntegrations.map((item) =>
-            item.id === integrationId ? { ...item, isEnabled: enabled } : item,
-          ),
-        }
+    try {
+      const call = await runMutation({
+        mutationPayload: { integrationId, isEnabled: enabled },
+        context: {
+          formId: mutationContextId,
+          operation: 'update',
+          actionId: 'toggle-state',
+          resourceKind: 'integrations.integration',
+          resourceId: integrationId,
+          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`, {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ isEnabled: enabled }),
+          }, { fallback: null }),
+        ),
       })
-    } else {
+      if (call.ok) {
+        setDetail((prev) => {
+          if (!prev) return prev
+          return {
+            ...prev,
+            bundleIntegrations: prev.bundleIntegrations.map((item) =>
+              item.id === integrationId ? { ...item, isEnabled: enabled } : item,
+            ),
+          }
+        })
+      } else {
+        flash(t('integrations.detail.stateError'), 'error')
+      }
+    } catch {
       flash(t('integrations.detail.stateError'), 'error')
+    } finally {
+      setTogglingIds((prev) => { const next = new Set(prev); next.delete(integrationId); return next })
     }
-    setTogglingIds((prev) => { const next = new Set(prev); next.delete(integrationId); return next })
-  }, [t])
+  }, [runMutation, mutationContextId, retryLastMutation, t])
 
   const handleBulkToggle = React.useCallback(async (enabled: boolean) => {
     if (!detail) return

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

@@ -9,6 +9,7 @@ import { Input } from '@open-mercato/ui/primitives/input'
 import { Spinner } from '@open-mercato/ui/primitives/spinner'
 import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
 import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -145,6 +146,9 @@ export default function IntegrationsMarketplacePage() {
   const [togglingIds, setTogglingIds] = React.useState<Set<string>>(new Set())
   const scopeVersion = useOrganizationScopeVersion()
   const t = useT()
+  const { runMutation, retryLastMutation } = useGuardedMutation<Record<string, unknown>>({
+    contextId: 'integrations.marketplace',
+  })
 
   React.useEffect(() => {
     const timer = setTimeout(() => setDebouncedSearch(searchInput.trim()), 300)
@@ -202,30 +206,47 @@ export default function IntegrationsMarketplacePage() {
 
   const handleToggle = React.useCallback(async (integrationId: string, enabled: boolean, updatedAt?: string | null) => {
     setTogglingIds((prev) => new Set(prev).add(integrationId))
-    const call = await withScopedApiRequestHeaders(
-      buildOptimisticLockHeader(updatedAt),
-      () => apiCall(`/api/integrations/${encodeURIComponent(integrationId)}/state`, {
-        method: 'PUT',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ isEnabled: enabled }),
-      }, { fallback: null }),
-    )
+    try {
+      const call = await runMutation({
+        mutationPayload: { integrationId, isEnabled: enabled },
+        context: {
+          formId: 'integrations.marketplace',
+          operation: 'update',
+          actionId: 'toggle-state',
+          resourceKind: 'integrations.integration',
+          resourceId: integrationId,
+          integrationId,
+          retryLastMutation,
+        },
+        operation: () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(updatedAt),
+          () => apiCall(`/api/integrations/${encodeURIComponent(integrationId)}/state`, {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ isEnabled: enabled }),
+          }, { fallback: null }),
+        ),
+      })
 
-    if (!call.ok) {
+      if (!call.ok) {
+        flash(t('integrations.detail.stateError'), 'error')
+      } else {
+        setData((prev) => {
+          if (!prev) return prev
+          return {
+            ...prev,
+            items: prev.items.map((item) =>
+              item.id === integrationId ? { ...item, isEnabled: enabled } : item,
+            ),
+          }
+        })
+      }
+    } catch {
       flash(t('integrations.detail.stateError'), 'error')
-    } else {
-      setData((prev) => {
-        if (!prev) return prev
-        return {
-          ...prev,
-          items: prev.items.map((item) =>
-            item.id === integrationId ? { ...item, isEnabled: enabled } : item,
-          ),
-        }
-      })
+    } finally {
+      setTogglingIds((prev) => { const next = new Set(prev); next.delete(integrationId); return next })
     }
-    setTogglingIds((prev) => { const next = new Set(prev); next.delete(integrationId); return next })
-  }, [t])
+  }, [retryLastMutation, runMutation, t])
 
   const grouped = React.useMemo(() => {
     if (!data) return { bundles: [] as Array<BundleItem & { integrations: IntegrationItem[] }>, standalone: [] as IntegrationItem[] }

package/src/modules/notifications/api/[id]/action/route.ts

@@ -1,9 +1,11 @@
 import { executeActionSchema } from '../../../data/validators'
 import { actionResultResponseSchema, errorResponseSchema } from '../../openapi'
 import {
+  NOTIFICATION_RESOURCE_KIND,
   notificationCrudErrorResponse,
   notificationValidationErrorResponse,
   resolveNotificationContext,
+  runGuardedNotificationWrite,
 } from '../../../lib/routeHelpers'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 
@@ -13,7 +15,7 @@ export const metadata = {
 
 export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
-  const { service, scope } = await resolveNotificationContext(req)
+  const { service, scope, ctx } = await resolveNotificationContext(req)
 
   const body = await req.json().catch(() => ({}))
   const parsed = executeActionSchema.safeParse(body)
@@ -23,7 +25,20 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
   const input = parsed.data
 
   try {
-    const { notification, result } = await service.executeAction(id, input, scope)
+    const guarded = await runGuardedNotificationWrite(
+      ctx.container,
+      scope,
+      req,
+      {
+        resourceKind: NOTIFICATION_RESOURCE_KIND,
+        resourceId: id,
+        operation: 'custom',
+        payload: input as Record<string, unknown>,
+      },
+      () => service.executeAction(id, input, scope),
+    )
+    if (!guarded.ok) return guarded.response
+    const { notification, result } = guarded.result
 
     const action = notification.actionData?.actions?.find((a) => a.id === input.actionId)
     const href = action?.href?.replace('{sourceEntityId}', notification.sourceEntityId ?? '')

package/src/modules/notifications/api/[id]/restore/route.ts

@@ -1,6 +1,10 @@
 import { z } from 'zod'
 import { restoreNotificationSchema } from '../../../data/validators'
-import { resolveNotificationContext } from '../../../lib/routeHelpers'
+import {
+  NOTIFICATION_RESOURCE_KIND,
+  resolveNotificationContext,
+  runGuardedNotificationWrite,
+} from '../../../lib/routeHelpers'
 
 export const metadata = {
   PUT: { requireAuth: true },
@@ -8,12 +12,24 @@ export const metadata = {
 
 export async function PUT(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
-  const { service, scope } = await resolveNotificationContext(req)
+  const { service, scope, ctx } = await resolveNotificationContext(req)
 
   const body = await req.json().catch(() => ({}))
   const input = restoreNotificationSchema.parse(body)
 
-  await service.restoreDismissed(id, input.status, scope)
+  const guarded = await runGuardedNotificationWrite(
+    ctx.container,
+    scope,
+    req,
+    {
+      resourceKind: NOTIFICATION_RESOURCE_KIND,
+      resourceId: id,
+      operation: 'update',
+      payload: input as Record<string, unknown>,
+    },
+    () => service.restoreDismissed(id, input.status, scope),
+  )
+  if (!guarded.ok) return guarded.response
 
   return Response.json({ ok: true })
 }

package/src/modules/notifications/api/mark-all-read/route.ts

@@ -1,16 +1,30 @@
 import { z } from 'zod'
-import { resolveNotificationContext } from '../../lib/routeHelpers'
+import {
+  NOTIFICATION_RESOURCE_KIND,
+  resolveNotificationContext,
+  runGuardedNotificationWrite,
+} from '../../lib/routeHelpers'
 
 export const metadata = {
   PUT: { requireAuth: true },
 }
 
 export async function PUT(req: Request) {
-  const { service, scope } = await resolveNotificationContext(req)
+  const { service, scope, ctx } = await resolveNotificationContext(req)
 
-  const count = await service.markAllAsRead(scope)
+  const guarded = await runGuardedNotificationWrite(
+    ctx.container,
+    scope,
+    req,
+    {
+      resourceKind: NOTIFICATION_RESOURCE_KIND,
+      operation: 'update',
+    },
+    () => service.markAllAsRead(scope),
+  )
+  if (!guarded.ok) return guarded.response
 
-  return Response.json({ ok: true, count })
+  return Response.json({ ok: true, count: guarded.result })
 }
 
 export const openApi = {

package/src/modules/notifications/api/route.ts

@@ -4,9 +4,11 @@ import { Notification } from '../data/entities'
 import { listNotificationsSchema, createNotificationSchema } from '../data/validators'
 import { toNotificationDto } from '../lib/notificationMapper'
 import {
+  NOTIFICATION_RESOURCE_KIND,
   notificationCrudErrorResponse,
   notificationValidationErrorResponse,
   resolveNotificationContext,
+  runGuardedNotificationWrite,
 } from '../lib/routeHelpers'
 import {
   buildNotificationsCrudOpenApi,
@@ -74,7 +76,7 @@ export async function GET(req: Request) {
 }
 
 export async function POST(req: Request) {
-  const { service, scope } = await resolveNotificationContext(req)
+  const { service, scope, ctx } = await resolveNotificationContext(req)
 
   const body = await req.json().catch(() => ({}))
   const parsed = createNotificationSchema.safeParse(body)
@@ -83,9 +85,20 @@ export async function POST(req: Request) {
   }
 
   try {
-    const notification = await service.create(parsed.data, scope)
+    const guarded = await runGuardedNotificationWrite(
+      ctx.container,
+      scope,
+      req,
+      {
+        resourceKind: NOTIFICATION_RESOURCE_KIND,
+        operation: 'create',
+        payload: parsed.data as Record<string, unknown>,
+      },
+      () => service.create(parsed.data, scope),
+    )
+    if (!guarded.ok) return guarded.response
 
-    return Response.json({ id: notification.id }, { status: 201 })
+    return Response.json({ id: guarded.result.id }, { status: 201 })
   } catch (error) {
     const errorResponse = notificationCrudErrorResponse(error)
     if (errorResponse) return errorResponse

package/src/modules/notifications/api/settings/route.ts

@@ -13,6 +13,10 @@ import {
   resolveNotificationDeliveryConfig,
   saveNotificationDeliveryConfig,
 } from '../../lib/deliveryConfig'
+import {
+  NOTIFICATION_SETTINGS_RESOURCE_KIND,
+  runGuardedNotificationWrite,
+} from '../../lib/routeHelpers'
 
 export const metadata = {
   GET: { requireAuth: true, requireFeatures: ['notifications.manage'] },
@@ -67,11 +71,28 @@ export async function POST(req: Request) {
 
   const container = await createRequestContainer()
   try {
-    await saveNotificationDeliveryConfig(container, parsed.data)
-    const settings = await resolveNotificationDeliveryConfig(container, {
-      defaultValue: DEFAULT_NOTIFICATION_DELIVERY_CONFIG,
-    })
-    return NextResponse.json({ ok: true, settings })
+    const guarded = await runGuardedNotificationWrite(
+      container,
+      {
+        tenantId: auth.tenantId ?? '',
+        organizationId: auth.orgId ?? null,
+        userId: auth.sub ?? null,
+      },
+      req,
+      {
+        resourceKind: NOTIFICATION_SETTINGS_RESOURCE_KIND,
+        operation: 'update',
+        payload: parsed.data as Record<string, unknown>,
+      },
+      async () => {
+        await saveNotificationDeliveryConfig(container, parsed.data)
+        return resolveNotificationDeliveryConfig(container, {
+          defaultValue: DEFAULT_NOTIFICATION_DELIVERY_CONFIG,
+        })
+      },
+    )
+    if (!guarded.ok) return guarded.response
+    return NextResponse.json({ ok: true, settings: guarded.result })
   } catch (error) {
     return NextResponse.json(
       { error: error instanceof Error ? error.message : t('api.errors.internal', 'Internal error') },

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

@@ -1,9 +1,24 @@
 import { z } from 'zod'
+import type { AwilixContainer } from 'awilix'
 import { resolveRequestContext } from '@open-mercato/shared/lib/api/context'
 import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { resolveNotificationService, type NotificationService } from './notificationService'
 
+/**
+ * Mutation-guard resource kind for notification rows.
+ */
+export const NOTIFICATION_RESOURCE_KIND = 'notifications.notification'
+
+/**
+ * Mutation-guard resource kind for notification delivery settings.
+ */
+export const NOTIFICATION_SETTINGS_RESOURCE_KIND = 'notifications.settings'
+
 /**
  * Notification scope context for service calls
  */
@@ -63,6 +78,65 @@ export async function resolveNotificationContext(req: Request): Promise<Notifica
   }
 }
 
+/**
+ * Mutation-guard options for a notification write.
+ */
+export interface NotificationMutationGuardOptions {
+  resourceKind: string
+  resourceId?: string | null
+  operation: 'create' | 'update' | 'delete' | 'custom'
+  payload?: Record<string, unknown> | null
+}
+
+export type GuardedNotificationWriteResult<T> =
+  | { ok: true; result: T }
+  | { ok: false; response: Response }
+
+/**
+ * Run a notification write through the mutation guard lifecycle.
+ * Validates before the mutation, performs the write, then runs after-success
+ * hooks only when the write succeeded and the guard requested them. Returns the
+ * guard's own block response when validation fails so authorization behavior and
+ * conflict shapes are preserved.
+ */
+export async function runGuardedNotificationWrite<T>(
+  container: AwilixContainer,
+  scope: NotificationScope,
+  req: Request,
+  options: NotificationMutationGuardOptions,
+  write: () => Promise<T>,
+): Promise<GuardedNotificationWriteResult<T>> {
+  const guardScope = {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    userId: scope.userId ?? '',
+    resourceKind: options.resourceKind,
+    resourceId: options.resourceId ?? '',
+    operation: options.operation,
+    requestMethod: req.method,
+    requestHeaders: req.headers,
+  }
+
+  const guardResult = await validateCrudMutationGuard(container, {
+    ...guardScope,
+    mutationPayload: options.payload ?? null,
+  })
+  if (guardResult && !guardResult.ok) {
+    return { ok: false, response: Response.json(guardResult.body, { status: guardResult.status }) }
+  }
+
+  const result = await write()
+
+  if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+    await runCrudMutationGuardAfterSuccess(container, {
+      ...guardScope,
+      metadata: guardResult.metadata ?? null,
+    })
+  }
+
+  return { ok: true, result }
+}
+
 /**
  * Create a POST handler for bulk notification creation routes.
  * Used by batch, role, and feature notification endpoints.
@@ -72,7 +146,7 @@ export function createBulkNotificationRoute<TSchema extends z.ZodTypeAny>(
   serviceMethod: 'createBatch' | 'createForRole' | 'createForFeature'
 ) {
   return async function POST(req: Request) {
-    const { service, scope } = await resolveNotificationContext(req)
+    const { service, scope, ctx } = await resolveNotificationContext(req)
 
     const body = await req.json().catch(() => ({}))
     const parsed = schema.safeParse(body)
@@ -81,7 +155,19 @@ export function createBulkNotificationRoute<TSchema extends z.ZodTypeAny>(
     }
 
     try {
-      const notifications = await service[serviceMethod](parsed.data as never, scope)
+      const guarded = await runGuardedNotificationWrite(
+        ctx.container,
+        scope,
+        req,
+        {
+          resourceKind: NOTIFICATION_RESOURCE_KIND,
+          operation: 'create',
+          payload: parsed.data as Record<string, unknown>,
+        },
+        () => service[serviceMethod](parsed.data as never, scope),
+      )
+      if (!guarded.ok) return guarded.response
+      const notifications = guarded.result
 
       return Response.json({
         ok: true,
@@ -144,10 +230,21 @@ export function createSingleNotificationActionRoute(
 ) {
   return async function PUT(req: Request, { params }: { params: Promise<{ id: string }> }) {
     const { id } = await params
-    const { service, scope } = await resolveNotificationContext(req)
+    const { service, scope, ctx } = await resolveNotificationContext(req)
 
     try {
-      await service[serviceMethod](id, scope)
+      const guarded = await runGuardedNotificationWrite(
+        ctx.container,
+        scope,
+        req,
+        {
+          resourceKind: NOTIFICATION_RESOURCE_KIND,
+          resourceId: id,
+          operation: 'update',
+        },
+        () => service[serviceMethod](id, scope),
+      )
+      if (!guarded.ok) return guarded.response
     } catch (error) {
       const errorResponse = notificationCrudErrorResponse(error)
       if (errorResponse) return errorResponse