<?php
/**
 * Referral & Tracking Functions
 *
 * Functions for affiliate referral tracking, token management, cookie handling,
 * and affiliate attribution. This includes validating referral tokens, managing
 * affiliate links, and tracking referral sources.
 *
 * @since   3.0.0
 * @package WC_Affiliate
 */

/**
 * Get affiliate by token
 *
 * @param string $token Affiliate token.
 *
 * @return bool|WP_User Affiliate user object or false
 */
function wca_get_affiliate_user_by_token( string $token ) {
	if ( empty( $token ) ) {
		return false;
	}

	$token_type = wca_get_token_type();

	switch ( $token_type ) {
		case 'ID':
			$user = get_user_by( 'ID', $token );
			break;
		case 'slug':
			$user = get_user_by( 'slug', $token );
			break;
		case 'email':
			$user = get_user_by( 'email', $token );
			break;
		case 'login':
			$user = get_user_by( 'login', $token );
			break;
		default:
			return false;
	}

	if ( ! $user instanceof WP_User || ! wca_is_affiliate( $user->ID ) ) {
		return false;
	}

	return $user;
}

/**
 * Validate referral token from URL parameters
 *
 * Checks if a valid affiliate referral token exists in the URL parameters
 * and returns the corresponding affiliate user ID if valid.
 *
 * @since 1.0.0
 *
 * @return bool|WP_User Affiliate user ID if token is valid, false otherwise
 */
function wca_validate_referral_token() {
	$ref_key = wca_get_ref_key();
	if ( ! isset( $_GET[ $ref_key ] ) ) { // phpcs:ignore WordPress.Security.NonceVerification.Recommended
		return false;
	}

	$token = sanitize_text_field( $_GET[ $ref_key ] ); // phpcs:ignore WordPress.Security
	if ( empty( $token ) ) {
		return false;
	}

	// Check if token corresponds to valid affiliate.
	$user = wca_get_affiliate_user_by_token( $token );

	if ( ! $user instanceof WP_User ) {
		return false;
	}

	return $user;
}

/**
 * Get user by referral token from cookie
 *
 * @return bool|WP_User
 */
function wca_get_user_by_referral_token() {
	$cookie_name = wca_get_cookie_name();
	if ( ! isset( $_COOKIE[ $cookie_name ] ) ) {
		return false;
	}

	$token = sanitize_text_field( $_COOKIE[ $cookie_name ] ); // phpcs:ignore WordPress.Security
	if ( empty( $token ) ) {
		return false;
	}

	// Check if token corresponds to valid affiliate.
	$user = wca_get_affiliate_user_by_token( $token );

	if ( ! $user instanceof WP_User ) {
		return false;
	}

	return $user;
}

/**
 * Get affiliate referrals.
 *
 * Retrieves an array of user IDs who were referred by the specified user.
 *
 * @since 1.0.0
 *
 * @param int   $referrer_user_id The user ID of the referrer.
 * @param array $args             Optional arguments for pagination (limit, offset).
 *
 * @return int[] Array of user IDs who were referred by the specified user.
 */
function wca_get_affiliate_referrals( int $referrer_user_id, array $args = array() ): array {
	return \WC_Affiliate\Models\Affiliate::get_referred_affiliates( $referrer_user_id, $args );
}

/**
 * Get affiliate referrals count.
 *
 * Retrieves the total count of users who were referred by the specified user.
 *
 * @since 1.0.0
 *
 * @param int $referrer_user_id The user ID of the referrer.
 *
 * @return int Total count of referred affiliates.
 */
function wca_get_affiliate_referrals_count( int $referrer_user_id ): int {
	return \WC_Affiliate\Models\Affiliate::get_referred_affiliates_count( $referrer_user_id );
}
