<?php
/**
 * The form-plugin adapter contract.
 *
 * @package RewindBrevoFormBridge
 */

namespace RewindBrevoFormBridge\Adapters;

defined( 'ABSPATH' ) || exit;

/**
 * Every form-plugin integration implements exactly this. Nothing outside
 * Adapters/ may know which form plugin is in play.
 *
 * @since 0.3.0
 */
interface Adapter {

	/**
	 * Machine slug, e.g. 'forminator'.
	 *
	 * @since 0.3.0
	 * @return string
	 */
	public function slug(): string;

	/**
	 * Human label, e.g. 'Forminator'.
	 *
	 * @since 0.3.0
	 * @return string
	 */
	public function label(): string;

	/**
	 * Whether the target form plugin is active and at a supported version.
	 *
	 * @since 0.3.0
	 * @return bool
	 */
	public function is_available(): bool;

	/**
	 * All forms the target plugin knows about.
	 *
	 * @since 0.3.0
	 * @return array [ ['id' => string, 'title' => string], ... ]
	 */
	public function get_forms(): array;

	/**
	 * The mappable fields of one form, in OUR type vocabulary:
	 * text, email, number, date, phone, checkbox, select, multiselect,
	 * textarea, name, address, file. Composite fields (name, address) are
	 * flattened into sub-keys like "name-1.first-name".
	 *
	 * @since 0.3.0
	 * @param string $form_id Form id as a string.
	 * @return array [ ['key' => string, 'label' => string, 'type' => string], ... ]
	 */
	public function get_fields( string $form_id ): array;

	/**
	 * Attach to the form plugin's submission hook(s).
	 *
	 * @since 0.3.0
	 * @return void
	 */
	public function register_hooks(): void;

	/**
	 * Turn the plugin's raw submission payload into our value object.
	 *
	 * @since 0.3.0
	 * @param mixed $raw Whatever the form plugin hands its hook.
	 * @return Submission|null Null when the payload cannot be normalised.
	 */
	public function normalize_submission( $raw ): ?Submission;
}
