<?php

namespace App\Services\QrCode\Contracts;

/**
 * Resolves an IP address to a coarse geographic location for scan
 * analytics. Implementations must fail soft — analytics should degrade
 * gracefully, never break the enrichment pipeline.
 */
interface GeoLocator
{
    /**
     * Look up geo data for the given IP address, or null if it could not
     * be resolved.
     *
     * @return array{country_code: ?string, country: ?string, region: ?string, city: ?string, latitude: ?string, longitude: ?string}|null
     */
    public function locate(string $ipAddress): ?array;
}
