@venizia/ignis-docs 0.0.5 → 0.0.6-1

package/wiki/references/components/mail/api.md

@@ -0,0 +1,505 @@
+# Mail -- API Reference
+
+> Architecture, interfaces, and internal implementation details of the Mail component.
+
+## Architecture
+
+```
+  ┌─────────────────────────────────────────────────┐
+  │               Your Application                   │
+  │                                                   │
+  │  NodemailerComponent (wrapper)                   │
+  │    ├── binds MailKeys.MAIL_OPTIONS               │
+  │    ├── binds MailKeys.MAIL_QUEUE_EXECUTOR_CONFIG │
+  │    └── registers MailComponent                    │
+  └───────────────────────┬─────────────────────────┘
+                          │
+                          ▼
+  ┌─────────────────────────────────────────────────┐
+  │               MailComponent                       │
+  │                                                   │
+  │  binding()                                        │
+  │    ├── initGenerators()                           │
+  │    │     ├── NumericCodeGenerator                 │
+  │    │     ├── RandomTokenGenerator                 │
+  │    │     └── DefaultVerificationDataGenerator     │
+  │    │                                               │
+  │    ├── initProviders()                            │
+  │    │     ├── MailTransportProvider (singleton)     │
+  │    │     └── MailQueueExecutorProvider (singleton) │
+  │    │                                               │
+  │    ├── initServices()                             │
+  │    │     ├── MailService (singleton)               │
+  │    │     └── TemplateEngineService (singleton)     │
+  │    │                                               │
+  │    └── createAndBindInstances()                   │
+  │          ├── Transport Instance ◄── MAIL_OPTIONS  │
+  │          └── Queue Executor ◄── QUEUE_CONFIG      │
+  └─────────────────────────────────────────────────┘
+```
+
+**Architecture Components:**
+
+- **`MailComponent`** -- Initializes and registers all mail services, transporters, and queue executors. Extends `BaseComponent`. Validates that `MailKeys.MAIL_OPTIONS` is bound before proceeding
+- **`MailService`** -- Extends `BaseService`. Provides `send()`, `sendBatch()`, `sendTemplate()`, and `verify()`. Injects transport instance and template engine. Validates messages before sending
+- **`TemplateEngineService`** -- Extends `BaseService`. Manages email templates with simple <code v-pre>{{variable}}</code> substitution. Stores templates in an in-memory `Map`
+- **`MailTransportProvider`** -- Extends `BaseProvider`. Factory that creates transport instances with type-guard methods (`isNodemailerOptions`, `isMailgunOptions`, `isCustomOptions`) and throws `MailErrorCodes` on invalid configs
+- **`MailQueueExecutorProvider`** -- Extends `BaseProvider`. Factory that creates queue executor instances. Throws for missing sub-configs (e.g., `config.internalQueue` or `config.bullmq`)
+- **Verification Generators** -- `NumericCodeGenerator`, `RandomTokenGenerator`, `DefaultVerificationDataGenerator`. Generate verification codes, tokens, and data for email verification flows
+
+**Tech Stack:**
+
+- **Nodemailer** -- SMTP-based email sending (peer dependency: `nodemailer`)
+- **Mailgun** -- Mailgun API client (peer dependency: `mailgun.js`)
+- **BullMQ** (optional) -- Redis-backed queue for distributed processing (peer dependency: `bullmq`)
+- **Handlebars-style Templates** -- Simple <code v-pre>{{variable}}</code> syntax for email templates (no external dependency)
+
+## Transport Layer
+
+### Transport Layer Implementation
+
+The `MailTransportProvider` extends `BaseProvider` and returns a factory function from its `value()` method. It creates the appropriate transport based on the `provider` field in `MailKeys.MAIL_OPTIONS`:
+
+- **`'nodemailer'`** -- Creates a `NodemailerTransportHelper` backed by `nodemailer` with SMTP or OAuth2 auth
+- **`'mailgun'`** -- Creates a `MailgunTransportHelper` using the Mailgun HTTP API
+- **`'custom'`** -- Expects the `config` value to implement `IMailTransport` directly (must have `send()` and `verify()`)
+- **Any other string** -- Falls through to `default` and throws `Unsupported mail provider: <provider>` with `MailErrorCodes.INVALID_CONFIGURATION`
+
+The provider uses three private type-guard methods to narrow the union type before creating transports:
+
+```typescript
+private isNodemailerOptions(options: TMailOptions): options is INodemailerMailOptions
+private isMailgunOptions(options: TMailOptions): options is IMailgunMailOptions
+private isCustomOptions(options: TMailOptions): options is ICustomMailOptions
+```
+
+For custom transports, an additional `isMailTransport()` utility validates that the config object has `send()` and `verify()` methods, reporting specific missing methods in the error message.
+
+Both built-in transports implement `IMailTransport`:
+
+```typescript
+interface IMailTransport {
+  send(message: IMailMessage): Promise<IMailSendResult>;
+  verify(): Promise<boolean>;
+  close?(): Promise<void>;
+}
+```
+
+### Module Validation
+
+Both `NodemailerTransportHelper` and `MailgunTransportHelper` call `validateModule()` in their `configure()` method before importing the peer dependency. This checks that the required npm module is installed:
+
+- `NodemailerTransportHelper` requires `nodemailer`
+- `MailgunTransportHelper` requires `mailgun.js`
+
+If the module is not installed, `validateModule()` throws an error identifying the missing peer dependency.
+
+**Nodemailer Transport:**
+
+The `NodemailerTransportHelper` extends `BaseHelper` and wraps Nodemailer's SMTP transport. In `configure()`, it calls `require('nodemailer')` and creates a transporter. Key behaviors:
+- `send()` maps `IMailMessage` fields to Nodemailer's mail options, joining array recipients with `, `
+- `send()` catches transport errors and returns `{ success: false, error: ... }` instead of throwing
+- `verify()` delegates to Nodemailer's built-in `transporter.verify()` SMTP handshake
+- `close()` calls `transporter.close()` to release the connection
+
+**Mailgun Transport:**
+
+The `MailgunTransportHelper` extends `BaseHelper` and uses the Mailgun REST API via `mailgun.js`. In `configure()`, it creates a `Mailgun` client using `FormData`. Key behaviors:
+- `send()` converts `IMailMessage` to Mailgun's format: `to` becomes an array, `replyTo` becomes `h:Reply-To`, all custom headers are prefixed with `h:`
+- Attachments are mapped to `{ filename, data }` objects where `data` is `path ?? content ?? Buffer.from('')`
+- `verify()` sends a test email to `verify@<domain>` with `o:testmode: 'yes'` flag to check API credentials without actually sending
+- No `close()` method (HTTP API is stateless)
+
+**Custom Transport:**
+
+You can provide your own transport implementation by setting `provider: MailProviders.CUSTOM` and passing an object that implements `IMailTransport` as the `config` value. The provider validates that `send()` and `verify()` are functions, reporting specific missing methods. This is useful for integrating with services like SendGrid, AWS SES, or custom SMTP relays.
+
+## IMailService Interface
+
+```typescript
+interface IMailService {
+  // Send a single email
+  send(message: IMailMessage): Promise<IMailSendResult>;
+
+  // Send multiple emails with controlled concurrency
+  sendBatch(
+    messages: IMailMessage[],
+    options?: { concurrency?: number },
+  ): Promise<IMailSendResult[]>;
+
+  // Send email using a registered template
+  sendTemplate(opts: {
+    templateName: string;
+    data: Record<string, any>;
+    recipients: string | string[];
+    options?: Partial<IMailMessage>;
+  }): Promise<IMailSendResult>;
+
+  // Verify transport connection
+  verify(): Promise<boolean>;
+}
+```
+
+**Method Details:**
+
+**`send(message: IMailMessage)`**
+
+Sends a single email using the configured transport. Internally:
+1. Calls `validateMessage()` which throws for missing `to`, `subject`, or both `text`/`html` (see error reference below)
+2. Merges `message.from` with the default from address (via `getDefaultFrom()`)
+3. Delegates to `transport.send()`
+4. Returns a result object with `success`, `messageId`, and optional `error` fields
+5. If the transport throws, catches the error and re-throws with `MailErrorCodes.SEND_FAILED`
+
+**`sendBatch(messages: IMailMessage[], options?: { concurrency?: number })`**
+
+Sends multiple emails with controlled concurrency using `executePromiseWithLimit()`. Default concurrency is `MailDefaults.BATCH_CONCURRENCY` (5). Each message is sent via `send()` individually. If an individual `send()` throws, it is caught and converted to `{ success: false, error: '...' }` so the batch continues. If the entire batch operation fails, throws with `MailErrorCodes.BATCH_SEND_FAILED`.
+
+**`sendTemplate(opts: { templateName, data, recipients, options? })`**
+
+Renders a registered template with the provided data and sends the email. The subject is resolved through a priority chain:
+
+1. `options.subject` -- explicit override from the caller
+2. Template subject rendered through the template engine (if `templateData.subject` is defined)
+3. `'No Subject'` -- fallback if neither is provided
+
+Throws `MailErrorCodes.INVALID_CONFIGURATION` if the template engine is not configured. Re-throws any other errors (including `TEMPLATE_NOT_FOUND` from the template engine).
+
+**`verify()`**
+
+Verifies the transport connection without sending an email. Delegates to `transport.verify()`. If the transport throws, catches and re-throws with `MailErrorCodes.VERIFICATION_FAILED`.
+
+### Protected Methods (MailService)
+
+**`validateMessage(message: IMailMessage)`**
+
+Pre-transport validation that throws immediately for invalid messages:
+
+| Check | Error Code | Status | Message |
+|-------|-----------|--------|---------|
+| `to` is falsy or empty array | `INVALID_RECIPIENT` | 400 | `Recipient email address is required` |
+| `subject` is falsy | `INVALID_CONFIGURATION` | 400 | `Email subject is required` |
+| Both `text` and `html` are falsy | `INVALID_CONFIGURATION` | 400 | `Email must have either text or html content` |
+
+**`getDefaultFrom()`**
+
+Constructs the default "from" address. If `options.fromName` is set, returns `"fromName" <from>`. Otherwise returns `options.from ?? 'noreply@example.com'`.
+
+## IMailMessage Interface
+
+```typescript
+interface IMailMessage {
+  from?: string; // Sender email (uses default if not provided)
+  to: string | string[]; // Recipient(s)
+  cc?: string | string[]; // CC recipient(s)
+  bcc?: string | string[]; // BCC recipient(s)
+  replyTo?: string; // Reply-to address
+  subject: string; // Email subject
+  text?: string; // Plain text content
+  html?: string; // HTML content
+  attachments?: IMailAttachment[]; // File attachments
+  headers?: Record<string, string>; // Custom headers
+  requireValidate?: boolean; // Validate template data
+  [key: string]: any; // Additional arbitrary fields
+}
+```
+
+**Field Details:**
+
+**`from`**
+
+Sender email address. If not provided, uses the default `from` value from `MailKeys.MAIL_OPTIONS`. When `fromName` is configured, the default from is formatted as `"Display Name" <email@example.com>`. Can be overridden per-message for multi-tenant scenarios.
+
+**`to`, `cc`, `bcc`**
+
+Recipient addresses. Can be a single string or an array of strings. Format can be either plain email (`user@example.com`) or display name + email (`John Doe <john@example.com>`). For Nodemailer, arrays are joined with `, `. For Mailgun, arrays are passed as-is.
+
+**`replyTo`**
+
+Reply-to address if different from the sender. Useful for no-reply addresses that route replies to a support inbox. Mailgun maps this to `h:Reply-To`.
+
+**`subject`**
+
+Email subject line. Supports template variables when used with `sendTemplate()` (the subject is rendered through the same template engine).
+
+**`text`, `html`**
+
+Plain text and HTML versions of the email body. At least one must be provided (validated by `validateMessage()`). Most email clients prefer HTML but fall back to text if HTML is not available. Best practice is to provide both.
+
+**`attachments`**
+
+Array of `IMailAttachment` objects:
+
+```typescript
+interface IMailAttachment {
+  filename?: string;
+  contentType?: string;
+  path?: string;
+  content?: string | Buffer | Readable;
+  cid?: string;
+  [key: string]: any;
+}
+```
+
+Examples:
+- A file path: `{ filename: 'doc.pdf', path: '/path/to/doc.pdf' }`
+- A buffer: `{ filename: 'data.txt', content: Buffer.from('...') }`
+- An inline image: `{ filename: 'logo.png', path: '...', cid: 'logo' }`
+
+**`headers`**
+
+Custom SMTP headers. For Nodemailer, passed directly. For Mailgun, each key is auto-prefixed with `h:`.
+
+**`requireValidate`**
+
+When `true`, template rendering will throw an error if any <code v-pre>{{variable}}</code> placeholders are missing from the data object. Defaults to `false` (missing variables are preserved as their original placeholder text, not replaced with empty strings).
+
+**`[key: string]: any`**
+
+The interface is open-ended -- additional fields are accepted for provider-specific options.
+
+## IMailTemplateEngine Interface
+
+```typescript
+interface IMailTemplateEngine {
+  // Render a template with data
+  render(opts: {
+    templateData?: string;
+    templateName?: string;
+    data: Record<string, any>;
+    requireValidate?: boolean;
+  }): string;
+
+  // Register a new template
+  registerTemplate(opts: { name: string; content: string }): void;
+
+  // Validate template data
+  validateTemplateData(opts: { template: string; data: Record<string, any> }): {
+    isValid: boolean;
+    missingKeys: string[];
+    allKeys: string[];
+  };
+
+  // Get a registered template
+  getTemplate(name: string): ITemplate | undefined;
+
+  // List all registered templates
+  listTemplates(): ITemplate[];
+
+  // Check if template exists
+  hasTemplate(name: string): boolean;
+
+  // Remove a template
+  removeTemplate(name: string): boolean;
+}
+```
+
+**Method Details:**
+
+**`render(opts: { templateData?, templateName?, data, requireValidate? })`**
+
+Renders a template by name (from registry) or by raw template string (`templateData`). At least one of `templateData` or `templateName` must be provided -- throws if neither is given. If `templateName` is used, looks up the template and throws `TEMPLATE_NOT_FOUND` if not registered. Delegates to `renderSimpleTemplate()` which replaces all <code v-pre>{{variable}}</code> placeholders with values from the `data` object. If `requireValidate` is `true`, throws `INVALID_CONFIGURATION` if any placeholders are missing from the data.
+
+**`registerTemplate(opts: { name, content, options? })`**
+
+Registers a new template in the in-memory registry. The `options` parameter (on the class implementation) can include `subject` and `description` via `Partial<ITemplate>`. Overwrites any existing template with the same name.
+
+**`validateTemplateData(opts: { template, data })`**
+
+Extracts all <code v-pre>{{variable}}</code> placeholders from the template string using the regex `/\{\{(\s*[\w.]+\s*)\}\}/g`. Deduplicates keys. For each unique key, resolves nested values via dot notation. Returns:
+- `isValid` -- `true` if all placeholders have non-null, non-undefined values
+- `missingKeys` -- Array of placeholder names that are missing or null/undefined in the data
+- `allKeys` -- Array of all unique placeholder names found in the template
+
+**`getTemplate(name: string)`**
+
+Retrieves a registered template by name. Returns `undefined` if the template does not exist.
+
+**`listTemplates()`**
+
+Returns an array of all registered templates (values from the internal `Map`).
+
+**`hasTemplate(name: string)`**
+
+Checks if a template with the given name exists in the registry.
+
+**`removeTemplate(name: string)`**
+
+Removes a template from the registry. Logs the removal. Returns `true` if the template was found and removed, `false` otherwise.
+
+### ITemplate Interface
+
+```typescript
+interface ITemplate {
+  name: string;
+  content?: string;
+  render?: (data: Record<string, AnyType>) => string;
+  subject?: string;
+  description?: string;
+}
+```
+
+The `render` function on the interface supports custom render implementations, though the built-in `TemplateEngineService` uses `content` + `renderSimpleTemplate()` instead.
+
+## Additional Interfaces
+
+### IMailSendResult
+
+```typescript
+interface IMailSendResult {
+  success: boolean;
+  messageId?: string;
+  response?: any;
+  error?: string;
+}
+```
+
+Returned by `send()` and individual entries in the `sendBatch()` result array. Transport-level errors populate `error` with the message string.
+
+### IMailQueueExecutor
+
+```typescript
+interface IMailQueueExecutor {
+  enqueueVerificationEmail(email: string, options?: IMailQueueOptions): Promise<IMailQueueResult>;
+  setProcessor(processor: (email: string) => Promise<IMailProcessorResult>): void;
+}
+```
+
+### IMailQueueOptions
+
+```typescript
+interface IMailQueueOptions {
+  priority?: number;
+  delay?: number;
+  attempts?: number;
+  backoff?: {
+    type: 'fixed' | 'exponential';
+    delay: number;
+  };
+}
+```
+
+### IMailQueueResult
+
+```typescript
+interface IMailQueueResult {
+  jobId?: string;
+  queued: boolean;
+  message: string;
+  result?: IMailProcessorResult;
+}
+```
+
+Returned by `enqueueVerificationEmail()`. The `queued` field is `false` for direct execution, `true` for internal queue and BullMQ. The `result` field is populated only for direct execution (since the processor runs synchronously).
+
+### IMailProcessorResult
+
+```typescript
+interface IMailProcessorResult {
+  success: boolean;
+  message: string;
+  expiresInMinutes: number;
+  nextResendAt?: string;
+}
+```
+
+The return type of the processor function registered via `setProcessor()`.
+
+### IVerificationData
+
+```typescript
+interface IVerificationData {
+  verificationCode: string;
+  codeGeneratedAt: string;
+  codeExpiresAt: string;
+  codeAttempts: number;
+  verificationToken: string;
+  tokenGeneratedAt: string;
+  tokenExpiresAt: string;
+  lastCodeSentAt: string;
+}
+```
+
+### IVerificationGenerationOptions
+
+```typescript
+interface IVerificationGenerationOptions {
+  codeLength: number;
+  tokenBytes: number;
+  codeExpiryMinutes: number;
+  tokenExpiryHours: number;
+}
+```
+
+All fields are required. Passed to `DefaultVerificationDataGenerator.generateVerificationData()`.
+
+### IBullMQMailExecutorOpts
+
+```typescript
+interface IBullMQMailExecutorOpts {
+  redis: IRedisHelperOptions;
+  queue: { identifier: string; name: string };
+  mode: TConstValue<typeof BullMQExecutorModes>; // REQUIRED
+}
+```
+
+The `mode` field is **required** -- there is no default value. This is the config object for `IMailQueueExecutorConfig.bullmq`.
+
+### BullMQ Dynamic Worker Management Methods
+
+Dynamic worker management methods (on `BullMQMailExecutorHelper`, not on the interface):
+
+- **`addWorker(opts)`** -- Adds a new BullMQ worker with configurable concurrency (default 5) and lock duration (default 30000ms). Requires `setProcessor()` to have been called first. Each worker gets a unique identifier
+- **`removeWorker(index)`** -- Removes a worker by its array index. Calls `worker.close()` before removal. Returns `false` if the index is out of range
+- **`clearWorkers()`** -- Closes all workers and empties the worker array. Called internally by `setProcessor()` before creating new workers
+- **`getWorkerCount()`** -- Returns the current number of active workers
+- **`getMode()`** -- Returns the current executor mode
+
+**Extended `setProcessor()` signature (BullMQ only):**
+
+Unlike the interface's synchronous `setProcessor()`, the BullMQ executor's version is `async` and accepts an optional second argument:
+
+```typescript
+async setProcessor(
+  processor: (email: string) => Promise<IMailProcessorResult>,
+  opts?: {
+    numberOfWorkers?: number;       // default: 1
+    concurrencyPerWorker?: number;  // default: 5
+    lockDuration?: number;          // default: 30000 (ms)
+  },
+): Promise<void>
+```
+
+It clears all existing workers before creating new ones. In `queue-only` mode, it stores the processor but skips worker creation entirely (logs a warning).
+
+## Utility Functions
+
+### Type Utilities
+
+```typescript
+// Check if a value implements IMailTransport
+function isMailTransport(value: AnyType): value is IMailTransport;
+
+// Check if a value is valid TMailOptions
+function isValidMailOptions(options: AnyType): options is TMailOptions;
+```
+
+`isMailTransport()` checks for `send` and `verify` as functions, and `close` as either a function or undefined.
+
+`isValidMailOptions()` checks for a string `provider` field and a truthy `config` field.
+
+### Verification Utilities
+
+```typescript
+// Get a Date object `minutes` minutes in the future
+function getExpiryTime(minutes: number): Date;
+
+// Get a Date object `hours` hours in the future
+function getExpiryTimeInHours(hours: number): Date;
+```
+
+## See Also
+
+- [Setup & Configuration](./) -- Quick reference, setup steps, configuration options, and binding keys
+- [Usage & Examples](./usage) -- Sending emails, templates, queue executors, and verification
+- [Error Reference](./errors) -- Error codes and troubleshooting

