types.ts

/**
 * Core entities for the FreClean payment abstraction layer.
 * These mirror the entities named in FreClean's payment architecture:
 * PaymentIntent, Payment, PaymentMethod, PaymentStatus, Transaction, Refund.
 */

export type PaymentMethod = 'cash' | 'card' | 'web3';

export type PaymentStatus =
  | 'requested'
  | 'pending'
  | 'detected'
  | 'verified'
  | 'confirmed'
  | 'failed'
  | 'expired'
  | 'refunded';

export const FORWARD_STATUS_ORDER: PaymentStatus[] = [
  'requested',
  'pending',
  'detected',
  'verified',
  'confirmed',
];

export const TERMINAL_FAILURE_STATUSES: PaymentStatus[] = ['failed', 'expired', 'refunded'];

export interface Web3Details {
  network: 'celo';
  asset: string; // symbol, e.g. "USDm", must exist and be enabled in the Supported Assets Registry
  walletAddress: string;
  txHash?: string;
  confirmations?: number;
}

/** A request to pay, before any money or asset has moved. */
export interface PaymentIntent {
  id: string;
  orderId?: string;
  bookingId?: string;
  method: PaymentMethod;
  amount: number;
  currency: string; // ISO code for cash/card; USD-pegged reference value for web3
  createdAt: string;
  expiresAt?: string;
}

/** The payment record tracked through its lifecycle. */
export interface Payment {
  id: string;
  intentId: string;
  method: PaymentMethod;
  amount: number;
  currency: string;
  status: PaymentStatus;
  web3?: Web3Details;
  createdAt: string;
  updatedAt: string;
}

/** A single on-chain (or card processor) transaction backing a Payment. */
export interface Transaction {
  id: string;
  paymentId: string;
  network?: 'celo';
  reference: string; // txHash for web3, processor reference for card, receipt number for cash
  amountObserved: number;
  detectedAt: string;
  verifiedAt?: string;
}

/** A refund issued against a confirmed Payment. */
export interface Refund {
  id: string;
  paymentId: string;
  amount: number;
  reason: string;
  status: 'requested' | 'processing' | 'completed' | 'failed';
  network?: 'celo';
  txHash?: string;
  createdAt: string;
}

export function isForwardTransition(from: PaymentStatus, to: PaymentStatus): boolean {
  const fromIndex = FORWARD_STATUS_ORDER.indexOf(from);
  const toIndex = FORWARD_STATUS_ORDER.indexOf(to);
  if (fromIndex === -1 || toIndex === -1) return false;
  return toIndex === fromIndex + 1;
}

export function isTerminalFailure(status: PaymentStatus): boolean {
  return TERMINAL_FAILURE_STATUSES.includes(status);
}