<?php

declare(strict_types=1);

/**
 * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
 * SPDX-License-Identifier: AGPL-3.0-or-later
 */

namespace KTXF\Mail\Service;

use DateTimeImmutable;

/**
 * Mail Service OAuth Identity Interface
 * 
 * OAuth2 token-based authentication for modern mail APIs.
 * 
 * @since 2025.05.01
 */
interface IServiceIdentityOAuth extends IServiceIdentity {

    /**
     * Gets the OAuth access token
     * 
     * @since 2025.05.01
     * 
     * @return string
     */
    public function getAccessToken(): string;

    /**
     * Gets the OAuth refresh token
     * 
     * @since 2025.05.01
     * 
     * @return string|null
     */
    public function getRefreshToken(): ?string;

    /**
     * Gets the token expiration time
     * 
     * @since 2025.05.01
     * 
     * @return DateTimeImmutable|null
     */
    public function getExpiresAt(): ?DateTimeImmutable;

    /**
     * Gets the granted OAuth scopes
     * 
     * @since 2025.05.01
     * 
     * @return array<string>
     */
    public function getScopes(): array;

    /**
     * Checks if the access token has expired
     * 
     * @since 2025.05.01
     * 
     * @return bool
     */
    public function isExpired(): bool;

}