<?php
/**
 * Connector Interface
 *
 * Base contract that all AmbassadorHub connectors must implement.
 * Connectors are self-contained WordPress plugins that integrate
 * external services (PSPs, CRMs, marketing automation tools) with
 * the AmbassadorHub ecosystem via the ConnectorRegistry.
 *
 * @package AmbassadorHub\Connectors
 */

namespace AmbassadorHub\Connectors;

/**
 * Base interface for all AmbassadorHub connectors.
 *
 * Connectors self-register with the ConnectorRegistry on `plugins_loaded`.
 * They plug into the ambassador-core automations engine by registering
 * triggers (ambh_automation_triggers) and action types (ambh_automation_actions).
 * The automations engine calls them back via ambh_execute_action_{type} when
 * a rule fires.
 */
interface ConnectorInterface {

	/**
	 * Initialize the connector module.
	 *
	 * Called from Plugin::load_components() after the ConnectorRegistry
	 * singleton is available (post ambh_loaded).
	 *
	 * @return void
	 */
	public static function register(): void;

	/**
	 * Callback fired when the connector is registered with the ConnectorRegistry.
	 *
	 * Called once during connector initialisation, after init_settings() and after
	 * the connector is added to the registry. Implementations can use this to perform
	 * any setup that requires the connector to be registered (e.g. registering REST routes,
	 * which should be done on the ambh_register_rest_routes action).
	 *
	 * @return void
	 */
	public static function on_registration(): void;

	/**
	 * Whether this connector is available for use.
	 *
	 * Returns true only when the connector is fully configured and (if applicable)
	 * licensed / authenticated. The registry and the settings UI rely on this to
	 * determine which connectors are operational.
	 *
	 * @return bool
	 */
	public static function is_available(): bool;

	/**
	 * Machine-readable connector ID.
	 *
	 * Must be unique across all registered connectors. Used as a slug in
	 * filter hook names (e.g. ambh_execute_action_sync_to_crm_{id}) and
	 * as the registry key.
	 *
	 * Examples: 'mollie', 'hubspot', 'mailchimp', 'campaignsuite'
	 *
	 * @return string
	 */
	public static function get_id(): string;

	/**
	 * Human-readable connector label for settings UI and logging.
	 *
	 * Examples: 'Mollie', 'HubSpot', 'Mailchimp', 'CampaignSuite'
	 *
	 * @return string
	 */
	public static function get_label(): string;

	/**
	 * Absolute URL to the connector's logo image, or an empty string.
	 *
	 * When a non-empty URL is returned it is displayed in the PSP settings
	 * table. When empty the UI falls back to a coloured square showing the
	 * first letter of the connector label.
	 *
	 * @return string
	 */
	public static function get_logo(): string;

	/**
	 * Short human-readable description of the connector for the settings UI.
	 *
	 * Return an empty string if no description is needed.
	 *
	 * @return string
	 */
	public static function get_description(): string;

	/**
	 * Connector type slug.
	 *
	 * Determines the registry slot this connector occupies. Recognised values:
	 * - 'psp'                  — payment service provider
	 * - 'crm'                  — customer relationship management
	 * - 'marketing_automation' — email / marketing automation
	 *
	 * @return string
	 */
	public static function get_type(): string;

	/**
	 * Register the settings for the connector.
	 *
	 * @return void
	 */
	public static function register_settings(): void;

	/**
	 * Register the settings section for this connector on the Integrations admin tab.
	 *
	 * @param array<int, array{connector_id: string, label: string, description?: string, render: callable}> $sections
	 * @return array<int, array{connector_id: string, label: string, description?: string, render: callable}>
	 */
	public static function register_settings_section( array $sections ): array;

	/**
	 * Settings fields definition for the Integrations admin tab.
	 *
	 * Returns an array of field descriptors compatible with the ambassador-core
	 * settings renderer. Each descriptor is an associative array with at minimum:
	 * - 'id'    string  Option key (stored in wp_options)
	 * - 'type'  string  Field type: 'text', 'password', 'select', 'checkbox', …
	 * - 'label' string  Human-readable field label
	 *
	 * Return an empty array if the connector has no configurable settings.
	 *
	 * @return array<int, array<string, mixed>>
	 */
	public static function get_settings_fields(): array;

	/**
	 * Called during a GDPR personal-data erasure for a user or donor.
	 *
	 * Connectors that maintain a contact record in an external system (CRM,
	 * marketing automation, etc.) must override this to delete or anonymise
	 * the record there. The default no-op implementation in AbstractConnector
	 * is sufficient for PSP connectors that hold no contact state externally.
	 *
	 * @param int    $entity_id   WordPress user ID (for ambassadors) or donor ID.
	 * @param string $entity_type 'user' for ambassadors, 'donor' for payment donors.
	 *
	 * @return void
	 */
	public static function on_erasure( int $entity_id, string $entity_type ): void;
}
