@open-mercato/core 0.6.7-develop.6572.1.3d8e83062f → 0.6.7-develop.6574.1.05dcf72ba8

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

@@ -36,6 +36,7 @@ export type CreateSessionPayload = z.infer<typeof createSessionSchema>
 export const captureSchema = z.object({
   transactionId: z.string().uuid(),
   amount: z.number().positive().optional(),
+  operationId: z.string().trim().min(1).max(200).optional(),
 })
 
 export type CapturePayload = z.infer<typeof captureSchema>
@@ -44,6 +45,7 @@ export const refundSchema = z.object({
   transactionId: z.string().uuid(),
   amount: z.number().positive().optional(),
   reason: z.string().max(200).optional(),
+  operationId: z.string().trim().min(1).max(200).optional(),
 })
 
 export type RefundPayload = z.infer<typeof refundSchema>
@@ -51,6 +53,7 @@ export type RefundPayload = z.infer<typeof refundSchema>
 export const cancelSchema = z.object({
   transactionId: z.string().uuid(),
   reason: z.string().max(200).optional(),
+  operationId: z.string().trim().min(1).max(200).optional(),
 })
 
 export type CancelPayload = z.infer<typeof cancelSchema>

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

@@ -8,6 +8,7 @@ import {
   type CaptureResult,
   type RefundResult,
   type CancelResult,
+  type GatewayAdapter,
   type GatewayPaymentStatus,
   type PaymentGatewayPresentationRequest,
   type UnifiedPaymentStatus,
@@ -20,6 +21,11 @@ import { GatewaySessionInitialization, GatewayTransaction } from '../data/entiti
 import { canApplyManualAction, isValidTransition, type ManualGatewayAction } from './status-machine'
 import { emitPaymentGatewayEvent } from '../events'
 import { readGatewayMetadata, readWebhookLog } from './transaction-fields'
+import {
+  completePaymentOperation,
+  failPaymentOperation,
+  preparePaymentOperation,
+} from './payment-operation-idempotency'
 import {
   buildPaymentSessionOperationKey,
   claimPaymentSessionInitialization,
@@ -46,6 +52,7 @@ function applyAdapterResultStatus(
 ): boolean {
   const current = transaction.unifiedStatus as UnifiedPaymentStatus
   if (resultStatus === current) return false
+  if (isValidTransition(resultStatus, current)) return false
   if (!isValidTransition(current, resultStatus)) {
     throw conflict(
       `Gateway returned status "${resultStatus}" which is not a valid transition from "${current}" for ${action}`,
@@ -97,9 +104,10 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
   async function findTransactionOrThrow(
     transactionId: string,
     scope: { organizationId: string; tenantId: string },
+    targetEm: EntityManager = em,
   ): Promise<GatewayTransaction> {
     const transaction = await findOneWithDecryption(
-      em,
+      targetEm,
       GatewayTransaction,
       {
         id: transactionId,
@@ -176,6 +184,82 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
     return { adapter, credentials }
   }
 
+  type ManualOperationResult = CaptureResult | RefundResult | CancelResult
+
+  async function executeManualOperation<TResult extends ManualOperationResult>(input: {
+    action: ManualGatewayAction
+    transactionId: string
+    operationId?: string
+    payload: Record<string, unknown>
+    scope: { organizationId: string; tenantId: string }
+    invoke: (context: {
+      adapter: GatewayAdapter
+      credentials: Record<string, unknown>
+      transaction: GatewayTransaction
+      idempotencyKey: string
+    }) => Promise<TResult>
+    applyResult: (transaction: GatewayTransaction, result: TResult) => void
+    afterCommit: (transaction: GatewayTransaction, result: TResult) => Promise<void>
+  }): Promise<TResult> {
+    const transaction = await findTransactionOrThrow(input.transactionId, input.scope)
+    const prepared = await preparePaymentOperation({
+      em,
+      transactionId: transaction.id,
+      providerKey: transaction.providerKey,
+      action: input.action,
+      operationId: input.operationId,
+      payload: input.payload,
+      scope: input.scope,
+      assertInitialAllowed: () => assertManualActionAllowed(input.action, transaction),
+    })
+    if (prepared.kind === 'completed') {
+      if (prepared.result.status !== transaction.unifiedStatus) {
+        throw conflict(
+          `Cannot replay ${input.action} because the payment status has changed since the operation completed`,
+        )
+      }
+      return prepared.result as unknown as TResult
+    }
+
+    try {
+      const { adapter, credentials } = await resolveAdapterAndCredentials(
+        transaction.providerKey,
+        { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
+      )
+      const result = await input.invoke({
+        adapter,
+        credentials,
+        transaction,
+        idempotencyKey: prepared.claim.providerIdempotencyKey,
+      })
+      const statusChanged = await completePaymentOperation(
+        em,
+        prepared.claim,
+        result as unknown as Record<string, unknown>,
+        async (tx) => {
+          const current = await findTransactionOrThrow(input.transactionId, input.scope, tx)
+          const changed = applyAdapterResultStatus(input.action, current, result.status)
+          input.applyResult(current, result)
+          return changed
+        },
+      )
+      if (statusChanged) {
+        await emitStatusEvent(result.status, {
+          transactionId: transaction.id,
+          paymentId: transaction.paymentId,
+          providerKey: transaction.providerKey,
+          organizationId: transaction.organizationId,
+          tenantId: transaction.tenantId,
+        })
+      }
+      await input.afterCommit(transaction, result)
+      return result
+    } catch (error: unknown) {
+      await Promise.allSettled([failPaymentOperation(em, prepared.claim)])
+      throw error
+    }
+  }
+
   function createGatewayTransaction(
     manager: EntityManager,
     input: CreatePaymentSessionInput,
@@ -391,46 +475,39 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
       }
     },
 
-    async capturePayment(transactionId: string, amount: number | undefined, scope: { organizationId: string; tenantId: string }): Promise<CaptureResult> {
-      const transaction = await findTransactionOrThrow(transactionId, scope)
-      assertManualActionAllowed('capture', transaction)
-      const { adapter, credentials } = await resolveAdapterAndCredentials(
-        transaction.providerKey,
-        { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
-      )
-
-      const result = await adapter.capture({
-        sessionId: readProviderSessionId(transaction),
-        amount,
-        credentials,
-      })
-
-      const statusChanged = applyAdapterResultStatus('capture', transaction, result.status)
-      transaction.gatewayMetadata = { ...readGatewayMetadata(transaction.gatewayMetadata), captureResult: result.providerData }
-      await em.flush()
-      if (statusChanged) {
-        await emitStatusEvent(result.status, {
-          transactionId: transaction.id,
-          paymentId: transaction.paymentId,
-          providerKey: transaction.providerKey,
-          organizationId: transaction.organizationId,
-          tenantId: transaction.tenantId,
-        })
-      }
-      await writeTransactionLog(
-        transaction.providerKey,
-        { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
-        transaction.id,
-        'info',
-        'Payment captured',
-        {
-          amount: amount ?? null,
-          status: result.status,
-          capturedAmount: result.capturedAmount,
+    async capturePayment(
+      transactionId: string,
+      amount: number | undefined,
+      scope: { organizationId: string; tenantId: string },
+      operationId?: string,
+    ): Promise<CaptureResult> {
+      return executeManualOperation({
+        action: 'capture',
+        transactionId,
+        operationId,
+        payload: { amount: amount ?? null },
+        scope,
+        invoke: ({ adapter, credentials, transaction, idempotencyKey }) => adapter.capture({
+          sessionId: readProviderSessionId(transaction),
+          amount,
+          credentials,
+          idempotencyKey,
+        }),
+        applyResult: (transaction, result) => {
+          transaction.gatewayMetadata = {
+            ...readGatewayMetadata(transaction.gatewayMetadata),
+            captureResult: result.providerData,
+          }
         },
-      )
-
-      return result
+        afterCommit: (transaction, result) => writeTransactionLog(
+          transaction.providerKey,
+          { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
+          transaction.id,
+          'info',
+          'Payment captured',
+          { amount: amount ?? null, status: result.status, capturedAmount: result.capturedAmount },
+        ),
+      })
     },
 
     async refundPayment(
@@ -438,93 +515,67 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
       amount: number | undefined,
       reason: string | undefined,
       scope: { organizationId: string; tenantId: string },
+      operationId?: string,
     ): Promise<RefundResult> {
-      const transaction = await findTransactionOrThrow(transactionId, scope)
-      assertManualActionAllowed('refund', transaction)
-      const { adapter, credentials } = await resolveAdapterAndCredentials(
-        transaction.providerKey,
-        { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
-      )
-
-      const result = await adapter.refund({
-        sessionId: readProviderSessionId(transaction),
-        amount,
-        reason,
-        credentials,
-      })
-
-      const statusChanged = applyAdapterResultStatus('refund', transaction, result.status)
-      transaction.gatewayRefundId = result.refundId
-      transaction.gatewayMetadata = { ...readGatewayMetadata(transaction.gatewayMetadata), refundResult: result.providerData }
-      await em.flush()
-      if (statusChanged) {
-        await emitStatusEvent(result.status, {
-          transactionId: transaction.id,
-          paymentId: transaction.paymentId,
-          providerKey: transaction.providerKey,
-          organizationId: transaction.organizationId,
-          tenantId: transaction.tenantId,
-        })
-      }
-      await writeTransactionLog(
-        transaction.providerKey,
-        { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
-        transaction.id,
-        'info',
-        'Payment refunded',
-        {
-          amount: amount ?? null,
-          reason: reason ?? null,
-          status: result.status,
-          refundId: result.refundId,
+      return executeManualOperation({
+        action: 'refund',
+        transactionId,
+        operationId,
+        payload: { amount: amount ?? null, reason: reason ?? null },
+        scope,
+        invoke: ({ adapter, credentials, transaction, idempotencyKey }) => adapter.refund({
+          sessionId: readProviderSessionId(transaction),
+          amount,
+          reason,
+          credentials,
+          idempotencyKey,
+        }),
+        applyResult: (transaction, result) => {
+          transaction.gatewayRefundId = result.refundId
+          transaction.gatewayMetadata = {
+            ...readGatewayMetadata(transaction.gatewayMetadata),
+            refundResult: result.providerData,
+          }
         },
-      )
-
-      return result
+        afterCommit: (transaction, result) => writeTransactionLog(
+          transaction.providerKey,
+          { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
+          transaction.id,
+          'info',
+          'Payment refunded',
+          { amount: amount ?? null, reason: reason ?? null, status: result.status, refundId: result.refundId },
+        ),
+      })
     },
 
     async cancelPayment(
       transactionId: string,
       reason: string | undefined,
       scope: { organizationId: string; tenantId: string },
+      operationId?: string,
     ): Promise<CancelResult> {
-      const transaction = await findTransactionOrThrow(transactionId, scope)
-      assertManualActionAllowed('cancel', transaction)
-      const { adapter, credentials } = await resolveAdapterAndCredentials(
-        transaction.providerKey,
-        { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
-      )
-
-      const result = await adapter.cancel({
-        sessionId: readProviderSessionId(transaction),
-        reason,
-        credentials,
+      return executeManualOperation({
+        action: 'cancel',
+        transactionId,
+        operationId,
+        payload: { reason: reason ?? null },
+        scope,
+        invoke: ({ adapter, credentials, transaction, idempotencyKey }) => adapter.cancel({
+          sessionId: readProviderSessionId(transaction),
+          reason,
+          credentials,
+          idempotencyKey,
+        }),
+        applyResult: () => {},
+        afterCommit: (transaction, result) => writeTransactionLog(
+          transaction.providerKey,
+          { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
+          transaction.id,
+          'info',
+          'Payment cancelled',
+          { reason: reason ?? null, status: result.status },
+        ),
       })
-
-      const statusChanged = applyAdapterResultStatus('cancel', transaction, result.status)
-      await em.flush()
-      if (statusChanged) {
-        await emitStatusEvent(result.status, {
-          transactionId: transaction.id,
-          paymentId: transaction.paymentId,
-          providerKey: transaction.providerKey,
-          organizationId: transaction.organizationId,
-          tenantId: transaction.tenantId,
-        })
-      }
-      await writeTransactionLog(
-        transaction.providerKey,
-        { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
-        transaction.id,
-        'info',
-        'Payment cancelled',
-        {
-          reason: reason ?? null,
-          status: result.status,
-        },
-      )
-
-      return result
     },
 
     async getPaymentStatus(transactionId: string, scope: { organizationId: string; tenantId: string }): Promise<GatewayPaymentStatus> {

package/src/modules/payment_gateways/lib/payment-operation-idempotency.ts

@@ -0,0 +1,238 @@
+import { createHash, randomUUID } from 'node:crypto'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { CrudHttpError, isUniqueViolation } from '@open-mercato/shared/lib/crud/errors'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { GatewayPaymentOperation } from '../data/entities'
+import type { ManualGatewayAction } from './status-machine'
+
+type Scope = { organizationId: string; tenantId: string }
+type OperationStatus = 'in_progress' | 'succeeded' | 'failed'
+
+const OPERATION_LEASE_MS = 10 * 60 * 1000
+const OPERATION_UNIQUE_CONSTRAINT = 'gateway_payment_operations_scope_operation_unique'
+
+export type ClaimedPaymentOperation = {
+  record: GatewayPaymentOperation
+  attemptToken: string
+  providerIdempotencyKey: string
+}
+
+export type PreparedPaymentOperation =
+  | { kind: 'completed'; result: Record<string, unknown> }
+  | { kind: 'claimed'; claim: ClaimedPaymentOperation }
+
+type PreparePaymentOperationInput = {
+  em: EntityManager
+  transactionId: string
+  providerKey: string
+  action: ManualGatewayAction
+  operationId?: string
+  payload: Record<string, unknown>
+  scope: Scope
+  assertInitialAllowed: () => void
+}
+
+function digest(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex')
+}
+
+function operationConflict(code: string, operationId: string, message: string): CrudHttpError {
+  return new CrudHttpError(409, { error: message, code, operationId })
+}
+
+async function findOperation(
+  em: EntityManager,
+  operationId: string,
+  scope: Scope,
+): Promise<GatewayPaymentOperation | null> {
+  return findOneWithDecryption(
+    em,
+    GatewayPaymentOperation,
+    {
+      operationId,
+      organizationId: scope.organizationId,
+      tenantId: scope.tenantId,
+    },
+    undefined,
+    scope,
+  )
+}
+
+function buildOperationIdentity(input: Omit<PreparePaymentOperationInput, 'em' | 'assertInitialAllowed'>) {
+  const requestHash = digest({
+    transactionId: input.transactionId,
+    providerKey: input.providerKey,
+    action: input.action,
+    payload: input.payload,
+  })
+  const operationId = input.operationId ?? `auto_${requestHash}`
+  const providerIdempotencyKey = `om-pg-${digest({
+    tenantId: input.scope.tenantId,
+    organizationId: input.scope.organizationId,
+    transactionId: input.transactionId,
+    action: input.action,
+    operationId,
+  })}`
+  return { operationId, providerIdempotencyKey, requestHash }
+}
+
+function claimFields(now: Date) {
+  return {
+    status: 'in_progress' as OperationStatus,
+    attemptToken: randomUUID(),
+    leaseExpiresAt: new Date(now.getTime() + OPERATION_LEASE_MS),
+    updatedAt: now,
+  }
+}
+
+async function resolveExistingOperation(
+  em: EntityManager,
+  existing: GatewayPaymentOperation,
+  identity: ReturnType<typeof buildOperationIdentity>,
+): Promise<PreparedPaymentOperation> {
+  if (existing.requestHash !== identity.requestHash) {
+    throw operationConflict(
+      'payment_operation_conflict',
+      identity.operationId,
+      'Payment operation id was already used with a different request',
+    )
+  }
+  if (existing.providerIdempotencyKey !== identity.providerIdempotencyKey) {
+    throw operationConflict(
+      'payment_operation_conflict',
+      identity.operationId,
+      'Payment operation id resolved to a different provider request',
+    )
+  }
+  if (existing.status === 'succeeded' && existing.result) {
+    return { kind: 'completed', result: existing.result }
+  }
+
+  const now = new Date()
+  const stale = existing.status === 'in_progress'
+    && existing.leaseExpiresAt instanceof Date
+    && existing.leaseExpiresAt <= now
+  if (existing.status !== 'failed' && !stale) {
+    throw operationConflict(
+      'payment_operation_in_progress',
+      identity.operationId,
+      'Payment operation is already in progress',
+    )
+  }
+
+  const next = claimFields(now)
+  const where = existing.status === 'failed'
+    ? { id: existing.id, status: 'failed', attemptToken: existing.attemptToken }
+    : { id: existing.id, status: 'in_progress', attemptToken: existing.attemptToken, leaseExpiresAt: { $lt: now } }
+  const claimed = await em.nativeUpdate(
+    GatewayPaymentOperation,
+    where,
+    { ...next, attemptCount: existing.attemptCount + 1 },
+  )
+  if (claimed !== 1) {
+    throw operationConflict(
+      'payment_operation_in_progress',
+      identity.operationId,
+      'Payment operation is already in progress',
+    )
+  }
+  Object.assign(existing, next, { attemptCount: existing.attemptCount + 1 })
+  return {
+    kind: 'claimed',
+    claim: {
+      record: existing,
+      attemptToken: next.attemptToken,
+      providerIdempotencyKey: existing.providerIdempotencyKey,
+    },
+  }
+}
+
+export async function preparePaymentOperation(
+  input: PreparePaymentOperationInput,
+): Promise<PreparedPaymentOperation> {
+  const identity = buildOperationIdentity(input)
+  const existing = await findOperation(input.em, identity.operationId, input.scope)
+  if (existing) {
+    return resolveExistingOperation(input.em, existing, identity)
+  }
+
+  input.assertInitialAllowed()
+  const now = new Date()
+  const claim = claimFields(now)
+  const record = input.em.create(GatewayPaymentOperation, {
+    operationId: identity.operationId,
+    transactionId: input.transactionId,
+    operationType: input.action,
+    providerKey: input.providerKey,
+    requestHash: identity.requestHash,
+    providerIdempotencyKey: identity.providerIdempotencyKey,
+    status: claim.status,
+    attemptToken: claim.attemptToken,
+    attemptCount: 1,
+    result: null,
+    leaseExpiresAt: claim.leaseExpiresAt,
+    organizationId: input.scope.organizationId,
+    tenantId: input.scope.tenantId,
+    createdAt: now,
+    updatedAt: now,
+  })
+  try {
+    await input.em.persist(record).flush()
+    return {
+      kind: 'claimed',
+      claim: {
+        record,
+        attemptToken: claim.attemptToken,
+        providerIdempotencyKey: identity.providerIdempotencyKey,
+      },
+    }
+  } catch (error: unknown) {
+    if (!isUniqueViolation(error, OPERATION_UNIQUE_CONSTRAINT) && !isUniqueViolation(error)) {
+      throw error
+    }
+    const winner = await findOperation(input.em, identity.operationId, input.scope)
+    if (!winner) throw error
+    return resolveExistingOperation(input.em, winner, identity)
+  }
+}
+
+export async function completePaymentOperation<T extends Record<string, unknown>>(
+  em: EntityManager,
+  claim: ClaimedPaymentOperation,
+  result: T,
+  applyResult: (tx: EntityManager) => Promise<boolean>,
+): Promise<boolean> {
+  const statusChanged = await em.transactional(async (tx) => {
+    const completed = await tx.nativeUpdate(
+      GatewayPaymentOperation,
+      { id: claim.record.id, status: 'in_progress', attemptToken: claim.attemptToken },
+      { status: 'succeeded', result, leaseExpiresAt: null, updatedAt: new Date() },
+    )
+    if (completed !== 1) {
+      throw operationConflict(
+        'payment_operation_claim_lost',
+        claim.record.operationId,
+        'Payment operation claim is no longer active',
+      )
+    }
+    const changed = await applyResult(tx)
+    await tx.flush()
+    return changed
+  })
+  Object.assign(claim.record, { status: 'succeeded', result, leaseExpiresAt: null })
+  return statusChanged
+}
+
+export async function failPaymentOperation(
+  em: EntityManager,
+  claim: ClaimedPaymentOperation,
+): Promise<void> {
+  const failed = await em.nativeUpdate(
+    GatewayPaymentOperation,
+    { id: claim.record.id, status: 'in_progress', attemptToken: claim.attemptToken },
+    { status: 'failed', leaseExpiresAt: null, updatedAt: new Date() },
+  )
+  if (failed === 1) {
+    Object.assign(claim.record, { status: 'failed', leaseExpiresAt: null })
+  }
+}