export interface CheckoutRequest {
  productId: string;
  resultCode: string;
  /** Absolute origin of the site, for building return URLs. */
  origin: string;
}

export interface CheckoutSession {
  /** Where to send the buyer: the provider's hosted checkout page. */
  url: string;
}

export interface CompletedPurchase {
  productId: string;
  resultCode: string;
  /** The provider's payment or session reference, for receipts and support. */
  reference: string;
}

/**
 * Every payment gateway (Stripe, Paystack, Flutterwave, Paddle, …) implements this interface.
 * The rest of the app never talks to a provider directly.
 */
export interface PaymentProvider {
  readonly name: string;
  createCheckout(request: CheckoutRequest): Promise<CheckoutSession>;
  /**
   * Called on the checkout return URL. Must confirm with the provider (server to server) that
   * the payment succeeded; never trust query parameters alone.
   */
  confirmCheckout(params: URLSearchParams): Promise<CompletedPurchase | null>;
}