<?php

namespace App\Services\Import\Contracts;

// PRC-707 — Kaynak-başına import driver sözleşmesi (CSV / WHMCS / Blesta).
// Her driver: (1) kaynağı analiz edip eşlenebilir alanları/örnekleri sunar,
// (2) verilen mapping + options ile satırları normalize edip PROCP entity'sine
// idempotent aktarır. Persist mantığı ImportService'te; driver yalnız
// kaynak-özel okuma + normalize sağlar.
interface ImporterInterface
{
    /** Kaynak driver anahtarı: csv | whmcs | blesta */
    public function key(): string;

    /**
     * Desteklenen hedef entity'ler → o entity için eşlenebilir alan listesi.
     *
     * @return array<string, array{required: array<string>, optional: array<string>}>
     */
    public function supportedEntities(): array;

    /**
     * Kaynağı analiz et: başlıklar/kolonlar + birkaç örnek satır (eşleme UI'ı).
     *
     * @param  array<string,mixed>  $source  csv: ['path'=>...] | db: ['host'=>...,'db'=>...]
     * @return array{headers: array<string>, sample: array<array<string,string>>, error?: string}
     */
    public function analyze(string $entity, array $source): array;

    /**
     * Kaynağı okuyup normalize edilmiş satırları döndür (lazy iterator).
     * Her satır: ['external_ref' => string, 'data' => array<string,mixed>].
     * Persist ETMEZ — ImportService idempotency + kayıt oluşturmayı üstlenir.
     *
     * @param  array<string,mixed>  $source
     * @param  array<string,?string>  $mapping  field => başlık/kolon
     * @param  array<string,mixed>  $options
     * @return iterable<array{external_ref: string, data: array<string,mixed>, error?: string}>
     */
    public function rows(string $entity, array $source, array $mapping, array $options): iterable;
}
