@nauth-toolkit/core 0.1.0 → 0.1.5

package/src/interfaces/template.interface.ts

@@ -1,510 +0,0 @@
-/**
- * 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 {
-  // User information
-  appName?: string;
-  userName?: string;
-  firstName?: string;
-  lastName?: string;
-  userEmail?: string;
-
-  // Verification and authentication
-  code?: string;
-  link?: string;
-  expiryMinutes?: number;
-
-  // Security alerts
-  reason?: string;
-  durationMinutes?: number;
-  deviceName?: string;
-  deviceType?: string;
-  ipAddress?: string;
-  location?: string;
-
-  // Timestamps
-  timestamp?: string;
-  currentYear?: number;
-
-  // Company branding (custom variables)
-  companyName?: string;
-  companyAddress?: string;
-  brandColor?: string;
-  logoUrl?: string;
-  dashboardUrl?: string;
-  supportEmail?: string;
-  footerDisclaimer?: string;
-
-  // Allow any custom variables
-  [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 enum TemplateType {
-  VERIFICATION = 'verification',
-  PASSWORD_RESET = 'passwordReset',
-  WELCOME = 'welcome',
-  ACCOUNT_LOCKOUT = 'accountLockout',
-  NEW_DEVICE = 'newDevice',
-  PASSWORD_CHANGED = 'passwordChanged',
-  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 files
-   *
-   * Allows loading templates from file system (.hbs, .html, .txt files).
-   * Consumer apps can provide paths to their own branded templates.
-   *
-   * @param type - Template type identifier
-   * @param templateFiles - Template file paths
-   *
-   * @example
-   * ```typescript
-   * engine.registerTemplateFromFiles(TemplateType.WELCOME, {
-   *   subject: { filePath: './templates/welcome.subject.hbs' },
-   *   html: { filePath: './templates/welcome.html.hbs' },
-   *   text: { filePath: './templates/welcome.text.hbs' }
-   * });
-   * ```
-   */
-  registerTemplateFromFiles?(type: TemplateType | string, templateFiles: TemplateFiles): Promise<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>; // No required params
-
-  /**
-   * Account lockout template required parameters
-   */
-  [TemplateType.ACCOUNT_LOCKOUT]: {
-    reason: string;
-    durationMinutes: number;
-  };
-
-  /**
-   * New device template required parameters
-   */
-  [TemplateType.NEW_DEVICE]: {
-    deviceName: string;
-    deviceType?: string;
-    ipAddress?: string;
-    location?: string;
-    timestamp: string;
-  };
-
-  /**
-   * Password changed template required parameters
-   */
-  [TemplateType.PASSWORD_CHANGED]: Record<string, never>; // No required params
-
-  /**
-   * Email changed template required parameters
-   */
-  [TemplateType.EMAIL_CHANGED]: {
-    userEmail: string;
-  };
-
-  /**
-   * MFA enabled template required parameters
-   */
-  [TemplateType.MFA_ENABLED]: Record<string, never>; // No required params
-}
-
-/**
- * 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>;
-}

package/src/interfaces/token-verifier.interface.ts

@@ -1,110 +0,0 @@
-/**
- * Token Verifier Service Interface
- *
- * Defines the contract for OAuth token verification services.
- * Each platform-specific implementation must follow this interface.
- *
- * Note: Provider-specific verified token profile types are defined in each provider package,
- * not in core, to maintain proper separation of concerns.
- *
- * @example
- * ```typescript
- * // In Google provider package
- * import { ITokenVerifierService } from '@nauth-toolkit/core';
- *
- * interface VerifiedGoogleTokenProfile {
- *   sub: string;
- *   email: string;
- *   // ...
- * }
- *
- * class GoogleTokenVerifierService implements ITokenVerifierService {
- *   async verifyGoogleToken(idToken: string, clientId: string | string[]): Promise<VerifiedGoogleTokenProfile> {
- *     // Implementation
- *   }
- * }
- * ```
- */
-export interface ITokenVerifierService {
-  /**
-   * Verify Google ID token with cryptographic signature validation
-   *
-   * Uses Google's public keys to verify the JWT signature, ensuring the token
-   * was issued by Google and has not been tampered with.
-   *
-   * @param idToken - ID token from Google OAuth
-   * @param clientId - Google OAuth client ID for audience validation (supports multiple IDs)
-   * @returns Verified user profile data (provider-specific type)
-   * @throws {BadRequestException} When token is invalid, expired, or signature fails
-   *
-   * @example
-   * ```typescript
-   * try {
-   *   const profile = await verifier.verifyGoogleToken(idToken, ['web-client-id', 'ios-client-id']);
-   *   console.log(`Verified email: ${profile.email}`);
-   * } catch (error) {
-   *   console.error('Token verification failed:', error.message);
-   * }
-   * ```
-   */
-  verifyGoogleToken?(idToken: string, clientId: string | string[]): Promise<unknown>;
-
-  /**
-   * Verify Apple ID token with JWT signature validation
-   *
-   * Fetches Apple's public keys from their JWKS endpoint and verifies the
-   * JWT signature to ensure authenticity.
-   *
-   * @param idToken - ID token from Apple Sign In
-   * @param clientId - Apple Services ID (client ID) for audience validation
-   * @returns Verified user profile data (provider-specific type)
-   * @throws {BadRequestException} When token is invalid, expired, or signature fails
-   *
-   * @example
-   * ```typescript
-   * try {
-   *   const profile = await verifier.verifyAppleToken(idToken, 'com.yourapp.service');
-   *   console.log(`Verified email: ${profile.email}`);
-   * } catch (error) {
-   *   console.error('Token verification failed:', error.message);
-   * }
-   * ```
-   */
-  verifyAppleToken?(idToken: string, clientId: string): Promise<unknown>;
-
-  /**
-   * Verify Facebook access token via Graph API
-   *
-   * Validates the access token by calling Facebook's debug_token endpoint,
-   * which checks the token's validity and returns user information.
-   *
-   * @param accessToken - Access token from Facebook OAuth
-   * @param appId - Facebook App ID
-   * @param appSecret - Facebook App Secret (server-side only)
-   * @returns Verified user profile data (provider-specific type)
-   * @throws {BadRequestException} When token is invalid or API call fails
-   *
-   * @example
-   * ```typescript
-   * try {
-   *   const profile = await verifier.verifyFacebookToken(accessToken, appId, appSecret);
-   *   console.log(`Verified Facebook user: ${profile.id}`);
-   * } catch (error) {
-   *   console.error('Token verification failed:', error.message);
-   * }
-   * ```
-   */
-  verifyFacebookToken?(accessToken: string, appId: string, appSecret: string): Promise<unknown>;
-
-  /**
-   * Clear cached clients and keys
-   *
-   * Useful for testing or when configuration changes
-   *
-   * @example
-   * ```typescript
-   * verifier.clearCache();
-   * ```
-   */
-  clearCache?(): void;
-}