[FEAT] Customisable Email & Templating System

[m-t-a97]

User Story

As a developer using Authula,
I want to define custom subject lines and message bodies for all system-generated emails,
So that I can maintain consistent brand identity and localized content without modifying the library's source code.

Context & Rationale

Currently, the library uses fixed string constants for email notifications. This feature introduces a templating layer that allows developers to provide their own string-based templates for every automated communication.

---

Technical Implementation Details

1. Configuration-Based Templates

• The library should allow defining email templates that can be loaded during runtime.

2. Dynamic Variable Support

• The system must support a standard templating syntax to allow the injection of dynamic data into the custom strings.
• Global Variables: App Name, Base URL, Support Email etc.
• Contextual Variables: User's Display Name, Expiry Time, Token, Redirect URL and more.

3. Execution Logic

• Validation at Startup: The library should validate that any provided templates contain valid syntax and do not reference non-existent variables.
• Fallback Mechanism: If a specific template is not provided in the configuration, the system must automatically fall back to the built-in "sensible default" templates.
• Data-Only Delivery: The system could prepare the final string and pass it to the existing Event Bus, allowing the underlying mailing plugin to handle the actual delivery.

---

Acceptance Criteria (AC)

• Configurable Overrides: Developers can override the subject and body for all core authentication emails via the main configuration object.
• Variable Interpolation: Dynamic data (like the Magic Link URL) is correctly injected into custom templates at runtime.
• Default Content: The library provides high-quality default templates if no custom configuration is detected.
• Syntax Safety: The library prevents startup if it detects a broken template (e.g., an unclosed variable tag).
• Formatting Agnostic: The system supports both plain text and rich text strings as inputs, depending on what the developer's mail provider supports.

Implementation Hints

• Consistency: Ensure the variable names (e.g., Token, UserEmail) are consistent across all template types to reduce the learning curve for developers.
• Event Payload: The event bus should receive the "Rendered" message so that the email-sending plugin doesn't need to know about the templating logic—it just sends the result.

---

Subject to change.