<?php
/**
 * Notification with merge tags interface for implementing merge tag support.
 *
 * @package Awesomemotive\Rewardswp\Interfaces
 * @since 1.1.0
 */

namespace Awesomemotive\Rewardswp\Interfaces;

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

/**
 * Interface NotificationWithMergeTagsInterface
 *
 * Defines the contract for notifications that support merge tags.
 * Merge tags are dynamic placeholders that get replaced with actual content when sending notifications.
 *
 * @since 1.1.0
 */
interface NotificationWithMergeTagsInterface {
	/**
	 * Get available merge tags for this notification.
	 *
	 * Returns a simple array of merge tag names (without braces) for backward compatibility.
	 *
	 * @since 1.1.0
	 *
	 * @return array Array of merge tag names (without braces).
	 */
	public function get_available_merge_tags(): array;

	/**
	 * Get detailed merge tag definitions for admin UI.
	 *
	 * Returns an array of merge tag definitions with labels, descriptions, and examples
	 * for use in the admin interface dropdown/selector.
	 *
	 * @since 1.1.0
	 *
	 * @return array Array of merge tag definitions with structure:
	 *               [
	 *                   [
	 *                       'tag' => 'merge_tag_name',
	 *                       'label' => 'Human Readable Label',
	 *                       'description' => 'What this merge tag represents',
	 *                       'example' => 'Sample output value'
	 *                   ],
	 *                   ...
	 *               ]
	 */
	public function get_merge_tag_definitions(): array;
}
