@nauth-toolkit/core 0.1.13 → 0.1.17

package/dist/interfaces/sms-template.interface.js

@@ -1,10 +1,36 @@
 "use strict";
+/**
+ * SMS Template System Interfaces
+ *
+ * Provides flexible template system for SMS notifications with support for:
+ * - Text templates with placeholder tokens ({{variable}})
+ * - Built-in and custom variables
+ * - Multiple template types (verification, MFA, password reset)
+ * - Handlebars syntax for template rendering
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SMSTemplateType = void 0;
+/**
+ * SMS Template Type
+ *
+ * Enum of available SMS template types
+ */
 var SMSTemplateType;
 (function (SMSTemplateType) {
+    /**
+     * Phone verification code template
+     * Required variables: {{code}}, {{expiryMinutes}}
+     */
     SMSTemplateType["VERIFICATION"] = "verification";
+    /**
+     * MFA code template
+     * Required variables: {{code}}, {{expiryMinutes}}
+     */
     SMSTemplateType["MFA"] = "mfa";
+    /**
+     * Password reset code template
+     * Required variables: {{code}}, {{expiryMinutes}}
+     */
     SMSTemplateType["PASSWORD_RESET"] = "passwordReset";
 })(SMSTemplateType || (exports.SMSTemplateType = SMSTemplateType = {}));
 //# sourceMappingURL=sms-template.interface.js.map

package/dist/interfaces/sms-template.interface.js.map

