<?php

namespace App\Contracts;

/**
 * Interface PaymentGatewayInterface
 *
 * Defines the standard contract for any payment gateway (Stripe, ACH, etc.),
 * abstracting customer creation, payment handling, and fund transfers.
 */
interface PaymentGatewayInterface
{
    // === Customer Setup ===

    /**
     * Create a new customer in the payment provider system.
     *
     * @param array $data Customer details (name, email, etc.)
     * @return string Provider-assigned customer ID
     */
    public function createCustomer(array $data): string;

    /**
     * Retrieve a customer object from the provider.
     *
     * This may include default payment method info or metadata.
     *
     * @param string $customerId
     * @return array
     */
    public function retrieveCustomer(string $customerId): array;

    // === Payment Methods ===

    /**
     * Change or set the default payment method.
     *
     * @param string $customerId
     * @param string $newPaymentMethodId
     * @return bool;
     */
     public function changePaymentMethod(string $customerId, string $newPaymentMethodId): bool;


    /**
     * Retrieve full details about a payment method.
     *
     * Must include properties like fingerprint, last4, brand, etc.
     *
     * @param string $paymentMethodId
     * @return array
     */
    public function getRawPaymentMethod(string $paymentMethodId): array;

    // === Payments ===

    /**
     * Create a payment intent/charge from customer to platform.
     *
     * @param array $data See: amount, currency, customer_id, etc.
     * @return array Provider-specific response (e.g., ID, status)
     */
    public function createPaymentIntent(array $data): array;

    // === Transfers & Payouts ===

    /**
     * Transfer funds to a connected account (contractor).
     *
     * @param array $data See: amount, destination_account_id, metadata, etc.
     * @return array Provider-specific response (e.g., ID, amount, destination)
     */
    public function transferToConnectedAccount(array $data): array;

    /**
     * Payout funds to recipient’s bank account.
     *
     * @param string $accountId
     * @param int $amount
     * @return void
     */
    public function createPayout(string $accountId, int $amount): void;

    /**
     * Create a SetupIntent for future off-session payments.
     *
     * @param string $customerId
     * @return array
     */
    public function createSetupIntent(string $customerId): array;

}