<?php

/**
 * Contract for all domain-specific Action Handlers.
 *
 * Every handler that takes over a slice of ActionExecutor responsibilities
 * must implement this interface. This allows HandlerRouter to discover and
 * delegate to handlers without knowing their internal details.
 *
 * @package LolaCore\Actions\Contracts
 * @license GPL-2.0-or-later
 */

declare( strict_types=1 );

namespace LolaCore\Actions\Contracts;

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

/**
 * Interface ActionHandlerInterface
 *
 * Domain handlers implement this contract to participate in the routing layer.
 * Handlers are stateless — they must not store per-request or per-session data.
 */
interface ActionHandlerInterface {

	/**
	 * Returns the list of action IDs (snake_case) this handler is responsible for.
	 *
	 * The IDs must exactly match the keys used in ActionExecutor::$registry.
	 * Example: ['get_content', 'create_content', 'edit_content']
	 *
	 * @return array<string> List of owned action IDs.
	 */
	public function getSupportedActions(): array;

	/**
	 * Executes the given action and returns the result array.
	 *
	 * The handler receives the already-normalized action ID, the raw params
	 * array from the LLM/MCP client, and the dryRun flag (true = preview only,
	 * false = real execution).
	 *
	 * Must throw \Exception on validation failure or execution error.
	 * Must NOT catch exceptions internally unless performing cleanup — let them
	 * bubble up to ActionExecutor for uniform logging and response formatting.
	 *
	 * @param string $actionId Normalized snake_case action ID.
	 * @param array  $params   Raw parameters from the tool call.
	 * @param bool   $dryRun   True for preview/dry-run mode, false for execution.
	 * @return array Result data array.
	 *
	 * @throws \Exception On validation failure or execution error.
	 */
	public function handle( string $actionId, array $params, bool $dryRun ): array;
}