@@ -1 +1 @@
-{"version":3,"file":"sms-template.interface.js","sourceRoot":"","sources":["../../src/interfaces/sms-template.interface.ts"],"names":[],"mappings":";;;AAeA,IAAY,eAkBX;AAlBD,WAAY,eAAe;IAKzB,gDAA6B,CAAA;IAM7B,8BAAW,CAAA;IAMX,mDAAgC,CAAA;AAClC,CAAC,EAlBW,eAAe,+BAAf,eAAe,QAkB1B"}
+{"version":3,"file":"sms-template.interface.js","sourceRoot":"","sources":["../../src/interfaces/sms-template.interface.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAEH;;;;GAIG;AACH,IAAY,eAkBX;AAlBD,WAAY,eAAe;IACzB;;;OAGG;IACH,gDAA6B,CAAA;IAE7B;;;OAGG;IACH,8BAAW,CAAA;IAEX;;;OAGG;IACH,mDAAgC,CAAA;AAClC,CAAC,EAlBW,eAAe,+BAAf,eAAe,QAkB1B"}

package/dist/interfaces/social-auth-provider.interface.d.ts

@@ -1,13 +1,128 @@
 import { AuthResponseDTO } from '../dto';
 import { OAuthUserProfile } from '../interfaces/oauth.interface';
+/**
+ * Social Auth Provider Service Interface
+ *
+ * Defines the contract for social authentication provider services.
+ * Each provider (Google, Apple, Facebook, etc.) must implement this interface
+ * to be registered with the core SocialAuthService.
+ *
+ * This allows for:
+ * - Modular provider imports (only install what you need)
+ * - Consistent API across all providers
+ * - Proper NestJS dependency injection
+ * - Easy addition of new providers without modifying core code
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class GoogleSocialAuthService implements ISocialAuthProviderService {
+ *   readonly providerName = 'google';
+ *
+ *   async getAuthUrl(state?: string): Promise<string> {
+ *     // Generate Google OAuth URL
+ *   }
+ *
+ *   async handleCallback(code: string, state: string): Promise<AuthResponseDTO> {
+ *     // Handle Google OAuth callback
+ *   }
+ *
+ *   async verifyToken(idToken: string, accessToken?: string, profileData?: any): Promise<AuthResponseDTO> {
+ *     // Verify Google ID token
+ *   }
+ * }
+ * ```
+ */
 export interface ISocialAuthProviderService {
+    /**
+     * Provider name (e.g., 'google', 'apple', 'facebook')
+     * Used as the key in the provider registry
+     */
     readonly providerName: string;
+    /**
+     * Generate OAuth authorization URL for this provider
+     *
+     * @param state - Optional state parameter for CSRF protection
+     * @returns Authorization URL to redirect user to
+     * @throws {BadRequestException} When provider is not properly configured
+     *
+     * @example
+     * ```typescript
+     * const authUrl = await provider.getAuthUrl('random-state-123');
+     * // Redirect user to authUrl
+     * ```
+     */
     getAuthUrl(state?: string): Promise<string>;
+    /**
+     * Handle OAuth callback and authenticate user
+     *
+     * Exchanges authorization code for access token, fetches user profile,
+     * and returns unified authentication response with JWT tokens.
+     *
+     * @param code - Authorization code from OAuth callback
+     * @param state - State parameter from OAuth callback (for CSRF protection)
+     * @returns Unified authentication response with tokens and user info
+     * @throws {BadRequestException} When callback is invalid
+     *
+     * @example
+     * ```typescript
+     * const result = await provider.handleCallback(code, state);
+     * console.log(result.accessToken); // JWT access token
+     * console.log(result.user.email); // User email
+     * ```
+     */
     handleCallback(code: string, state: string): Promise<AuthResponseDTO>;
+    /**
+     * Verify social authentication token from native mobile apps
+     *
+     * Handles authentication tokens from native mobile apps (iOS/Android)
+     * that use native SDKs (Google Sign-In SDK, Apple Sign In, etc.)
+     *
+     * @param idToken - ID token from native SDK
+     * @param accessToken - Optional access token from native SDK
+     * @param profileData - Optional profile data from native SDK (for name extraction)
+     * @returns Unified authentication response with tokens and user info
+     * @throws {BadRequestException} When token is invalid
+     *
+     * @example
+     * ```typescript
+     * const result = await provider.verifyToken(idToken, accessToken, profileData);
+     * return result; // Same format as login/signup
+     * ```
+     */
     verifyToken(idToken: string, accessToken?: string, profileData?: any): Promise<AuthResponseDTO>;
+    /**
+     * Link social account to existing user
+     *
+     * Used when an authenticated user wants to link a social account
+     * to their existing account.
+     *
+     * @param userId - User ID (sub)
+     * @param code - Authorization code from OAuth callback
+     * @param state - State parameter from OAuth callback
+     * @returns Success message
+     * @throws {NotFoundException} When user is not found
+     * @throws {ConflictException} When account is already linked
+     *
+     * @example
+     * ```typescript
+     * await provider.linkAccount(userId, code, state);
+     * ```
+     */
     linkAccount(userId: string, code: string, state: string): Promise<{
         message: string;
     }>;
+    /**
+     * Get OAuth user profile from callback
+     *
+     * Internal method used by handleCallback to extract user profile.
+     * Exposed for advanced use cases.
+     *
+     * @param code - Authorization code from OAuth callback
+     * @param state - State parameter from OAuth callback
+     * @returns OAuth user profile
+     * @private
+     */
     getUserProfileFromCallback(code: string, state: string): Promise<OAuthUserProfile>;
 }
 //# sourceMappingURL=social-auth-provider.interface.d.ts.map

package/dist/interfaces/social-auth-provider.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"social-auth-provider.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/social-auth-provider.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAmCjE,MAAM,WAAW,0BAA0B;IAKzC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAe9B,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAoB5C,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAoBtE,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAoBhG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAavF,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACpF"}
+{"version":3,"file":"social-auth-provider.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/social-auth-provider.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5C;;;;;;;;;;;;;;;;;OAiBG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAEtE;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAEhG;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEvF;;;;;;;;;;OAUG;IACH,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACpF"}

package/dist/interfaces/storage-adapter.interface.d.ts

