/**
 * Refund domain events — discriminated union.
 *
 *   paid | fulfilled | completed | unfulfillable | partially_refunded
 *     + refund_executed → refunded / partially_refunded
 *     effects: [set-refunded, enqueue-outbox(refund.executed_email), referral-clawback]
 *
 * Pure module: no imports from @/server/db, do-client, outbox-producer, payments, fetch.
 */

/** order.status values relevant to the refund state machine (T7 order model, lowercase). */
export type RefundPaymentState =
  | 'pending'
  | 'charging'
  | 'paid'
  | 'fulfilled'
  | 'completed'
  | 'unfulfillable'
  | 'partially_refunded'
  | 'refunded'
  | 'failed';

export type RefundEvent = {
  kind: 'refund_executed';
  purchaseId: string;
  userId: string | null;
  dealId: string;
  refundAmount: string;
  refundReasonText: string;
  at: Date;
  /** Real Stripe refund id (re_...). Convergence key shared with the T2 webhook clawback. */
  stripeRefundId: string;
  /** Fraction of the original charge being refunded (refundAmountAgorot / originalAgorot). */
  refundFraction: number;
  /** Actual agorot refunded by the provider. */
  refundAmountAgorot: number;
  /**
   * Business intent of the refund. 'full' = full cancellation (voucher closes
   * even when a statutory fee makes the refunded fraction < 1). Absent =
   * fraction-based semantics (external/webhook-settled refunds).
   */
  refundType?: 'full' | 'partial' | 'admin';
};