<?php

declare(strict_types=1);

namespace App\Framework\OAuth;

use App\Framework\OAuth\ValueObjects\OAuthToken;

/**
 * OAuth Provider Interface
 *
 * Defines contract for OAuth 2.0 providers (Spotify, Tidal, Google, etc.)
 */
interface OAuthProvider
{
    /**
     * Get the provider name (e.g., 'spotify', 'tidal')
     */
    public function getName(): string;

    /**
     * Get authorization URL for OAuth flow
     *
     * @param array<string, mixed> $options Additional options (scope, state, etc.)
     */
    public function getAuthorizationUrl(array $options = []): string;

    /**
     * Exchange authorization code for access token
     */
    public function getAccessToken(string $code, ?string $state = null): OAuthToken;

    /**
     * Refresh an expired access token
     */
    public function refreshToken(OAuthToken $token): OAuthToken;

    /**
     * Revoke a token (logout)
     */
    public function revokeToken(OAuthToken $token): bool;

    /**
     * Get user profile from provider
     *
     * @return array<string, mixed>
     */
    public function getUserProfile(OAuthToken $token): array;

    /**
     * Get required scopes for this provider
     *
     * @return array<string>
     */
    public function getDefaultScopes(): array;
}
