<?php
defined( 'ABSPATH' ) || exit;

/**
 * Click-ID and UTM capture.
 *
 * The browser captures the advertising click identifiers and campaign
 * parameters at landing and persists them in one first-party cookie. PHP only
 * ever READS that cookie, which is what makes this work behind a full-page
 * cache: nothing is written from PHP, so a cached HTML response cannot carry a
 * stale Set-Cookie header.
 *
 * Cookie
 *   name      advisorppc_cids
 *   value     URL-encoded JSON object
 *   lifetime  90 days (matches the longest advertising click window we track)
 *   path      /
 *   SameSite  Lax          - the click always arrives as a top-level GET
 *   Secure    yes on HTTPS - set by the browser from the page protocol
 *   HttpOnly  no           - the browser writes it, so it cannot be HttpOnly.
 *                            It holds no credential and no personal data, only
 *                            the advertising identifiers already present in the
 *                            landing URL.
 *
 * Consent: when consent mode is on, the cookie is not written until
 * `ad_storage` is granted. See public/js/clickids.js.
 *
 * FOR LANE C - the accessors you need are, in order of usefulness:
 *   AdvisorPPC_ClickIDs::get_click_ids()   exact `click_ids` envelope shape
 *   AdvisorPPC_ClickIDs::get_session_id()  the envelope `session_id`
 *   AdvisorPPC_ClickIDs::get_utms()        the five utm_* parameters
 *   AdvisorPPC_ClickIDs::get_meta_cookies() _fbc / _fbp for Meta CAPI matching
 *   AdvisorPPC_ClickIDs::get_all()         everything, including landing page
 *
 * @package AdvisorPPC
 */
class AdvisorPPC_ClickIDs {

	/** Script handle. */
	const HANDLE = 'advisorppc-clickids';

	/** Cookie name. Public so lane C can reference it in documentation. */
	const COOKIE_NAME = 'advisorppc_cids';

	/** Cookie lifetime, days. */
	const COOKIE_DAYS = 90;

	/** Session idle timeout, seconds. A new session id is minted after this. */
	const SESSION_TTL = 1800;

	/** Hard cap on a stored click identifier. */
	const MAX_VALUE_LENGTH = 512;

	/** @var bool */
	private static $booted = false;

	/** @var array|null Parsed cookie, cached per request. */
	private static $cache = null;

	/**
	 * The nine advertising click identifiers, in the exact order and spelling
	 * used by the `click_ids` object of the event envelope.
	 *
	 * @return string[]
	 */
	public static function click_id_keys() {
		return array(
			'gclid',
			'gbraid',
			'wbraid',
			'fbclid',
			'msclkid',
			'ttclid',
			'li_fat_id',
			'twclid',
			'epik',
		);
	}

	/**
	 * The five campaign parameters.
	 *
	 * @return string[]
	 */
	public static function utm_keys() {
		return array(
			'utm_source',
			'utm_medium',
			'utm_campaign',
			'utm_term',
			'utm_content',
		);
	}

	/**
	 * Register hooks. Idempotent.
	 *
	 * @return void
	 */
	public static function init() {
		if ( self::$booted ) {
			return;
		}
		self::$booted = true;
		add_action( 'wp_enqueue_scripts', array( __CLASS__, 'enqueue' ), 5 );
	}

	/**
	 * Read an option without hard-depending on the options class.
	 *
	 * @param string $key     Option key.
	 * @param mixed  $default Fallback.
	 * @return mixed
	 */
	private static function opt( $key, $default = null ) {
		if ( ! class_exists( 'AdvisorPPC_Options' ) ) {
			return $default;
		}
		return AdvisorPPC_Options::get( $key, $default );
	}

	/**
	 * Is the tags module active? Click-ID capture belongs to module 1 and
	 * follows the same switch. Absent means on, so a fresh install tracks.
	 *
	 * @return bool
	 */
	public static function is_active() {
		if ( class_exists( 'AdvisorPPC_Options' ) && method_exists( 'AdvisorPPC_Options', 'module_enabled' ) ) {
			return (bool) AdvisorPPC_Options::module_enabled( 'tags' );
		}
		$modules = self::opt( 'modules', array() );
		if ( ! is_array( $modules ) || ! array_key_exists( 'tags', $modules ) ) {
			return true;
		}
		return ! empty( $modules['tags'] );
	}

