<?php

namespace WPSN\Core\Queue;

defined('ABSPATH') || exit;

interface QueueInterface
{
    /**
     * @param array<string,mixed> $payload
     */
    public function enqueue(string $jobType, array $payload, int $runAtTimestamp = 0): int;

    /**
     * @return array<string,mixed>|null
     */
    public function claimNext(): ?array;

    /**
     * Claim the next pending job, restricted to a set of allowed job types.
     *
     * This is useful for UI-driven workers (admin-ajax) where we want to
     * advance a specific workflow (e.g. Audit scan) without accidentally
     * running heavy unrelated background jobs.
     *
     * @param array<int,string> $jobTypes
     * @return array<string,mixed>|null
     */
    public function claimNextByTypes(array $jobTypes): ?array;

    public function markDone(int $jobId): void;

    public function markFailed(int $jobId, string $errorMessage): void;

    public function retryLater(int $jobId, int $delaySeconds, string $errorMessage = ''): void;

    /**
     * @return array<string,int> Map of status => count
     */
    public function counts(): array;

    /**
     * Delete failed jobs from the queue.
     *
     * @return int Number of deleted rows
     */
    public function clearFailed(): int;

    /**
     * Requeue failed jobs back to pending.
     *
     * @return int Number of updated rows
     */
    public function requeueFailed(): int;
}
