<?php
/**
 * UAEL Analytics Events helper for one-time milestone tracking.
 *
 * Tracks events temporarily, sends them once via BSF Analytics,
 * then cleans up. Only a minimal dedup flag remains.
 *
 * @package UAEL
 * @since 1.44.2
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit; // Exit if accessed directly.
}

if ( ! class_exists( 'UAEL_Analytics_Events' ) ) {

	/**
	 * UAEL Analytics Events Class.
	 *
	 * @since 1.44.2
	 */
	class UAEL_Analytics_Events {

		/**
		 * Track a one-time event. Skips if already tracked or pending.
		 *
		 * @param string $event_name  Event identifier.
		 * @param string $event_value Primary value (version, mode, etc.).
		 * @param array  $properties  Additional context as key-value pairs.
		 * @since 1.44.2
		 * @return void
		 */
		public static function track( $event_name, $event_value = '', $properties = array() ) {
			// Check dedup flag — already sent in a previous cycle.
			$pushed = get_option( 'uael_usage_events_pushed', array() );
			$pushed = is_array( $pushed ) ? $pushed : array();
			if ( in_array( $event_name, $pushed, true ) ) {
				return;
			}

			// Check if already queued in current cycle.
			$pending = get_option( 'uael_usage_events_pending', array() );
			$pending = is_array( $pending ) ? $pending : array();
			if ( in_array( $event_name, array_column( $pending, 'event_name' ), true ) ) {
				return;
			}

			// Add to pending queue.
			$pending[] = array(
				'event_name'  => sanitize_text_field( $event_name ),
				'event_value' => sanitize_text_field( (string) $event_value ),
				'properties'  => ! empty( $properties ) ? $properties : new \stdClass(),
				'date'        => current_time( 'mysql' ),
			);
			update_option( 'uael_usage_events_pending', $pending, false );
		}

		/**
		 * Flush pending events: returns them for the payload, then cleans up.
		 *
		 * After this call:
		 * - uael_usage_events_pending is EMPTY (full event data deleted).
		 * - uael_usage_events_pushed has event_name strings added (minimal dedup).
		 *
		 * @since 1.44.2
		 * @return array Pending events to include in payload. Empty if none.
		 */
		public static function flush_pending() {
			$pending = get_option( 'uael_usage_events_pending', array() );
			if ( empty( $pending ) || ! is_array( $pending ) ) {
				return array();
			}

			// Add event names to dedup flag (minimal — just strings).
			$pushed = get_option( 'uael_usage_events_pushed', array() );
			$pushed = is_array( $pushed ) ? $pushed : array();
			$pushed = array_unique(
				array_merge( $pushed, array_column( $pending, 'event_name' ) )
			);
			update_option( 'uael_usage_events_pushed', $pushed, false );

			// DELETE all temporary event data.
			update_option( 'uael_usage_events_pending', array(), false );

			return $pending;
		}

		/**
		 * Check if an event has already been tracked (sent or pending).
		 *
		 * @param string $event_name Event identifier.
		 * @since 1.44.2
		 * @return bool
		 */
		public static function is_tracked( $event_name ) {
			$pushed = get_option( 'uael_usage_events_pushed', array() );
			$pushed = is_array( $pushed ) ? $pushed : array();
			if ( in_array( $event_name, $pushed, true ) ) {
				return true;
			}

			$pending = get_option( 'uael_usage_events_pending', array() );
			$pending = is_array( $pending ) ? $pending : array();
			return in_array( $event_name, array_column( $pending, 'event_name' ), true );
		}
	}
}