@nauth-toolkit/core 0.1.14 → 0.1.17

package/dist/interfaces/mfa-provider.interface.d.ts

@@ -1,11 +1,145 @@
 import { IUser } from './entities.interface';
+/**
+ * MFA Provider Service Interface
+ *
+ * Defines the contract that all MFA provider services must implement.
+ * Each MFA method (TOTP, SMS, Passkey) is a separate provider that extends
+ * the base class and implements this interface.
+ *
+ * Provider-specific types (e.g., SetupTOTPResponseDTO) are defined in each
+ * provider package, not in core, to maintain proper separation of concerns.
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class TOTPMFAProviderService extends BaseMFAProviderService implements IMFAProviderService {
+ *   readonly methodName = 'totp';
+ *
+ *   async setup(user: IUser): Promise<unknown> {
+ *     // TOTP-specific setup logic
+ *   }
+ *
+ *   async verify(user: IUser, code: string, deviceId?: number): Promise<boolean> {
+ *     // TOTP verification logic
+ *   }
+ * }
+ * ```
+ */
 export interface IMFAProviderService {
+    /**
+     * Unique method name for this MFA provider
+     * Examples: 'totp', 'sms', 'passkey'
+     */
     readonly methodName: string;
+    /**
+     * Check if this MFA method is allowed by configuration
+     *
+     * @returns True if method is allowed
+     */
     isMethodAllowed(): boolean;
+    /**
+     * Setup MFA device for user
+     *
+     * Initiates the setup process for this MFA method.
+     * Provider-specific setup data is returned.
+     *
+     * @param user - User setting up MFA
+     * @returns Provider-specific setup data (e.g., QR code for TOTP, options for Passkey)
+     * @throws {NAuthException} If method is not allowed or setup fails
+     *
+     * @example
+     * ```typescript
+     * // TOTP provider returns { secret, qrCode, manualEntryKey }
+     * const setupData = await totpProvider.setup(user);
+     *
+     * // Passkey provider returns WebAuthn registration options
+     * const options = await passkeyProvider.setup(user);
+     * ```
+     */
     setup(user: IUser, setupData?: unknown): Promise<unknown>;
+    /**
+     * Verify and complete MFA setup
+     *
+     * Validates the verification code/credential and creates the MFA device.
+     *
+     * @param user - User completing setup
+     * @param verificationData - Provider-specific verification data (code, credential, etc.)
+     * @param deviceName - Optional device name
+     * @returns Created MFA device ID
+     * @throws {NAuthException} If verification fails
+     *
+     * @example
+     * ```typescript
+     * // TOTP: verificationData = { secret, code }
+     * const deviceId = await totpProvider.verifySetup(user, { secret: '...', code: '123456' });
+     *
+     * // SMS: verificationData = { phoneNumber, code }
+     * const deviceId = await smsProvider.verifySetup(user, { phoneNumber: '+1234567890', code: '123456' });
+     *
+     * // Passkey: verificationData = { credential, challenge }
+     * const deviceId = await passkeyProvider.verifySetup(user, { credential: {...}, challenge: '...' });
+     * ```
+     */
     verifySetup(user: IUser, verificationData: unknown, deviceName?: string): Promise<number>;
+    /**
+     * Verify MFA code/credential during authentication
+     *
+     * Validates the MFA code or credential for an existing device.
+     *
+     * @param user - User being authenticated
+     * @param code - MFA code or credential (provider-specific)
+     * @param deviceId - Optional device ID to verify against (if not provided, finds active device)
+     * @returns True if verification succeeds
+     * @throws {NAuthException} If device not found or verification fails
+     *
+     * @example
+     * ```typescript
+     * // TOTP: code = '123456'
+     * const isValid = await totpProvider.verify(user, '123456');
+     *
+     * // SMS: code = '123456'
+     * const isValid = await smsProvider.verify(user, '123456');
+     *
+     * // Passkey: code = { credential: {...}, challenge: '...' }
+     * const isValid = await passkeyProvider.verify(user, { credential: {...}, challenge: '...' });
+     * ```
+     */
     verify(user: IUser, code: unknown, deviceId?: number): Promise<boolean>;
+    /**
+     * Send verification code/challenge for authentication
+     *
+     * Used during login to send SMS code or generate passkey challenge.
+     * Not applicable for TOTP (user generates code locally).
+     *
+     * @param user - User requesting verification
+     * @returns Provider-specific challenge data (e.g., masked phone for SMS, WebAuthn options for Passkey)
+     * @throws {NAuthException} If no device registered or send fails
+     *
+     * @example
+     * ```typescript
+     * // SMS: returns masked phone number
+     * const maskedPhone = await smsProvider.sendChallenge(user); // '***-***-1234'
+     *
+     * // Passkey: returns WebAuthn authentication options
+     * const options = await passkeyProvider.sendChallenge(user); // { challenge: '...', ... }
+     * ```
+     */
     sendChallenge?(user: IUser): Promise<unknown>;
+    /**
+     * Generate backup codes for user
+     *
+     * Creates single-use recovery codes that can be used when MFA devices are unavailable.
+     * Provided by BaseMFAProviderService for all providers.
+     *
+     * @param user - User to generate codes for
+     * @returns Generated backup codes (plain text - shown only once)
+     *
+     * @example
+     * ```typescript
+     * const codes = await provider.generateBackupCodes?.(user);
+     * // Returns: ['ABC12345', 'DEF67890', ...]
+     * ```
+     */
     generateBackupCodes?(user: IUser): Promise<string[]>;
 }
 export type MFAProviderWithChallenge = IMFAProviderService & Required<Pick<IMFAProviderService, 'sendChallenge'>>;

