<?php
/**
 * Visitor context contract.
 *
 * @package AdPix\Analytics
 */

declare( strict_types = 1 );

namespace AdPix\Analytics\Contracts;

defined( 'ABSPATH' ) || exit;

/**
 * What the browser tracker already knows about this visitor, read from the server side.
 *
 * This is the join between the two halves of the integration: the tag records the acquisition in
 * first-party cookies, and PHP reads them back so a server-sent conversion lands on the same person
 * and the same campaign instead of arriving anonymous.
 */
interface VisitorContextInterface {

	/**
	 * The tracker's anonymous visitor id, or null when this browser has none yet.
	 *
	 * @return string|null
	 */
	public function anonymous_id(): ?string;

	/**
	 * First/last touch plus request metadata, in the shape the S2S `context` object expects.
	 *
	 * @return array<string,mixed>
	 */
	public function to_array(): array;

	/**
	 * Whether the visitor has opted out of measurement entirely.
	 *
	 * @return bool
	 */
	public function has_opted_out(): bool;

	/**
	 * Whether the visitor's consent choice permits a given category.
	 *
	 * @param string $category Consent category, e.g. `statistics`.
	 * @return bool
	 */
	public function allows( string $category ): bool;
}