<?php

declare(strict_types=1);

namespace Instinctor\Core\Mailer;

/**
 * Mailer driver interface.
 *
 * On WordPress:  routes through the Instinctor relay server (instinctor.com/wp-json/ilm/v1/send_email)
 *                which delivers via SendGrid. Requires a valid license key.
 *
 * On Standalone: calls SendGrid v3 API directly using cURL.
 *                Requires SENDGRID_API_KEY and SENDGRID_FROM_EMAIL in config.
 */

if (!defined('ABSPATH')) exit;
interface DriverInterface
{
    /**
     * Send an email immediately.
     *
     * @param string $to      Recipient email address
     * @param string $subject Email subject
     * @param string $body    Email body — plain text or HTML
     * @param array  $options {
     *   @type bool   $html       Force HTML rendering (auto-detected if omitted)
     *   @type string $reply_to   Reply-To email address
     *   @type string $store_name Store name for relay metadata
     *   @type string $from_name  Override sender display name
     * }
     */
    public function send(string $to, string $subject, string $body, array $options = []): bool;

    /**
     * Queue an email for async delivery.
     * On WordPress: pushes to WP-cron via T6 Queue (stub until T6).
     * On Standalone: pushes to instinctor_jobs table via T6 Queue (stub until T6).
     */
    public function queue(string $to, string $subject, string $body, array $options = []): bool;
}