package/dist/interfaces/mfa-provider.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mfa-provider.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/mfa-provider.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AA4B7C,MAAM,WAAW,mBAAmB;IAKlC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAO5B,eAAe,IAAI,OAAO,CAAC;IAqB3B,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAyB1D,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAyB1F,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAqBxE,aAAa,CAAC,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAiB9C,mBAAmB,CAAC,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACtD;AAGD,MAAM,MAAM,wBAAwB,GAAG,mBAAmB,GAAG,QAAQ,CAAC,IAAI,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAAC,CAAC"}
+{"version":3,"file":"mfa-provider.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/mfa-provider.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;OAIG;IACH,eAAe,IAAI,OAAO,CAAC;IAE3B;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE1D;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE1F;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAExE;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE9C;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,CAAC,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACtD;AAGD,MAAM,MAAM,wBAAwB,GAAG,mBAAmB,GAAG,QAAQ,CAAC,IAAI,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAAC,CAAC"}

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

@@ -1,24 +1,134 @@
+/**
+ * OAuth User Profile Interface
+ * Standardized user profile data from OAuth providers
+ *
+ * @example
+ * ```typescript
+ * const profile: OAuthUserProfile = {
+ *   id: 'google_123',
+ *   email: 'user@gmail.com',
+ *   firstName: 'John',
+ *   lastName: 'Doe',
+ *   picture: 'https://...',
+ *   verified: true
+ * };
+ * ```
+ */
 export interface OAuthUserProfile {
+    /**
+     * Provider's unique identifier for the user
+     * Examples: Google sub, Apple user ID, Facebook ID
+     */
     id: string;
+    /**
+     * User's email address
+     * May be null if not provided by provider
+     */
     email?: string | null;
+    /**
+     * User's first name
+     * May be null if not provided by provider
+     */
     firstName?: string | null;
+    /**
+     * User's last name
+     * May be null if not provided by provider
+     */
     lastName?: string | null;
+    /**
+     * User's profile picture URL
+     * May be null if not provided by provider
+     */
     picture?: string | null;
+    /**
+     * Whether the email is verified by the provider
+     * @default false
+     */
     verified?: boolean;
+    /**
+     * Additional provider-specific data
+     * Contains raw response from OAuth provider
+     */
     raw?: Record<string, unknown>;
 }
