<?php
/**
 * Pointics Analytics Guidance Trait
 *
 * @package Aisentic\Integrations\Pointics
 */

declare(strict_types=1);

namespace Aisentic\Integrations\Pointics;

defined( 'ABSPATH' ) || exit;

/** Adds plan-aware guidance to analytics range errors without changing taxonomy fields. */
trait Pointics_Analytics_Guidance_Trait {

	/**
	 * Add free-plan range guidance to an analytics invalid-argument or validation response.
	 *
	 * @param array<string, mixed> $data Normalized Pointics response.
	 * @return array<string, mixed>
	 */
	protected function steer_analytics_error( array $data ): array {
		if ( ! $this->is_error( $data ) || ! in_array( $data['code'] ?? null, [ 'invalid_argument', 'validation' ], true ) ) {
			return $data;
		}

		$markers        = strtolower( (string) ( $data['error'] ?? '' ) . ' ' . (string) ( $data['pointics_code'] ?? '' ) );
		$is_range_error = 1 === preg_match( '/\b(?:range|pro)\b/', $markers );

		if ( ! $is_range_error ) {
			return $data;
		}

		$guidance = $this->free_range_guidance();
		if ( false === strpos( (string) $data['error'], $guidance ) ) {
			$data['error'] = trim( (string) $data['error'] . ' ' . $guidance );
		}

		return $data;
	}

	/**
	 * Build guidance from Pointics' current free-range vocabulary when available.
	 *
	 * @return string
	 */
	private function free_range_guidance(): string {
		$constant = 'Pointics\\Analytics\\Values\\Date_Window::FREE_RANGES';
		$ranges   = defined( $constant ) ? (array) constant( $constant ) : [];
		$ranges   = array_values( array_filter( $ranges, 'is_string' ) );

		if ( empty( $ranges ) ) {
			return __( 'Choose a free-plan analytics preset instead.', 'aisentic' );
		}

		$labels = array_map(
			static fn ( string $range ): string => str_replace( '_', ' ', $range ),
			$ranges
		);

		/* translators: %s: the currently accepted free-plan analytics presets. */
		return sprintf( __( 'Choose a free-plan analytics preset such as %s.', 'aisentic' ), implode( ', ', $labels ) );
	}
}