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

declare(strict_types=1);

namespace Sequensy\Triggers\Contracts;

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

/**
 * Interface TriggerHandler
 *
 * All trigger handlers must implement this interface.
 */
interface TriggerHandler {

	/**
	 * Get trigger type identifier.
	 *
	 * @return string Trigger type (e.g., 'wordpress/user_registration').
	 */
	public function get_type(): string;

	/**
	 * Get trigger display label.
	 *
	 * @return string Human-readable label (e.g., 'User Registration').
	 */
	public function get_label(): string;

	/**
	 * Get trigger description.
	 *
	 * @return string Trigger description.
	 */
	public function get_description(): string;

	/**
	 * Register trigger hooks.
	 *
	 * This method should hook into WordPress actions/filters to detect events.
	 */
	public function register(): void;

	/**
	 * Get available data fields for this trigger.
	 *
	 * Returns an array of field definitions describing the data this trigger
	 * provides to workflow actions. Each field definition includes metadata
	 * about the field for display in the workflow builder UI.
	 *
	 * Optional method. If not implemented, trigger will report no available fields.
	 *
	 * @return array Array of field definition objects. Each object should have:
	 *               - 'name' (string): Field key (e.g., 'user_email')
	 *               - 'type' (string): Data type - one of: 'string', 'integer', 'boolean', 'datetime', 'array'
	 *               - 'description' (string): Human-readable description of the field
	 *               - 'example' (string): Example value for the field
	 */
	// phpcs:ignore Squiz.PHP.CommentedOutCode.Found -- Documents optional interface method for implementors.
	// public function get_available_fields(): array;
}
