/**
 * INotificationSettings - Interface defining user notification preferences
 *
 * This interface represents a user's configurable notification settings,
 * allowing granular control over how and when they receive different types
 * of notifications. It's commonly used in user profile/preferences systems,
 * notification management panels, and application configuration.
 *
 * @example
 * // User wants email notifications for promotions, weekly digest
 * const userSettings: INotificationSettings = {
 *   medium: ['email'],
 *   category: ['promotions', 'news'],
 *   freq_type: 'weekly',
 *   frequency: 'monday',
 *   note_type: 'digest'
 * };
 *
 * // Minimal settings - just SMS for security alerts
 * const minimalSettings: INotificationSettings = {
 *   medium: ['sms'],
 *   category: ['security']
 * };
 */
export interface INotificationSettings {
  /**
   * Preferred notification delivery channels
   *
   * Defines which communication channels the user wants to receive
   * notifications through. Each medium represents a different delivery method.
   *
   * Common values:
   * - 'email': Email notifications
   * - 'sms': Text message notifications
   * - 'push': Mobile/desktop push notifications
   * - 'in_app': In-application notifications (badges, banners)
   * - 'webhook': External system integration
   * - 'slack': Slack/Discord/Teams integration
   *
   * @optional If undefined or empty, user may not receive any notifications
   * @default ['email'] - Common default if not specified
   *
   * @example ['email', 'push'] // Receive via both email and push notifications
   */
  medium?: string[];

  /**
   * Notification categories the user wants to receive
   *
   * Allows users to opt-in/out of specific types of notifications based on
   * their interests or relevance. Categories should be well-defined in the
   * application's notification system.
   *
   * Common categories:
   * - 'security': Security alerts, login attempts, password changes
   * - 'promotions': Marketing offers, discounts, special deals
   * - 'news': Company/news updates, blog posts, announcements
   * - 'social': Friend requests, messages, comments, likes
   * - 'transactional': Order confirmations, shipping updates, invoices
   * - 'system': System alerts, maintenance notices, updates
   * - 'reminders': Calendar events, task reminders, deadlines
   *
   * @optional If undefined or empty, may receive all categories or none
   * @example ['security', 'transactional'] // Only security and transactional alerts
   */
  category?: string[];

  /**
   * Frequency type for digest/grouped notifications
   *
   * Determines how often the user wants to receive batched notifications
   * when using digest mode. This is particularly useful for reducing
   * notification noise for non-urgent communications.
   *
   * Common values:
   * - 'realtime': Send immediately when event occurs
   * - 'digest': Group multiple notifications together
   * - 'daily': Once per day
   * - 'weekly': Once per week
   * - 'monthly': Once per month
   * - 'never': Do not send notifications (opt-out)
   *
   * @optional If undefined, defaults to application's default frequency
   * @default 'realtime' for critical alerts, 'daily' for non-urgent
   */
  freq_type?: string;

  /**
   * Specific timing for notification delivery
   *
   * Provides granular control over when notifications are sent,
   * particularly useful for digest or scheduled notifications.
   *
   * Interpretation depends on `freq_type`:
   * - daily: Time of day (e.g., '18:00' for 6 PM)
   * - weekly: Day of week (e.g., 'monday', 'sunday')
   * - monthly: Day of month (e.g., '1', '15', 'last')
   * - digest: Maximum batch size or time window (e.g., '10', '1h')
   *
   * @optional If undefined, uses application default timing
   * @example '18:00' for daily digest at 6 PM
   * @example 'monday' for weekly digest every Monday
   */
  frequency?: string;

  /**
   * Type of notification content/format
   *
   * Specifies the format or style of notifications the user prefers.
   * This can affect both the content length and presentation style.
   *
   * Common values:
   * - 'full': Complete notification with all details
   * - 'summary': Brief summary/headline only
   * - 'digest': Batched multiple notifications together
   * - 'alert': Urgent/important style notifications
   * - 'silent': Notifications without sound/vibration
   * - 'rich': Notifications with images/attachments
   * - 'plain_text': Text-only, no HTML formatting
   *
   * @optional If undefined, uses default notification type
   * @default 'full' for most notification types
   */
  note_type?: string;
}

/**
 * Best Practices and Implementation Notes:
 *
 * 1. **Validation and Sanitization**:
 *
 *    ```typescript
 *    const VALID_MEDIUMS = ['email', 'sms', 'push', 'in_app'] as const;
 *    const VALID_CATEGORIES = ['security', 'promotions', 'news'] as const;
 *
 *    function validateSettings(settings: INotificationSettings): boolean {
 *      // Validate mediums are known values
 *      if (settings.medium) {
 *        return settings.medium.every(m => VALID_MEDIUMS.includes(m as any));
 *      }
 *      return true;
 *    }
 *    ```
 *
 * 2. **Using Type-Safe Enums (Recommended Enhancement)**:
 *
 *    ```typescript
 *    export enum NotificationMedium {
 *      EMAIL = 'email',
 *      SMS = 'sms',
 *      PUSH = 'push',
 *      IN_APP = 'in_app'
 *    }
 *
 *    export enum NotificationCategory {
 *      SECURITY = 'security',
 *      PROMOTIONS = 'promotions',
 *      NEWS = 'news',
 *      TRANSACTIONAL = 'transactional'
 *    }
 *
 *    // Then use these enums in a stricter interface
 *    ```
 *
 * 3. **Default Settings Factory**:
 *
 *    ```typescript
 *    export function getDefaultNotificationSettings(): Required<INotificationSettings> {
 *      return {
 *        medium: ['email'],
 *        category: ['security', 'transactional'],
 *        freq_type: 'realtime',
 *        frequency: '',
 *        note_type: 'full'
 *      };
 *    }
 *    ```
 *
 * 4. **Database Storage Considerations**:
 *    - Store as JSON in database for flexibility
 *    - Consider versioning for schema changes
 *    - Provide migration paths for user settings
 *    - Index frequently queried fields (like 'medium')
 *
 * 5. **User Interface Integration**:
 *    - Provide sensible defaults for new users
 *    - Allow bulk category selection (select all/none)
 *    - Group related categories together
 *    - Preview notification examples with different settings
 *
 * 6. **Notification System Integration**:
 *
 *    ```typescript
 *    function shouldNotifyUser(
 *      settings: INotificationSettings,
 *      notification: Notification
 *    ): boolean {
 *      // Check if user wants this category
 *      if (settings.category && !settings.category.includes(notification.category)) {
 *        return false;
 *      }
 *
 *      // Check if user wants this medium
 *      if (settings.medium && !settings.medium.includes(notification.medium)) {
 *        return false;
 *      }
 *
 *      return true;
 *    }
 *    ```
 *
 * 7. **Privacy and Compliance**:
 *    - Always get explicit opt-in for promotional notifications
 *    - Provide easy opt-out mechanisms
 *    - Comply with regulations (GDPR, CAN-SPAM, etc.)
 *    - Log when users change notification preferences
 *    - Respect "do not disturb" hours if implemented
 */
