<?php
/**
 * Background job scheduler port.
 *
 * @package Bookline
 */

declare( strict_types=1 );

namespace Bookline\Infrastructure\Scheduling;

use DateTimeImmutable;

/**
 * Abstraction over Action Scheduler (with testable in-memory driver).
 *
 * @since 0.1.0
 */
interface JobScheduler {

	/**
	 * Schedule a single action.
	 *
	 * @param string                 $hook      Hook name.
	 * @param array<string, mixed>   $args      Args.
	 * @param DateTimeImmutable|null $run_at    When (null = ASAP).
	 * @param string                 $group     Group.
	 * @param string|null            $unique_key Optional uniqueness token.
	 * @return int Action id (0 when deferred / unavailable).
	 *
	 * @since 0.1.0
	 */
	public function schedule_single( string $hook, array $args, ?DateTimeImmutable $run_at = null, string $group = 'bookline', ?string $unique_key = null ): int;

	/**
	 * Schedule a recurring action if not already present.
	 *
	 * @param string $hook     Hook.
	 * @param int    $interval Interval seconds.
	 * @param string $group    Group.
	 *
	 * @since 0.1.0
	 */
	public function schedule_recurring( string $hook, int $interval, string $group = 'bookline' ): void;

	/**
	 * Cancel actions matching hook + args in group.
	 *
	 * @param string               $hook  Hook.
	 * @param array<string, mixed> $args  Args.
	 * @param string               $group Group.
	 *
	 * @since 0.1.0
	 */
	public function cancel( string $hook, array $args = [], string $group = 'bookline' ): void;

	/**
	 * Cancel every action in the group.
	 *
	 * @param string $group Group.
	 *
	 * @since 0.1.0
	 */
	public function cancel_group( string $group = 'bookline' ): void;

	/**
	 * Whether the underlying scheduler is available.
	 *
	 * @since 0.1.0
	 */
	public function is_available(): bool;

	/**
	 * Pending action count in the group (best-effort).
	 *
	 * @param string $group Group.
	 *
	 * @since 0.1.0
	 */
	public function pending_count( string $group = 'bookline' ): int;

	/**
	 * Failed action count in the group (best-effort).
	 *
	 * @param string $group Group.
	 *
	 * @since 0.1.0
	 */
	public function failed_count( string $group = 'bookline' ): int;
}