<?php
/**
 * Email delivery provider contract.
 *
 * @package EmailSmtp
 * @since 1.1.0
 */

namespace EmailSmtp\Includes;

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

interface ProviderInterface {

	public function get_id(): string;

	public function get_name(): string;

	public function get_description(): string;

	/**
	 * Transport label shown on provider cards (e.g. SMTP, API, OAuth).
	 */
	public function get_transport_label(): string;

	/**
	 * Short recommended-use copy for the provider card.
	 */
	public function get_recommended_use(): string;

	/**
	 * Official documentation URL.
	 */
	public function get_docs_url(): string;

	/**
	 * Dashicon class or empty for custom logo markup.
	 */
	public function get_icon(): string;

	/**
	 * @return list<string> Setting keys required for a complete configuration.
	 */
	public function get_required_fields(): array;

	/**
	 * @param array<string, mixed> $settings Provider-specific settings.
	 * @return true|\WP_Error
	 */
	public function validate_settings( array $settings );

	/**
	 * Authenticate / verify connection without sending mail when possible.
	 *
	 * @param array<string, mixed> $settings Provider-specific settings.
	 */
	public function connect( array $settings ): DeliveryResult;

	/**
	 * Clear provider connection state (OAuth tokens, cached status, etc.).
	 *
	 * @param array<string, mixed> $settings Provider-specific settings.
	 * @return array<string, mixed> Updated settings after disconnect.
	 */
	public function disconnect( array $settings ): array;

	public function send( EmailMessage $message, array $settings ): DeliveryResult;

	public function send_test( EmailMessage $message, array $settings ): DeliveryResult;

	/**
	 * @param array<string, mixed> $settings Provider-specific settings.
	 */
	public function get_connection_status( array $settings ): string;

	/**
	 * @param mixed $error Provider-native error.
	 */
	public function normalize_error( $error ): DeliveryResult;

	public function supports_attachments(): bool;

	public function supports_html(): bool;

	public function supports_reply_to(): bool;

	public function supports_custom_headers(): bool;

	public function supports_tags(): bool;

	public function supports_metadata(): bool;

	public function supports_batching(): bool;

	/**
	 * Whether this provider uses PHPMailer SMTP configuration.
	 */
	public function uses_phpmailer_smtp(): bool;

	/**
	 * Whether this provider short-circuits wp_mail via pre_wp_mail.
	 */
	public function uses_api_transport(): bool;
}
