<?php
/**
 * GA4 traffic metrics an admin can choose from.
 *
 * @package TurtleReport
 */

namespace TurtleReport\Policy;

defined( 'ABSPATH' ) || exit;

/**
 * A curated list of GA4 metrics, with how to format them.
 *
 * Formats: int, pct (GA4 returns 0–1), duration (seconds), money.
 * "lower" marks metrics where a fall is good news (bounce rate).
 */
final class TrafficMetrics {

	/**
	 * All selectable metrics, keyed by GA4 API name.
	 *
	 * @return array<string,array> Items with label, format and lower.
	 */
	public static function all() {
		$metrics = array(
			'sessions'               => array( __( 'Sessions', 'turtlereport' ), 'int', false ),
			'totalUsers'             => array( __( 'Users', 'turtlereport' ), 'int', false ),
			'newUsers'               => array( __( 'New users', 'turtlereport' ), 'int', false ),
			'engagedSessions'        => array( __( 'Engaged sessions', 'turtlereport' ), 'int', false ),
			'engagementRate'         => array( __( 'Engagement rate', 'turtlereport' ), 'pct', false ),
			'bounceRate'             => array( __( 'Bounce rate', 'turtlereport' ), 'pct', true ),
			'averageSessionDuration' => array( __( 'Avg. session duration', 'turtlereport' ), 'duration', false ),
			'screenPageViews'        => array( __( 'Views', 'turtlereport' ), 'int', false ),
			'keyEvents'              => array( __( 'Key events', 'turtlereport' ), 'int', false ),
			'ecommercePurchases'     => array( __( 'Purchases', 'turtlereport' ), 'int', false ),
			'purchaseRevenue'        => array( __( 'Purchase revenue', 'turtlereport' ), 'money', false ),
		);

		/**
		 * Filters the GA4 metrics admins can add to a site's traffic section.
		 *
		 * Keys must be valid GA4 Data API metric names. Values are
		 * [ label, format (int|pct|duration|money), lower_is_better ].
		 *
		 * @param array $metrics Metrics.
		 */
		return self::normalize( apply_filters( 'turtlereport_traffic_metrics', $metrics ), $metrics );
	}

	/**
	 * Validates an extension's filter result while retaining safe defaults.
	 *
	 * @param mixed $filtered Extension-provided value.
	 * @param array $metrics Default definitions.
	 * @return array<string,array>
	 */
	private static function normalize( $filtered, array $metrics ) {
		$out = array();
		foreach ( is_array( $filtered ) ? $filtered : $metrics as $key => $def ) {
			if ( preg_match( '/^[A-Za-z][A-Za-z0-9:_]*$/', (string) $key ) && is_array( $def ) && isset( $def[0], $def[1] ) ) {
				$out[ $key ] = array(
					'label'  => (string) $def[0],
					'format' => in_array( $def[1], array( 'int', 'pct', 'duration', 'money' ), true ) ? $def[1] : 'int',
					'lower'  => ! empty( $def[2] ),
				);
			}
		}
		return $out;
	}

	/**
	 * Metrics selected for new sites.
	 *
	 * @return string[]
	 */
	public static function defaults() {
		return array( 'sessions', 'totalUsers', 'engagementRate', 'keyEvents' );
	}
}