@open-mercato/core 0.6.7-develop.6795.1.8a3f27921c → 0.6.7-develop.6824.1.21fff90682

package/src/modules/entities/backend/config/settings/page.tsx

@@ -0,0 +1,12 @@
+import { Page, PageBody } from '@open-mercato/ui/backend/Page'
+import { EntitySettingsManager } from '../../../components/EntitySettingsManager'
+
+export default function EntitySettingsPage() {
+  return (
+    <Page>
+      <PageBody className="space-y-8">
+        <EntitySettingsManager />
+      </PageBody>
+    </Page>
+  )
+}

package/src/modules/entities/backend/entities/user/create/page.tsx

@@ -10,6 +10,7 @@ import { useRouter } from 'next/navigation'
 import { pushWithFlash } from '@open-mercato/ui/backend/utils/flash'
 import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
 import { LoadingMessage } from '@open-mercato/ui/backend/detail'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
 
 const schema = upsertCustomEntitySchema
 
@@ -24,15 +25,23 @@ export default function CreateEntityPage() {
   React.useEffect(() => {
     let active = true
     ;(async () => {
-      const data = await readApiResultOrThrow<{ newEntitiesRestrictedByDefault?: boolean }>(
-        '/api/entities/entity-settings',
-        undefined,
-        { errorMessage: '[internal] Failed to load entity settings', fallback: { newEntitiesRestrictedByDefault: false } },
-      ).catch(() => ({ newEntitiesRestrictedByDefault: false }))
-      if (active) setDefaultRestricted(data?.newEntitiesRestrictedByDefault === true)
+      try {
+        const data = await readApiResultOrThrow<{ newEntitiesRestrictedByDefault?: boolean }>(
+          '/api/entities/entity-settings',
+          undefined,
+          {
+            errorMessage: t('entities.userEntities.errors.settingsLoadFailed', 'Could not load default restriction policy; using default'),
+            fallback: { newEntitiesRestrictedByDefault: false },
+          },
+        )
+        if (active) setDefaultRestricted(data?.newEntitiesRestrictedByDefault === true)
+      } catch {
+        flash(t('entities.userEntities.errors.settingsLoadFailed', 'Could not load default restriction policy; using default'), 'warning')
+        if (active) setDefaultRestricted(false)
+      }
     })()
     return () => { active = false }
-  }, [])
+  }, [t])
   const fields = React.useMemo<CrudField[]>(() => ([
     {
       id: 'entityId',

package/src/modules/entities/components/EntitySettingsManager.tsx

@@ -0,0 +1,160 @@
+"use client"
+
+import * as React from 'react'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { Checkbox } from '@open-mercato/ui/primitives/checkbox'
+import { Label } from '@open-mercato/ui/primitives/label'
+import { Spinner } from '@open-mercato/ui/primitives/spinner'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { apiCall, apiCallOrThrow, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { ErrorMessage } from '@open-mercato/ui/backend/detail'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { buildOptimisticLockHeader, extractOptimisticLockConflict } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+
+export function EntitySettingsManager(): React.ReactElement {
+  const t = useT()
+  const [loading, setLoading] = React.useState(true)
+  const [loadError, setLoadError] = React.useState(false)
+  const [saving, setSaving] = React.useState(false)
+  const [restricted, setRestricted] = React.useState(false)
+  const [updatedAt, setUpdatedAt] = React.useState<string | null>(null)
+
+  const { runMutation } = useGuardedMutation({
+    contextId: 'custom-entities-settings',
+  })
+
+  const loadSettings = React.useCallback(async () => {
+    setLoading(true)
+    setLoadError(false)
+    try {
+      const data = await readApiResultOrThrow<{ newEntitiesRestrictedByDefault?: boolean; updatedAt?: string | null }>(
+        '/api/entities/entity-settings',
+        undefined,
+        {
+          errorMessage: t('entities.settings.errors.loadFailed', 'Failed to load settings'),
+        }
+      )
+      setRestricted(data.newEntitiesRestrictedByDefault === true)
+      setUpdatedAt(data.updatedAt ?? null)
+    } catch {
+      setLoadError(true)
+    } finally {
+      setLoading(false)
+    }
+  }, [t])
+
+  React.useEffect(() => {
+    void loadSettings()
+  }, [loadSettings])
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setSaving(true)
+    try {
+      const headers = buildOptimisticLockHeader(updatedAt)
+      await runMutation({
+        operation: () =>
+          withScopedApiRequestHeaders(headers, async () => {
+            const res = await apiCallOrThrow<{ ok: boolean; newEntitiesRestrictedByDefault: boolean; updatedAt: string | null }>(
+              '/api/entities/entity-settings',
+              {
+                method: 'PUT',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({
+                  newEntitiesRestrictedByDefault: restricted,
+                  expectedUpdatedAt: updatedAt ?? undefined,
+                }),
+              },
+              {
+                errorMessage: t('entities.settings.errors.saveFailed', 'Failed to save settings'),
+              }
+            )
+
+            if (res.ok && res.result) {
+              setUpdatedAt(res.result.updatedAt)
+              flash(t('entities.settings.flash.saved', 'Settings saved'), 'success')
+            }
+            return res
+          }),
+        context: {},
+        mutationPayload: {
+          newEntitiesRestrictedByDefault: restricted,
+        },
+      })
+    } catch (err) {
+      const conflict = extractOptimisticLockConflict(err)
+      if (conflict) {
+        setLoading(true)
+        await loadSettings()
+      } else {
+        flash(t('entities.settings.errors.saveFailed', 'Failed to save settings'), 'error')
+      }
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  if (loading) {
+    return (
+      <div className="flex items-center gap-2 text-sm text-muted-foreground">
+        <Spinner className="h-4 w-4" />
+        <span>{t('entities.userEntities.form.loading', 'Loading…')}</span>
+      </div>
+    )
+  }
+
+  if (loadError) {
+    return (
+      <ErrorMessage
+        label={t('entities.settings.errors.loadFailed', 'Failed to load settings')}
+        action={(
+          <Button type="button" variant="outline" size="sm" onClick={() => void loadSettings()}>
+            {t('common.retry', 'Retry')}
+          </Button>
+        )}
+      />
+    )
+  }
+
+  return (
+    <form onSubmit={(e) => void handleSubmit(e)} className="space-y-6 max-w-2xl">
+      <div className="space-y-1">
+        <h3 className="text-base font-semibold">
+          {t('entities.settings.title', 'Custom Entities')}
+        </h3>
+        <p className="text-sm text-muted-foreground">
+          {t('entities.settings.description', 'Manage global custom entity configurations.')}
+        </p>
+      </div>
+
+      <div className="rounded-lg border bg-card p-4 space-y-4">
+        <div className="flex items-start gap-3">
+          <Checkbox
+            id="newEntitiesRestrictedByDefault"
+            checked={restricted}
+            onCheckedChange={(checked) => setRestricted(checked === true)}
+            disabled={saving}
+            className="mt-1"
+          />
+          <div className="space-y-1">
+            <Label htmlFor="newEntitiesRestrictedByDefault" className="font-medium cursor-pointer">
+              {t('entities.settings.newEntitiesRestrictedByDefault.label', 'Restrict record access by default')}
+            </Label>
+            <p className="text-sm text-muted-foreground">
+              {t('entities.settings.newEntitiesRestrictedByDefault.description', 'Require explicit per-entity permissions for records of newly created custom entities by default.')}
+            </p>
+          </div>
+        </div>
+      </div>
+
+      <div className="flex items-center justify-end gap-3 border-t pt-4">
+        <Button type="submit" disabled={saving}>
+          {saving ? <Spinner className="mr-2 h-4 w-4" /> : null}
+          {t('common.save', 'Save')}
+        </Button>
+      </div>
+    </form>
+  )
+}

package/src/modules/entities/i18n/de.json

@@ -196,6 +196,14 @@
   "entities.nav.systemEntities": "Systementitäten",
   "entities.nav.userEntities": "Benutzerentitäten",
   "entities.nav.userEntities.create": "Entität erstellen",
+  "entities.settings.description": "Globale Konfigurationen für benutzerdefinierte Entitäten verwalten.",
+  "entities.settings.errors.conflict": "Die Einstellungen wurden von einem anderen Benutzer geändert. Bitte neu laden.",
+  "entities.settings.errors.loadFailed": "Laden der Einstellungen fehlgeschlagen",
+  "entities.settings.errors.saveFailed": "Speichern der Einstellungen fehlgeschlagen",
+  "entities.settings.flash.saved": "Einstellungen gespeichert",
+  "entities.settings.newEntitiesRestrictedByDefault.description": "Für Datensätze neu erstellter benutzerdefinierter Entitäten standardmäßig explizite Berechtigungen pro Entität erfordern.",
+  "entities.settings.newEntitiesRestrictedByDefault.label": "Datensatzzugriff standardmäßig einschränken",
+  "entities.settings.title": "Benutzerdefinierte Entitäten",
   "entities.userEntities.edit.errors.deleteEntityFailed": "Entität konnte nicht gelöscht werden",
   "entities.userEntities.edit.errors.invalidEntityDescription": "Die angeforderte Entitäts-ID fehlt oder ist ungültig.",
   "entities.userEntities.edit.errors.invalidEntityId": "Ungültige Entitäts-ID",
@@ -221,6 +229,7 @@
   "entities.userEntities.errors.entityIdExists": "Entitäts-ID ist bereits vorhanden",
   "entities.userEntities.errors.entityIdRequired": "Entitäts-ID ist erforderlich",
   "entities.userEntities.errors.loadFailed": "Entitäten konnten nicht geladen werden",
+  "entities.userEntities.errors.settingsLoadFailed": "Standardeinschränkungsrichtlinie konnte nicht geladen werden; Standardwert wird verwendet",
   "entities.userEntities.flash.created": "Entität erstellt",
   "entities.userEntities.form.accessRestricted.help": "Erfordert eine explizite entitätsspezifische Berechtigung zum Anzeigen oder Verwalten der Datensätze dieser Entität. Deaktiviert lassen, um allen Benutzern mit der allgemeinen Datensatzberechtigung Zugriff zu gewähren.",
   "entities.userEntities.form.accessRestricted.label": "Datensatzzugriff einschränken",

package/src/modules/entities/i18n/en.json

@@ -196,6 +196,14 @@
   "entities.nav.systemEntities": "System Entities",
   "entities.nav.userEntities": "User Entities",
   "entities.nav.userEntities.create": "Create Entity",
+  "entities.settings.description": "Manage global custom entity configurations.",
+  "entities.settings.errors.conflict": "Settings were modified by another user. Please reload.",
+  "entities.settings.errors.loadFailed": "Failed to load settings",
+  "entities.settings.errors.saveFailed": "Failed to save settings",
+  "entities.settings.flash.saved": "Settings saved",
+  "entities.settings.newEntitiesRestrictedByDefault.description": "Require explicit per-entity permissions for records of newly created custom entities by default.",
+  "entities.settings.newEntitiesRestrictedByDefault.label": "Restrict record access by default",
+  "entities.settings.title": "Custom Entities",
   "entities.userEntities.edit.errors.deleteEntityFailed": "Failed to delete entity",
   "entities.userEntities.edit.errors.invalidEntityDescription": "The requested entity ID is missing or invalid.",
   "entities.userEntities.edit.errors.invalidEntityId": "Invalid entity ID",
@@ -221,6 +229,7 @@
   "entities.userEntities.errors.entityIdExists": "Entity ID already exists",
   "entities.userEntities.errors.entityIdRequired": "Entity ID is required",
   "entities.userEntities.errors.loadFailed": "Failed to load entities",
+  "entities.userEntities.errors.settingsLoadFailed": "Could not load default restriction policy; using default",
   "entities.userEntities.flash.created": "Entity created",
   "entities.userEntities.form.accessRestricted.help": "Require an explicit per-entity permission to view or manage this entity’s records. Leave off to allow anyone with the general records permission.",
   "entities.userEntities.form.accessRestricted.label": "Restrict record access",

package/src/modules/entities/i18n/es.json

@@ -196,6 +196,14 @@
   "entities.nav.systemEntities": "Entidades del sistema",
   "entities.nav.userEntities": "Entidades de usuario",
   "entities.nav.userEntities.create": "Crear entidad",
+  "entities.settings.description": "Administrar configuraciones globales de entidades personalizadas.",
+  "entities.settings.errors.conflict": "La configuración fue modificada por otro usuario. Por favor recarga.",
+  "entities.settings.errors.loadFailed": "Error al cargar la configuración",
+  "entities.settings.errors.saveFailed": "Error al guardar la configuración",
+  "entities.settings.flash.saved": "Configuración guardada",
+  "entities.settings.newEntitiesRestrictedByDefault.description": "Requerir permisos explícitos por entidad para registros de nuevas entidades creadas por defecto.",
+  "entities.settings.newEntitiesRestrictedByDefault.label": "Restringir acceso a registros por defecto",
+  "entities.settings.title": "Entidades personalizadas",
   "entities.userEntities.edit.errors.deleteEntityFailed": "No se pudo eliminar la entidad",
   "entities.userEntities.edit.errors.invalidEntityDescription": "Falta el ID de la entidad solicitada o no es válido.",
   "entities.userEntities.edit.errors.invalidEntityId": "ID de entidad no válido",
@@ -221,6 +229,7 @@
   "entities.userEntities.errors.entityIdExists": "El ID de la entidad ya existe",
   "entities.userEntities.errors.entityIdRequired": "El ID de la entidad es obligatorio",
   "entities.userEntities.errors.loadFailed": "No se pudieron cargar las entidades",
+  "entities.userEntities.errors.settingsLoadFailed": "No se pudo cargar la política de restricción por defecto; usando valor predeterminado",
   "entities.userEntities.flash.created": "Entidad creada",
   "entities.userEntities.form.accessRestricted.help": "Requiere un permiso explícito por entidad para ver o gestionar los registros de esta entidad. Déjalo desactivado para permitir el acceso a cualquiera con el permiso general de registros.",
   "entities.userEntities.form.accessRestricted.label": "Restringir acceso a registros",

package/src/modules/entities/i18n/pl.json

@@ -196,6 +196,14 @@
   "entities.nav.systemEntities": "Encje systemowe",
   "entities.nav.userEntities": "Encje użytkownika",
   "entities.nav.userEntities.create": "Utwórz encję",
+  "entities.settings.description": "Zarządzaj globalnymi ustawieniami niestandardowych encji.",
+  "entities.settings.errors.conflict": "Ustawienia zostały zmodyfikowane przez innego użytkownika. Proszę przeładować.",
+  "entities.settings.errors.loadFailed": "Nie udało się załadować ustawień",
+  "entities.settings.errors.saveFailed": "Nie udało się zapisać ustawień",
+  "entities.settings.flash.saved": "Ustawienia zostały zapisane",
+  "entities.settings.newEntitiesRestrictedByDefault.description": "Domyślnie wymagaj jawnych uprawnień dla poszczególnych encji do rekordów nowo tworzonych niestandardowych encji.",
+  "entities.settings.newEntitiesRestrictedByDefault.label": "Domyślnie ograniczaj dostęp do rekordów",
+  "entities.settings.title": "Niestandardowe encje",
   "entities.userEntities.edit.errors.deleteEntityFailed": "Nie udało się usunąć encji",
   "entities.userEntities.edit.errors.invalidEntityDescription": "Brakuje identyfikatora encji albo jest on nieprawidłowy.",
   "entities.userEntities.edit.errors.invalidEntityId": "Nieprawidłowy identyfikator encji",
@@ -221,6 +229,7 @@
   "entities.userEntities.errors.entityIdExists": "Identyfikator encji już istnieje",
   "entities.userEntities.errors.entityIdRequired": "Identyfikator encji jest wymagany",
   "entities.userEntities.errors.loadFailed": "Nie udało się wczytać encji",
+  "entities.userEntities.errors.settingsLoadFailed": "Nie udało się załadować domyślnej polityki ograniczeń; używanie wartości domyślnej",
   "entities.userEntities.flash.created": "Encja została utworzona",
   "entities.userEntities.form.accessRestricted.help": "Wymaga jawnego uprawnienia dla tej encji, aby przeglądać lub zarządzać jej rekordami. Pozostaw wyłączone, aby zezwolić na dostęp każdemu z ogólnym uprawnieniem do rekordów.",
   "entities.userEntities.form.accessRestricted.label": "Ogranicz dostęp do rekordów",

package/src/modules/inbox_ops/api/webhook/inbound.ts

@@ -13,6 +13,11 @@ import { parseInboundEmail } from '../../lib/emailParser'
 import { checkRateLimit } from '../../lib/rateLimiter'
 import { emitInboxOpsEvent } from '../../events'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import {
+  readBoundedRequestBody,
+  resolveWebhookBodyLimitBytes,
+  WebhookBodyTooLargeError,
+} from '@open-mercato/shared/lib/webhooks'
 
 const logger = createLogger('inbox_ops').child({ component: 'webhook' })
 
@@ -20,7 +25,10 @@ export const metadata = {
   POST: { requireAuth: false },
 }
 
-const MAX_PAYLOAD_SIZE = 2 * 1024 * 1024 // 2MB
+const MAX_PAYLOAD_SIZE = resolveWebhookBodyLimitBytes(
+  process.env.INBOX_OPS_WEBHOOK_MAX_BODY_BYTES ?? process.env.OM_WEBHOOK_MAX_BODY_BYTES,
+  2 * 1024 * 1024,
+)
 const REPLAY_WINDOW_MS = 5 * 60 * 1000 // 5 minutes
 
 function isTimestampFresh(timestamp: string): boolean {
@@ -211,22 +219,16 @@ export async function POST(req: Request) {
     return NextResponse.json({ error: 'Service unavailable' }, { status: 503 })
   }
 
-  const contentLength = parseInt(req.headers.get('content-length') || '0', 10)
-  if (contentLength > MAX_PAYLOAD_SIZE) {
-    return NextResponse.json({ error: 'Payload too large' }, { status: 413 })
-  }
-
   let rawBody: string
   try {
-    rawBody = await req.text()
-  } catch {
+    rawBody = await readBoundedRequestBody(req, { maxBytes: MAX_PAYLOAD_SIZE })
+  } catch (error) {
+    if (error instanceof WebhookBodyTooLargeError) {
+      return NextResponse.json({ error: 'Payload too large' }, { status: 413 })
+    }
     return NextResponse.json({ error: 'Bad request' }, { status: 400 })
   }
 
-  if (rawBody.length > MAX_PAYLOAD_SIZE) {
-    return NextResponse.json({ error: 'Payload too large' }, { status: 413 })
-  }
-
   const verified = await verifyAndParse(req, rawBody)
   if (!verified.ok) {
     return verified.response

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

@@ -102,9 +102,7 @@ export async function POST(req: Request) {
     if (isCrudHttpError(err)) {
       return NextResponse.json(err.body, { status: err.status })
     }
-    const message = err instanceof Error ? err.message : 'Failed to create payment session'
-    const status = message.includes('No gateway adapter') ? 422 : 502
-    return NextResponse.json({ error: message }, { status })
+    return NextResponse.json({ error: 'Failed to create payment session' }, { status: 502 })
   }
 }
 

package/src/modules/payment_gateways/api/webhook/[provider]/route.ts

@@ -14,6 +14,7 @@ import { getPaymentGatewayQueue } from '../../../lib/queue'
 import { processPaymentGatewayWebhookJob } from '../../../lib/webhook-processor'
 import { paymentGatewaysTag } from '../../openapi'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import { readBoundedRequestBody, WebhookBodyTooLargeError } from '@open-mercato/shared/lib/webhooks'
 
 const logger = createLogger('payment_gateways').child({ component: 'webhook' })
 
@@ -42,7 +43,17 @@ export async function POST(req: Request, { params }: { params: Promise<{ provide
   const rateLimitResponse = await checkProviderWebhookRateLimit(container, req, providerKey)
   if (rateLimitResponse) return rateLimitResponse
 
-  const rawBody = await req.text()
+  let rawBody: string
+  try {
+    rawBody = registration.maxBodyBytes === undefined
+      ? await req.text()
+      : await readBoundedRequestBody(req, { maxBytes: registration.maxBodyBytes })
+  } catch (error) {
+    if (error instanceof WebhookBodyTooLargeError) {
+      return NextResponse.json({ error: 'Webhook payload too large' }, { status: 413 })
+    }
+    throw error
+  }
   const headers: Record<string, string> = {}
   req.headers.forEach((value, key) => {
     headers[key] = value
@@ -164,6 +175,7 @@ export const openApi = {
       responses: [
         { status: 202, description: 'Webhook accepted for async processing' },
         { status: 401, description: 'Signature verification failed' },
+        { status: 413, description: 'Webhook payload too large' },
         { status: 404, description: 'Unknown provider' },
       ],
     },

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

@@ -145,6 +145,11 @@ export class GatewayPaymentOperation {
   name: 'gateway_session_initializations_scope_operation_unique',
   properties: ['operationKey', 'providerKey', 'organizationId', 'tenantId'],
 })
+@Index({
+  name: 'gateway_session_initializations_prune_idx',
+  expression:
+    'create index "gateway_session_initializations_prune_idx" on "gateway_session_initializations" ("tenant_id", "organization_id", "updated_at") where "gateway_transaction_id" is not null',
+})
 export class GatewaySessionInitialization {
   [OptionalProps]?: 'claimToken' | 'claimedAt' | 'gatewayTransactionId' | 'createdAt' | 'updatedAt'
 

package/src/modules/payment_gateways/i18n/de.json

@@ -79,5 +79,9 @@
   "payment_gateways.transactions.success.capture": "Payment erfasst",
   "payment_gateways.transactions.success.refreshStatus": "Der Transaktionsstatus wurde aktualisiert",
   "payment_gateways.transactions.tableTitle": "Transaktionen",
-  "payment_gateways.transactions.title": "Zahlungstransaktionen"
+  "payment_gateways.transactions.title": "Zahlungstransaktionen",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.cta": "Bereinigung der Ansprüche planen",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.loading": "Bereinigung der Ansprüche wird geplant…",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.message": "Registrieren Sie den täglichen Bereinigungsplan, der abgeschlossene Zahlungssitzungsansprüche nach ihrem 24-stündigen Wiederholungsfenster entfernt.",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.success": "Die Bereinigung der Zahlungssitzungsansprüche ist geplant."
 }

package/src/modules/payment_gateways/i18n/en.json

@@ -79,5 +79,9 @@
   "payment_gateways.transactions.success.capture": "Payment captured",
   "payment_gateways.transactions.success.refreshStatus": "Transaction status refreshed",
   "payment_gateways.transactions.tableTitle": "Transactions",
-  "payment_gateways.transactions.title": "Payment Transactions"
+  "payment_gateways.transactions.title": "Payment Transactions",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.cta": "Schedule claim cleanup",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.loading": "Scheduling claim cleanup…",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.message": "Register the daily cleanup schedule that removes completed payment-session claims after their 24-hour replay window.",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.success": "Payment-session claim cleanup is scheduled."
 }

package/src/modules/payment_gateways/i18n/es.json

@@ -79,5 +79,9 @@
   "payment_gateways.transactions.success.capture": "Pago capturado",
   "payment_gateways.transactions.success.refreshStatus": "El estado de la transaccion se actualizo",
   "payment_gateways.transactions.tableTitle": "Transacciones",
-  "payment_gateways.transactions.title": "Transacciones de pago"
+  "payment_gateways.transactions.title": "Transacciones de pago",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.cta": "Programar limpieza de reclamaciones",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.loading": "Programando limpieza de reclamaciones…",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.message": "Registra la limpieza diaria que elimina las reclamaciones de sesiones de pago completadas después de su ventana de repetición de 24 horas.",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.success": "La limpieza de reclamaciones de sesiones de pago está programada."
 }

package/src/modules/payment_gateways/i18n/pl.json

@@ -79,5 +79,9 @@
   "payment_gateways.transactions.success.capture": "Płatność została przechwycona",
   "payment_gateways.transactions.success.refreshStatus": "Status transakcji odświeżony",
   "payment_gateways.transactions.tableTitle": "Transakcje",
-  "payment_gateways.transactions.title": "Transakcje płatności"
+  "payment_gateways.transactions.title": "Transakcje płatności",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.cta": "Zaplanuj czyszczenie roszczeń",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.loading": "Planowanie czyszczenia roszczeń…",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.message": "Zarejestruj codzienny harmonogram usuwający zakończone roszczenia inicjalizacji sesji płatności po 24-godzinnym oknie ponowienia.",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.success": "Czyszczenie roszczeń inicjalizacji sesji płatności zostało zaplanowane."
 }

package/src/modules/payment_gateways/lib/gateway-service.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { createLogger } from '@open-mercato/shared/lib/logger'
 import {
   getGatewayAdapter,
   type CreateSessionInput,
@@ -17,7 +18,7 @@ import {
 import type { CredentialsService } from '../../integrations/lib/credentials-service'
 import type { IntegrationStateService } from '../../integrations/lib/state-service'
 import type { IntegrationLogService } from '../../integrations/lib/log-service'
-import { conflict } from '@open-mercato/shared/lib/crud/errors'
+import { conflict, CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { GatewayPaymentOperation, GatewaySessionInitialization, GatewayTransaction } from '../data/entities'
 import { canApplyManualAction, isValidTransition, type ManualGatewayAction } from './status-machine'
 import { emitPaymentGatewayEvent } from '../events'
@@ -48,6 +49,7 @@ import {
 
 const PAYMENT_SESSION_CLAIM_STALE_MS = 30_000
 const PAYMENT_SESSION_WAIT_INTERVAL_MS = 25
+const logger = createLogger('payment_gateways').child({ component: 'gateway-service' })
 
 function assertManualActionAllowed(action: ManualGatewayAction, transaction: GatewayTransaction): void {
   const current = transaction.unifiedStatus as UnifiedPaymentStatus
@@ -189,11 +191,10 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
       : undefined
     const adapter = getGatewayAdapter(providerKey, selectedVersion)
     if (!adapter) {
-      throw new Error(
-        selectedVersion
-          ? `No gateway adapter registered for provider: ${providerKey} (version: ${selectedVersion})`
-          : `No gateway adapter registered for provider: ${providerKey}`,
-      )
+      const message = selectedVersion
+        ? `No gateway adapter registered for provider: ${providerKey} (version: ${selectedVersion})`
+        : `No gateway adapter registered for provider: ${providerKey}`
+      throw new CrudHttpError(422, { error: message })
     }
     const credentials = await integrationCredentialsService.resolve(integrationId, scope) ?? {}
 
@@ -469,7 +470,7 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
             scope,
           )
           if (!transaction) {
-            throw new Error('Completed payment session is missing its gateway transaction')
+            throw new Error('[internal] Completed payment session is missing its gateway transaction')
           }
           return { transaction, session: restoreSession(transaction) }
         }
@@ -490,7 +491,15 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
         try {
           session = await adapter.createSession({ ...sessionInput, idempotencyKey: operationKey })
         } catch (error) {
-          await releasePaymentSessionInitialization(em, ownership, scope).catch(() => undefined)
+          try {
+            await releasePaymentSessionInitialization(em, ownership, scope)
+          } catch (releaseError) {
+            logger.warn('Failed to release payment session initialization claim', {
+              claimId: ownership.id,
+              providerKey: input.providerKey,
+              err: releaseError,
+            })
+          }
           throw error
         } finally {
           await stopHeartbeat()

package/src/modules/payment_gateways/lib/session-idempotency.ts

@@ -6,6 +6,11 @@ import { GatewaySessionInitialization } from '../data/entities'
 
 type Scope = { organizationId: string; tenantId: string }
 
+export const PAYMENT_SESSION_REPLAY_WINDOW_MS = 24 * 60 * 60 * 1000
+export const PAYMENT_SESSION_INITIALIZATION_PRUNE_QUEUE =
+  'payment-gateway-session-initialization-prune'
+export const PAYMENT_SESSION_INITIALIZATION_PRUNE_BATCH_SIZE = 1_000
+
 export type OwnedPaymentSessionInitialization = {
   id: string
   claimToken: string
@@ -140,3 +145,34 @@ export async function refreshPaymentSessionInitialization(
   )
   return refreshedRows > 0
 }
+
+export async function pruneCompletedPaymentSessionInitializations(
+  em: EntityManager,
+  scope: Scope,
+  options: { now?: Date; batchSize?: number } = {},
+): Promise<number> {
+  const now = options.now ?? new Date()
+  const batchSize = options.batchSize ?? PAYMENT_SESSION_INITIALIZATION_PRUNE_BATCH_SIZE
+  if (!Number.isInteger(batchSize) || batchSize < 1) {
+    throw new Error('[internal] Payment-session initialization prune batch size must be a positive integer')
+  }
+  const cutoff = new Date(now.getTime() - PAYMENT_SESSION_REPLAY_WINDOW_MS)
+  const connection = em.getConnection()
+  const result = await connection.execute(
+    `
+    delete from gateway_session_initializations
+    where id in (
+      select id from gateway_session_initializations
+      where tenant_id = ?
+        and organization_id = ?
+        and gateway_transaction_id is not null
+        and updated_at < ?
+      order by updated_at asc
+      limit ?
+    )
+    `,
+    [scope.tenantId, scope.organizationId, cutoff, batchSize],
+    'run',
+  ) as { affectedRows?: number; rowCount?: number } | undefined
+  return result?.affectedRows ?? result?.rowCount ?? 0
+}

package/src/modules/payment_gateways/migrations/.snapshot-open-mercato.json

@@ -537,6 +537,15 @@
           "primary": true,
           "unique": true
         },
+        {
+          "columnNames": [],
+          "composite": false,
+          "constraint": false,
+          "keyName": "gateway_session_initializations_prune_idx",
+          "primary": false,
+          "unique": false,
+          "expression": "create index \"gateway_session_initializations_prune_idx\" on \"gateway_session_initializations\" (\"tenant_id\", \"organization_id\", \"updated_at\") where \"gateway_transaction_id\" is not null"
+        },
         {
           "columnNames": [
             "operation_key",
@@ -1162,4 +1171,4 @@
   ],
   "views": [],
   "nativeEnums": {}
-}
+}

package/src/modules/payment_gateways/migrations/Migration20260803103035_payment_gateways.ts

@@ -0,0 +1,17 @@
+import { Migration } from '@mikro-orm/migrations'
+
+export class Migration20260803103035_payment_gateways extends Migration {
+  override isTransactional(): boolean {
+    return false
+  }
+
+  override up(): void | Promise<void> {
+    this.addSql(
+      'create index concurrently if not exists "gateway_session_initializations_prune_idx" on "gateway_session_initializations" ("tenant_id", "organization_id", "updated_at") where "gateway_transaction_id" is not null;',
+    )
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql('drop index concurrently if exists "gateway_session_initializations_prune_idx";')
+  }
+}