<?php
/**
 * CRM Connector Interface
 *
 * Contract for customer relationship management connectors.
 *
 * @package AmbassadorHub\Connectors
 */

namespace AmbassadorHub\Connectors;

/**
 * Interface for CRM (customer relationship management) connectors.
 *
 * CRM connectors do not expose direct invocation methods. Instead, a CRM
 * registers a `sync_to_crm` action type via register_actions() so that the
 * automations engine can trigger contact/deal synchronisation as part of a rule.
 *
 * Execution flow:
 *
 *   Automation rule fires
 *     → ambh_execute_action_sync_to_crm_{connector_id} hook
 *       → CRM connector maps the context payload to CRM fields and sends it
 *
 * The action config (stored in the automation rule) contains the field mapping
 * and any CRM-specific options (e.g. deduplication strategy, target object type).
 *
 * Only one CRM connector may be active at a time. The active connector is
 * selected on the Integrations settings tab. The ConnectorRegistry enforces
 * this single-active-CRM constraint.
 */
interface CrmConnectorInterface extends ConnectorInterface {

	// The CRM registers its action types (e.g. 'sync_to_crm') via
	// register_actions() and responds to the corresponding execute hook:
	//
	//   add_action(
	//       'ambh_execute_action_sync_to_crm_' . $this->get_id(),
	//       [ $this, 'handle_sync_to_crm' ],
	//       10,
	//       2   // ( array $action_config, array $context )
	//   );

	/**
	 * Remove or anonymise the contact in the CRM when a GDPR erasure fires.
	 *
	 * @param int    $entity_id   WordPress user ID or donor table ID.
	 * @param string $entity_type 'user' (ambassador) or 'donor' (payment donor).
	 *
	 * @return void
	 */
	public static function on_erasure( int $entity_id, string $entity_type ): void;
}
