<?php
/**
 * UTM Detector — Traffic Source Detection & Labeling
 *
 * Analyses URL parameters (UTMs and platform click IDs) to determine
 * the traffic source and builds a human-readable label.
 *
 * @package TrueConversion
 */

// Prevent direct file access.
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

/**
 * Class FTCON_Detector
 *
 * Handles all traffic source detection logic.
 * All methods are static — this class holds no state.
 */
class FTCON_Detector {

    /**
     * Platform Click ID Mapping
     *
     * @var array<string, string>
     */
    private static $click_id_map = array(
        'gclid'    => 'Google Ads',
        'fbclid'   => 'Meta Ads',
        'li_fat_id' => 'LinkedIn Ads',
        'msclkid'  => 'Microsoft Ads',
        'ttclid'   => 'TikTok Ads',
        'epik'     => 'Pinterest Ads',
        'qclid'    => 'Quora Ads',
        'scclid'   => 'Snapchat Ads',
        'aclk'     => 'Amazon Ads',
    );

    /**
     * UTM Source to Platform Mapping
     *
     * @var array<string, string>
     */
    private static $utm_source_map = array(
        'google'    => 'Google Ads',
        'facebook'  => 'Meta Ads',
        'instagram' => 'Meta Ads',
        'fb'        => 'Meta Ads',
        'ig'        => 'Meta Ads',
        'linkedin'  => 'LinkedIn Ads',
        'bing'      => 'Microsoft Ads',
        'tiktok'    => 'TikTok Ads',
        'pinterest' => 'Pinterest Ads',
        'reddit'    => 'Reddit Ads',
        'quora'     => 'Quora Ads',
        'snapchat'  => 'Snapchat Ads',
        'amazon'    => 'Amazon Ads',
    );

    /**
     * Known Organic Search Engine Domains
     *
     * @var array<string, string>
     */
    private static $organic_referrers = array(
        'google'     => 'Google',
        'bing'       => 'Bing',
        'yahoo'      => 'Yahoo',
        'duckduckgo' => 'DuckDuckGo',
        'baidu'      => 'Baidu',
        'yandex'     => 'Yandex',
    );

    /**
     * Detect Traffic Source
     *
     * @param array $params All available tracking data.
     *
     * @return array Detection result with traffic_source, platform, click_id, click_id_type.
     */
    public static function detect_source( $params ) {
        $params = self::sanitize_params( $params );

        $result = array(
            'traffic_source' => 'Direct',
            'platform'       => 'Direct',
            'click_id'       => '',
            'click_id_type'  => '',
        );

        // Step 1: Check for platform click IDs (most reliable).
        foreach ( self::$click_id_map as $param_name => $platform ) {
            if ( ! empty( $params[ $param_name ] ) ) {
                $result['platform']      = $platform;
                $result['click_id']      = $params[ $param_name ];
                $result['click_id_type'] = $param_name;
                break;
            }
        }

        // Step 2: If no click ID, check utm_source.
        if ( 'Direct' === $result['platform'] && ! empty( $params['utm_source'] ) ) {
            $source_lower = strtolower( $params['utm_source'] );

            if ( isset( self::$utm_source_map[ $source_lower ] ) ) {
                $result['platform'] = self::$utm_source_map[ $source_lower ];
            } else {
                $result['platform'] = 'Referral';
            }
        }

        // Step 3: If still Direct, check HTTP referrer.
        if ( 'Direct' === $result['platform'] && ! empty( $params['referrer'] ) ) {
            $referrer_host = wp_parse_url( $params['referrer'], PHP_URL_HOST );

            if ( $referrer_host ) {
                $referrer_host = strtolower( $referrer_host );

                foreach ( self::$organic_referrers as $keyword => $engine_name ) {
                    if ( false !== strpos( $referrer_host, $keyword ) ) {
                        $result['platform']       = 'Organic';
                        $result['traffic_source'] = 'Organic - ' . $engine_name;
                        break;
                    }
                }

                if ( 'Direct' === $result['platform'] ) {
                    $result['platform']       = 'Referral';
                    $result['traffic_source'] = 'Referral - ' . $referrer_host;
                }
            }
        }

        // Step 4: Build the full traffic source label.
        if ( 'Direct' === $result['traffic_source'] || 'Referral' !== $result['platform'] ) {
            $result['traffic_source'] = self::build_label( $result['platform'], $params );
        }

        return $result;
    }

    /**
     * Build Human-Readable Label
     *
     * @param string $platform The detected platform name.
     * @param array  $params   All available tracking parameters.
     *
     * @return string The formatted label.
     */
    private static function build_label( $platform, $params ) {
        $label   = $platform;
        $details = array();

        if ( ! empty( $params['utm_source'] ) ) {
            $details[] = 'Source: ' . $params['utm_source'];
        }
        if ( ! empty( $params['utm_medium'] ) ) {
            $details[] = 'Medium: ' . $params['utm_medium'];
        }
        if ( ! empty( $params['utm_campaign'] ) ) {
            $details[] = 'Campaign: ' . $params['utm_campaign'];
        }
        if ( ! empty( $params['utm_term'] ) ) {
            $details[] = 'Term: ' . $params['utm_term'];
        }
        if ( ! empty( $params['utm_content'] ) ) {
            $details[] = 'Content: ' . $params['utm_content'];
        }

        if ( ! empty( $details ) ) {
            $label .= ' - ' . implode( ', ', $details );
        }

        return $label;
    }

    /**
     * Sanitize Parameters
     *
     * @param array $params Raw parameters from URL/cookies.
     *
     * @return array Sanitized parameters.
     */
    private static function sanitize_params( $params ) {
        $sanitized = array();

        foreach ( $params as $key => $value ) {
            $key = sanitize_text_field( $key );

            if ( 'referrer' === $key || 'landing_page' === $key || 'page_url' === $key ) {
                $sanitized[ $key ] = esc_url_raw( $value );
            } else {
                $sanitized[ $key ] = sanitize_text_field( $value );
            }
        }

        return $sanitized;
    }

    /**
     * Get Supported Platforms
     *
     * @return array<string> List of platform names.
     */
    public static function get_supported_platforms() {
        return array(
            'Google Ads',
            'Meta Ads',
            'LinkedIn Ads',
            'Microsoft Ads',
            'TikTok Ads',
            'Pinterest Ads',
            'Reddit Ads',
            'Quora Ads',
            'Snapchat Ads',
            'Amazon Ads',
            'Organic',
            'Referral',
            'Direct',
        );
    }

    /**
     * Get Click ID Types
     *
     * @return array<string, string> Parameter name => Platform name.
     */
    public static function get_click_id_map() {
        return self::$click_id_map;
    }
}