<?php

declare(strict_types=1);

namespace Instinctor\Core\Queue;

/**
 * Queue driver interface.
 *
 * On WordPress:  jobs are stored in instinctor_jobs, runner fires via WP-cron
 *                on the 'instinctor_queue_runner' hook (every minute).
 *
 * On Standalone: same instinctor_jobs table, runner called by a real system cron
 *                or PHP-CLI: `php artisan queue:work` (simple custom runner).
 */

if (!defined('ABSPATH')) exit;
interface DriverInterface
{
    /**
     * Dispatch a job for immediate (or delayed) execution.
     *
     * @param string $type    Job type identifier, e.g. 'email', 'sms', 'webhook', 'abandoned_cart'
     * @param array  $payload Job data — will be JSON-encoded
     * @param int    $delay   Seconds to wait before the job becomes available (0 = immediately)
     */
    public function dispatch(string $type, array $payload, int $delay = 0): int;

    /**
     * Process up to $limit pending jobs.
     * Returns the number of jobs processed.
     */
    public function run(int $limit = 50): int;

    /**
     * Return count of jobs by status.
     *
     * @return array{pending: int, running: int, completed: int, failed: int}
     */
    public function stats(): array;

    /**
     * Delete completed and failed jobs older than $days days.
     */
    public function prune(int $days = 7): int;
}
