<?php

namespace App\ScheduledTasks\Contracts;

use App\ScheduledTasks\ActionResult;
use App\ScheduledTasks\TaskRunContext;

interface TaskAction
{
    /**
     * Registry key, e.g. 'export-map'. Must match the config key.
     */
    public function key(): string;

    /**
     * Translated label shown in the admin action picker.
     */
    public function label(): string;

    /**
     * Is this action available for the current tenant (integration setting enabled etc).
     * Checked when building the picker, at save, and again at run time.
     */
    public function available(): bool;

    /**
     * May admins add this action to their own tasks? System-only actions return false.
     */
    public function userSelectable(): bool;

    /**
     * Backend-described config fields the admin UI renders generically.
     *
     * @return array<int, array<string, mixed>>
     */
    public function configFields(): array;

    /**
     * Laravel validation rules for the action config, keyed by config field.
     *
     * @return array<string, mixed>
     */
    public function rules(array $config): array;

    /**
     * Execute the action. Must not throw for expected failures; return a failed
     * ActionResult instead so run_when branching applies cleanly.
     */
    public function execute(array $config, TaskRunContext $context): ActionResult;

    /**
     * Advisory queue for the work this action performs.
     */
    public function queue(): string;
}
