<?php

declare(strict_types=1);

namespace App\Infrastructure\Enrichment\Downloaders;

/**
 * Provider abstraction for the refresh-geoip job.
 *
 * Three impls (DB-IP, MaxMind, IPinfo) all produce two `.mmdb` files in
 * the supplied temp dir. The job atomic-renames them onto the configured
 * `GEOIP_COUNTRY_DB` / `GEOIP_ASN_DB` paths; the lookup service never
 * sees provider details. The download path is the only thing that forks
 * per provider.
 */
interface GeoIpDownloader
{
    public function name(): string;

    public function requiresCredential(): bool;

    public function hasCredential(): bool;

    /**
     * Pull the country + ASN MMDBs into $tempDir and return the paths
     * to the verified files. May throw on network / verification error.
     *
     * @return array{country: string, asn: string}
     */
    public function download(string $tempDir): array;
}
