<?php
/**
 * Marketing Automation Connector Interface
 *
 * Contract for marketing automation / email platform connectors.
 *
 * @package AmbassadorHub\Connectors
 */

namespace AmbassadorHub\Connectors;

/**
 * Interface for marketing automation connectors.
 *
 * Marketing automation connectors do not expose direct invocation methods.
 * Instead, a connector registers a `subscribe_to_list` action type via
 * register_actions() so that the automations engine can trigger list/audience
 * subscription as part of a rule.
 *
 * Execution flow:
 *
 *   Automation rule fires
 *     → ambh_execute_action_subscribe_to_list_{connector_id} hook
 *       → Marketing connector maps context data, subscribes the contact,
 *         and optionally adds them to a journey / automation workflow
 *
 * The action config (stored in the automation rule) contains the target list ID
 * and any platform-specific options (e.g. merge fields, tags, journey entry).
 *
 * Only one marketing automation connector may be active at a time. The active
 * connector is selected on the Integrations settings tab. The ConnectorRegistry
 * enforces this single-active-MA constraint.
 */
interface MarketingConnectorInterface extends ConnectorInterface {

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

	/**
	 * Unsubscribe or delete the contact in the marketing platform 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;
}
