using CvMatcher.Models.Responses;
using Models.Requests;

namespace Api.Services.Contracts
{
    /// <summary>
    /// Abstraction for sending transactional emails from the public API.
    /// </summary>
    public interface IEmailSender
    {
        /// <summary>
        /// Sends a contact-form message to the configured operator address.
        /// </summary>
        /// <param name="req">Contact request containing name, email, subject, and message.</param>
        /// <param name="ct">Cancellation token.</param>
        Task SendContactAsync(ContactRequest req, CancellationToken ct);

        /// <summary>
        /// Notifies the configured operator address that a new email subscription was received.
        /// </summary>
        /// <param name="req">Subscription request containing the subscriber's email address.</param>
        /// <param name="ct">Cancellation token.</param>
        Task SendSubscribeAsync(SubscribeRequest req, CancellationToken ct);

        /// <summary>
        /// Sends a background notification when a file download is initiated.
        /// Does nothing when no notification address is configured.
        /// </summary>
        /// <param name="fileName">Name of the downloaded file.</param>
        /// <param name="userIp">Remote IP address of the downloader, or <c>null</c> if unavailable.</param>
        /// <param name="ct">Cancellation token.</param>
        Task SendFileDownloadNotificationAsync(string fileName, string? userIp, CancellationToken ct);

        /// <summary>
        /// Sends a CV match results email to the user and the operator copy address.
        /// </summary>
        /// <param name="explicitTo">Primary recipient email address, or <c>null</c> to send only the operator copy.</param>
        /// <param name="subject">Email subject line.</param>
        /// <param name="body">Pre-built HTML body fragment.</param>
        /// <param name="attachmentPath">Full path to a CV PDF to attach, or <c>null</c> for no attachment.</param>
        /// <param name="ct">Cancellation token.</param>
        Task SendMatchAsync(string? explicitTo, string subject, string body, string? attachmentPath, CancellationToken ct);

        /// <summary>
        /// Builds the localised subject line for a CV match email.
        /// </summary>
        /// <param name="score">Match score percentage (0–100).</param>
        /// <param name="jobLabel">Human-readable job title or label.</param>
        /// <param name="language">Two-letter language code (e.g. <c>"en"</c>, <c>"ro"</c>).</param>
        /// <returns>Rendered subject string.</returns>
        string BuildMatchEmailSubject(int score, string? jobLabel, string language);

        /// <summary>
        /// Builds the full HTML body for a CV match email, including an optional job-search footer link.
        /// </summary>
        /// <param name="cvDocumentId">Identifier of the indexed CV document.</param>
        /// <param name="result">Structured match response from the CV matcher engine.</param>
        /// <param name="jobLabel">Human-readable job title or label.</param>
        /// <param name="language">Two-letter language code.</param>
        /// <param name="jobSearchLink">Optional one-click job-search URL to append as a footer CTA.</param>
        /// <param name="expiryDays">Number of days until the job-search link expires (shown in the footer copy).</param>
        /// <returns>Rendered HTML body string.</returns>
        string BuildMatchEmailBody(string cvDocumentId, JobMatchResponse result, string? jobLabel, string language, string? jobSearchLink = null, int expiryDays = 7);

        /// <summary>
        /// Returns the localised label for a manually-entered job description (no URL provided).
        /// </summary>
        /// <param name="language">Two-letter language code.</param>
        string GetManualJobLabel(string language);
    }
}