@@ -1,33 +1,70 @@
+/**
+ * Storage adapter interface for shared state management
+ * Critical for multi-server deployments
+ */
 export interface StorageAdapter {
+    /**
+     * Initialize the storage adapter
+     */
     initialize(): Promise<void>;
+    /**
+     * Check if adapter is healthy
+     */
     isHealthy(): Promise<boolean>;
+    /**
+     * Basic key-value operations
+     */
     get(key: string): Promise<string | null>;
     set(key: string, value: string, ttlSeconds?: number, options?: {
         nx?: boolean;
     }): Promise<string | null | void>;
     del(key: string): Promise<void>;
     exists(key: string): Promise<boolean>;
+    /**
+     * Atomic operations
+     */
     incr(key: string, ttlSeconds?: number): Promise<number>;
     decr(key: string): Promise<number>;
     expire(key: string, ttl: number): Promise<void>;
     ttl(key: string): Promise<number>;
+    /**
+     * Hash operations (for complex data structures)
+     */
     hget(key: string, field: string): Promise<string | null>;
     hset(key: string, field: string, value: string): Promise<void>;
     hgetall(key: string): Promise<Record<string, string>>;
     hdel(key: string, ...fields: string[]): Promise<number>;
+    /**
+     * List operations (for token families)
+     */
     lpush(key: string, value: string): Promise<void>;
     lrange(key: string, start: number, stop: number): Promise<string[]>;
     llen(key: string): Promise<number>;
+    /**
+     * Pattern operations
+     */
     keys(pattern: string): Promise<string[]>;
     scan(cursor: number, pattern: string, count: number): Promise<[number, string[]]>;
+    /**
+     * Cleanup and disconnect
+     */
     cleanup(): Promise<void>;
     disconnect(): Promise<void>;
 }
+/**
+ * Rate limiting specific operations
+ */
 export interface RateLimitStorage {
     incrementRateLimit(identifier: string, endpoint: string, windowMs: number): Promise<number>;
     getRateLimit(identifier: string, endpoint: string): Promise<number>;
     resetRateLimit(identifier: string, endpoint: string): Promise<void>;
 }
+/**
+ * Account lockout specific operations
+ *
+ * SECURITY: Uses IP addresses instead of user identifiers to prevent
+ * attackers from locking out legitimate users by guessing their email/username.
+ */
 export interface AccountLockoutStorage {
     recordFailedAttempt(ipAddress: string): Promise<number>;
     getFailedAttempts(ipAddress: string): Promise<number>;

package/dist/interfaces/storage-adapter.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-adapter.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/storage-adapter.interface.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"storage-adapter.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/storage-adapter.interface.ts"],"names":[],"mappings":"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"}

