<?php
/**
 * Acquisition touch value object.
 *
 * @package AdPix\Analytics
 */

declare( strict_types = 1 );

namespace AdPix\Analytics\Model;

defined( 'ABSPATH' ) || exit;

/**
 * One acquisition touch — the campaign, referrer or click that brought the visitor here.
 *
 * The browser tracker stores these in first-party cookies; this class is the translation between
 * that cookie shape and the field names the S2S contract expects. The two are close but not
 * identical, and the difference is the whole value of the class: the cookie writes the touch time as
 * `ts` in milliseconds, while the collector reads `timestamp`. A touch handed over with the cookie's
 * own key names loses its time silently, which turns "converted 12 days after the ad" into
 * "converted the moment we heard about it".
 */
final class Touch {

	/**
	 * Fields carried through verbatim, in the collector's own vocabulary.
	 *
	 * @var string[]
	 */
	private const FIELDS = array(
		'source',
		'medium',
		'campaign',
		'content',
		'term',
		'channel',
		'click_id_type',
		'landing_path',
		'referrer',
	);

	/**
	 * Normalised values.
	 *
	 * @var array<string,mixed>
	 */
	private $values;

	/**
	 * @param array<string,mixed> $values Normalised values.
	 */
	private function __construct( array $values ) {
		$this->values = $values;
	}

	/**
	 * Build from a decoded tracker cookie.
	 *
	 * @param mixed $decoded Decoded `__sov_ft` / `__sov_lt` payload.
	 * @return self|null Null when the cookie held nothing describing an acquisition.
	 */
	public static function from_cookie( $decoded ): ?self {
		if ( ! is_array( $decoded ) ) {
			return null;
		}

		$values = array();
		foreach ( self::FIELDS as $field ) {
			if ( isset( $decoded[ $field ] ) && is_scalar( $decoded[ $field ] ) ) {
				$value = sanitize_text_field( (string) $decoded[ $field ] );
				if ( '' !== $value ) {
					$values[ $field ] = $value;
				}
			}
		}

		// The collector treats an empty touch as "unknown" rather than "direct", which is the honest
		// reading — so a cookie with only a timestamp in it is not a touch at all.
		if ( ! array_filter( $values ) ) {
			return null;
		}

		// `ts` (cookie, milliseconds) becomes `timestamp` (contract). The collector accepts a numeric
		// millisecond value or an RFC3339 string; milliseconds round-trip without a timezone guess.
		$ts = $decoded['ts'] ?? ( $decoded['timestamp'] ?? null );
		if ( is_numeric( $ts ) && $ts > 0 ) {
			$values['timestamp'] = (int) $ts;
		}

		return new self( $values );
	}

	/**
	 * The contract shape.
	 *
	 * @return array<string,mixed>
	 */
	public function to_array(): array {
		return $this->values;
	}
}