<?php

declare(strict_types=1);

namespace App\Framework\OAuth\Storage;

use App\Framework\OAuth\ValueObjects\OAuthToken;

/**
 * OAuth Token Repository Interface
 *
 * Defines contract for OAuth token persistence
 */
interface OAuthTokenRepositoryInterface
{
    /**
     * Find token for user and provider
     */
    public function findForUser(string $userId, string $provider): ?StoredOAuthToken;

    /**
     * Find token by ID
     */
    public function findById(int $id): ?StoredOAuthToken;

    /**
     * Save or update token
     */
    public function save(StoredOAuthToken $storedToken): StoredOAuthToken;

    /**
     * Save token for user (upsert by user_id + provider)
     */
    public function saveForUser(
        string $userId,
        string $provider,
        OAuthToken $token
    ): StoredOAuthToken;

    /**
     * Delete token for user and provider
     */
    public function deleteForUser(string $userId, string $provider): bool;

    /**
     * Delete expired tokens without refresh token (cleanup job)
     *
     * @return int Number of deleted tokens
     */
    public function deleteExpiredWithoutRefreshToken(): int;

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

    /**
     * Get all tokens expiring soon (for refresh worker)
     *
     * @param int $withinSeconds Tokens expiring within this many seconds
     * @return array<StoredOAuthToken>
     */
    public function findExpiringSoon(int $withinSeconds = 300): array;
}
