<?php
/**
 * Interface for AI Intents.
 *
 * @package Replyan_AI
 */

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

interface Replyan_AI_Intent_Interface {

	/**
	 * Get the unique action name for this intent (e.g., 'show_form').
	 */
	public function get_action_name(): string;

	/**
	 * Get the description of when to trigger this action and what parameters to include.
	 *
	 * @param string $session_id
	 * @param int    $agent_id
	 * @return string
	 */
	public function get_instructions( string $session_id, int $agent_id ): string;

	/**
	 * Handle the parsed intent if it matches this action.
	 * This is optional if the frontend handles it directly.
	 * Return the modified payload to be passed to the frontend.
	 *
	 * @param array  $payload The parsed JSON action payload.
	 * @param string $session_id The current chat session ID.
	 * @param array  $context The conversation context (settings, message, history).
	 * @return array The updated payload or response.
	 */
	public function handle( array $payload, string $session_id, array $context = array() ): array;
}
