namespace Email.Data.Services;

/// <summary>
/// Provides access to localised email templates stored in the <c>emailApi.EmailTemplates</c> table.
/// Implementations are expected to cache templates and refresh periodically.
/// </summary>
public interface IEmailTemplateService
{
    /// <summary>
    /// Returns the template value for the given key and language.
    /// Falls back to <c>"en"</c> when the requested language has no entry.
    /// Returns the raw key string when no matching template is found.
    /// </summary>
    /// <param name="key">Template key (e.g. <c>"email.match.subject"</c>).</param>
    /// <param name="language">Two-letter language code (e.g. <c>"en"</c>, <c>"ro"</c>).</param>
    /// <returns>Template value string.</returns>
    string Get(string key, string language = "en");

    /// <summary>
    /// Retrieves the template and substitutes <c>{{placeholder}}</c> tokens with the provided values.
    /// </summary>
    /// <param name="key">Template key.</param>
    /// <param name="language">Two-letter language code.</param>
    /// <param name="placeholders">Named replacement pairs in the form <c>("name", value)</c>.</param>
    /// <returns>Rendered template string with all placeholders replaced.</returns>
    string Render(string key, string language, params (string Key, string Value)[] placeholders);

    /// <summary>
    /// Returns the operator copy address for the given template key.
    /// Uses the specific row's <c>OperatorCopy</c> value when non-empty; otherwise falls back
    /// to the first non-empty <c>OperatorCopy</c> across all cached rows, so future template rows
    /// with an empty value automatically inherit the globally configured address.
    /// </summary>
    /// <param name="key">Template key used to look up the specific row (typically the subject key).</param>
    /// <param name="language">Two-letter language code.</param>
    /// <returns>Operator copy email address, or <c>null</c> when none is configured.</returns>
    string? GetOperatorCopy(string key, string language);
}