<?php
/**
 * A candidate booking slot returned by the availability engine.
 *
 * @package Bookline
 */

declare( strict_types=1 );

namespace Bookline\Domain\Availability;

use DateTimeImmutable;

/**
 * Slot presentation DTO — engine returns UTC; presentation formats locally.
 */
final class Slot {

	/**
	 * Constructor.
	 *
	 * @param DateTimeImmutable $start              Slot start UTC.
	 * @param DateTimeImmutable $end                Slot end UTC.
	 * @param int|null          $agent_id           Assigned agent id.
	 * @param int|null          $location_id        Location id.
	 * @param int               $capacity_total     Total capacity.
	 * @param int               $capacity_remaining Remaining capacity.
	 * @param bool              $is_available       Whether bookable.
	 * @param BusyReason|null   $unavailable_reason Reason when unavailable.
	 */
	public function __construct(
		private readonly DateTimeImmutable $start,
		private readonly DateTimeImmutable $end,
		private readonly ?int $agent_id,
		private readonly ?int $location_id,
		private readonly int $capacity_total,
		private readonly int $capacity_remaining,
		private readonly bool $is_available,
		private readonly ?BusyReason $unavailable_reason = null,
	) {}

	/**
	 * Slot start instant (UTC).
	 */
	public function start(): DateTimeImmutable {
		return $this->start;
	}

	/**
	 * Slot end instant (UTC).
	 */
	public function end(): DateTimeImmutable {
		return $this->end;
	}

	/**
	 * Assigned agent id, if any.
	 */
	public function agent_id(): ?int {
		return $this->agent_id;
	}

	/**
	 * Location id, if any.
	 */
	public function location_id(): ?int {
		return $this->location_id;
	}

	/**
	 * Total capacity for this start.
	 */
	public function capacity_total(): int {
		return $this->capacity_total;
	}

	/**
	 * Remaining capacity for this start.
	 */
	public function capacity_remaining(): int {
		return $this->capacity_remaining;
	}

	/**
	 * Whether the slot is bookable.
	 */
	public function is_available(): bool {
		return $this->is_available;
	}

	/**
	 * Reason when the slot is unavailable.
	 */
	public function unavailable_reason(): ?BusyReason {
		return $this->unavailable_reason;
	}

	/**
	 * Return a copy with a different agent id.
	 *
	 * @param int $agent_id Agent id.
	 */
	public function with_agent_id( int $agent_id ): self {
		return new self(
			$this->start,
			$this->end,
			$agent_id,
			$this->location_id,
			$this->capacity_total,
			$this->capacity_remaining,
			$this->is_available,
			$this->unavailable_reason
		);
	}

	/**
	 * Return a copy with updated capacity figures.
	 *
	 * @param int $total     Total capacity.
	 * @param int $remaining Remaining capacity.
	 */
	public function with_capacity( int $total, int $remaining ): self {
		return new self(
			$this->start,
			$this->end,
			$this->agent_id,
			$this->location_id,
			$total,
			$remaining,
			$remaining > 0 && $this->is_available,
			$remaining > 0 ? $this->unavailable_reason : BusyReason::Capacity
		);
	}
}