<?php

namespace Modules\ProductCompat\Entities\Enrichment;

use App\Product;

/**
 * Contract for an enrichment data source. Providers are tried in the priority
 * order from config('productcompat.enrichment.provider_priority'); the first
 * that returns candidates wins. Mirrors the LabCore vendor-driver pattern.
 */
interface EnrichmentProvider
{
    /** Stable key: 'official' | 'trusted' | 'api' — also stored as the row `source`. */
    public function key(): string;

    /** Whether this provider is configured well enough to run. */
    public function isAvailable(): bool;

    /** Fetch candidate part numbers / device models for a product. Must not throw. */
    public function fetch(Product $product): EnrichmentResult;
}
