<?php
/**
 * Contract every notification channel implements.
 *
 * Adding a new channel:
 *   1. Implement this interface (see {@see \Backreload\Notifiers\SlackNotifier} for the simplest reference).
 *   2. Register the class via the filter:
 *
 *      add_filter( 'backreload_register_notifiers', function ( array $types ): array {
 *          $types['my_channel'] = \My\Plugin\MyNotifier::class;
 *          return $types;
 *      } );
 *
 * @package Backreload\Notifiers
 */

namespace Backreload\Notifiers;

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

interface Notifier {

	/** Machine identifier, lowercase a-z + underscore. */
	public static function type(): string;

	/** Human-readable label. */
	public static function label(): string;

	/** One-line description shown under the label in the UI. */
	public static function description(): string;

	/**
	 * Field schema for the connection form.
	 *
	 * Same shape as Destinations\Destination::config_schema().
	 *
	 * @return array<int,array{key:string,label:string,type:string,required?:bool,secret?:bool,help?:string,options?:array<int,string>,default?:mixed}>
	 */
	public static function config_schema(): array;

	/**
	 * Validate user-supplied config; throw NotifierValidationException on failure.
	 *
	 * @param array<string,mixed> $config
	 * @return array<string,mixed> Sanitized config to persist.
	 */
	public function validate( array $config ): array;

	/**
	 * Send a message. Implementation should throw on transport failure.
	 *
	 * @param array<string,mixed> $config
	 * @param array{title:string,message:string,level:string,context?:array<string,mixed>} $payload
	 */
	public function send( array $config, array $payload ): void;
}
