* * @since 0.1.0 */ public function find_busy_intervals_for_agent( int $agent_id, DateTimeImmutable $from_utc, DateTimeImmutable $to_utc ): array; /** * Busy intervals for a location over a UTC range (location_window index). * * @param int $location_id Location id. * @param DateTimeImmutable $from_utc Range start. * @param DateTimeImmutable $to_utc Range end. * @return list * * @since 0.1.0 */ public function find_busy_intervals_for_location( int $location_id, DateTimeImmutable $from_utc, DateTimeImmutable $to_utc ): array; /** * Capacity used per slot start for a group service (service_window index). * * @param int $service_id Service id. * @param DateTimeImmutable $from_utc Range start. * @param DateTimeImmutable $to_utc Range end. * @return list * * @since 0.1.0 */ public function find_capacity_used_per_slot( int $service_id, DateTimeImmutable $from_utc, DateTimeImmutable $to_utc ): array; /** * Upcoming bookings for a customer (customer index). * * @param int $customer_id Customer id. * @param DateTimeImmutable $from_utc From instant. * @param int $limit Max rows. * @return list * * @since 0.1.0 */ public function find_upcoming_for_customer( int $customer_id, DateTimeImmutable $from_utc, int $limit = 50 ): array; /** * Booking history for a customer (includes cancelled; excludes rescheduled and deleted). * * @param int $customer_id Customer id. * @param int $limit Max rows, newest first. * @return list * * @since 0.1.0 */ public function find_history_for_customer( int $customer_id, int $limit = 100 ): array; /** * Booking counts and earliest start per customer (excludes rescheduled and deleted). * * @param list $customer_ids Customer ids. * @return array * * @since 0.1.0 */ public function summarise_for_customers( array $customer_ids ): array; /** * Bookings needing reminders in a window (status_start index). * * @param DateTimeImmutable $from_utc Window start. * @param DateTimeImmutable $to_utc Window end. * @return list * * @since 0.1.0 */ public function find_needing_reminders( DateTimeImmutable $from_utc, DateTimeImmutable $to_utc ): array; /** * Admin calendar week across agents (status_start + optional agent filter). * * @param DateTimeImmutable $from_utc Week start UTC. * @param DateTimeImmutable $to_utc Week end UTC. * @param list|null $agent_ids Optional agent filter. * @return list * * @since 0.1.0 */ public function find_for_admin_calendar( DateTimeImmutable $from_utc, DateTimeImmutable $to_utc, ?array $agent_ids = null ): array; /** * Lock an agent row for update (serialises slot claims for that agent). * * @param int $agent_id Agent id. * * @since 0.1.0 */ public function lock_agent_for_update( int $agent_id ): void; /** * Lock overlapping occupying bookings for an agent (SELECT … FOR UPDATE). * * Must be called inside an open transaction. * * @param int $agent_id Agent id. * @param DateTimeImmutable $buffer_start_utc New buffer start. * @param DateTimeImmutable $buffer_end_utc New buffer end. * @param int|null $exclude_booking_id Optional booking to exclude. * @return list * * @since 0.1.0 */ public function lock_overlapping_for_agent( int $agent_id, DateTimeImmutable $buffer_start_utc, DateTimeImmutable $buffer_end_utc, ?int $exclude_booking_id = null, ): array; /** * Pending soft holds whose hold_expires_at is at or before $now. * * @param DateTimeImmutable $now Instant UTC. * @param int $limit Max rows. * @return list * * @since 0.1.0 */ public function find_expired_holds( DateTimeImmutable $now, int $limit = 100 ): array; /** * Pending bookings that still carry a soft-hold expiry (active or expired). * * @param int $limit Max rows. * @return list * * @since 0.1.0 */ public function find_pending_holds( int $limit = 100 ): array; }