<?php declare(strict_types=1);
/**
 * @package messenger
 * @author kputyr
 * @date 20.04.2026
 */

namespace IMATHUZH\Messenger;

/**
 * An interface for a class storing channel tokens.
 */
interface TokenStorageInterface
{
    /**
     * Returns true is the provided token exists.
     * 
     * @param string $tokenId The token to check
     */
    public function tokenExists(string $tokenId): bool;

    /**
     * Attempt to delete the provided token and returns the status.
     * 
     * The false value may indicate that no token has been found or that the token
     * cannot be deleted. Use {@see self::tokenExists()} in order to determine the outcome
     * in such case.
     * 
     * @param string $tokenId The token to delete
     * @return bool true if the token has been deleted
     */
    public function deleteToken(string $tokenId): bool;

    /**
     * Loads the payload associated with the provided token.
     * 
     * @param string $tokenId The identifier of the token to load
     * @return TokenInterface The token
     * @throws \Exception if the token does not exist or is invalid
     */
    public function loadToken(string $tokenId): TokenInterface;

    /**
     * Saves the token in the store and returns its identifier.
     * 
     * @param TokenInterface $token The token to store
     * @param string $tokenId       An identifier. If empty, then a new random
     *                              indentifier is generated.
     * @return string      The identifier of the token
     */
    public function saveToken(TokenInterface $token, string $tokenId = ''): string;

}
