<?php

declare(strict_types=1);

namespace GitContributionGraph\Service\Provider;

interface ProviderInterface
{
    /**
     * Fire the HTTP request(s) without blocking; the result is read later by
     * resolveFetch() so multiple providers' requests can be in flight at once.
     *
     * @param  ?\DateTimeImmutable $since lower bound (inclusive); defaults to 365 days ago
     * @param  ?\DateTimeImmutable $until upper bound (inclusive); defaults to now
     * @return mixed opaque handle to pass into resolveFetch()
     */
    public function startFetch(?\DateTimeImmutable $since = null, ?\DateTimeImmutable $until = null): mixed;

    /**
     * Block on the handle from startFetch() and parse it into a per-day count map.
     *
     * @param  mixed $handle the value returned by startFetch()
     * @return array<string, int> date (Y-m-d) => contribution count
     */
    public function resolveFetch(mixed $handle): array;

    /** Whether the required credentials/URL for this provider are all set. */
    public function isConfigured(): bool;

    /** Short lowercase identifier for this provider, e.g. "github". */
    public function getName(): string;

    /** Check reachability/credentials without fetching contribution data; used by the /health endpoint. */
    public function probe(): ProviderStatus;

    /** Make a lightweight authenticated request to verify the provider is reachable; throws on failure. */
    public function ping(): void;
}