<?php

declare(strict_types=1);

namespace apexl\Io\modules\payment\Contract;

use apexl\Io\modules\payment\Dto\GatewayConfig;

/**
 * Identity + lifecycle for a payment gateway adapter.
 *
 * Every concrete gateway (Stripe / PayPal / GoCardless / Revolut / …)
 * implements this base interface plus one or more capability-specific
 * sub-interfaces below.
 *
 * The set of supported sub-interfaces signals what the gateway can do —
 * consuming code uses `instanceof` to gate features:
 *
 *   if ($gateway instanceof HostedCheckoutInterface) {
 *       $session = $gateway->createCheckoutSession($req);
 *   }
 *
 * A central `PaymentGatewayRegistry` (in the consuming product — Hermes,
 * TC, etc.) collects adapters via the `payments.collectGateways` hook,
 * indexed by `key()`.
 */
interface PaymentGatewayInterface
{
    /**
     * Short stable identifier — `stripe`, `paypal`, `gocardless`, `revolut`.
     * Used as a discriminator in the `payments.provider` column + everywhere
     * a gateway is referenced by string.
     */
    public function key(): string;

    /**
     * Human-readable name — `Stripe`, `PayPal`, `GoCardless`, `Revolut Business`.
     * Shown in admin pickers + invoices.
     */
    public function label(): string;

    /**
     * Initialise the gateway with config (API keys, mode, currency, etc.).
     * Implementations should be cheap-to-construct; expensive work (SDK
     * initialisation, key warming) goes in `boot()` if needed.
     */
    public function configure(GatewayConfig $config): void;

    /**
     * Whether this gateway is operating in sandbox / test mode. Affects
     * which API keys are used + which webhook endpoint the gateway sends to.
     */
    public function isTestMode(): bool;
}
