import { EmailTransportInterface } from './email-transport.interface';

/**
 * siteconfig - Main site configuration interface
 *
 * This interface defines the comprehensive configuration settings for a website/application.
 * It centralizes various site-wide settings including email configuration, branding,
 * URLs, and operational parameters. This is typically used as a single configuration
 * object that gets loaded at application startup and used across different modules.
 *
 * @example
 * // Production site configuration
 * const prodConfig: siteconfig = {
 *   config: {
 *     host: 'smtp.sendgrid.net',
 *     secure: true,
 *     auth: {
 *       user: 'apikey',
 *       pass: process.env.SENDGRID_API_KEY
 *     }
 *   },
 *   replyTo: 'support@example.com',
 *   siteName: 'My Awesome App',
 *   template_path: './src/email-templates',
 *   url: 'https://app.example.com',
 *   adminEmail: 'admin@example.com',
 *   resetlink: 'https://app.example.com/reset-password'
 * };
 *
 * @example
 * // Development configuration
 * const devConfig: siteconfig = {
 *   config: {
 *     host: 'smtp.mailtrap.io',
 *     secure: false,
 *     auth: {
 *       user: process.env.MAILTRAP_USER,
 *       pass: process.env.MAILTRAP_PASS
 *     }
 *   },
 *   replyTo: 'dev@example.com',
 *   siteName: 'My App (Dev)',
 *   template_path: './src/email-templates',
 *   url: 'http://localhost:3000',
 *   adminEmail: 'developer@example.com',
 *   resetlink: 'http://localhost:3000/reset-password'
 * };
 */
export interface siteconfig {
  /**
   * Email transport configuration
   *
   * Contains the SMTP/email server settings used for sending transactional emails
   * from the application (welcome emails, password resets, notifications, etc.)
   *
   * @see EmailTransportInterface for detailed structure
   *
   * @example
   * config: {
   *   host: 'smtp.gmail.com',
   *   secure: true,
   *   auth: {
   *     user: 'noreply@example.com',
   *     pass: 'your-app-password'
   *   }
   * }
   */
  config: EmailTransportInterface;

  /**
   * Default reply-to email address
   *
   * The email address that users can reply to when they receive emails from the system.
   * This should be a monitored inbox for customer support or general inquiries.
   *
   * @remarks Different from the 'from' address which might be a no-reply address
   * @example 'support@example.com'
   * @example 'help@company.com'
   */
  replyTo: string;

  /**
   * Site/application display name
   *
   * The human-readable name of the website or application, used in:
   * - Email subject lines and footers
   * - Page titles and headers
   * - System notifications
   * - Legal documents and terms
   *
   * @example 'Acme Corporation'
   * @example 'SocialConnect Pro'
   * @example 'TaskMaster 360'
   */
  siteName: string;

  /**
   * Path to email template directory
   *
   * Filesystem path where email templates are stored. These templates are typically
   * HTML files with placeholders that get populated with dynamic content.
   *
   * Common template patterns:
   * - welcome.html - New user welcome email
   * - password-reset.html - Password reset instructions
   * - notification.html - General notifications
   * - invoice.html - Payment/invoice emails
   *
   * @example './templates/emails'
   * @example './src/assets/email-templates'
   * @example '/var/www/app/email-templates'
   *
   * @note Consider using absolute paths for reliability across environments
   */
  template_path: string;

  /**
   * Base URL of the application
   *
   * The public-facing URL of the website/application, used for:
   * - Generating absolute URLs in emails
   * - CORS configuration
   * - Sitemap generation
   * - Social media sharing
   * - Redirect URIs for OAuth
   *
   * Should include protocol (http/https) but no trailing slash
   *
   * @example 'https://www.example.com'
   * @example 'https://app.example.com'
   * @example 'http://localhost:3000'
   * @example 'https://staging.example.com'
   */
  url: string;

  /**
   * Administrator contact email
   *
   * The email address for system administrators, used for:
   * - Critical system alerts and errors
   * - Security notifications
   * - Compliance reports
   * - Contact form submissions (if no dedicated support)
   *
   * @remarks This should be a separate address from general support for prioritization
   * @example 'admin@example.com'
   * @example 'sysadmin@company.com'
   * @example 'it-support@organization.org'
   */
  adminEmail: string;

