Unified Interface

// IPaymentProvider -- implement this interface for every PSP adapter

export interface IPaymentProvider {
  initiateDeposit(req: DepositRequest): Promise<UnifiedResponse>
  initiateWithdrawal(req: WithdrawalRequest): Promise<UnifiedResponse>
  getTransactionStatus(psp_payment_id: string): Promise<UnifiedStatusResponse>
  handleWebhook(payload: RawWebhookPayload): Promise<UnifiedEvent>
  getSupportedMethods(geo: string, currency: string): Promise<PaymentMethod[]>
}

// ── Request types ──────────────────────────────────────────────────────────────

export interface DepositRequest {
  payment_id:   string                      // idempotency key
  user_id:      string
  brand_id:     string
  amount:       number                      // USD cents, integer
  currency:     string                      // ISO 4217
  method:       string                      // e.g. "btc", "usdt_trc20"
  return_url?:  string
  metadata?:    Record<string, string>
}

export interface WithdrawalRequest {
  payment_id:      string                   // idempotency key
  user_id:         string
  brand_id:        string
  amount:          number                   // USD cents, integer
  currency:        string                   // ISO 4217
  method:          string
  wallet_address:  string
  tag?:            string                   // required for XRP, TON
}

export interface RawWebhookPayload {
  body:      unknown
  headers:   Record<string, string>
  raw_body:  Buffer                         // for HMAC verification
}

// ── Response types ─────────────────────────────────────────────────────────────

export interface UnifiedResponse {
  payment_id:      string
  psp_payment_id:  string
  status:          UnifiedStatus
  action:          UnifiedAction
  redirect_url?:   string | null
  address?:        string | null
  tag?:            string | null
  expires_at?:     string | null            // ISO 8601
}

export interface UnifiedStatusResponse {
  psp_payment_id:   string
  status:           UnifiedStatus
  amount_credited?: number | null           // USD cents
  blockchain_tx_id?:string | null
}

export interface UnifiedEvent {
  event_type:       UnifiedEventType
  psp_payment_id:   string
  status:           UnifiedStatus
  amount_credited?: number | null           // USD cents
  amount_debited?:  number | null           // USD cents
  fee_total?:       number | null           // USD cents
  blockchain_tx_id?:string | null
}

export interface PaymentMethod {
  slug:        string
  name:        string
  min_amount:  number                       // USD cents
  max_amount:  number                       // USD cents
  fee_pct?:    number                       // 0--100
  logo_url?:   string
}

// ── Enums ──────────────────────────────────────────────────────────────────────

export type UnifiedStatus =
  | 'INITIATED'
  | 'PROCESSING'
  | 'PENDING_CONFIRMATION'
  | 'PENDING_PARTIAL'
  | 'COMPLETED'
  | 'FAILED'
  | 'TIMED_OUT'
  | 'CANCELLED'

export type UnifiedAction =
  | 'redirect'
  | 'show_address'
  | 'show_qr'

export type UnifiedEventType =
  | 'deposit_confirmed'
  | 'deposit_processing'
  | 'withdrawal_completed'
  | 'withdrawal_failed'
  | 'partial_payment'

export class UnifiedPaymentError extends Error {
  constructor(
    public readonly code: UnifiedErrorCode,
    public readonly message: string,
    public readonly psp_raw?: unknown,      // original PSP error for logging
  ) {
    super(message)
  }
}

export type UnifiedErrorCode =
  | 'PSP_UNAVAILABLE'           // PSP returned 5xx or timed out
  | 'INVALID_METHOD'            // method not supported for this geo/currency
  | 'AMOUNT_BELOW_MIN'          // amount < method minimum
  | 'AMOUNT_ABOVE_MAX'          // amount > method maximum
  | 'CURRENCY_NOT_SUPPORTED'    // PSP does not support this currency
  | 'INVALID_WALLET_ADDRESS'    // wallet address failed validation
  | 'INSUFFICIENT_PSP_BALANCE'  // PSP account balance too low for withdrawal
  | 'TRANSACTION_NOT_FOUND'     // psp_payment_id not found at PSP
  | 'INVALID_SIGNATURE'         // webhook HMAC verification failed
  | 'UNKNOWN_EVENT_TYPE'        // webhook event type not recognized
  | 'MALFORMED_PAYLOAD'         // webhook payload missing required fields