import { AuthenticationState } from '../../domain/value-objects/AuthenticationState';
import { Result } from '../../shared/result/Result';

/**
 * Port for authentication services implementing zero-knowledge login.
 * 
 * GridPilot never sees, stores, or transmits user credentials.
 * Authentication is handled by opening a visible browser window where
 * the user logs in directly with iRacing. GridPilot only observes
 * URL changes to detect successful authentication.
 */
export interface IAuthenticationService {
  /**
   * Check if user has a valid session without prompting login.
   * Navigates to a protected iRacing page and checks for login redirects.
   * 
   * @returns Result containing the current authentication state
   */
  checkSession(): Promise<Result<AuthenticationState>>;

  /**
   * Open browser for user to login manually.
   * The browser window is visible so user can verify they're on the real iRacing site.
   * GridPilot waits for URL change indicating successful login.
   * 
   * @returns Result indicating success (login complete) or failure (cancelled/timeout)
   */
  initiateLogin(): Promise<Result<void>>;

  /**
   * Clear the persistent session (logout).
   * Removes stored browser context and cookies.
   * 
   * @returns Result indicating success or failure
   */
  clearSession(): Promise<Result<void>>;

  /**
   * Get current authentication state.
   * Returns cached state without making network requests.
   * 
   * @returns The current AuthenticationState
   */
  getState(): AuthenticationState;
}