<?php

/**
 * Booktics List Appointments Tool
 *
 * @package Aisentic\Integrations\Booktics
 */

declare(strict_types=1);

namespace Aisentic\Integrations\Booktics;

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

defined( 'ABSPATH' ) || exit;

/**
 * Tool to list Booktics appointments (bookings) with optional filters.
 *
 * Administrators see every appointment. Team members are always restricted to
 * the appointments assigned to them, regardless of any team_member_id filter
 * they pass — the scope is enforced server-side.
 */
class Booktics_List_Appointments_Tool extends Booktics_Base_Tool {

	/**
	 * Constructor
	 */
	public function __construct() {
		parent::__construct(
			'booktics-list-appointments',
			'List, browse, search, or filter Booktics appointments (bookings). Filter by date, status, service, team member, or customer. ' .
			'Administrators see all bookings; team members see only their own. Use booktics-get-upcoming-bookings for a quick forward-looking schedule.'
		);
	}

	/**
	 * Define tool properties
	 *
	 * @return array
	 */
	protected function properties(): array {
		return [
			new ToolProperty(
				name: 'per_page',
				type: PropertyType::NUMBER,
				description: 'Number of appointments per page. Default: 10, maximum: 50.',
				required: false
			),
			new ToolProperty(
				name: 'paged',
				type: PropertyType::NUMBER,
				description: 'Page number. Default: 1.',
				required: false
			),
			new ToolProperty(
				name: 'date_from',
				type: PropertyType::STRING,
				description: 'Only return appointments on or after this date (Y-m-d).',
				required: false
			),
			new ToolProperty(
				name: 'status',
				type: PropertyType::STRING,
				description: 'Filter by status. One of: pending, active, approved, completed, cancelled, canceled, not_now.',
				required: false
			),
			new ToolProperty(
				name: 'service_id',
				type: PropertyType::NUMBER,
				description: 'Filter to a specific service ID.',
				required: false
			),
			new ToolProperty(
				name: 'team_member_id',
				type: PropertyType::NUMBER,
				description: 'Filter to a specific team member (WP user) ID. Ignored for team members, who are always scoped to their own bookings.',
				required: false
			),
			new ToolProperty(
				name: 'customer_id',
				type: PropertyType::NUMBER,
				description: 'Filter to a specific customer (guest) ID.',
				required: false
			),
			new ToolProperty(
				name: 'search',
				type: PropertyType::STRING,
				description: 'Search across service, customer, and team-member names.',
				required: false
			),
		];
	}

	/**
	 * Execute the tool
	 *
	 * @param int|null    $per_page       Items per page.
	 * @param int|null    $paged          Page number.
	 * @param string|null $date_from      Earliest date (Y-m-d).
	 * @param string|null $status         Status filter.
	 * @param int|null    $service_id     Service filter.
	 * @param int|null    $team_member_id Team-member filter (admins only).
	 * @param int|null    $customer_id    Customer filter.
	 * @param string|null $search         Search term.
	 * @return array
	 */
	public function __invoke(
		?int $per_page = 10,
		?int $paged = 1,
		?string $date_from = null,
		?string $status = null,
		?int $service_id = null,
		?int $team_member_id = null,
		?int $customer_id = null,
		?string $search = null
	): array {
		$check = $this->guard_staff();
		if ( $check ) {
			return $check;
		}

		if ( null !== $date_from && ! $this->is_valid_date( $date_from ) ) {
			return [ 'error' => 'date_from must be in Y-m-d format.' ];
		}

		try {
			$params = [
				'per_page' => min( 50, max( 1, (int) ( $per_page ?? 10 ) ) ),
				'paged'    => max( 1, (int) ( $paged ?? 1 ) ),
			];
			if ( null !== $date_from ) {
				$params['date_from'] = $date_from;
			}
			if ( ! empty( $status ) ) {
				$params['status'] = $status;
			}
			if ( null !== $service_id ) {
				$params['service_id'] = $service_id;
			}
			if ( null !== $customer_id ) {
				$params['customer_id'] = $customer_id;
			}
			if ( ! empty( $search ) ) {
				$params['search'] = $search;
			}

			// Team members are locked to their own bookings; admins may filter freely.
			$scoped_team_member = $this->enforced_team_member_id();
			if ( null !== $scoped_team_member ) {
				$params['team_member_id'] = $scoped_team_member;
			} elseif ( null !== $team_member_id ) {
				$params['team_member_id'] = $team_member_id;
			}

			$request = new \WP_REST_Request( 'GET', '/booktics/v1/appointments' );
			$request->set_query_params( $params );

			$controller = new \Booktics\Appointment\Controllers\Appointment_Controller();
			$result     = $this->extract_response( $controller->get_items( $request ), 'Failed to retrieve appointments.' );

			if ( isset( $result['error'] ) ) {
				return $result;
			}

			// Defence-in-depth: Booktics OR-combines the team_member_id filter with
			// `search` matches, so re-scope staff to their own rows before shaping.
			if ( $this->is_staff_only() ) {
				$result['items'] = $this->filter_to_own_appointments( $result['items'] ?? [] );
				$result['total'] = count( $result['items'] );
			}

			return $this->shape_paginated( $result, fn( $appointment ) => $this->shape_appointment( $appointment ) );
		} catch ( \Throwable $e ) {
			Log::error( 'Booktics_List_Appointments_Tool error', [ 'error' => $e->getMessage() ] );

			return [ 'error' => 'Failed to retrieve appointments: ' . $e->getMessage() ];
		}
	}
}