namespace GoodBooks.PAY.PAYBLL.Abstractions
{
    /// <summary>
    /// Contract all payment gateway implementations must fulfill.
    /// Vendor payout and transaction status query are Phase 2 features — all implementations
    /// currently throw NotImplementedException for InitiatePayoutAsync.
    /// </summary>
    public interface IPaymentGateway
    {
        string GatewayCode { get; }

        Task<GatewayOrderResult>       CreateOrderAsync(CreateGatewayOrderRequest req, CancellationToken ct);
        Task<GatewayVerifyResult>      VerifyPaymentAsync(VerifyPaymentRequest req, CancellationToken ct);
        Task<GatewayPayoutResult>      InitiatePayoutAsync(PayoutRequest req, CancellationToken ct);
        Task<GatewayWebhookEvent?>     ParseAndVerifyWebhookAsync(string rawPayload, string sigHeader, string webhookSecret, CancellationToken ct);
        Task<GatewayTransactionStatus> GetTransactionStatusAsync(string gatewayTxnId, CancellationToken ct);
    }

    /// <summary>Result returned after creating an order/payment-intent on the gateway.</summary>
    public record GatewayOrderResult(
        bool    Success,
        string  GatewayOrderId,
        string? CheckoutUrl,
        string? ErrorMessage);

    /// <summary>Result returned after verifying a completed payment.</summary>
    public record GatewayVerifyResult(
        bool    Success,
        string  Status,
        string  GatewayTransactionId,
        decimal AmountPaid,
        string? ErrorMessage);

    /// <summary>Result returned after initiating a vendor payout (Phase 2).</summary>
    public record GatewayPayoutResult(
        bool    Success,
        string  PayoutId,
        string? ErrorMessage);

    /// <summary>Parsed and signature-verified webhook event from a gateway.</summary>
    public record GatewayWebhookEvent(
        string  IdempotencyKey,
        string  EventType,
        string  GatewayOrderId,
        string  GatewayTxnId,
        string  Status,
        decimal Amount);

    /// <summary>Live transaction status fetched from the gateway.</summary>
    public record GatewayTransactionStatus(
        string    Status,
        decimal   Amount,
        string?   PaymentMethod,
        DateTime? PaidAt);

    // ── Request records ──────────────────────────────────────────────────────────

    /// <summary>
    /// All data required to create a gateway order / payment-intent.
    /// ApiKey and ApiSecret are pre-fetched from Vault by BLL before calling the gateway —
    /// gateways are pure HTTP adapters with no infrastructure dependencies.
    /// </summary>
    public record CreateGatewayOrderRequest(
        int     PayOrderId,
        string  PayOrderNo,
        decimal Amount,
        string  Currency,
        string  CustomerEmail,
        string  CustomerPhone,
        string  CallbackUrl,
        string  ApiKey,
        string  ApiSecret);

    /// <summary>
    /// Data required to verify a payment against the gateway.
    /// ApiKey and ApiSecret are pre-fetched from Vault by BLL.
    /// </summary>
    public record VerifyPaymentRequest(
        string GatewayOrderId,
        string GatewayTransactionId,
        string ApiKey,
        string ApiSecret);

    /// <summary>
    /// Data required to initiate a vendor payout (Phase 2).
    /// ApiKey and ApiSecret are pre-fetched from Vault by BLL.
    /// </summary>
    public record PayoutRequest(
        string  RecipientAccount,
        string  RecipientIfsc,
        decimal Amount,
        string  Reference,
        string  ApiKey,
        string  ApiSecret);
}