/**
 * ForgotPasswordEvent - Domain event for password reset operations
 *
 * This event class represents a password reset request in the application's
 * event-driven architecture. It encapsulates the data needed to process
 * password reset operations, typically emitted after a user requests a
 * password reset.
 *
 * Domain events like this enable:
 * - Decoupling of password reset logic from notification logic
 * - Asynchronous processing of password reset side effects
 * - Multiple handlers for the same event (email, SMS, audit logging)
 * - Scalable architecture through event-driven patterns
 *
 * Typical use cases:
 * 1. Send password reset email with reset link
 * 2. Send SMS notification for password reset
 * 3. Log password reset attempt for security monitoring
 * 4. Update user's security audit trail
 * 5. Trigger fraud detection checks
 *
 * @example
 * // Creating and emitting the event
 * const forgotPasswordEvent = new ForgotPasswordEvent(user, resetToken);
 * this.eventEmitter.emit('password.forgot', forgotPasswordEvent);
 *
 * @example
 * // Handling the event in a listener
 * @OnEvent('password.forgot')
 * async handleForgotPassword(event: ForgotPasswordEvent) {
 *   await this.emailService.sendPasswordResetEmail(
 *     event.student.email,
 *     event.password // reset token
 *   );
 *
 *   await this.auditService.logPasswordResetAttempt(event.student.id);
 * }
 */
export class ForgotPasswordEvent {
  /**
   * Creates a new ForgotPasswordEvent instance
   *
   * @param student - User/student entity requesting password reset
   * @param password - Password reset token or temporary password (nullable)
   */
  constructor(
    /**
     * User/student entity
     *
     * The user who requested the password reset. Contains user information
     * needed for personalized notifications and audit logging.
     *
     * Should include at minimum:
     * - User identifier (id)
     * - Email address
     * - Name (for personalization)
     * - Any other relevant user data
     *
     * @note Using 'any' type for flexibility - consider using a proper User type
     * @example { id: 123, email: 'user@example.com', name: 'John Doe' }
     */
    public student: any,

    /**
     * Password reset token or temporary password
     *
     * Typically contains:
     * - Reset token: JWT or random string for reset link
     * - Temporary password: One-time password for immediate access
     * - null: If token generation happens elsewhere in the flow
     *
     * Security considerations:
     * - Tokens should be time-limited and single-use
     * - Never log or store plain text tokens in insecure locations
     * - Consider encrypting tokens in transit and at rest
     *
     * @example "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." // JWT reset token
     * @example "abc123def456" // Random reset token
     * @example "TempPass123!" // Temporary password
     * @example null // Token generated elsewhere
     */
    public password: string | null,
  ) {}
}
