<?php
/**
 * Tracking Provider Interface
 *
 * @package AmbassadorHub\Tracking
 */

namespace AmbassadorHub\Tracking;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Contract for all analytics/tracking providers.
 *
 * Implement this interface to add a new tracking platform (e.g. Meta CAPI,
 * Squeezely, Mixpanel). Register your provider via the ambh_tracking_providers
 * filter — no other changes to core tracking code are needed.
 *
 * Example:
 *
 *   add_filter( 'ambh_tracking_providers', function( array $providers ): array {
 *       $providers[] = new MyCustomProvider();
 *       return $providers;
 *   } );
 */
interface TrackingProviderInterface {

	/**
	 * Unique provider identifier (e.g. 'ga4', 'meta_capi').
	 *
	 * @return string
	 */
	public function get_id(): string;

	/**
	 * Send tracking data for a single event.
	 *
	 * Called by TrackingDispatcher for every dispatched event.
	 * The method should be non-blocking where possible.
	 *
	 * @param TrackingEvent $event The event to track.
	 *
	 * @return void
	 */
	public function track( TrackingEvent $event ): void;

	/**
	 * Whether the provider has the minimum required configuration to operate.
	 *
	 * Return false when required credentials are missing to prevent the
	 * provider from firing (and silently failing).
	 *
	 * @return bool
	 */
	public function is_configured(): bool;
}
