<?php
/**
 * PaymentGatewayInterface
 * 
 * Interface que define o contrato para todos os adaptadores de pagamento.
 * Qualquer novo gateway deve implementar esta interface.
 * 
 * @package Payment
 */

namespace Payment;

interface PaymentGatewayInterface
{
    /**
     * Cria uma transação de pagamento
     * 
     * @param float $amount Valor da transação
     * @param array $customerData Dados do cliente (email, nome, documento)
     * @param array $items Itens da compra
     * @param string $paymentMethod Método de pagamento (pix, credit_card, boleto)
     * @return array Resposta com dados da transação
     */
    public function createTransaction(
        float $amount, 
        array $customerData, 
        array $items,
        string $paymentMethod = 'pix'
    ): array;

    /**
     * Cria um link de checkout hospedado
     * 
     * @param float $amount Valor total
     * @param array $customerData Dados do cliente
     * @param array $items Itens da compra
     * @param string $successUrl URL de redirecionamento após sucesso
     * @param string $failureUrl URL de redirecionamento após falha
     * @return array Resposta com URL do checkout
     */
    public function createCheckoutSession(
        float $amount,
        array $customerData,
        array $items,
        string $successUrl,
        string $failureUrl
    ): array;

    /**
     * Consulta o status de uma transação
     * 
     * @param string $transactionId ID da transação no gateway
     * @return array Status e detalhes da transação
     */
    public function getTransactionStatus(string $transactionId): array;

    /**
     * Consulta o status de uma assinatura
     * 
     * @param string $subscriptionId ID da assinatura no gateway
     * @return array Status e detalhes da assinatura
     */
    public function getSubscriptionStatus(string $subscriptionId): array;

    /**
     * Cancela uma assinatura
     * 
     * @param string $subscriptionId ID da assinatura
     * @return bool Sucesso ou falha
     */
    public function cancelSubscription(string $subscriptionId): bool;

    /**
     * Processa webhook do gateway
     * 
     * @param array $payload Dados recebidos do webhook
     * @param string $signature Assinatura para validação
     * @return array Dados processados do webhook
     */
    public function processWebhook(array $payload, string $signature = ''): array;

    /**
     * Retorna o nome do gateway
     * 
     * @return string
     */
    public function getName(): string;

    /**
     * Verifica se o gateway suporta determinado método de pagamento
     * 
     * @param string $method Método de pagamento
     * @return bool
     */
    public function supportsPaymentMethod(string $method): bool;
}
