<?php

namespace App\Contracts;

use App\Models\ImportMap;

interface ImportMapSource
{
    /**
     * Stable string identifier for this source type (e.g. 'file', 'http_json').
     *
     * Used by the factory to resolve a configured ImportMap to its source
     * implementation, and stored on the map as data['source_type'].
     */
    public function name(): string;

    /**
     * Fetch from the source and yield rows.
     *
     * Each yielded row is an associative array keyed by source field name
     * (i.e. the value of ImportMapField::on_file). Sources are responsible
     * for parsing, deduplication, and any source-specific quirks; row
     * processing and field mapping happen in the orchestrator.
     *
     * @return iterable<array<string, mixed>>
     */
    public function fetch(ImportMap $map): iterable;
}
