<?php

declare(strict_types=1);

namespace App\Framework\OAuth;

use App\Framework\OAuth\Storage\StoredOAuthToken;

/**
 * OAuth Service Interface
 *
 * Contract for OAuth token management services
 */
interface OAuthServiceInterface
{
    /**
     * Get provider by name
     */
    public function getProvider(string $name): OAuthProvider;

    /**
     * Get authorization URL for provider
     *
     * @param array<string, mixed> $options
     */
    public function getAuthorizationUrl(string $provider, array $options = []): string;

    /**
     * Handle OAuth callback and store token
     */
    public function handleCallback(
        string $userId,
        string $provider,
        string $code,
        ?string $state = null
    ): StoredOAuthToken;

    /**
     * Get token for user with automatic refresh if expired
     */
    public function getTokenForUser(string $userId, string $provider): StoredOAuthToken;

    /**
     * Refresh an expired token
     */
    public function refreshToken(StoredOAuthToken $storedToken): StoredOAuthToken;

    /**
     * Revoke token and remove from storage
     */
    public function revokeToken(string $userId, string $provider): bool;

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

    /**
     * Check if user has connected a provider
     */
    public function hasProvider(string $userId, string $provider): bool;

    /**
     * Get all providers for user
     *
     * @return array<StoredOAuthToken>
     */
    public function getUserProviders(string $userId): array;

    /**
     * Refresh all expiring tokens (background job)
     */
    public function refreshExpiringTokens(int $withinSeconds = 300): int;

    /**
     * Clean up expired tokens without refresh token (background job)
     */
    public function cleanupExpiredTokens(): int;
}
