<?php

namespace EasyLinkAutomations\Actions\Contracts;

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

/**
 * Interface that all actions must implement.
 *
 * Actions perform operations when triggered by automations.
 */
interface ActionInterface
{
    /**
     * Unique identifier: 'category/action_name'
     */
    public static function getSlug(): string;

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

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

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

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

    /**
     * Whether this action requires the pro add-on.
     */
    public static function isPro(): bool;

    /**
     * Platform slug if this action requires a connection.
     *
     * Return the platform slug (e.g., 'google_sheets', 'slack') if this action
     * requires a connection, or null if no connection is needed.
     */
    public static function getRequiresConnection(): ?string;

    /**
     * Fields user needs to configure for this action
     *
     * @return array<string, array{label: string, type: string, supports_mapping?: bool, options?: array, default?: mixed, required?: bool}>
     */
    public static function getConfigFields(): array;

    /**
     * Execute the action with mapped data
     *
     * @param array $triggerData Data from the trigger
     * @param array $config      User's configuration for this action
     *
     * @return array{success: bool, message: string, data?: array}
     */
    public function execute(array $triggerData, array $config): array;

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