<?php

declare(strict_types=1);

namespace App\Administration\Domain\Repository;

use App\Administration\Domain\Exception\SessionNotFoundException;
use App\Administration\Domain\Model\RefreshToken\TokenFamilyId;
use App\Administration\Domain\Model\Session\Session;
use App\Administration\Domain\Model\User\UserId;
use DateTimeImmutable;

/**
 * Repository pour la gestion des sessions utilisateur.
 *
 * Implémentation attendue : Redis avec TTL automatique.
 *
 * @see Story 1.6 - Gestion des sessions
 */
interface SessionRepository
{
    /**
     * Sauvegarde une session.
     *
     * @param int $ttlSeconds TTL en secondes (aligné avec le refresh token)
     */
    public function save(Session $session, int $ttlSeconds): void;

    /**
     * Récupère une session par son family ID.
     *
     * @throws SessionNotFoundException si la session n'existe pas
     */
    public function getByFamilyId(TokenFamilyId $familyId): Session;

    /**
     * Recherche une session par son family ID (nullable).
     */
    public function findByFamilyId(TokenFamilyId $familyId): ?Session;

    /**
     * Récupère toutes les sessions d'un utilisateur.
     *
     * @return list<Session>
     */
    public function findAllByUserId(UserId $userId): array;

    /**
     * Supprime une session.
     */
    public function delete(TokenFamilyId $familyId): void;

    /**
     * Supprime toutes les sessions sauf celle spécifiée.
     *
     * @return list<TokenFamilyId> Les family IDs des sessions supprimées
     */
    public function deleteAllExcept(UserId $userId, TokenFamilyId $exceptFamilyId): array;

    /**
     * Met à jour le timestamp de dernière activité.
     *
     * @param int $ttlSeconds TTL restant en secondes (aligné avec le refresh token)
     */
    public function updateActivity(TokenFamilyId $familyId, DateTimeImmutable $at, int $ttlSeconds): void;
}
