<?php

namespace App\Framework\Smartlinks\Services;

use App\Framework\Smartlinks\SmartlinkData;
use App\Framework\Smartlinks\SmartLinkToken;
use App\Framework\Smartlinks\TokenAction;
use App\Framework\Smartlinks\TokenConfig;

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

    /**
     * Validate and retrieve smartlink data
     */
    public function validate(SmartlinkToken $token): ?SmartlinkData;

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

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

    /**
     * Check if a token exists and is valid
     */
    public function exists(SmartlinkToken $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;
}