+/**
+ * OAuth Client Interface
+ * Defines the contract for OAuth provider clients
+ *
+ * @example
+ * ```typescript
+ * class GoogleOAuthClient implements OAuthClient {
+ *   async getUserProfile(accessToken: string): Promise<OAuthUserProfile> {
+ *     // Implementation for Google
+ *   }
+ * }
+ * ```
+ */
 export interface OAuthClient {
+    /**
+     * Get user profile from OAuth provider using access token
+     *
+     * @param accessToken - OAuth access token
+     * @returns User profile data
+     * @throws {Error} When API call fails or token is invalid
+     *
+     * @example
+     * ```typescript
+     * const profile = await oauthClient.getUserProfile(accessToken);
+     * console.log(profile.email); // user@example.com
+     * ```
+     */
     getUserProfile(accessToken: string): Promise<OAuthUserProfile>;
+    /**
+     * Exchange authorization code for access token
+     *
+     * @param code - Authorization code from OAuth callback
+     * @param redirectUri - Redirect URI used in OAuth flow
+     * @returns Access token and optional refresh token
+     * @throws {Error} When token exchange fails
+     *
+     * @example
+     * ```typescript
+     * const tokens = await oauthClient.exchangeCodeForToken(code, redirectUri);
+     * console.log(tokens.accessToken); // access_token_here
+     * ```
+     */
     exchangeCodeForToken(code: string, redirectUri: string): Promise<{
         accessToken: string;
         refreshToken?: string;
         expiresIn?: number;
     }>;
 }
+/**
+ * OAuth Configuration Interface
+ * Configuration for OAuth clients
+ *
+ * @example
+ * ```typescript
+ * const config: OAuthConfig = {
+ *   clientId: 'google_client_id',
+ *   clientSecret: 'google_client_secret',
+ *   redirectUri: 'https://myapp.com/auth/google/callback'
+ * };
+ * ```
+ */
 export interface OAuthConfig {
+    /**
+     * OAuth client ID
+     */
     clientId: string;
+    /**
+     * OAuth client secret
+     */
     clientSecret: string;
+    /**
+     * OAuth redirect URI
+     */
     redirectUri: string;
+    /**
+     * OAuth scopes
+     * @default ['openid', 'email', 'profile']
+     */
     scopes?: string[];
 }
 //# sourceMappingURL=oauth.interface.d.ts.map

package/dist/interfaces/oauth.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/oauth.interface.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,gBAAgB;IAK/B,EAAE,EAAE,MAAM,CAAC;IAMX,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAMtB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAM1B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAMzB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAMxB,QAAQ,CAAC,EAAE,OAAO,CAAC;IAMnB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAeD,MAAM,WAAW,WAAW;IAc1B,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAgB/D,oBAAoB,CAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;QACT,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;CACJ;AAeD,MAAM,WAAW,WAAW;IAI1B,QAAQ,EAAE,MAAM,CAAC;IAKjB,YAAY,EAAE,MAAM,CAAC;IAKrB,WAAW,EAAE,MAAM,CAAC;IAMpB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB"}
+{"version":3,"file":"oauth.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/oauth.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEtB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAExB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAE/D;;;;;;;;;;;;;OAaG;IACH,oBAAoB,CAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;QACT,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;CACJ;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB"}

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

@@ -1,14 +1,97 @@
+/**
+ * Email provider interface for sending emails
+ */
 export interface EmailProvider {
+    /**
+     * Send email verification code/link
+     * @param to - Recipient email address
+     * @param code - Verification code (e.g., "123456")
+     * @param link - Optional verification link (only sent if provided by consumer app)
+     */
     sendVerificationEmail(to: string, code: string, link?: string): Promise<void>;
+    /**
+     * Send password reset email
+     */
     sendPasswordResetEmail(to: string, token: string, link: string): Promise<void>;
+    /**
+     * Send welcome email
+     */
     sendWelcomeEmail(to: string, name: string): Promise<void>;
+    /**
+     * Send account lockout notification
+     */
     sendLockoutEmail?(to: string, reason: string, duration: number): Promise<void>;
+    /**
+     * Send new device login notification
+     */
     sendNewDeviceEmail?(to: string, deviceInfo: any, location?: any): Promise<void>;
 }
