<?php
/**
 * Pointics Top Rules 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 earn rules. */
class Pointics_Get_Top_Rules_Tool extends Pointics_Base_Tool {
	use Pointics_Analytics_Guidance_Trait;

	/** Constructor. */
	public function __construct() {
		parent::__construct( 'pointics-get-top-rules', __( 'Get the Pointics rules that issued the most points for a requested analytics range.', '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: '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 rules to return; values above the Pointics limit are clamped.', 'aisentic' ), required: false ),
		];
	}

	/**
	 * Retrieve and curate top rules.
	 *
	 * @param string      $range Pointics analytics range preset.
	 * @param string|null $from  Optional custom range start.
	 * @param string|null $to    Optional custom range end.
	 * @param int         $limit Maximum number of rules.
	 * @return array<string, mixed>
	 */
	public function __invoke( string $range, ?string $from = null, ?string $to = null, ?int $limit = null ): array {
		// NeuronAI passes an explicit null for a property the model omitted, so the
		// default has to live here rather than in the signature.
		$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-rules' );
			$request->set_param( 'range', $range );
			$request->set_param( 'limit', max( 1, min( 20, $limit ) ) );
			$this->set_dates( $request, $from, $to );

			$controller = pointics_container()->make( \Pointics\Api\Controllers\Analytics_Controller::class );
			$data       = $this->extract_response( $controller->top_rules( $request ), __( 'Failed to retrieve Pointics top rules.', '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' ] ),
				'max_points'   => $data['max_points'] ?? 0,
				'total_points' => $data['total_points'] ?? 0,
				'items'        => $this->shape_rows(
					is_array( $data['items'] ?? null ) ? $data['items'] : [],
					fn ( array $item ): array => $this->pluck( $item, [ 'channel_id', 'name', 'slug', 'points', 'share', 'deleted' ] )
				),
			];
			if ( $requested_limit > 20 ) {
				/* translators: %d: maximum number of analytics records. */
				$result['note'] = sprintf( __( 'The requested limit was clamped to %d to keep the analytics result bounded.', 'aisentic' ), 20 );
			}

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

	/**
	 * Set optional custom range boundaries on a request.
	 *
	 * @param \WP_REST_Request $request Analytics request.
	 * @param string|null      $from    Optional custom range start.
	 * @param string|null      $to      Optional custom range end.
	 * @return void
	 */
	protected function set_dates( \WP_REST_Request $request, ?string $from, ?string $to ): void {
		if ( null !== $from ) {
			$request->set_param( 'from', $from );
		}
		if ( null !== $to ) {
			$request->set_param( 'to', $to );
		}
	}
}