<?php
/**
 * File Path: includes/api/class-mbs-esp-adapter.php
 *
 * ESP Adapter Interface — My Book Showroom
 *
 * Defines the contract all Email Service Provider adapters must fulfill.
 * Introduced in Sprint F-026: Email Channel Integration.
 *
 * @package    My_Book_Showroom
 * @subpackage Includes/Api
 * @since      1.1.0
 */

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

interface MBS_ESP_Adapter { // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedInterfaceFound -- mbs_/MBS_ prefix is correct; scanner not configured with plugin prefix

	/**
	 * Test the API credentials. Returns true if the connection succeeds.
	 * Must not throw -- catch exceptions and return false.
	 */
	public function connect(): bool;

	/**
	 * Return all available lists/audiences for the account.
	 * Return format: [ ['id' => string, 'name' => string], ... ]
	 * Return [] on failure.
	 */
	public function get_lists(): array;

	/**
	 * Subscribe an email address to a list.
	 *
	 * @param string $email        Sanitized email address.
	 * @param string $name         Subscriber display name (may be empty).
	 * @param string $list_id      Platform list/audience ID.
	 * @param bool   $double_optin Whether to use double opt-in flow.
	 * @return bool True on success or already-subscribed; false on API error.
	 */
	public function subscribe( string $email, string $name, string $list_id, bool $double_optin ): bool;

	/**
	 * Apply tags to an existing contact.
	 * Return true on success, false on failure, or true as a no-op (Sendy).
	 *
	 * @param string   $email   Sanitized email address.
	 * @param string[] $tags    Tag strings to apply.
	 * @param string   $list_id Platform list/audience ID.
	 */
	public function tag_contact( string $email, array $tags, string $list_id ): bool;

	/**
	 * Whether this platform natively supports tags.
	 * Sendy returns false. All other platforms return true.
	 */
	public function supports_tags(): bool;

	/**
	 * Create a broadcast/campaign from a subject + HTML body.
	 * Returns a platform campaign ID string on success, or null on failure.
	 * Platforms that do not support campaign creation via API return null and
	 * must implement supports_campaigns() returning false.
	 *
	 * @param string $subject   Email subject line.
	 * @param string $body_html Full HTML email body.
	 * @param string $list_id   List to send to.
	 */
	public function create_campaign( string $subject, string $body_html, string $list_id ): ?string;

	/**
	 * Send a previously created campaign by its platform ID.
	 * Returns true on success, false on failure.
	 * Platforms where supports_campaigns() is false must return false.
	 */
	public function send_campaign( string $campaign_id ): bool;

	/**
	 * Whether this platform supports campaign creation/send via API.
	 * Sendy returns false.
	 */
	public function supports_campaigns(): bool;
}