+/**
+ * SMS provider interface for sending text messages
+ */
 export interface SMSProvider {
+    /**
+     * Send OTP code via SMS
+     *
+     * @param phone - Recipient phone number in E.164 format
+     * @param code - OTP code to send
+     * @param templateType - Optional template type (verification, mfa, passwordReset)
+     * @param variables - Optional template variables (expiryMinutes, appName, etc.)
+     *
+     * @example
+     * ```typescript
+     * await provider.sendOTP('+1234567890', '123456');
+     * // With template support:
+     * await provider.sendOTP('+1234567890', '123456', 'verification', { expiryMinutes: 5 });
+     * ```
+     */
     sendOTP(phone: string, code: string, templateType?: string, variables?: Record<string, unknown>): Promise<void>;
+    /**
+     * Send verification code
+     *
+     * Alias for sendOTP(). Sends the same SMS message.
+     *
+     * @param phone - Recipient phone number in E.164 format
+     * @param code - Verification code to send
+     *
+     * @example
+     * ```typescript
+     * await provider.sendVerificationCode('+1234567890', '123456');
+     * ```
+     */
     sendVerificationCode?(phone: string, code: string): Promise<void>;
+    /**
+     * Set template engine for SMS message customization
+     *
+     * Optional method to enable template-based SMS messages.
+     * If not set, provider will use hard-coded default messages.
+     *
+     * @param engine - SMS template engine instance
+     *
+     * @example
+     * ```typescript
+     * const engine = new SMSTemplateEngine();
+     * provider.setTemplateEngine(engine);
+     * ```
+     */
     setTemplateEngine?(engine: import('./sms-template.interface').SMSTemplateEngine): void;
+    /**
+     * Set global variables for SMS templates
+     *
+     * Optional method to set global variables (appName, companyName, etc.)
+     * that will be available to all SMS templates.
+     *
+     * @param variables - Global template variables
+     *
+     * @example
+     * ```typescript
+     * provider.setGlobalVariables({
+     *   appName: 'My App',
+     *   companyName: 'My Company Inc.',
+     *   supportPhone: '+1-800-123-4567',
+     * });
+     * ```
+     */
     setGlobalVariables?(variables: import('./sms-template.interface').SMSTemplateVariables): void;
 }
 //# sourceMappingURL=provider.interface.d.ts.map

package/dist/interfaces/provider.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/provider.interface.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,aAAa;IAO5B,qBAAqB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAK9E,sBAAsB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAK/E,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAK1D,gBAAgB,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAK/E,kBAAkB,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjF;AAKD,MAAM,WAAW,WAAW;IAgB1B,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAehH,oBAAoB,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAgBlE,iBAAiB,CAAC,CAAC,MAAM,EAAE,OAAO,0BAA0B,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAmBvF,kBAAkB,CAAC,CAAC,SAAS,EAAE,OAAO,0BAA0B,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAC/F"}
+{"version":3,"file":"provider.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/provider.interface.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9E;;OAEG;IACH,sBAAsB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/E;;OAEG;IACH,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1D;;OAEG;IACH,gBAAgB,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/E;;OAEG;IACH,kBAAkB,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjF;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhH;;;;;;;;;;;;OAYG;IACH,oBAAoB,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElE;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,CAAC,MAAM,EAAE,OAAO,0BAA0B,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAEvF;;;;;;;;;;;;;;;;OAgBG;IACH,kBAAkB,CAAC,CAAC,SAAS,EAAE,OAAO,0BAA0B,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAC/F"}

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

@@ -1,8 +1,40 @@
+/**
+ * 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
+ */
+/**
+ * SMS Template Type
+ *
+ * Enum of available SMS template types
+ */
 export declare enum SMSTemplateType {
+    /**
+     * Phone verification code template
+     * Required variables: {{code}}, {{expiryMinutes}}
+     */
     VERIFICATION = "verification",
+    /**
+     * MFA code template
+     * Required variables: {{code}}, {{expiryMinutes}}
+     */
     MFA = "mfa",
+    /**
+     * Password reset code template
+     * Required variables: {{code}}, {{expiryMinutes}}
+     */
     PASSWORD_RESET = "passwordReset"
 }