  /**
   * Password reset link base URL
   *
   * The base URL for password reset functionality. When combined with a reset token,
   * this forms the complete password reset link sent to users.
   *
   * Format: `${resetlink}/${token}` or `${resetlink}?token=${token}`
   *
   * @example 'https://app.example.com/reset-password'
   * @example 'https://auth.example.com/recover'
   * @example 'http://localhost:3000/auth/reset'
   *
   * @note Should be a secure (HTTPS) URL in production
   * @note Consider making this a path relative to `url` for consistency
   */
  resetlink: string;
}

/**
 * Configuration Management Best Practices:
 *
 * 1. **Environment-Specific Configuration**:
 *
 *    ```typescript
 *    export function getSiteConfig(env: string): siteconfig {
 *      const baseConfig = {
 *        siteName: 'My Application',
 *        template_path: './email-templates',
 *        adminEmail: 'admin@example.com'
 *      };
 *
 *      switch (env) {
 *        case 'production':
 *          return {
 *            ...baseConfig,
 *            config: { /* prod email config *\/ },
 *            url: 'https://app.example.com',
 *            replyTo: 'support@example.com',
 *            resetlink: 'https://app.example.com/reset-password'
 *          };
 *        case 'development':
 *          return {
 *            ...baseConfig,
 *            config: { /* dev email config *\/ },
 *            url: 'http://localhost:3000',
 *            replyTo: 'dev@example.com',
 *            resetlink: 'http://localhost:3000/reset-password'
 *          };
 *      }
 *    }
 *    ```
 *
 * 2. **Validation and Defaults**:
 *
 *    ```typescript
 *    function validateSiteConfig(config: siteconfig): string[] {
 *      const errors: string[] = [];
 *
 *      if (!config.url.startsWith('http')) {
 *        errors.push('URL must start with http:// or https://');
 *      }
 *
 *      if (!config.replyTo.includes('@')) {
 *        errors.push('Reply-to email is invalid');
 *      }
 *
 *      return errors;
 *    }
 *    ```
 *
 * 3. **Extension Suggestions**:
 *
 *    Consider adding these commonly needed properties:
 *
 *    ```typescript
 *    export interface ExtendedSiteConfig extends siteconfig {
 *      // Timezone for date displays
 *      timezone?: string;
 *
 *      // Default language/locale
 *      defaultLocale?: string;
 *
 *      // Contact information
 *      contactPhone?: string;
 *      contactAddress?: string;
 *
 *      // Social media links
 *      socialMedia?: {
 *        facebook?: string;
 *        twitter?: string;
 *        linkedin?: string;
 *      };
 *
 *      // Legal URLs
 *      privacyPolicyUrl?: string;
 *      termsOfServiceUrl?: string;
 *    }
 *    ```
 *
 * 4. **Security Considerations**:
 *    - Never hardcode sensitive values (API keys, passwords)
 *    - Use environment variables for all secrets
 *    - Consider using a secrets management service in production
 *    - Validate URLs to prevent open redirect vulnerabilities
 *    - Use HTTPS URLs in production configurations
 *
 * 5. **Database Storage Alternative**:
 *    For dynamic configuration that can be changed without redeployment,
 *    consider storing in a database:
 *
 *    ```typescript
 *    interface SiteConfigRecord {
 *      key: keyof siteconfig;
 *      value: string;
 *      environment: 'development' | 'staging' | 'production';
 *    }
 *    ```
 *
 * 6. **Testing Strategy**:
 *    - Create mock configurations for unit tests
 *    - Test configuration validation thoroughly
 *    - Verify email templates exist at the specified path
 *    - Test URL generation with different environments
 *
 * 7. **Common Usage Patterns**:
 *
 *    ```typescript
 *    // Dependency injection
 *    @Injectable()
 *    export class EmailService {
 *      constructor(@Inject('SITE_CONFIG') private config: siteconfig) {}
 *
 *      async sendWelcomeEmail(to: string) {
 *        const template = readFileSync(
 *          `${this.config.template_path}/welcome.html`
 *        ).toString();
 *
 *        // ... send email using this.config.config
 *      }
 *    }
 *
 *    // In app module
 *    @Module({
 *      providers: [
 *        {
 *          provide: 'SITE_CONFIG',
 *          useValue: siteConfig
 *        }
 *      ]
 *    })
 *    ```
 */
