import type { Page } from 'playwright';

/**
 * Infra-level abstraction for Playwright-based authentication flows.
 *
 * Encapsulates game/site-specific URL patterns and UI detection so that
 * auth/session orchestration can remain generic and reusable.
 */
export interface IPlaywrightAuthFlow {
  /** Get the URL of the login page. */
  getLoginUrl(): string;

  /**
   * Get a canonical URL that indicates the user is in an authenticated
   * area suitable for running automation (e.g. hosted sessions dashboard).
   */
  getPostLoginLandingUrl(): string;

  /** True if the given URL points at the login experience. */
  isLoginUrl(url: string): boolean;

  /** True if the given URL is considered authenticated (members area). */
  isAuthenticatedUrl(url: string): boolean;

  /**
   * True if the URL represents a successful login redirect, distinct from
   * the raw login form page or intermediate OAuth pages.
   */
  isLoginSuccessUrl(url: string): boolean;

  /** Detect whether an authenticated UI is currently rendered. */
  detectAuthenticatedUi(page: Page): Promise<boolean>;

  /** Detect whether a login UI is currently rendered. */
  detectLoginUi(page: Page): Promise<boolean>;

  /**
   * Navigate the given page into an authenticated area that the automation
   * engine can assume as a starting point after login.
   */
  navigateToAuthenticatedArea(page: Page): Promise<void>;

  /**
   * Wait for the browser to reach a post-login state within the timeout.
   *
   * Implementations may use URL changes, UI detection, or a combination of
   * both to determine success.
   */
  waitForPostLoginRedirect(page: Page, timeoutMs: number): Promise<boolean>;
}