	/**
	 * Should any front-end script be printed on this request?
	 *
	 * @return bool
	 */
	public static function should_load() {
		if ( is_admin() || is_feed() || is_robots() || is_preview() ) {
			return false;
		}
		if ( function_exists( 'wp_doing_ajax' ) && wp_doing_ajax() ) {
			return false;
		}
		if ( defined( 'REST_REQUEST' ) && REST_REQUEST ) {
			return false;
		}
		if ( defined( 'DOING_CRON' ) && DOING_CRON ) {
			return false;
		}
		/**
		 * Filters whether AdvisorPPC front-end scripts load on this request.
		 * Use it to exclude staff traffic, for example.
		 *
		 * @since 0.1.0
		 * @param bool $load Default true.
		 */
		return (bool) apply_filters( 'advisorppc_should_load_scripts', true );
	}

	/**
	 * Enqueue the capture script.
	 *
	 * @return void
	 */
	public static function enqueue() {
		if ( ! self::is_active() || ! self::should_load() ) {
			return;
		}

		$config = array(
			'cookie'         => self::COOKIE_NAME,
			'days'           => self::COOKIE_DAYS,
			'sessionTtl'     => self::SESSION_TTL,
			'clickIdKeys'    => self::click_id_keys(),
			'utmKeys'        => self::utm_keys(),
			'maxLength'      => self::MAX_VALUE_LENGTH,
			/* When consent mode is on, hold the cookie until ad_storage. */
			'requireConsent' => AdvisorPPC_Consent::is_enabled(),
			'consentSignal'  => 'ad_storage',
			'secure'         => is_ssl(),
			/* WordPress's own COOKIEPATH, not a hardcoded "/": on a
			 * subdirectory install a "/" cookie leaks this site's click ids
			 * to every other WordPress on the same host. */
			'path'           => self::cookie_path(),
		);

		/*
		 * With no tags or workspace and consent off, an untagged visit has no consumer
		 * for a session ID. Keep only a small browser-side check in the HTML;
		 * load capture when attribution data is present. The decision belongs
		 * in the browser so a page cache cannot hide a later visitor's click.
		 */
		$lazy   = ! AdvisorPPC_Consent::is_enabled() && empty( AdvisorPPC_Options::get_tag_ids() ) && ! AdvisorPPC_Options::is_connected();
		$handle = $lazy ? self::HANDLE . '-loader' : self::HANDLE;
		$src    = AdvisorPPC_Consent::asset_url( 'public/js/clickids.js' );

		wp_register_script(
			$handle,
			$lazy ? false : $src,
			AdvisorPPC_Consent::is_enabled() ? array( AdvisorPPC_Consent::HANDLE ) : array(),
			AdvisorPPC_Consent::asset_version(),
			// A loading strategy needs a src; WordPress rejects one on the src-less loader alias.
			$lazy ? array( 'in_footer' => false ) : array( 'strategy' => 'defer', 'in_footer' => false )
		);
		wp_enqueue_script( $handle );

		wp_add_inline_script(
			$handle,
			'window.advisorppcClickIds = ' . wp_json_encode( $config ) . ';',
			'before'
		);

		if ( $lazy ) {
			wp_add_inline_script(
				$handle,
				'(function(w,d){
					var c=w.advisorppcClickIds, q=new URLSearchParams(w.location.search);
					var landing=c.clickIdKeys.concat(c.utmKeys).some(function(k){return q.has(k);});
					var stored=d.cookie.split(";").some(function(v){return v.trim().indexOf(c.cookie+"=")===0;});
					if(!landing&&!stored){return;}
					var s=d.createElement("script");
					s.src=' . wp_json_encode( $src . '?ver=' . rawurlencode( AdvisorPPC_Consent::asset_version() ) ) . ';
					s.async=true;
					d.head.appendChild(s);
				})(window,document);'
			);
		}
	}

	/**
	 * The path the click-ID cookie is written under.
	 *
	 * WordPress's COOKIEPATH, so the cookie is scoped to this install rather
	 * than to the whole host.
	 *
	 * @return string
	 */
	public static function cookie_path() {
		$path = defined( 'COOKIEPATH' ) ? (string) COOKIEPATH : '';

		return '' !== $path ? $path : '/';
	}

	/* ------------------------------------------------------------------ */
	/* Read side. Everything below is safe to call from any lane.          */
	/* ------------------------------------------------------------------ */

	/**
	 * Parse and sanitise the cookie once per request.
	 *
	 * Values in this cookie originate from the query string of the landing
	 * page, which means they are attacker controlled. Nothing leaves this
	 * method that is not a short, character-restricted scalar.
	 *
	 * @return array
	 */
	private static function cookie() {
		if ( null !== self::$cache ) {
			return self::$cache;
		}
		self::$cache = array();

		if ( empty( $_COOKIE[ self::COOKIE_NAME ] ) ) {
			return self::$cache;
		}

		// PHP has already URL-decoded the cookie value.
		$raw = wp_unslash( $_COOKIE[ self::COOKIE_NAME ] ); // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- sanitised field by field below.
		if ( ! is_string( $raw ) || strlen( $raw ) > 8192 ) {
			return self::$cache;
		}

		$data = json_decode( $raw, true );
		if ( ! is_array( $data ) ) {
			return self::$cache;
		}

		$out = array();

		foreach ( self::click_id_keys() as $key ) {
			$value = self::sanitize_click_id( isset( $data[ $key ] ) ? $data[ $key ] : null );
			if ( null !== $value ) {
				$out[ $key ] = $value;
			}
		}

		foreach ( self::utm_keys() as $key ) {
			$value = self::sanitize_param( isset( $data[ $key ] ) ? $data[ $key ] : null, 255 );
			if ( null !== $value ) {
				$out[ $key ] = $value;
			}
		}

		$sid = self::sanitize_click_id( isset( $data['_sid'] ) ? $data['_sid'] : null );
		if ( null !== $sid ) {
			$out['_sid'] = $sid;
		}

		if ( isset( $data['_ts'] ) && is_numeric( $data['_ts'] ) ) {
			$out['_ts'] = (int) $data['_ts'];
		}
		if ( isset( $data['_sts'] ) && is_numeric( $data['_sts'] ) ) {
			$out['_sts'] = (int) $data['_sts'];
		}

		if ( ! empty( $data['_lp'] ) && is_string( $data['_lp'] ) ) {
			$url = esc_url_raw( substr( $data['_lp'], 0, 1000 ) );
			if ( $url ) {
				$out['_lp'] = $url;
			}
		}
		if ( ! empty( $data['_rf'] ) && is_string( $data['_rf'] ) ) {
			$url = esc_url_raw( substr( $data['_rf'], 0, 1000 ) );
			if ( $url ) {
				$out['_rf'] = $url;
			}
		}

		self::$cache = $out;
		return self::$cache;
	}

	/**
	 * Click identifiers are opaque tokens. Allow only the characters the
	 * platforms actually emit, and cap the length.
	 *
	 * @param mixed $value Raw value.
	 * @return string|null
	 */
	private static function sanitize_click_id( $value ) {
		if ( ! is_string( $value ) || '' === $value ) {
			return null;
		}
		$value = substr( $value, 0, self::MAX_VALUE_LENGTH );
		$value = preg_replace( '/[^A-Za-z0-9._~\-]/', '', $value );
		return ( '' === $value ) ? null : $value;
	}

	/**
	 * Campaign parameters are human readable, so they get the normal text
	 * treatment plus a length cap.
	 *
	 * @param mixed $value Raw value.
	 * @param int   $max   Maximum length.
	 * @return string|null
	 */
	private static function sanitize_param( $value, $max ) {
		if ( ! is_string( $value ) || '' === $value ) {
			return null;
		}
		$value = sanitize_text_field( substr( $value, 0, (int) $max ) );
		return ( '' === $value ) ? null : $value;
	}

	/**
	 * The `click_ids` object of the event envelope.
	 *
	 * Always returns all nine keys. A key that was never captured is null, not
	 * missing, so lane C can hand the array straight to wp_json_encode() and
	 * get the shape the contract specifies.
	 *
	 * @return array<string,string|null>
	 */
	public static function get_click_ids() {
		$cookie = self::cookie();
		$out    = array();
		foreach ( self::click_id_keys() as $key ) {
			$out[ $key ] = isset( $cookie[ $key ] ) ? $cookie[ $key ] : null;
		}
		return $out;
	}

	/**
	 * True when not a single click identifier was captured, which means this
	 * visitor did not arrive from a tracked ad click.
	 *
	 * @return bool
	 */
	public static function has_click_id() {
		foreach ( self::get_click_ids() as $value ) {
			if ( null !== $value ) {
				return true;
			}
		}
		return false;
	}

	/**
	 * The five campaign parameters, all keys always present, null when absent.
	 *
	 * @return array<string,string|null>
	 */
	public static function get_utms() {
		$cookie = self::cookie();
		$out    = array();
		foreach ( self::utm_keys() as $key ) {
			$out[ $key ] = isset( $cookie[ $key ] ) ? $cookie[ $key ] : null;
		}
		return $out;
	}

	/**
	 * The visitor's current session id, for the envelope `session_id` field.
	 *
	 * Minted in the browser, rotated after SESSION_TTL seconds of inactivity.
	 * Null when no cookie exists yet, for example on a first pageview or when
	 * consent has not been granted.
	 *
	 * @return string|null
	 */
	public static function get_session_id() {
		$cookie = self::cookie();
		return isset( $cookie['_sid'] ) ? $cookie['_sid'] : null;
	}

	/**
	 * Unix timestamp of the first pageview in this cookie's life.
	 *
	 * @return int|null
	 */
	public static function get_first_seen() {
		$cookie = self::cookie();
		return isset( $cookie['_ts'] ) ? $cookie['_ts'] : null;
	}

	/**
	 * The landing page URL and the referrer recorded on the first pageview.
	 *
	 * @return array{landing_url:string|null,referrer:string|null}
	 */
	public static function get_landing() {
		$cookie = self::cookie();
		return array(
			'landing_url' => isset( $cookie['_lp'] ) ? $cookie['_lp'] : null,
			'referrer'    => isset( $cookie['_rf'] ) ? $cookie['_rf'] : null,
		);
	}

	/**
	 * Meta's own first-party cookies, which raise CAPI match quality a long
	 * way. Written by the Meta pixel, not by us; we only read and validate.
	 *
	 * @return array{_fbc:string|null,_fbp:string|null}
	 */
	public static function get_meta_cookies() {
		$out = array(
			'_fbc' => null,
			'_fbp' => null,
		);
		foreach ( array_keys( $out ) as $name ) {
			if ( empty( $_COOKIE[ $name ] ) ) {
				continue;
			}
			$value = wp_unslash( $_COOKIE[ $name ] ); // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- validated by the pattern below.
			if ( ! is_string( $value ) || strlen( $value ) > 512 ) {
				continue;
			}
			// Meta's documented format: fb.<subdomain-index>.<creation-ms>.<payload>
			if ( preg_match( '/^fb\.[0-9]{1,2}\.[0-9]{1,20}\.[A-Za-z0-9._~\-]{1,400}$/', $value ) ) {
				$out[ $name ] = $value;
			}
		}
		return $out;
	}

	/**
	 * Everything we hold about this visitor's acquisition, in one array.
	 *
	 * Keys: the nine click ids, the five utm_*, session_id, first_seen,
	 * landing_url, referrer.
	 *
	 * @return array
	 */
	public static function get_all() {
		$landing = self::get_landing();
		return array_merge(
			self::get_click_ids(),
			self::get_utms(),
			array(
				'session_id'  => self::get_session_id(),
				'first_seen'  => self::get_first_seen(),
				'landing_url' => $landing['landing_url'],
				'referrer'    => $landing['referrer'],
			)
		);
	}
}

/*
 * Registered on lane A's documented extension point. AdvisorPPC_Plugin::run()
 * requires this file and then fires `advisorppc_loaded`, so the hook is always
 * in place before it runs.
 */
add_action( 'advisorppc_loaded', array( 'AdvisorPPC_ClickIDs', 'init' ) );