@open-mercato/core 0.6.6-develop.6229.1.ebe6706732 → 0.6.6-develop.6241.1.47c01ad4ed

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

@@ -24,7 +24,8 @@ import { PasswordInput } from '@open-mercato/ui/primitives/password-input'
 import { Spinner } from '@open-mercato/ui/primitives/spinner'
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@open-mercato/ui/primitives/tabs'
 import { JsonDisplay } from '@open-mercato/ui/backend/JsonDisplay'
-import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -105,8 +106,10 @@ type IntegrationDetail = {
     lastHealthCheckedAt: string | null
     lastHealthLatencyMs: number | null
     enabledAt: string | null
+    updatedAt: string | null
   }
   hasCredentials: boolean
+  credentialsUpdatedAt?: string | null
   healthStatus: 'healthy' | 'degraded' | 'unhealthy' | 'unconfigured'
   analytics: IntegrationLogAnalytics
 }
@@ -423,6 +426,7 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
   const [isNotFound, setIsNotFound] = React.useState(false)
 
   const [credValues, setCredValues] = React.useState<Record<string, unknown>>({})
+  const [credentialsUpdatedAt, setCredentialsUpdatedAt] = React.useState<string | null>(null)
   const [credentialsFormKey, setCredentialsFormKey] = React.useState(0)
   const [isSavingCredentials, setIsSavingCredentials] = React.useState(false)
 
@@ -486,11 +490,14 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
   const loadCredentials = React.useCallback(async () => {
     const currentIntegrationId = resolveCurrentIntegrationId()
     if (!currentIntegrationId) return
-    const call = await apiCall<{ credentials: Record<string, unknown> }>(
+    const call = await apiCall<{ credentials: Record<string, unknown>; updatedAt?: string | null }>(
       `/api/integrations/${encodeURIComponent(currentIntegrationId)}/credentials`,
       undefined,
       { fallback: null },
     )
+    if (call.ok && call.result) {
+      setCredentialsUpdatedAt(call.result.updatedAt ?? null)
+    }
     if (call.ok && call.result?.credentials) {
       const next = { ...call.result.credentials }
       if (currentIntegrationId === 'storage_s3') {
@@ -671,11 +678,14 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
       const call = await runMutationWithContext({
         actionId: 'toggle-state',
         mutationPayload: { integrationId: currentIntegrationId, isEnabled: enabled },
-        operation: () => apiCall(`/api/integrations/${encodeURIComponent(currentIntegrationId)}/state`, {
-          method: 'PUT',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ isEnabled: enabled }),
-        }, { fallback: null }),
+        operation: () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(detail?.state.updatedAt),
+          () => apiCall(`/api/integrations/${encodeURIComponent(currentIntegrationId)}/state`, {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ isEnabled: enabled }),
+          }, { fallback: null }),
+        ),
       })
       if (call.ok) {
         setDetail((prev) => prev ? {
@@ -687,6 +697,7 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
           },
         } : prev)
         flash(t('integrations.detail.stateUpdated'), 'success')
+        void refreshDetail()
       } else {
         flash(t('integrations.detail.stateError'), 'error')
       }
@@ -695,7 +706,7 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
     } finally {
       setIsTogglingState(false)
     }
-  }, [resolveCurrentIntegrationId, runMutationWithContext, t])
+  }, [detail?.state.updatedAt, refreshDetail, resolveCurrentIntegrationId, runMutationWithContext, t])
 
   const handleSaveCredentials = React.useCallback(async (values: Record<string, unknown>) => {
     const currentIntegrationId = resolveCurrentIntegrationId()
@@ -719,17 +730,21 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
         actionId: 'save-credentials',
         tabId: 'credentials',
         mutationPayload: { integrationId: currentIntegrationId, credentials: sanitizedValues },
-        operation: () => apiCall(`/api/integrations/${encodeURIComponent(currentIntegrationId)}/credentials`, {
-          method: 'PUT',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ credentials: sanitizedValues }),
-        }, { fallback: null }),
+        operation: () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(credentialsUpdatedAt),
+          () => apiCall(`/api/integrations/${encodeURIComponent(currentIntegrationId)}/credentials`, {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ credentials: sanitizedValues }),
+          }, { fallback: null }),
+        ),
       })
 
       if (call.ok) {
         setCredValues(sanitizedValues)
         setCredentialsFormKey((current) => current + 1)
         flash(t('integrations.detail.credentials.saved'), 'success')
+        void loadCredentials()
         return
       }
 
@@ -745,7 +760,7 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
     } finally {
       setIsSavingCredentials(false)
     }
-  }, [resolveCurrentIntegrationId, runMutationWithContext, t])
+  }, [credentialsUpdatedAt, loadCredentials, resolveCurrentIntegrationId, runMutationWithContext, t])
 
   const handleVersionChange = React.useCallback(async (version: string) => {
     const currentIntegrationId = resolveCurrentIntegrationId()
@@ -755,22 +770,26 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
         actionId: 'change-version',
         tabId: 'version',
         mutationPayload: { integrationId: currentIntegrationId, apiVersion: version },
-        operation: () => apiCall(`/api/integrations/${encodeURIComponent(currentIntegrationId)}/version`, {
-          method: 'PUT',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ apiVersion: version }),
-        }, { fallback: null }),
+        operation: () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(detail?.state.updatedAt),
+          () => apiCall(`/api/integrations/${encodeURIComponent(currentIntegrationId)}/version`, {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ apiVersion: version }),
+          }, { fallback: null }),
+        ),
       })
       if (call.ok) {
         setDetail((prev) => prev ? { ...prev, state: { ...prev.state, apiVersion: version } } : prev)
         flash(t('integrations.detail.version.saved'), 'success')
+        void refreshDetail()
       } else {
         flash(t('integrations.detail.version.saveError'), 'error')
       }
     } catch {
       flash(t('integrations.detail.version.saveError'), 'error')
     }
-  }, [resolveCurrentIntegrationId, runMutationWithContext, t])
+  }, [detail?.state.updatedAt, refreshDetail, resolveCurrentIntegrationId, runMutationWithContext, t])
 
   const handleHealthCheck = React.useCallback(async () => {
     const currentIntegrationId = resolveCurrentIntegrationId()

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' },
+      ],
+    },
   },
 }