<?php
/**
 * Pointics Top Customers Tool
 *
 * @package Aisentic\Integrations\Pointics
 */

declare(strict_types=1);

namespace Aisentic\Integrations\Pointics;

use Aisentic\Util\Log;
use NeuronAI\Tools\PropertyType;
use NeuronAI\Tools\ToolProperty;

defined( 'ABSPATH' ) || exit;

/** Return Pointics' top customers by a stable leaderboard metric. */
class Pointics_Get_Top_Customers_Tool extends Pointics_Base_Tool {
	use Pointics_Analytics_Guidance_Trait;

	private const METRICS = [ 'points_earned', 'points_available', 'points_lifetime' ];

	/** Constructor. */
	public function __construct() {
		parent::__construct( 'pointics-get-top-customers', __( 'Get the top Pointics customers for a requested range and stable leaderboard metric.', 'aisentic' ) );
	}

	/** Define tool properties. */
	protected function properties(): array {
		return [
			new ToolProperty( name: 'range', type: PropertyType::STRING, description: __( 'Pointics analytics range preset.', 'aisentic' ), required: true ),
			new ToolProperty( name: 'metric', type: PropertyType::STRING, description: __( 'Leaderboard metric.', 'aisentic' ), required: false, enum: self::METRICS ),
			new ToolProperty( name: 'from', type: PropertyType::STRING, description: __( 'Optional custom range start.', 'aisentic' ), required: false ),
			new ToolProperty( name: 'to', type: PropertyType::STRING, description: __( 'Optional custom range end.', 'aisentic' ), required: false ),
			new ToolProperty( name: 'limit', type: PropertyType::INTEGER, description: __( 'Maximum customers to return; values above the Pointics limit are clamped.', 'aisentic' ), required: false ),
		];
	}

	/**
	 * Retrieve and curate top customers.
	 *
	 * @param string      $range  Pointics analytics range preset.
	 * @param string      $metric Stable leaderboard metric.
	 * @param string|null $from   Optional custom range start.
	 * @param string|null $to     Optional custom range end.
	 * @param int         $limit  Maximum number of customers.
	 * @return array<string, mixed>
	 */
	public function __invoke( string $range, ?string $metric = null, ?string $from = null, ?string $to = null, ?int $limit = null ): array {
		// NeuronAI passes an explicit null for a property the model omitted, so the
		// defaults have to live here rather than in the signature.
		$metric          = $metric ?? 'points_earned';
		$limit           = $limit ?? 5;
		$requested_limit = $limit;
		$check           = $this->guard( 'manage_pointics', 'manage_options' );
		if ( $check ) {
			return $check;
		}
		$check = $this->pointics_tables_ready();
		if ( $check ) {
			return $check;
		}

		try {
			$request = new \WP_REST_Request( 'GET', '/pointics/v1/analytics/top-customers' );
			$request->set_param( 'range', $range );
			$request->set_param( 'metric', $metric );
			$request->set_param( 'limit', max( 1, min( 50, $limit ) ) );
			if ( null !== $from ) {
				$request->set_param( 'from', $from );
			}
			if ( null !== $to ) {
				$request->set_param( 'to', $to );
			}

			$controller = pointics_container()->make( \Pointics\Api\Controllers\Analytics_Controller::class );
			$data       = $this->extract_response( $controller->top_customers( $request ), __( 'Failed to retrieve Pointics top customers.', 'aisentic' ), $this->getName() );
			if ( $this->is_error( $data ) ) {
				return $this->steer_analytics_error( $data );
			}

			$result = [
				'range'  => $this->pluck( is_array( $data['range'] ?? null ) ? $data['range'] : [], [ 'preset', 'from', 'to', 'previous_from', 'previous_to', 'timezone' ] ),
				'metric' => $data['metric'] ?? $metric,
				'items'  => $this->shape_rows(
					is_array( $data['items'] ?? null ) ? $data['items'] : [],
					function ( array $item ): array {
						$shaped = $this->pluck( $item, [ 'user_id', 'name', 'email', 'avatar_url', 'points' ] );
						if ( array_key_exists( 'tier', $item ) ) {
							$shaped['tier'] = is_array( $item['tier'] ) ? $this->pluck( $item['tier'], [ 'id', 'name', 'slug' ] ) : null;
						}

						return $shaped;
					}
				),
			];
			if ( $requested_limit > 50 ) {
				/* translators: %d: maximum number of analytics records. */
				$result['note'] = sprintf( __( 'The requested limit was clamped to %d to keep the analytics result bounded.', 'aisentic' ), 50 );
			}

			return $result;
		} catch ( \Throwable $e ) {
			Log::error( 'Pointics_Get_Top_Customers_Tool error', [ 'error' => $e->getMessage() ] );
			return $this->steer(
				[
					'error'  => __( 'Failed to retrieve Pointics top customers.', 'aisentic' ),
					'code'   => 'internal',
					'status' => 500,
				]
			);
		}
	}
}