<?php

namespace MintyPHP\Repository\Scheduler;

/** Contract for scheduled job CRUD, due-job queries, and run status tracking. */
interface ScheduledJobRepositoryInterface
{
    public function create(array $data): int|false;

    public function find(int $id): ?array;

    public function findByKey(string $jobKey): ?array;

    public function listPaged(array $filters): array;

    public function listDueJobs(string $nowUtc, int $limit = 20): array;

    public function updateJobMeta(int $id, array $data): bool;

    public function markRunning(int $id, string $startedAtUtc): bool;

    public function finishRun(
        int $id,
        string $status,
        string $startedAtUtc,
        string $finishedAtUtc,
        ?string $nextRunAtUtc,
        ?string $errorCode,
        ?string $errorMessage
    ): bool;

    /** Delete jobs whose job_key is not in the given list of valid keys. Returns affected row count. */
    public function deleteOrphanedJobs(array $validKeys): int;
}