package/dist/interfaces/template.interface.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Email Template System Interfaces
+ *
+ * Provides flexible template system for email notifications with support for:
+ * - HTML templates with placeholder tokens ({{variable}})
+ * - Built-in and custom variables
+ * - Multiple template types (verification, password reset, etc.)
+ */
+/**
+ * Template Variables
+ *
+ * Variables that can be used in email templates.
+ * All variables are optional as not all templates use all variables.
+ */
 export interface TemplateVariables {
     appName?: string;
     userName?: string;
@@ -24,11 +38,32 @@ export interface TemplateVariables {
     footerDisclaimer?: string;
     [key: string]: string | number | boolean | undefined;
 }
+/**
+ * Email Template
+ *
+ * Defines the structure of an email template with subject and content.
+ * Both subject and content support placeholder variables.
+ */
 export interface EmailTemplate {
+    /**
+     * Email subject line (supports {{variables}})
+     */
     subject: string;
+    /**
+     * HTML content of the email (supports {{variables}})
+     */
     html: string;
+    /**
+     * Optional plain text version (supports {{variables}})
+     * Falls back to stripping HTML tags if not provided
+     */
     text?: string;
 }
+/**
+ * Template Type
+ *
+ * Enum of available email template types
+ */
 export declare enum TemplateType {
     VERIFICATION = "verification",
     PASSWORD_RESET = "passwordReset",
@@ -39,37 +74,177 @@ export declare enum TemplateType {
     EMAIL_CHANGED = "emailChanged",
     MFA_ENABLED = "mfaEnabled"
 }
+/**
+ * Template Source
+ *
+ * Defines how template content can be provided - as a string or file path
+ */
 export interface TemplateSource {
+    /**
+     * Template content as a string
+     */
     content?: string;
+    /**
+     * Path to template file (relative or absolute)
+     * Supports .hbs, .html, .txt, etc.
+     */
     filePath?: string;
 }
+/**
+ * Template Files
+ *
+ * Defines template files for subject, HTML, and text content.
+ * Used for file-based template registration.
+ *
+ * @example
+ * ```typescript
+ * const templateFiles: TemplateFiles = {
+ *   subject: { filePath: './templates/welcome.subject.hbs' },
+ *   html: { filePath: './templates/welcome.html.hbs' },
+ *   text: { filePath: './templates/welcome.text.hbs' }
+ * };
+ * ```
+ */
 export interface TemplateFiles {
+    /**
+     * Subject line template source
+     */
     subject: TemplateSource;
+    /**
+     * HTML content template source
+     */
     html: TemplateSource;
+    /**
+     * Plain text content template source (optional)
+     */
     text?: TemplateSource;
 }
+/**
+ * Template Engine Interface
+ *
+ * Contract for template engines that can render email templates with variables.
+ * Implementations can support HTML, MJML, Handlebars, or other template formats.
+ *
+ * @example
+ * ```typescript
+ * const engine = new HandlebarsTemplateEngine();
+ * const result = await engine.render(
+ *   TemplateType.VERIFICATION,
+ *   { userName: 'John', code: '123456' }
+ * );
+ * logger.debug('Subject:', result.subject); // "Verify your email - My App"
+ * logger.debug('HTML generated');    // HTML with variables replaced
+ * ```
+ */
 export interface TemplateEngine {
+    /**
+     * Render a template with the provided variables
+     *
+     * @param type - Type of template to render
+     * @param variables - Variables to inject into the template
+     * @returns Rendered email template with subject and content
+     *
+     * @throws {Error} If template type is not found
+     *
+     * @example
+     * ```typescript
+     * const result = await engine.render(
+     *   TemplateType.VERIFICATION,
+     *   {
+     *     userName: 'John Doe',
+     *     code: '123456',
+     *     expiryMinutes: 60
+     *   }
+     * );
+     * ```
+     */
     render(type: TemplateType | string, variables: TemplateVariables): Promise<EmailTemplate>;
+    /**
+     * Register a custom template from inline strings
+     *
+     * Allows overriding default templates or adding new ones.
+     *
+     * @param type - Template type identifier
+     * @param template - Template definition with inline content
+     *
+     * @example
+     * ```typescript
+     * engine.registerTemplate(TemplateType.WELCOME, {
+     *   subject: 'Welcome {{userName}}!',
+     *   html: '<h1>Hello {{userName}}!</h1>',
+     *   text: 'Hello {{userName}}!'
+     * });
+     * ```
+     */
     registerTemplate(type: TemplateType | string, template: EmailTemplate): void;
+    /**
+     * Register a custom template from mixed sources (strings or files)
+     *
+     * Flexible registration that supports both inline content and file paths.
+     *
+     * @param type - Template type identifier
+     * @param templateSources - Template sources (content or file paths)
+     *
+     * @example
+     * ```typescript
+     * engine.registerTemplateFromSources(TemplateType.WELCOME, {
+     *   subject: { content: 'Welcome {{userName}}!' },
+     *   html: { filePath: './templates/welcome.html.hbs' },
+     *   text: { content: 'Welcome {{userName}}!' }
+     * });
+     * ```
+     */
     registerTemplateFromSources?(type: TemplateType | string, templateSources: TemplateFiles): Promise<void>;
+    /**
+     * Get available template types
+     *
+     * @returns Array of registered template type identifiers
+     */
     getAvailableTemplates(): string[];
+    /**
+     * Check if a template exists
+     *
+     * @param type - Template type to check
+     * @returns True if template is registered
+     */
     hasTemplate(type: TemplateType | string): boolean;
 }
+/**
+ * Required template parameters for each template type
+ *
+ * Defines which variables MUST be present in custom templates.
+ * Optional variables (firstName, lastName, etc.) can be included but are not required.
+ */
 export interface TemplateRequiredParams {
+    /**
+     * Email verification template required parameters
+     */
     [TemplateType.VERIFICATION]: {
         code: string;
         link: string;
         expiryMinutes: number;
     };
+    /**
+     * Password reset template required parameters
+     */
     [TemplateType.PASSWORD_RESET]: {
         link: string;
         expiryMinutes: number;
     };
+    /**
+     * Welcome template required parameters
+     */
     [TemplateType.WELCOME]: Record<string, never>;
+    /**
+     * Account lockout template required parameters
+     */
     [TemplateType.ACCOUNT_LOCKOUT]: {
         reason: string;
         durationMinutes: number;
     };
+    /**
+     * New device template required parameters
+     */
     [TemplateType.NEW_DEVICE]: {
         deviceName: string;
         deviceType?: string;
@@ -77,22 +252,198 @@ export interface TemplateRequiredParams {
         location?: string;
         timestamp: string;
     };
+    /**
+     * Password changed template required parameters
+     */
     [TemplateType.PASSWORD_CHANGED]: Record<string, never>;
+    /**
+     * Email changed template required parameters
+     */
     [TemplateType.EMAIL_CHANGED]: {
         userEmail: string;
     };
+    /**
+     * MFA enabled template required parameters
+     */
     [TemplateType.MFA_ENABLED]: Record<string, never>;
 }
+/**
+ * Custom template definition with file paths or content
+ *
+ * Allows specifying templates as file paths or inline content.
+ * All templates support Handlebars syntax for dynamic content.
+ *
+ * @example
+ * ```typescript
+ * const customTemplate: CustomTemplateDefinition = {
+ *   htmlPath: './templates/verification.html.hbs',
+ *   // OR
+ *   html: '<html>{{code}}</html>',
+ *   // Optional text version
+ *   textPath: './templates/verification.text.hbs'
+ * };
+ * ```
+ */
 export interface CustomTemplateDefinition {
+    /**
+     * Path to HTML template file (supports frontmatter for subject)
+     * Mutually exclusive with `html`
+     */
     htmlPath?: string;
+    /**
+     * HTML template content as string (supports frontmatter for subject)
+     * Mutually exclusive with `htmlPath`
+     */
     html?: string;
+    /**
+     * Path to plain text template file
+     * Mutually exclusive with `text`
+     */
     textPath?: string;
+    /**
+     * Plain text template content as string
+     * Mutually exclusive with `textPath`
+     */
     text?: string;
+    /**
+     * Email subject (can include Handlebars variables)
+     * If not provided, will be extracted from HTML frontmatter
+     */
     subject?: string;
 }
+/**
+ * Template Configuration
+ *
+ * Configuration options for the template system.
+ * Used in AuthModule.forRoot() configuration.
+ *
+ * Custom templates are validated at startup to ensure they include
+ * all required parameters for their template type.
+ *
+ * @example
+ * ```typescript
+ * AuthModule.forRoot({
+ *   email: {
+ *     templates: {
+ *       // Global variables (optional, available to all templates)
+ *       globalVariables: {
+ *         appName: 'My Application',
+ *         companyName: 'My Company Inc.',
+ *         supportEmail: 'support@example.com',
+ *         brandColor: '#4CAF50',
+ *         logoUrl: 'https://example.com/logo.png'
+ *       },
+ *       // Custom templates (override defaults)
+ *       customTemplates: {
+ *         verification: {
+ *           htmlPath: './templates/verification.html.hbs',
+ *           textPath: './templates/verification.text.hbs'
+ *           // Must include: {{code}}, {{link}}, {{expiryMinutes}}
+ *         },
+ *         welcome: {
+ *           html: `
+ *             ---
+ *             subject: Welcome to {{appName}}!
+ *             ---
+ *             <h1>Hello {{firstName}}!</h1>
+ *           `,
+ *           // No required params for welcome
+ *         }
+ *       }
+ *     }
+ *   }
+ * })
+ * ```
+ */
 export interface TemplateConfig {
+    /**
+     * Template engine instance
+     *
+     * @default HandlebarsTemplateEngine with default templates
+     */
     engine?: TemplateEngine;
+    /**
+     * Global variables available to all templates
+     *
+     * These are merged with template-specific variables at render time.
+     * Template-specific variables take precedence over globals.
+     *
+     * Common global variables:
+     * - appName: Your application name
+     * - companyName: Your company name
+     * - supportEmail: Support contact email
+     * - brandColor: Primary brand color (hex)
+     * - logoUrl: URL to your logo image
+     * - dashboardUrl: URL to user dashboard
+     * - footerDisclaimer: Custom footer disclaimer text (optional, has default)
+     *
+     * Optional user-specific variables (injected at runtime):
+     * - firstName, lastName, userName: User information
+     * - currentYear: Current year (injected automatically)
+     *
+     * @example
+     * ```typescript
+     * globalVariables: {
+     *   appName: process.env.APP_NAME || 'My App',
+     *   companyName: 'My Company Inc.',
+     *   supportEmail: 'support@example.com',
+     *   brandColor: '#4f46e5',
+     *   logoUrl: 'https://example.com/logo.png'
+     * }
+     * ```
+     */
     globalVariables?: TemplateVariables;
+    /**
+     * Custom template definitions
+     *
+     * Override default templates or add new ones.
+     * Templates are validated at startup to ensure required parameters are present.
+     *
+     * Key is the template type, value is the template definition.
+     * Templates can be provided as file paths or inline content.
+     *
+     * All templates support Handlebars syntax:
+     * - {{variable}}: Insert variable
+     * - {{#if variable}}...{{/if}}: Conditional
+     * - {{#each items}}...{{/each}}: Loop
+     *
+     * Required parameters by template type:
+     * - verification: {{code}}, {{link}}, {{expiryMinutes}}
+     * - passwordReset: {{link}}, {{expiryMinutes}}
+     * - accountLockout: {{reason}}, {{durationMinutes}}
+     * - newDevice: {{deviceName}}, {{timestamp}}
+     * - emailChanged: {{userEmail}}
+     * - welcome, passwordChanged, mfaEnabled: No required params
+     *
+     * @example
+     * ```typescript
+     * customTemplates: {
+     *   // File-based template (with frontmatter for subject)
+     *   verification: {
+     *     htmlPath: './templates/verification.html.hbs',
+     *     textPath: './templates/verification.text.hbs'
+     *   },
+     *   // Inline template (with frontmatter for subject)
+     *   welcome: {
+     *     html: `
+     *       ---
+     *       subject: Welcome to {{appName}}!
+     *       ---
+     *       <html>
+     *         <h1>Hello {{firstName}}!</h1>
+     *         <p>Welcome to our platform!</p>
+     *       </html>
+     *     `
+     *   },
+     *   // Mixed (HTML from file, explicit subject)
+     *   passwordReset: {
+     *     subject: 'Reset your password - {{appName}}',
+     *     htmlPath: './templates/password-reset.html.hbs',
+     *     text: 'Reset link: {{link}} (expires in {{expiryMinutes}} minutes)'
+     *   }
+     * }
+     * ```
+     */
     customTemplates?: Record<string, CustomTemplateDefinition>;
 }
 //# sourceMappingURL=template.interface.d.ts.map