<?php

declare(strict_types=1);

namespace Abovault\Gateway;

defined('ABSPATH') || exit;

/**
 * Provider-agnostic gateway contract. Stripe is the first implementation;
 * Mollie / GoCardless slot in behind the same interface later.
 *
 * SEPA note: charges are ASYNCHRONOUS. chargeOffSession() typically returns
 * status 'processing' — the final 'succeeded'/'failed' arrives via webhook days
 * later. The webhook (not the charge call) is the source of truth that drives
 * the dunning state machine. This is the core difference from card dunning.
 */
interface GatewayInterface
{
    public function id(): string;

    /**
     * Create a reusable SEPA mandate (Stripe: SetupIntent with sepa_debit).
     *
     * @param array<string,mixed> $ctx customer/email/iban-token/return_url …
     * @return array{ok:bool, mandate_ref?:string, client_secret?:string, error?:string}
     */
    public function createMandate(array $ctx): array;

    /**
     * Charge a stored mandate off-session for a renewal.
     *
     * @param array<string,mixed> $subscription row from abovault_subscriptions
     * @return array{status:'succeeded'|'processing'|'failed', reference?:string, reason?:string}
     */
    public function chargeOffSession(array $subscription): array;

    /**
     * @return array{ok:bool, reference?:string, error?:string}
     */
    public function refund(string $chargeRef, ?int $amountCents = null): array;
}