<?php
/**
 * Default report definitions (spec §5). Data only.
 *
 * @package Tagsmith
 */

declare(strict_types=1);

namespace Tagsmith\Reports;

defined( 'ABSPATH' ) || exit;

/**
 * The built-in report definitions, keyed by id. Keys omitted here take the
 * defaults applied by ReportRegistry (order_by null, limit null, compare
 * false, filter null, path_filter false, page_filter false,
 * exclude_site_host null).
 *
 * Reports with 'compare' => true ask Google for the previous period in the
 * same request (a second date range, so no extra call) when the range has
 * one: overview_kpis, and the channels, devices and top_pages rows the
 * dashboard's insights compare. Their rows come back as 'rows' (current) and
 * 'compare_rows' (previous). GA4's limit counts the rows of both ranges, so a
 * compared request asks for four times the 'limit' (at least 100) and keeps
 * 'limit' current rows (see RequestBuilder).
 *
 * The exclude_site_host key names a URL dimension whose values on the
 * site's own hosts (this install's host and the GA stream's host, with or
 * without www.) are excluded (self-referrals).
 *
 * Filter shape: ['field' => name, 'value' => exact string] or
 * ['field' => name, 'empty' => true]; add 'not' => true to negate.
 */
class Definitions {

	/**
	 * The default definitions.
	 *
	 * @return array<string, array<string, mixed>>
	 */
	public static function all(): array {
		$gsc_metrics = array( 'clicks', 'impressions', 'ctr', 'position' );

		return array(
			'overview_kpis'      => array(
				'api'        => 'data',
				'dimensions' => array(),
				'metrics'    => array( 'activeUsers', 'newUsers', 'sessions', 'screenPageViews', 'engagementRate', 'averageSessionDuration', 'bounceRate' ),
				'compare'    => true,
			),
			'overview_trend'     => array(
				'api'        => 'data',
				'dimensions' => array( 'date' ),
				'metrics'    => array( 'activeUsers', 'sessions', 'screenPageViews' ),
			),
			'top_pages'          => array(
				'api'        => 'data',
				'dimensions' => array( 'pagePath', 'pageTitle' ),
				'metrics'    => array( 'screenPageViews', 'activeUsers', 'userEngagementDuration', 'bounceRate' ),
				'order_by'   => array(
					'metric' => 'screenPageViews',
					'desc'   => true,
				),
				'limit'      => 25,
				'compare'    => true,
			),
			'landing_pages'      => array(
				'api'        => 'data',
				'dimensions' => array( 'landingPage' ),
				'metrics'    => array( 'sessions', 'engagementRate' ),
				'order_by'   => array(
					'metric' => 'sessions',
					'desc'   => true,
				),
				'limit'      => 25,
			),
			'channels'           => array(
				'api'        => 'data',
				'dimensions' => array( 'sessionDefaultChannelGroup' ),
				'metrics'    => array( 'sessions', 'activeUsers', 'engagementRate' ),
				'order_by'   => array(
					'metric' => 'sessions',
					'desc'   => true,
				),
				'compare'    => true,
			),
			'sources'            => array(
				'api'        => 'data',
				'dimensions' => array( 'sessionSource', 'sessionMedium' ),
				'metrics'    => array( 'sessions', 'activeUsers' ),
				'order_by'   => array(
					'metric' => 'sessions',
					'desc'   => true,
				),
				'limit'      => 25,
			),
			'referrers'          => array(
				'api'               => 'data',
				'dimensions'        => array( 'pageReferrer' ),
				'metrics'           => array( 'screenPageViews' ),
				'order_by'          => array(
					'metric' => 'screenPageViews',
					'desc'   => true,
				),
				'limit'             => 25,
				'filter'            => array(
					'field' => 'pageReferrer',
					'empty' => true,
					'not'   => true,
				),
				'exclude_site_host' => 'pageReferrer',
			),
			'social'             => array(
				'api'        => 'data',
				'dimensions' => array( 'sessionSource' ),
				'metrics'    => array( 'sessions' ),
				'order_by'   => array(
					'metric' => 'sessions',
					'desc'   => true,
				),
				'limit'      => 25,
				'filter'     => array(
					'field' => 'sessionDefaultChannelGroup',
					'value' => 'Organic Social',
				),
			),
			'countries'          => array(
				'api'        => 'data',
				'dimensions' => array( 'country' ),
				'metrics'    => array( 'activeUsers', 'sessions' ),
				'order_by'   => array(
					'metric' => 'activeUsers',
					'desc'   => true,
				),
				'limit'      => 25,
			),
			'cities'             => array(
				'api'        => 'data',
				'dimensions' => array( 'city' ),
				'metrics'    => array( 'activeUsers' ),
				'order_by'   => array(
					'metric' => 'activeUsers',
					'desc'   => true,
				),
				'limit'      => 25,
			),
			'devices'            => array(
				'api'        => 'data',
				'dimensions' => array( 'deviceCategory' ),
				'metrics'    => array( 'activeUsers', 'sessions', 'engagementRate' ),
				'order_by'   => array(
					'metric' => 'activeUsers',
					'desc'   => true,
				),
				'compare'    => true,
			),
			'browsers'           => array(
				'api'        => 'data',
				'dimensions' => array( 'browser' ),
				'metrics'    => array( 'activeUsers' ),
				'order_by'   => array(
					'metric' => 'activeUsers',
					'desc'   => true,
				),
				'limit'      => 10,
			),
			'os'                 => array(
				'api'        => 'data',
				'dimensions' => array( 'operatingSystem' ),
				'metrics'    => array( 'activeUsers' ),
				'order_by'   => array(
					'metric' => 'activeUsers',
					'desc'   => true,
				),
				'limit'      => 10,
			),
			'realtime_total'     => array(
				'api'        => 'realtime',
				'dimensions' => array(),
				'metrics'    => array( 'activeUsers' ),
			),
			'realtime_pages'     => array(
				'api'        => 'realtime',
				'dimensions' => array( 'unifiedScreenName' ),
				'metrics'    => array( 'activeUsers' ),
				'order_by'   => array(
					'metric' => 'activeUsers',
					'desc'   => true,
				),
				'limit'      => 10,
			),
			'realtime_countries' => array(
				'api'        => 'realtime',
				'dimensions' => array( 'country' ),
				'metrics'    => array( 'activeUsers' ),
				'order_by'   => array(
					'metric' => 'activeUsers',
					'desc'   => true,
				),
				'limit'      => 10,
			),
			'realtime_devices'   => array(
				'api'        => 'realtime',
				'dimensions' => array( 'deviceCategory' ),
				'metrics'    => array( 'activeUsers' ),
				'order_by'   => array(
					'metric' => 'activeUsers',
					'desc'   => true,
				),
			),
			'post_stats'         => array(
				'api'         => 'data',
				'dimensions'  => array( 'date' ),
				'metrics'     => array( 'screenPageViews', 'activeUsers', 'userEngagementDuration' ),
				'path_filter' => true,
			),
			'post_sources'       => array(
				'api'         => 'data',
				'dimensions'  => array( 'sessionDefaultChannelGroup' ),
				'metrics'     => array( 'screenPageViews' ),
				'order_by'    => array(
					'metric' => 'screenPageViews',
					'desc'   => true,
				),
				'path_filter' => true,
			),
			'posts_column'       => array(
				'api'         => 'data',
				'dimensions'  => array( 'pagePath' ),
				'metrics'     => array( 'screenPageViews' ),
				'limit'       => 100,
				'path_filter' => true,
			),
			// Views of the pages listed by the Clarity insights: at most 100
			// of their pagePath variants per request (Insights splits them).
			'page_views'         => array(
				'api'         => 'data',
				'dimensions'  => array( 'pagePath' ),
				'metrics'     => array( 'screenPageViews' ),
				'limit'       => 100,
				'path_filter' => true,
			),
			'gsc_queries'        => array(
				'api'        => 'gsc',
				'dimensions' => array( 'query' ),
				'metrics'    => $gsc_metrics,
				'limit'      => 25,
			),
			'gsc_pages'          => array(
				'api'        => 'gsc',
				'dimensions' => array( 'page' ),
				'metrics'    => $gsc_metrics,
				'limit'      => 25,
			),
			'gsc_post_queries'   => array(
				'api'         => 'gsc',
				'dimensions'  => array( 'query' ),
				'metrics'     => $gsc_metrics,
				'limit'       => 10,
				'page_filter' => true,
			),
			// Site-wide totals (one row): gsc_queries' totals only sum its top rows.
			'gsc_totals'         => array(
				'api'        => 'gsc',
				'dimensions' => array(),
				'metrics'    => $gsc_metrics,
			),
		);
	}
}