@open-mercato/core 0.4.7-develop-0a657b411f → 0.4.7-develop-e249d3e7d0

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

@@ -0,0 +1,486 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import {
+  getGatewayAdapter,
+  type CreateSessionInput,
+  type CreateSessionResult,
+  type CaptureResult,
+  type RefundResult,
+  type CancelResult,
+  type GatewayPaymentStatus,
+  type UnifiedPaymentStatus,
+} from '@open-mercato/shared/modules/payment_gateways/types'
+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 { GatewayTransaction } from '../data/entities'
+import { isValidTransition } from './status-machine'
+import { emitPaymentGatewayEvent } from '../events'
+
+export interface PaymentGatewayServiceDeps {
+  em: EntityManager
+  integrationCredentialsService: CredentialsService
+  integrationStateService?: IntegrationStateService
+  integrationLogService?: IntegrationLogService
+}
+
+export interface CreatePaymentSessionInput {
+  providerKey: string
+  paymentId: string
+  orderId?: string
+  amount: number
+  currencyCode: string
+  captureMethod?: 'automatic' | 'manual'
+  description?: string
+  successUrl?: string
+  cancelUrl?: string
+  metadata?: Record<string, unknown>
+  organizationId: string
+  tenantId: string
+}
+
+export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
+  const { em, integrationCredentialsService, integrationLogService } = deps
+
+  async function findTransactionOrThrow(
+    transactionId: string,
+    scope: { organizationId: string; tenantId: string },
+  ): Promise<GatewayTransaction> {
+    const transaction = await findOneWithDecryption(
+      em,
+      GatewayTransaction,
+      {
+        id: transactionId,
+        organizationId: scope.organizationId,
+        tenantId: scope.tenantId,
+        deletedAt: null,
+      },
+      undefined,
+      scope,
+    )
+    if (!transaction) {
+      throw new Error('Transaction not found')
+    }
+    return transaction
+  }
+
+  function readProviderSessionId(transaction: GatewayTransaction): string {
+    if (typeof transaction.providerSessionId === 'string' && transaction.providerSessionId.trim().length > 0) {
+      return transaction.providerSessionId
+    }
+    throw new Error('Transaction is missing provider session id')
+  }
+
+  async function emitStatusEvent(status: UnifiedPaymentStatus, payload: Record<string, unknown>) {
+    type PaymentGatewayEventId = Parameters<typeof emitPaymentGatewayEvent>[0]
+    const eventMap: Partial<Record<UnifiedPaymentStatus, PaymentGatewayEventId>> = {
+      authorized: 'payment_gateways.payment.authorized',
+      captured: 'payment_gateways.payment.captured',
+      failed: 'payment_gateways.payment.failed',
+      refunded: 'payment_gateways.payment.refunded',
+      cancelled: 'payment_gateways.payment.cancelled',
+    }
+    const eventId = eventMap[status]
+    if (!eventId) return
+    await emitPaymentGatewayEvent(eventId, payload)
+  }
+
+  async function writeTransactionLog(
+    providerKey: string,
+    scope: { organizationId: string; tenantId: string },
+    transactionId: string,
+    level: 'info' | 'warn' | 'error',
+    message: string,
+    payload?: Record<string, unknown> | null,
+    code?: string | null,
+  ) {
+    if (!integrationLogService) return
+    await integrationLogService.write({
+      integrationId: `gateway_${providerKey}`,
+      scopeEntityType: 'payment_transaction',
+      scopeEntityId: transactionId,
+      level,
+      message,
+      code,
+      payload: payload ?? null,
+    }, scope)
+  }
+
+  async function resolveAdapterAndCredentials(providerKey: string, scope: { organizationId: string; tenantId: string }) {
+    const integrationId = `gateway_${providerKey}`
+    const selectedVersion = deps.integrationStateService
+      ? await deps.integrationStateService.resolveApiVersion(integrationId, scope)
+      : 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 credentials = await integrationCredentialsService.resolve(integrationId, scope) ?? {}
+
+    return { adapter, credentials }
+  }
+
+  return {
+    async createPaymentSession(input: CreatePaymentSessionInput): Promise<{ transaction: GatewayTransaction; session: CreateSessionResult }> {
+      const scope = { organizationId: input.organizationId, tenantId: input.tenantId }
+      const { adapter, credentials } = await resolveAdapterAndCredentials(input.providerKey, scope)
+
+      const sessionInput: CreateSessionInput = {
+        paymentId: input.paymentId,
+        orderId: input.orderId,
+        tenantId: input.tenantId,
+        organizationId: input.organizationId,
+        amount: input.amount,
+        currencyCode: input.currencyCode,
+        captureMethod: input.captureMethod,
+        description: input.description,
+        successUrl: input.successUrl,
+        cancelUrl: input.cancelUrl,
+        metadata: input.metadata,
+        credentials,
+      }
+
+      const session = await adapter.createSession(sessionInput)
+
+      const transaction = em.create(GatewayTransaction, {
+        paymentId: input.paymentId,
+        providerKey: input.providerKey,
+        providerSessionId: session.sessionId,
+        unifiedStatus: session.status,
+        redirectUrl: session.redirectUrl ?? null,
+        clientSecret: null,
+        amount: String(input.amount),
+        currencyCode: input.currencyCode,
+        gatewayMetadata: session.providerData ?? null,
+        organizationId: input.organizationId,
+        tenantId: input.tenantId,
+      })
+      await em.persistAndFlush(transaction)
+      await emitPaymentGatewayEvent('payment_gateways.session.created', {
+        transactionId: transaction.id,
+        paymentId: transaction.paymentId,
+        providerKey: transaction.providerKey,
+        status: transaction.unifiedStatus,
+        organizationId: transaction.organizationId,
+        tenantId: transaction.tenantId,
+      })
+      await writeTransactionLog(
+        transaction.providerKey,
+        scope,
+        transaction.id,
+        'info',
+        'Payment session created',
+        {
+          paymentId: transaction.paymentId,
+          providerSessionId: transaction.providerSessionId,
+          status: transaction.unifiedStatus,
+          amount: input.amount,
+          currencyCode: input.currencyCode,
+        },
+      )
+
+      return { transaction, session }
+    },
+
+    async capturePayment(transactionId: string, amount: number | undefined, scope: { organizationId: string; tenantId: string }): Promise<CaptureResult> {
+      const transaction = await findTransactionOrThrow(transactionId, scope)
+      const { adapter, credentials } = await resolveAdapterAndCredentials(
+        transaction.providerKey,
+        { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
+      )
+
+      const result = await adapter.capture({
+        sessionId: readProviderSessionId(transaction),
+        amount,
+        credentials,
+      })
+
+      transaction.unifiedStatus = result.status
+      transaction.gatewayMetadata = { ...transaction.gatewayMetadata, captureResult: result.providerData }
+      await em.flush()
+      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,
+        },
+      )
+
+      return result
+    },
+
+    async refundPayment(
+      transactionId: string,
+      amount: number | undefined,
+      reason: string | undefined,
+      scope: { organizationId: string; tenantId: string },
+    ): Promise<RefundResult> {
+      const transaction = await findTransactionOrThrow(transactionId, scope)
+      const { adapter, credentials } = await resolveAdapterAndCredentials(
+        transaction.providerKey,
+        { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
+      )
+
+      const result = await adapter.refund({
+        sessionId: readProviderSessionId(transaction),
+        amount,
+        reason,
+        credentials,
+      })
+
+      transaction.unifiedStatus = result.status
+      transaction.gatewayRefundId = result.refundId
+      transaction.gatewayMetadata = { ...transaction.gatewayMetadata, refundResult: result.providerData }
+      await em.flush()
+      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 result
+    },
+
+    async cancelPayment(
+      transactionId: string,
+      reason: string | undefined,
+      scope: { organizationId: string; tenantId: string },
+    ): Promise<CancelResult> {
+      const transaction = await findTransactionOrThrow(transactionId, scope)
+      const { adapter, credentials } = await resolveAdapterAndCredentials(
+        transaction.providerKey,
+        { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
+      )
+
+      const result = await adapter.cancel({
+        sessionId: readProviderSessionId(transaction),
+        reason,
+        credentials,
+      })
+
+      transaction.unifiedStatus = result.status
+      await em.flush()
+      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> {
+      const transaction = await findTransactionOrThrow(transactionId, scope)
+      const { adapter, credentials } = await resolveAdapterAndCredentials(
+        transaction.providerKey,
+        { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
+      )
+
+      const status = await adapter.getStatus({
+        sessionId: readProviderSessionId(transaction),
+        credentials,
+      })
+
+      if (status.status !== transaction.unifiedStatus && isValidTransition(transaction.unifiedStatus as UnifiedPaymentStatus, status.status)) {
+        const previousStatus = transaction.unifiedStatus
+        transaction.unifiedStatus = status.status
+        transaction.gatewayStatus = status.status
+        transaction.gatewayMetadata = { ...transaction.gatewayMetadata, statusResult: status.providerData ?? null }
+        transaction.lastPolledAt = new Date()
+        await em.flush()
+        await emitStatusEvent(status.status, {
+          transactionId: transaction.id,
+          paymentId: transaction.paymentId,
+          providerKey: transaction.providerKey,
+          previousStatus,
+          organizationId: transaction.organizationId,
+          tenantId: transaction.tenantId,
+        })
+        await writeTransactionLog(
+          transaction.providerKey,
+          { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
+          transaction.id,
+          'info',
+          'Payment status updated by poller',
+          {
+            previousStatus,
+            nextStatus: status.status,
+          },
+        )
+      }
+
+      return status
+    },
+
+    async syncTransactionStatus(transactionId: string, update: {
+      unifiedStatus: UnifiedPaymentStatus
+      providerStatus?: string
+      providerData?: Record<string, unknown>
+      webhookEvent?: {
+        eventType: string
+        idempotencyKey: string
+        processed: boolean
+        receivedAt?: string
+      }
+    }, scope: { organizationId: string; tenantId: string }): Promise<void> {
+      const transaction = await findTransactionOrThrow(transactionId, scope)
+      const currentStatus = transaction.unifiedStatus as UnifiedPaymentStatus
+      const canTransition = isValidTransition(currentStatus, update.unifiedStatus)
+      const shouldApplyStatus = canTransition && update.unifiedStatus !== currentStatus
+      const previousStatus = transaction.unifiedStatus
+      if (shouldApplyStatus) {
+        transaction.unifiedStatus = update.unifiedStatus
+      }
+      if (update.providerStatus) {
+        transaction.gatewayStatus = update.providerStatus
+      }
+      if (update.providerData) {
+        transaction.gatewayMetadata = { ...transaction.gatewayMetadata, ...update.providerData }
+      }
+      if (update.webhookEvent) {
+        const webhookLog = Array.isArray(transaction.webhookLog) ? transaction.webhookLog : []
+        webhookLog.push({
+          eventType: update.webhookEvent.eventType,
+          receivedAt: update.webhookEvent.receivedAt ?? new Date().toISOString(),
+          idempotencyKey: update.webhookEvent.idempotencyKey,
+          unifiedStatus: update.unifiedStatus,
+          processed: update.webhookEvent.processed,
+        })
+        transaction.webhookLog = webhookLog
+      }
+      transaction.lastWebhookAt = new Date()
+      await em.flush()
+      if (shouldApplyStatus) {
+        await emitStatusEvent(update.unifiedStatus, {
+          transactionId: transaction.id,
+          paymentId: transaction.paymentId,
+          providerKey: transaction.providerKey,
+          previousStatus,
+          organizationId: transaction.organizationId,
+          tenantId: transaction.tenantId,
+        })
+      }
+      await writeTransactionLog(
+        transaction.providerKey,
+        { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
+        transaction.id,
+        shouldApplyStatus ? 'info' : 'warn',
+        shouldApplyStatus ? 'Payment status synchronized from webhook' : 'Webhook received with no status transition',
+        {
+          previousStatus,
+          nextStatus: update.unifiedStatus,
+          providerStatus: update.providerStatus ?? null,
+          eventType: update.webhookEvent?.eventType ?? null,
+          idempotencyKey: update.webhookEvent?.idempotencyKey ?? null,
+        },
+      )
+    },
+
+    async findTransaction(id: string, scope: { organizationId: string; tenantId: string }): Promise<GatewayTransaction | null> {
+      return findOneWithDecryption(
+        em,
+        GatewayTransaction,
+        {
+          id,
+          organizationId: scope.organizationId,
+          tenantId: scope.tenantId,
+          deletedAt: null,
+        },
+        undefined,
+        scope,
+      )
+    },
+
+    async findTransactionBySessionId(
+      providerSessionId: string,
+      scope: { organizationId: string; tenantId: string },
+      providerKey?: string,
+    ): Promise<GatewayTransaction | null> {
+      return findOneWithDecryption(
+        em,
+        GatewayTransaction,
+        {
+          providerSessionId,
+          organizationId: scope.organizationId,
+          tenantId: scope.tenantId,
+          deletedAt: null,
+          ...(providerKey ? { providerKey } : {}),
+        },
+        undefined,
+        scope,
+      )
+    },
+
+    async listTransactionsForStatusPolling(scope?: {
+      organizationId?: string
+      tenantId?: string
+      providerKey?: string
+      limit?: number
+    }): Promise<GatewayTransaction[]> {
+      const where: Record<string, unknown> = {
+        unifiedStatus: { $in: ['pending', 'authorized', 'partially_captured'] },
+        deletedAt: null,
+      }
+      if (scope?.organizationId) where.organizationId = scope.organizationId
+      if (scope?.tenantId) where.tenantId = scope.tenantId
+      if (scope?.providerKey) where.providerKey = scope.providerKey
+
+      return findWithDecryption(
+        em,
+        GatewayTransaction,
+        where,
+        {
+          orderBy: { updatedAt: 'asc' },
+          limit: scope?.limit ?? 100,
+        },
+        scope,
+      )
+    },
+  }
+}
+
+export type PaymentGatewayService = ReturnType<typeof createPaymentGatewayService>

package/src/modules/payment_gateways/lib/queue.ts

@@ -0,0 +1,19 @@
+import { createQueue, type Queue } from '@open-mercato/queue'
+import { getRedisUrl } from '@open-mercato/shared/lib/redis/connection'
+
+const queues = new Map<string, Queue<Record<string, unknown>>>()
+
+export function getPaymentGatewayQueue(queueName: string): Queue<Record<string, unknown>> {
+  const existing = queues.get(queueName)
+  if (existing) return existing
+
+  const created = process.env.QUEUE_STRATEGY === 'async'
+    ? createQueue<Record<string, unknown>>(queueName, 'async', {
+      connection: { url: getRedisUrl('QUEUE') },
+      concurrency: Math.max(1, Number.parseInt(process.env.PAYMENT_GATEWAY_QUEUE_CONCURRENCY ?? '5', 10) || 5),
+    })
+    : createQueue<Record<string, unknown>>(queueName, 'local')
+
+  queues.set(queueName, created)
+  return created
+}

package/src/modules/payment_gateways/lib/status-machine.ts

@@ -0,0 +1,28 @@
+import type { UnifiedPaymentStatus } from '@open-mercato/shared/modules/payment_gateways/types'
+
+const VALID_TRANSITIONS: Record<string, UnifiedPaymentStatus[]> = {
+  pending: ['authorized', 'captured', 'failed', 'expired', 'cancelled'],
+  authorized: ['captured', 'partially_captured', 'cancelled', 'failed'],
+  captured: ['refunded', 'partially_refunded'],
+  partially_captured: ['captured', 'refunded', 'partially_refunded', 'cancelled'],
+  partially_refunded: ['refunded'],
+  // Terminal states: refunded, cancelled, failed, expired — no valid transitions out
+}
+
+export const TERMINAL_STATUSES: Set<UnifiedPaymentStatus> = new Set([
+  'refunded',
+  'cancelled',
+  'failed',
+  'expired',
+])
+
+export function isValidTransition(from: UnifiedPaymentStatus, to: UnifiedPaymentStatus): boolean {
+  if (from === to) return false
+  const allowed = VALID_TRANSITIONS[from]
+  if (!allowed) return false
+  return allowed.includes(to)
+}
+
+export function isTerminalStatus(status: UnifiedPaymentStatus): boolean {
+  return TERMINAL_STATUSES.has(status)
+}

package/src/modules/payment_gateways/lib/webhook-processor.ts

@@ -0,0 +1,133 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { getGatewayAdapter, type WebhookEvent } from '@open-mercato/shared/modules/payment_gateways/types'
+import type { IntegrationLogService } from '../../integrations/lib/log-service'
+import type { PaymentGatewayService } from './gateway-service'
+import { claimWebhookProcessing, releaseWebhookClaim } from './webhook-utils'
+
+export type PaymentGatewayWebhookJobPayload = {
+  providerKey: string
+  event: WebhookEvent
+  transactionId?: string | null
+  scope?: {
+    organizationId: string
+    tenantId: string
+  } | null
+}
+
+type PaymentGatewayWebhookProcessorDeps = {
+  em: EntityManager
+  paymentGatewayService: PaymentGatewayService
+  integrationLogService: IntegrationLogService
+}
+
+function readSessionIdFromEvent(event: WebhookEvent): string | null {
+  const id = event.data.id
+  if (typeof id === 'string' && id.trim().length > 0) return id.trim()
+  const paymentIntent = event.data.payment_intent
+  if (typeof paymentIntent === 'string' && paymentIntent.trim().length > 0) return paymentIntent.trim()
+  return null
+}
+
+function readScopeFromEvent(event: WebhookEvent): { organizationId: string; tenantId: string } | null {
+  const metadata = event.data.metadata
+  if (!metadata || typeof metadata !== 'object') return null
+
+  const metadataRecord = metadata as Record<string, unknown>
+  const organizationId = typeof metadataRecord.organizationId === 'string'
+    ? metadataRecord.organizationId.trim()
+    : ''
+  const tenantId = typeof metadataRecord.tenantId === 'string'
+    ? metadataRecord.tenantId.trim()
+    : ''
+
+  if (!organizationId || !tenantId) return null
+  return { organizationId, tenantId }
+}
+
+async function writeTransactionLog(
+  integrationLogService: IntegrationLogService,
+  providerKey: string,
+  scope: { organizationId: string; tenantId: string },
+  transactionId: string,
+  level: 'info' | 'warn' | 'error',
+  message: string,
+  payload?: Record<string, unknown>,
+) {
+  await integrationLogService.write({
+    integrationId: `gateway_${providerKey}`,
+    scopeEntityType: 'payment_transaction',
+    scopeEntityId: transactionId,
+    level,
+    message,
+    payload: payload ?? null,
+  }, scope)
+}
+
+export async function processPaymentGatewayWebhookJob(
+  deps: PaymentGatewayWebhookProcessorDeps,
+  payload: PaymentGatewayWebhookJobPayload,
+): Promise<void> {
+  const { em, paymentGatewayService, integrationLogService } = deps
+  const { providerKey, event } = payload
+  const scopedPayload = payload.scope ?? readScopeFromEvent(event)
+
+  let transaction = payload.transactionId && scopedPayload
+    ? await paymentGatewayService.findTransaction(payload.transactionId, scopedPayload)
+    : null
+
+  if (!transaction) {
+    const sessionId = readSessionIdFromEvent(event)
+    if (sessionId && scopedPayload) {
+      transaction = await paymentGatewayService.findTransactionBySessionId(sessionId, scopedPayload, providerKey)
+    }
+  }
+  if (!transaction) return
+
+  const scope = { organizationId: transaction.organizationId, tenantId: transaction.tenantId }
+  const claimed = await claimWebhookProcessing(em, event.idempotencyKey, providerKey, scope, event.eventType)
+  if (!claimed) {
+    await writeTransactionLog(integrationLogService, providerKey, scope, transaction.id, 'info', 'Duplicate payment gateway webhook skipped', {
+      eventType: event.eventType,
+      idempotencyKey: event.idempotencyKey,
+    })
+    return
+  }
+
+  try {
+    const adapter = getGatewayAdapter(providerKey)
+    if (!adapter) {
+      await writeTransactionLog(integrationLogService, providerKey, scope, transaction.id, 'warn', 'Missing payment gateway adapter for webhook event', {
+        providerKey,
+        eventType: event.eventType,
+      })
+      return
+    }
+
+    const providerStatus = typeof event.data.status === 'string' ? event.data.status : ''
+    const unifiedStatus = adapter.mapStatus(providerStatus, event.eventType)
+    await writeTransactionLog(integrationLogService, providerKey, scope, transaction.id, 'info', 'Payment gateway webhook received', {
+      eventType: event.eventType,
+      providerStatus,
+      unifiedStatus,
+    })
+
+    await paymentGatewayService.syncTransactionStatus(transaction.id, {
+      unifiedStatus,
+      providerStatus: event.eventType,
+      providerData: event.data,
+      webhookEvent: {
+        eventType: event.eventType,
+        idempotencyKey: event.idempotencyKey,
+        processed: true,
+      },
+    }, scope)
+
+    await writeTransactionLog(integrationLogService, providerKey, scope, transaction.id, 'info', 'Payment gateway webhook processed', {
+      eventType: event.eventType,
+      unifiedStatus,
+    })
+  } catch (error: unknown) {
+    await releaseWebhookClaim(em, event.idempotencyKey, providerKey, scope)
+    throw error
+  }
+}