<?php

namespace GriffinForms\Includes\Migration;

/**
 * Contract for competitor migration sources.
 *
 * Source adapters must discover external forms, map them into canonical
 * GriffinForms import/export `form_data`, and delegate final form creation to
 * `\GriffinForms\Includes\ImportExport\FormImport` rather than performing ad hoc
 * inserts into GriffinForms layout tables.
 */
interface MigrationSourceInterface
{
    /**
     * Stable internal key for the source.
     */
    public function getSlug(): string;

    /**
     * Human-readable source label.
     */
    public function getLabel(): string;

    /**
     * Optional source logo URL for UI surfaces.
     */
    public function getLogoUrl(): string;

    /**
     * Whether the source plugin/runtime is installed on this site.
     */
    public function isInstalled(): bool;

    /**
     * Return source forms in a UI-safe summary shape.
     *
     * Each item should follow:
     * - `source_id`   => string|int
     * - `title`       => string
     * - `field_count` => int
     *
     * @return array<int, array<string, mixed>>
     */
    public function getForms(): array;

    /**
     * Import one source form into canonical GriffinForms `form_data`.
     *
     * The returned result must carry the created GriffinForms form ID when the
     * import succeeds so later phases may continue with submission migration.
     *
     * @param string|int $source_id
     * @param array<string, mixed> $options
     */
    public function importForm($source_id, array $options = []): MigrationResult;

    /**
     * Whether submission import is supported for this source.
     */
    public function supportsSubmissions(): bool;

    /**
     * Import submissions for a previously imported source form.
     *
     * @param string|int $source_form_id
     * @param array<string, mixed> $options
     */
    public function importSubmissions($source_form_id, int $griffinforms_form_id, array $options = []): MigrationResult;
}