+/**
+ * SMS Template Variables
+ *
+ * Variables that can be used in SMS templates.
+ * All variables are optional as not all templates use all variables.
+ */
 export interface SMSTemplateVariables {
     appName?: string;
     userName?: string;
@@ -16,27 +48,241 @@ export interface SMSTemplateVariables {
     supportPhone?: string;
     [key: string]: string | number | boolean | undefined;
 }
+/**
+ * SMS Template
+ *
+ * Defines the structure of an SMS template (text only, no HTML/subject).
+ * Content supports placeholder variables using Handlebars syntax.
+ */
 export interface SMSTemplate {
+    /**
+     * SMS message content (supports {{variables}})
+     * Plain text only - SMS does not support HTML formatting
+     */
     content: string;
 }
+/**
+ * Template Source
+ *
+ * Defines how SMS template content can be provided - as a string or file path
+ */
 export interface SMSTemplateSource {
+    /**
+     * Template content as string
+     * Mutually exclusive with filePath
+     */
     content?: string;
+    /**
+     * Path to template file
+     * Mutually exclusive with content
+     */
     filePath?: string;
 }
+/**
+ * Custom SMS Template Definition
+ *
+ * Allows specifying SMS templates as file paths or inline content.
+ * All templates support Handlebars syntax for dynamic content.
+ *
+ * @example
+ * ```typescript
+ * const customTemplate: CustomSMSTemplateDefinition = {
+ *   contentPath: './sms-templates/verification.txt.hbs',
+ *   // OR
+ *   content: '{{appName}}: Your code is {{code}}. Expires in {{expiryMinutes}} min.',
+ * };
+ * ```
+ */
 export interface CustomSMSTemplateDefinition {
+    /**
+     * Path to SMS template file
+     * Mutually exclusive with `content`
+     */
     contentPath?: string;
+    /**
+     * SMS template content as string
+     * Mutually exclusive with `contentPath`
+     */
     content?: string;
 }
+/**
+ * SMS Template Engine Interface
+ *
+ * Contract for template engines that can render SMS templates with variables.
+ * Implementations can support Handlebars or other template formats.
+ *
+ * @example
+ * ```typescript
+ * const engine = new SMSTemplateEngine();
+ * const result = await engine.render(
+ *   SMSTemplateType.VERIFICATION,
+ *   { appName: 'My App', code: '123456', expiryMinutes: 5 }
+ * );
+ * // result.content: "My App: Your verification code is 123456. Valid for 5 minutes."
+ * ```
+ */
 export interface SMSTemplateEngine {
+    /**
+     * Render a template with the provided variables
+     *
+     * @param type - Type of template to render
+     * @param variables - Variables to inject into the template
+     * @returns Rendered SMS template with content
+     *
+     * @throws {Error} If template type is not found
+     *
+     * @example
+     * ```typescript
+     * const result = await engine.render(
+     *   SMSTemplateType.VERIFICATION,
+     *   {
+     *     appName: 'My App',
+     *     code: '123456',
+     *     expiryMinutes: 5
+     *   }
+     * );
+     * ```
+     */
     render(type: SMSTemplateType | string, variables: SMSTemplateVariables): Promise<SMSTemplate>;
+    /**
+     * Register a custom template from inline string
+     *
+     * Allows overriding default templates or adding new ones.
+     *
+     * @param type - Template type identifier
+     * @param template - Template definition with inline content
+     *
+     * @example
+     * ```typescript
+     * engine.registerTemplate(SMSTemplateType.VERIFICATION, {
+     *   content: '{{appName}}: Your code is {{code}}. Expires in {{expiryMinutes}} min.',
+     * });
+     * ```
+     */
     registerTemplate(type: SMSTemplateType | string, template: SMSTemplate): 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 templateSource - Template source (content or file path)
+     *
+     * @example
+     * ```typescript
+     * engine.registerTemplateFromSources(SMSTemplateType.VERIFICATION, {
+     *   content: { content: '{{appName}}: Your code is {{code}}.' },
+     * });
+     * // OR
+     * engine.registerTemplateFromSources(SMSTemplateType.MFA, {
+     *   content: { filePath: './sms-templates/mfa.txt.hbs' },
+     * });
+     * ```
+     */
     registerTemplateFromSources(type: SMSTemplateType | string, templateSource: {
         content: SMSTemplateSource;
     }): Promise<void>;
 }
+/**
+ * SMS Template Configuration
+ *
+ * Configuration options for the SMS 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({
+ *   sms: {
+ *     templates: {
+ *       // Global variables (optional, available to all templates)
+ *       globalVariables: {
+ *         appName: 'My Application',
+ *         companyName: 'My Company Inc.',
+ *         supportPhone: '+1-800-123-4567',
+ *       },
+ *       // Custom templates (override defaults)
+ *       customTemplates: {
+ *         verification: {
+ *           content: '{{appName}}: Your verification code is {{code}}. Valid for {{expiryMinutes}} minutes.',
+ *           // Must include: {{code}}, {{expiryMinutes}}
+ *         },
+ *         mfa: {
+ *           contentPath: './sms-templates/mfa.txt.hbs',
+ *           // Must include: {{code}}, {{expiryMinutes}}
+ *         },
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ */
 export interface SMSTemplateConfig {
+    /**
+     * Template engine instance
+     *
+     * @default SMSTemplateEngine with default templates
+     */
     engine?: SMSTemplateEngine;
+    /**
+     * 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
+     * - supportPhone: Support contact phone number
+     *
+     * Optional user-specific variables (injected at runtime):
+     * - firstName, lastName, userName: User information
+     *
+     * @example
+     * ```typescript
+     * globalVariables: {
+     *   appName: process.env.APP_NAME || 'My App',
+     *   companyName: 'My Company Inc.',
+     *   supportPhone: '+1-800-123-4567',
+     * }
+     * ```
+     */
     globalVariables?: SMSTemplateVariables;
+    /**
+     * 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}}, {{expiryMinutes}}
+     * - mfa: {{code}}, {{expiryMinutes}}
+     * - passwordReset: {{code}}, {{expiryMinutes}}
+     *
+     * @example
+     * ```typescript
+     * customTemplates: {
+     *   // File-based template
+     *   verification: {
+     *     contentPath: './sms-templates/verification.txt.hbs',
+     *   },
+     *   // Inline template
+     *   mfa: {
+     *     content: '{{appName}}: Your MFA code is {{code}}. Valid for {{expiryMinutes}} minutes.',
+     *   },
+     * }
+     * ```
+     */
     customTemplates?: Record<string, CustomSMSTemplateDefinition>;
 }
 //# sourceMappingURL=sms-template.interface.d.ts.map

package/dist/interfaces/sms-template.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sms-template.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/sms-template.interface.ts"],"names":[],"mappings":"AAeA,oBAAY,eAAe;IAKzB,YAAY,iBAAiB;IAM7B,GAAG,QAAQ;IAMX,cAAc,kBAAkB;CACjC;AAQD,MAAM,WAAW,oBAAoB;IAEnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IAGvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IAGtB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CACtD;AAQD,MAAM,WAAW,WAAW;IAK1B,OAAO,EAAE,MAAM,CAAC;CACjB;AAOD,MAAM,WAAW,iBAAiB;IAKhC,OAAO,CAAC,EAAE,MAAM,CAAC;IAMjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAiBD,MAAM,WAAW,2BAA2B;IAK1C,WAAW,CAAC,EAAE,MAAM,CAAC;IAMrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAkBD,MAAM,WAAW,iBAAiB;IAsBhC,MAAM,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,EAAE,SAAS,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAiB9F,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;IAqB9E,2BAA2B,CACzB,IAAI,EAAE,eAAe,GAAG,MAAM,EAC9B,cAAc,EAAE;QAAE,OAAO,EAAE,iBAAiB,CAAA;KAAE,GAC7C,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAsCD,MAAM,WAAW,iBAAiB;IAMhC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAyB3B,eAAe,CAAC,EAAE,oBAAoB,CAAC;IAmCvC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAC;CAC/D"}
+{"version":3,"file":"sms-template.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/sms-template.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,oBAAY,eAAe;IACzB;;;OAGG;IACH,YAAY,iBAAiB;IAE7B;;;OAGG;IACH,GAAG,QAAQ;IAEX;;;OAGG;IACH,cAAc,kBAAkB;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IAEnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IAGvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IAGtB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CACtD;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,EAAE,SAAS,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAE9F;;;;;;;;;;;;;;OAcG;IACH,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;IAE9E;;;;;;;;;;;;;;;;;;OAkBG;IACH,2BAA2B,CACzB,IAAI,EAAE,eAAe,GAAG,MAAM,EAC9B,cAAc,EAAE;QAAE,OAAO,EAAE,iBAAiB,CAAA;KAAE,GAC7C,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAE3B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,eAAe,CAAC,EAAE,oBAAoB,CAAC;IAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAC;CAC/D"}