<?php

declare(strict_types=1);

namespace App\Repositories;

use App\Models\PractitionerDocument;
use Illuminate\Support\Collection;

/**
 * Contract for PractitionerDocument repository operations.
 */
interface PractitionerDocumentRepositoryInterface
{
    /**
     * Get all practitioner documents with optional filtering.
     *
     * @param array<string, mixed> $filters
     * @return Collection<int, PractitionerDocument>
     */
    public function getAll(array $filters = []): Collection;

    /**
     * Find a practitioner document by ID.
     *
     * @param int $id
     * @return PractitionerDocument|null
     */
    public function findById(int $id): ?PractitionerDocument;

    /**
     * Get documents by practitioner ID.
     *
     * @param int $practitionerId
     * @return Collection<int, PractitionerDocument>
     */
    public function getByPractitionerId(int $practitionerId): Collection;

    /**
     * Get documents by type.
     *
     * @param string $docType
     * @return Collection<int, PractitionerDocument>
     */
    public function getByDocumentType(string $docType): Collection;

    /**
     * Get valid documents (not expired).
     *
     * @return Collection<int, PractitionerDocument>
     */
    public function getValid(): Collection;

    /**
     * Get expired documents.
     *
     * @return Collection<int, PractitionerDocument>
     */
    public function getExpired(): Collection;

    /**
     * Get documents with pagination.
     *
     * @param int $perPage
     * @return array{documents: Collection<int, PractitionerDocument>, pagination: array}
     */
    public function getPaginated(int $perPage = 10): array;

    /**
     * Get document statistics.
     *
     * @return array<string, int>
     */
    public function getStatistics(): array;
}