<?php
/**
 * Action Handler Interface
 *
 * Defines the contract for all action implementations.
 *
 * @package Sequensy
 * @since 2.0.0
 */

declare(strict_types=1);

namespace Sequensy\Actions\Contracts;

// If this file is called directly, abort.
if ( ! defined( 'WPINC' ) ) {
	die;
}

/**
 * Interface ActionHandler
 *
 * All action handlers must implement this interface.
 */
interface ActionHandler {

	/**
	 * Get action type identifier.
	 *
	 * @return string Action type (e.g., 'wordpress/send_email').
	 */
	public function get_type(): string;

	/**
	 * Get action display label.
	 *
	 * @return string Human-readable label (e.g., 'Send Email').
	 */
	public function get_label(): string;

	/**
	 * Get action description.
	 *
	 * @return string Action description.
	 */
	public function get_description(): string;

	/**
	 * Get action configuration schema.
	 *
	 * @return array Schema defining expected config fields.
	 */
	public function get_schema(): array;

	/**
	 * Execute the action with the given configuration and context.
	 *
	 * @param array<string, mixed> $config  Action configuration values from workflow.
	 * @param array<string, mixed> $context Execution context from trigger and previous actions.
	 * @return array<string, mixed> Result array with 'success' boolean and optional 'data' or 'error'.
	 *
	 * @throws \Sequensy\Exceptions\ActionException      On action execution failure.
	 * @throws \Sequensy\Exceptions\IntegrationException On third-party API failure.
	 */
	public function execute( array $config, array $context ): array;

	/**
	 * Get output fields produced by this action.
	 *
	 * Defines what data this action makes available to subsequent actions
	 * in the workflow context. Each field should include name, type,
	 * description, and example value.
	 *
	 * @return array Array of output field definitions, each containing:
	 *               - name: string Field identifier (e.g., 'post_id')
	 *               - type: string Data type ('string', 'integer', 'boolean', 'datetime', 'array')
	 *               - description: string Human-readable description
	 *               - example: string Example value for display
	 */
	public function get_output_fields(): array;
}
