<?php
/**
 * Notification driver contracts.
 *
 * @package Rahkar\WP
 */

declare( strict_types = 1 );

namespace Rahkar\WP\Contracts;

use Rahkar\WP\Notifications\Message;
use Rahkar\WP\Notifications\Result;

defined( 'ABSPATH' ) || exit;

/**
 * One provider inside a channel.
 *
 * A channel is the carrier — SMS, email. A driver is a specific service behind
 * it: IPPanel, Kavenegar, `wp_mail`, SMTP. Splitting them this way means adding
 * a provider is one small class, and adding a whole new carrier later does not
 * touch any calling code.
 *
 * Drivers are resolved lazily by id, so only the one a store actually selected
 * is ever constructed.
 */
interface Driver {

	/**
	 * Stable identifier, stored in settings. Changing it breaks configurations.
	 */
	public function id(): string;

	/**
	 * Provider name, for the settings screen.
	 */
	public function name(): string;

	/**
	 * Send a message.
	 *
	 * Implementations must never throw for an expected failure — a wrong API key
	 * or an unreachable host is a {@see Result}, not an exception. The queue reads
	 * `retryable` off that result to decide whether trying again is worthwhile.
	 *
	 * @param Message $message Message to deliver.
	 */
	public function send( Message $message ): Result;

	/**
	 * Has the store filled in everything this provider needs?
	 */
	public function isConfigured(): bool;

	/**
	 * Field definitions for the settings screen, in the shared schema shape.
	 *
	 * Declarative rather than rendering its own markup, so one renderer and one
	 * sanitiser serve every provider and the settings screen cannot drift out of
	 * step with what the driver actually reads.
	 *
	 * @return array<string, array<string, mixed>>
	 */
	public function settingsSchema(): array;
}