<?php
/**
 * Brevo Mailer Implementation.
 *
 * @package NimblyMail\SMTP
 *
 * @since 1.0.0
 */

namespace NimblyMail\SMTP\Mailers;

use PHPMailer\PHPMailer\PHPMailer;

defined( 'ABSPATH' ) || exit;

/**
 * Class BrevoMailer
 *
 * Sends email through the Brevo (formerly Sendinblue) Transactional Email
 * API. The mailer injects a custom SMTP transport subclass that intercepts
 * `data()` and dispatches the message via HTTPS to Brevo's `/v3/smtp/email`
 * endpoint instead of opening a real SMTP connection.
 *
 * @since 1.0.0
 */
class BrevoMailer extends AbstractMailer {

    /**
     * Get the mailer slug.
     *
     * @since 1.0.0
     *
     * @return string The slug used as the `mail.mailer` option value.
     */
    public function get_slug(): string {
        return 'brevo';
    }

    /**
     * Get the mailer's human-readable title.
     *
     * @since 1.0.0
     *
     * @return string Translated provider title.
     */
    public function get_title(): string {
        return __( 'Brevo', 'nimblymail-smtp' );
    }

    /**
     * Get a short description for the mailer card UI.
     *
     * @since 1.0.0
     *
     * @return string Translated short description.
     */
    public function get_description(): string {
        return __( 'Send emails via the Brevo Transactional Email API.', 'nimblymail-smtp' );
    }

    /**
     * Get the settings schema for this mailer as a section descriptor.
     *
     * @since 1.0.0
     *
     * @return array Section descriptor consumed by SettingsProvider.
     */
    public function get_settings_fields(): array {
        return array(
            'id'          => 'brevo_settings',
            'title'       => __( 'Brevo', 'nimblymail-smtp' ),
            'description' => __( 'Connect to the Brevo API.', 'nimblymail-smtp' ),
            'help_url'    => 'https://app.brevo.com/settings/keys/api',
            'fields'      => array(
                array(
                    'id'          => 'api_key',
                    'group'       => 'brevo',
                    'title'       => __( 'API Key', 'nimblymail-smtp' ),
                    'type'        => 'password',
                    'required'    => true,
                    'encrypted'   => true,
                    'placeholder' => 'xkeysib-xxxxxxxxxxxxxxxxxxxxxxx',
                    'description' => __( 'Your Brevo v3 API key.', 'nimblymail-smtp' ),
                ),
            ),
        );
    }

    /**
     * Configure the PHPMailer instance to send through Brevo.
     *
     * Forces SMTP mode so we can swap the transport, then injects a
     * BrevoTransport subclass that intercepts `data()` and posts the
     * payload to Brevo's REST endpoint.
     *
     * @since 1.0.0
     *
     * @param PHPMailer $phpmailer The PHPMailer instance about to send.
     *
     * @return void
     */
    public function configure( PHPMailer $phpmailer ): void {
        $phpmailer->isSMTP();
        $phpmailer->SMTPAutoTLS = false;

        $api_key = (string) $this->get_option( 'api_key' );

        $phpmailer->setSMTPInstance( new BrevoTransport( $phpmailer, $api_key ) );
    }

    /**
     * Get this mailer's deliverability audit requirements.
     *
     * @since 1.0.0
     *
     * @return array{spf_includes: string[], dkim_selectors: string[], docs_url: string}
     */
    public function get_audit_requirements(): array {
        return array(
            'spf_includes'   => array( 'spf.brevo.com', 'spf.sendinblue.com' ),
            'dkim_selectors' => array( 'mail' ),
            'docs_url'       => 'https://help.brevo.com/hc/en-us/articles/12163873383186',
        );
    }

    /**
     * Get the connectivity endpoints for the Brevo API mailer.
     *
     * @since 1.0.0
     *
     * @return array<array<string, mixed>>
     */
    public function get_connectivity_endpoints(): array {
        return array(
            array(
                'type' => 'api',
                'url'  => 'https://api.brevo.com/v3/smtp/email',
            ),
        );
    }
}
