<?php

namespace App\Interfaces;

use App\Models\User;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Contracts\Pagination\LengthAwarePaginator;

/**
 * User Repository Interface
 * 
 * Defines the contract for user-specific data operations.
 * Extends the base repository with user-specific methods.
 * 
 * @author David Valera Melendez <david@valera-melendez.de>
 * @since February  2025
 */
interface UserRepositoryInterface extends BaseRepositoryInterface
{
    /**
     * Find a user by email address
     *
     * @param string $email
     * @return User|null
     */
    public function findByEmail(string $email): ?User;

    /**
     * Find users by status
     *
     * @param string $status
     * @return Collection
     */
    public function findByStatus(string $status): Collection;

    /**
     * Get users who haven't logged in recently
     *
     * @param int $days
     * @return Collection
     */
    public function getInactiveUsers(int $days = 30): Collection;

    /**
     * Get users with completed profiles
     *
     * @return Collection
     */
    public function getUsersWithCompletedProfiles(): Collection;

    /**
     * Get users with incomplete profiles
     *
     * @return Collection
     */
    public function getUsersWithIncompleteProfiles(): Collection;

    /**
     * Get users subscribed to newsletter
     *
     * @return Collection
     */
    public function getNewsletterSubscribers(): Collection;

    /**
     * Search users by name or email
     *
     * @param string $query
     * @param int $limit
     * @return Collection
     */
    public function searchUsers(string $query, int $limit = 10): Collection;

    /**
     * Get user statistics
     *
     * @return array
     */
    public function getUserStatistics(): array;

    /**
     * Update user's last login information
     *
     * @param int $userId
     * @param string $ipAddress
     * @return bool
     */
    public function updateLastLogin(int $userId, string $ipAddress): bool;

    /**
     * Increment user's login attempts
     *
     * @param string $email
     * @return bool
     */
    public function incrementLoginAttempts(string $email): bool;

    /**
     * Reset user's login attempts
     *
     * @param string $email
     * @return bool
     */
    public function resetLoginAttempts(string $email): bool;

    /**
     * Lock user account
     *
     * @param string $email
     * @param int $minutes
     * @return bool
     */
    public function lockAccount(string $email, int $minutes = 15): bool;

    /**
     * Check if account is locked
     *
     * @param string $email
     * @return bool
     */
    public function isAccountLocked(string $email): bool;

    /**
     * Suspend user account
     *
     * @param int $userId
     * @param string $reason
     * @return bool
     */
    public function suspendAccount(int $userId, string $reason): bool;

    /**
     * Reactivate user account
     *
     * @param int $userId
     * @return bool
     */
    public function reactivateAccount(int $userId): bool;

    /**
     * Get users registered in date range
     *
     * @param string $startDate
     * @param string $endDate
     * @return Collection
     */
    public function getUsersRegisteredBetween(string $startDate, string $endDate): Collection;

    /**
     * Get paginated users with filters
     *
     * @param array $filters
     * @param int $perPage
     * @return LengthAwarePaginator
     */
    public function getPaginatedUsersWithFilters(array $filters = [], int $perPage = 15): LengthAwarePaginator;
}