<?php

declare(strict_types=1);

namespace App\Framework\MagicLinks\Services;

use App\Framework\MagicLinks\MagicLinkData;
use App\Framework\MagicLinks\MagicLinkToken;
use App\Framework\MagicLinks\TokenAction;
use App\Framework\MagicLinks\TokenConfig;

interface MagicLinkService
{
    /**
     * Generate a new magiclink token
     */
    public function generate(
        TokenAction $action,
        array $payload,
        ?TokenConfig $config = null,
        ?string $createdByIp = null,
        ?string $userAgent = null
    ): MagicLinkToken;

    /**
     * Validate and retrieve magiclink data
     */
    public function validate(MagicLinkToken $token): ?MagicLinkData;

    /**
     * Mark a token as used (for one-time use tokens)
     */
    public function markAsUsed(MagicLinkToken $token): void;

    /**
     * Revoke/invalidate a token
     */
    public function revoke(MagicLinkToken $token): void;

    /**
     * Check if a token exists and is valid
     */
    public function exists(MagicLinkToken $token): bool;

    /**
     * Get all active tokens for debugging/admin purposes
     */
    public function getActiveTokens(int $limit = 100): array;

    /**
     * Clean up expired tokens
     */
    public function cleanupExpired(): int;
}
