<?php

declare(strict_types=1);

namespace App\Services\Billing;

use App\Models\Plan;
use App\Models\User;

interface BillingServiceInterface
{
    /**
     * Create a new subscription for a user.
     *
     * @return array{subscription_id: string, status: string, client_secret?: string, approval_url?: string}
     */
    public function createSubscription(User $user, Plan $plan, ?string $paymentMethodId = null, ?string $couponCode = null, string $billingCycle = 'monthly'): array;

    /**
     * Cancel a subscription.
     */
    public function cancelSubscription(User $user, string $subscriptionId, bool $immediately = false): bool;

    /**
     * Swap a subscription to a different plan.
     *
     * @return array{subscription_id: string, status: string}
     */
    public function swapSubscription(User $user, string $subscriptionId, Plan $newPlan, string $billingCycle = 'monthly'): array;

    /**
     * Resume a cancelled subscription.
     */
    public function resumeSubscription(User $user, string $subscriptionId): bool;

    /**
     * Add a payment method for a user.
     */
    public function addPaymentMethod(User $user, string $paymentMethodId): bool;

    /**
     * Remove a payment method.
     */
    public function removePaymentMethod(User $user, string $paymentMethodId): bool;

    /**
     * Set the default payment method.
     */
    public function setDefaultPaymentMethod(User $user, string $paymentMethodId): bool;

    /**
     * Get all payment methods for a user.
     *
     * @return array<int, array{id: string, brand: string, last_four: string, exp_month: int, exp_year: int, is_default: bool}>
     */
    public function getPaymentMethods(User $user): array;

    /**
     * Get the gateway name.
     */
    public function getGateway(): string;
}
