<?php
/**
 * Tracking Event Value Object
 *
 * @package AmbassadorHub\Tracking
 */

namespace AmbassadorHub\Tracking;

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

/**
 * Immutable value object describing a single trackable event.
 *
 * Passed to every registered TrackingProviderInterface::track() call.
 * Providers map the standard fields to their platform-specific payload.
 */
final class TrackingEvent {

	/**
	 * @param string      $name        Canonical event name (e.g. 'donation_completed', 'ambassador_registered').
	 * @param string      $entity_type Domain entity type ('donation', 'campaign', 'fundraiser', 'user').
	 * @param int|null    $entity_id   Primary key of the entity, if applicable.
	 * @param array       $properties  Provider-agnostic event properties (amount, currency, fundraiser_id, …).
	 * @param string|null $client_id   GA4-compatible client_id from the _ga browser cookie, if available.
	 */
	public function __construct(
		public readonly string $name,
		public readonly string $entity_type,
		public readonly ?int $entity_id,
		public readonly array $properties = array(),
		public readonly ?string $client_id = null,
	) {}
}
