/**
 * OTP Type Definitions
 *
 * Centralized type definitions for OTP-related operations
 * Ensures type safety across the authentication system
 *
 * @module lib/types/otp.types
 */

/**
 * Supported languages for OTP communications
 */
export type Language = 'ar' | 'en';

/**
 * Purpose of OTP code generation
 */
export type OTPPurpose = 'login' | 'signup' | 'reset';

/**
 * OTP configuration constants
 */
export const OTP_CONFIG = {
  /** Length of OTP code (digits) */
  CODE_LENGTH: 6,
  /** OTP validity duration in minutes */
  EXPIRY_MINUTES: 10,
  /** Maximum verification attempts before lockout */
  MAX_ATTEMPTS: 5,
  /** Rate limit window in minutes */
  RATE_LIMIT_WINDOW_MINUTES: 5,
  /** Maximum OTP requests per window */
  MAX_REQUESTS_PER_WINDOW: 3,
} as const;

/**
 * User information for OTP personalization
 */
export interface OTPUserContext {
  /** User's email address */
  email: string;
  /** User's display name (optional) */
  name?: string;
  /** User's preferred language */
  language: Language;
  /** Purpose of the OTP */
  purpose: OTPPurpose;
  /** IP address for security tracking (optional) */
  ipAddress?: string;
}

/**
 * Result of OTP generation operation
 */
export interface OTPGenerationResult {
  /** Whether OTP was generated successfully */
  success: boolean;
  /** The OTP code (only returned in development) */
  code?: string;
  /** Error message if generation failed */
  error?: string;
  /** When the OTP expires */
  expiresAt?: Date;
}

/**
 * Result of OTP verification operation
 */
export interface OTPVerificationResult {
  /** Whether OTP was verified successfully */
  success: boolean;
  /** Error message if verification failed */
  error?: string;
  /** Remaining verification attempts */
  remainingAttempts?: number;
  /** User ID if verification succeeded */
  userId?: string;
}

/**
 * Email check result
 */
export interface EmailCheckResult {
  /** Whether email exists in database */
  exists: boolean;
  /** Whether email is verified */
  verified?: boolean;
  /** Whether account uses Google OAuth */
  isGoogleAccount?: boolean;
  /** Whether email is available for signup */
  available?: boolean;
}

/**
 * OTP email template data
 */
export interface OTPEmailTemplate {
  /** Email subject line */
  subject: string;
  /** HTML email body */
  html: string;
  /** Plain text email body */
  text: string;
}

/**
 * OTP service interface
 * Defines the contract for OTP operations
 */
export interface IOTPService {
  /**
   * Generate and send OTP to user
   */
  generateAndSend(context: OTPUserContext): Promise<OTPGenerationResult>;

  /**
   * Verify OTP code
   */
  verify(email: string, code: string, purpose: OTPPurpose): Promise<OTPVerificationResult>;

  /**
   * Check remaining verification attempts
   */
  getRemainingAttempts(email: string): Promise<number>;

  /**
   * Invalidate all OTPs for an email
   */
  invalidate(email: string): Promise<void>;
}