package/wiki/references/components/mail/errors.md

@@ -0,0 +1,176 @@
+# Mail -- Error Reference & Troubleshooting
+
+> Complete error code reference and troubleshooting guide for the Mail component.
+
+## Error Reference
+
+All errors are created via `getError()` and include `statusCode`, `messageCode`, and `message` fields.
+
+### MailService Errors
+
+| Condition | Status | Error Code | Message |
+|-----------|--------|-----------|---------|
+| `to` is missing or empty array | 400 | `MAIL_INVALID_RECIPIENT` | `Recipient email address is required` |
+| `subject` is falsy | 400 | `MAIL_INVALID_CONFIGURATION` | `Email subject is required` |
+| Both `text` and `html` are falsy | 400 | `MAIL_INVALID_CONFIGURATION` | `Email must have either text or html content` |
+| Transport throws during `send()` | 500 | `MAIL_SEND_FAILED` | `Failed to send email: <error>` |
+| Batch operation fails | 500 | `MAIL_BATCH_SEND_FAILED` | `Failed to send batch emails: <error>` |
+| Template engine not configured for `sendTemplate()` | 500 | `MAIL_INVALID_CONFIGURATION` | `Template engine not configured` |
+| Transport throws during `verify()` | 500 | `MAIL_VERIFICATION_FAILED` | `Mail transport verification failed: <error>` |
+
+### MailComponent Errors
+
+| Condition | Status | Error Code | Message |
+|-----------|--------|-----------|---------|
+| `MAIL_OPTIONS` not bound | -- | -- | `Mail options not configured` |
+
+### MailTransportProvider Errors
+
+| Condition | Status | Error Code | Message |
+|-----------|--------|-----------|---------|
+| Unsupported provider string | 500 | `MAIL_INVALID_CONFIGURATION` | `Unsupported mail provider: <provider>` |
+| Nodemailer options fail type guard | 500 | `MAIL_INVALID_CONFIGURATION` | `Invalid Nodemailer configuration` |
+| Mailgun options fail type guard | 500 | `MAIL_INVALID_CONFIGURATION` | `Invalid Mailgun configuration` |
+| Custom options fail type guard | 500 | `MAIL_INVALID_CONFIGURATION` | `Invalid custom mail provider configuration` |
+| Custom config missing `send`/`verify` | 500 | `MAIL_INVALID_CONFIGURATION` | `Custom mail provider must implement IMailTransport interface. Missing methods: <methods>` |
+
+### MailQueueExecutorProvider Errors
+
+| Condition | Status | Error Code | Message |
+|-----------|--------|-----------|---------|
+| `config.internalQueue` missing for `internal-queue` type | -- | -- | `Internal queue configuration is missing` |
+| `config.bullmq` missing for `bullmq` type | -- | -- | `BullMQ configuration is missing` |
+| Unknown executor type | -- | -- | `Unknown mail queue executor type: <type>` |
+
+### TemplateEngineService Errors
+
+| Condition | Status | Error Code | Message |
+|-----------|--------|-----------|---------|
+| Neither `templateName` nor `templateData` provided | -- | -- | `Either templateName or templateData must be provided` |
+| Template name not found in registry | 404 | `TEMPLATE_NOT_FOUND` | `Template not found: <name>` |
+| Missing template data keys (with `requireValidate: true`) | 400 | `MAIL_INVALID_CONFIGURATION` | `Missing template data for keys: <keys>` |
+
+### Queue Executor Errors
+
+| Condition | Executor | Message |
+|-----------|----------|---------|
+| Processor not set before enqueue | Direct, Internal Queue, BullMQ | `Processor not set. Call setProcessor() first.` |
+| Processor not set before adding worker | BullMQ | `Processor not set. Call setProcessor() first.` |
+| Enqueue in worker-only mode | BullMQ | `Cannot enqueue jobs in worker-only mode. Set mode to "queue-only" or "both".` |
+| Queue helper unexpectedly null | BullMQ | `Queue helper not initialized. This should not happen in queue-enabled mode.` |
+
+## Troubleshooting
+
+### "Mail options not configured"
+
+**Cause:** `MailKeys.MAIL_OPTIONS` was not bound in the DI container before `MailComponent` was registered. The component checks `isBound()` in its `binding()` phase and throws immediately.
+
+**Fix:** Ensure the options binding exists before calling `this.application.component(MailComponent)`:
+
+```typescript
+this.application.bind({ key: MailKeys.MAIL_OPTIONS }).toValue({
+  provider: MailProviders.NODEMAILER,
+  from: 'noreply@example.com',
+  config: { host: 'smtp.example.com', port: 587, secure: false, auth: { user: '...', pass: '...' } },
+});
+
+// Then register the component
+this.application.component(MailComponent);
+```
+
+### "TEMPLATE_NOT_FOUND" when calling `sendTemplate()`
+
+**Cause:** The template name passed to `sendTemplate()` was never registered via `templateEngine.registerTemplate()`.
+
+**Fix:** Register the template before sending. If templates are loaded from a database, ensure the sync runs before the first `sendTemplate()` call:
+
+```typescript
+this.templateEngine.registerTemplate({
+  name: 'welcome-email',
+  content: '<h1>Welcome {{userName}}</h1>',
+});
+```
+
+### Emails silently fail with `success: false`
+
+**Cause:** The transport connection is misconfigured (wrong credentials, blocked port, expired OAuth2 token). The `MailService.send()` method catches transport errors and returns `{ success: false, error: '...' }` rather than throwing.
+
+**Fix:** Check `result.error` for the specific transport error. Verify transport on startup:
+
+```typescript
+const isConnected = await this.mailService.verify();
+if (!isConnected) {
+  this.logger.error('Mail transport verification failed');
+}
+```
+
+### BullMQ executor not processing jobs
+
+**Cause:** The `mode` is set to `'queue-only'` which only enqueues jobs without starting a worker, or the Redis connection is unreachable.
+
+**Fix:** Ensure `mode` is `'both'` or `'worker-only'` on the instance that should process jobs. Verify Redis connectivity:
+
+```typescript
+{
+  type: 'bullmq',
+  bullmq: {
+    redis: { host: 'localhost', port: 6379, /* ... */ },
+    queue: { identifier: 'mail-queue', name: 'mail-queue' },
+    mode: 'both', // Must be 'both' or 'worker-only' to process
+  },
+}
+```
+
+### Template variables not replaced (placeholders preserved)
+
+**Cause:** The `data` object passed to `render()` or `sendTemplate()` does not contain all <code v-pre>{{key}}</code> placeholders found in the template. When `requireValidate` is **not** set (or set to `false`), the template engine preserves the original placeholder text as-is (e.g., <code v-pre>{{missingKey}}</code> remains literally in the output). It does **not** replace missing variables with empty strings.
+
+**Fix:** Use `validateTemplateData()` to check which keys are missing before rendering:
+
+```typescript
+const validation = this.templateEngine.validateTemplateData({ template, data });
+if (!validation.isValid) {
+  console.error('Missing keys:', validation.missingKeys);
+}
+```
+
+Or set `requireValidate: true` to throw an error when keys are missing:
+
+```typescript
+const html = this.templateEngine.render({
+  templateName: 'welcome-email',
+  data,
+  requireValidate: true, // Throws if any placeholders are missing
+});
+```
+
+### "Processor not set. Call setProcessor() first."
+
+**Cause:** The queue executor's `enqueueVerificationEmail()` was called before `setProcessor()`. All three executor types (Direct, Internal Queue, BullMQ) require a processor function to be registered first.
+
+**Fix:** Call `setProcessor()` before enqueuing any jobs:
+
+```typescript
+executor.setProcessor(async (email: string) => {
+  // Your email processing logic here
+  return { success: true, message: 'Verification email sent', expiresInMinutes: 10 };
+});
+```
+
+### "Cannot enqueue jobs in worker-only mode"
+
+**Cause:** The BullMQ executor is configured with `mode: 'worker-only'`, which does not initialize a queue and therefore cannot accept new jobs.
+
+**Fix:** Use `mode: 'both'` or `mode: 'queue-only'` on instances that need to enqueue jobs. Use `mode: 'worker-only'` only on dedicated worker processes.
+
+### Credential logging at startup
+
+**Cause:** The `MailComponent.createAndBindInstances()` method logs the full `mailOptions` object (including credentials) at `info` level during initialization. This is by design for debugging, but it means sensitive values like API keys, passwords, and OAuth tokens will appear in logs.
+
+**Fix:** In production, either use a log level higher than `info` for the mail component scope, or ensure your log pipeline redacts sensitive fields.
+
+## See Also
+
+- [Setup & Configuration](./) -- Quick reference, setup steps, configuration options, and binding keys
+- [Usage & Examples](./usage) -- Sending emails, templates, queue executors, and verification
+- [API Reference](./api) -- Architecture, interfaces, and internals