<?php
/**
 * Where the Client Monitor reads its numbers.
 *
 * @package TurtleReport
 */

namespace TurtleReport\Attention;

use TurtleReport\Profiles\Profile;

defined( 'ABSPATH' ) || exit;

/**
 * The few Google questions the checks ask. ReportData answers them through
 * the plugin's own reports and cache; tests answer them from fixtures.
 *
 * Every method throws TurtleReport\Auth\ApiException when Google fails.
 */
interface Data {

	/**
	 * Search Console rows for one dimension.
	 *
	 * @param Profile $site      Site.
	 * @param string  $dimension date|page|query.
	 * @param string  $start     Y-m-d.
	 * @param string  $end       Y-m-d.
	 * @param string  $page      Only this page (full URL), or '' for all.
	 * @return array[] Rows with keys, clicks, impressions, ctr, position.
	 */
	public function search( Profile $site, $dimension, $start, $end, $page = '' );

	/**
	 * Organic conversion counts per event.
	 *
	 * @param Profile $site  Site.
	 * @param string  $start Y-m-d.
	 * @param string  $end   Y-m-d.
	 * @return array<string,int>
	 */
	public function events( Profile $site, $start, $end );

	/**
	 * Organic conversion counts per landing page and event.
	 *
	 * @param Profile $site  Site.
	 * @param string  $start Y-m-d.
	 * @param string  $end   Y-m-d.
	 * @return array<string,array<string,int>> Path => event => count.
	 */
	public function landing_pages( Profile $site, $start, $end );

	/**
	 * Organic GA4 sessions.
	 *
	 * @param Profile $site  Site.
	 * @param string  $start Y-m-d.
	 * @param string  $end   Y-m-d.
	 * @return int
	 */
	public function sessions( Profile $site, $start, $end );
}