<?php

declare(strict_types=1);

namespace apexl\Io\modules\payment\Contract;

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

/**
 * Gateway supports tokenised payment methods bound to a customer ref.
 *
 * The gateway holds the actual sensitive data (PAN, etc.) — we only ever
 * see + store tokens + brand/last-4/expiry metadata. Required for any
 * recurring-billing setup that needs to re-charge an existing customer
 * without re-prompting for card details.
 */
interface PaymentMethodGatewayInterface
{
    /**
     * List saved payment methods for a customer.
     *
     * @return PaymentMethodDescriptor[]
     */
    public function listPaymentMethods(string $gatewayCustomerRef): array;

    /**
     * Attach a payment method (already-tokenised via the gateway's
     * client-side tokenisation flow) to a customer.
     */
    public function attachPaymentMethod(
        string $gatewayCustomerRef,
        string $gatewayPaymentMethodRef,
    ): PaymentMethodDescriptor;

    /**
     * Detach (delete-or-deactivate) a payment method from a customer.
     */
    public function detachPaymentMethod(string $gatewayPaymentMethodRef): void;

    /**
     * Mark a payment method as the customer's default for future charges.
     */
    public function setDefaultPaymentMethod(
        string $gatewayCustomerRef,
        string $gatewayPaymentMethodRef,
    ): void;
}
