<?php

namespace EasyLinkAutomations\Triggers\Contracts;

if (!defined('ABSPATH')) {
    exit;
}

/**
 * Interface that all triggers must implement.
 *
 * Triggers listen for WordPress events and fire automations when conditions are met.
 */
interface TriggerInterface
{
    /**
     * Unique identifier: 'category/trigger_name'
     */
    public static function getSlug(): string;

    /**
     * Human-readable name
     */
    public static function getName(): string;

    /**
     * Description of what triggers this
     */
    public static function getDescription(): string;

    /**
     * Category for UI grouping
     */
    public static function getCategory(): string;

    /**
     * Icon identifier for frontend
     */
    public static function getIcon(): string;

    /**
     * Fields that this trigger outputs (available for mapping to actions)
     *
     * @return array<string, array{label: string, type: string}>
     */
    public static function getOutputFields(): array;

    /**
     * Configuration fields for the trigger settings
     *
     * @return array<string, array{label: string, type: string, options?: array, default?: mixed, required?: bool}>
     */
    public static function getConfigFields(): array;

    /**
     * Register WordPress hooks to listen for this trigger.
     *
     * @param callable $callback Function to call when trigger fires, receives trigger data array
     */
    public function register(callable $callback): void;

    /**
     * Called when trigger fires - returns data to pass to actions
     */
    public function handle(mixed ...$args): array;

    /**
     * Convert trigger to array for API response
     */
    public static function toArray(): array;

    /**
     * Check if the required plugin/dependency is active.
     * Return false to skip registration when the plugin is not installed.
     */
    public static function isAvailable(): bool;
}
