/**
 * Auth Form Types
 *
 * Single source of truth for auth form state and handlers.
 * Used by both @djangocfg/api/auth hooks and @djangocfg/layouts/AuthLayout.
 */

import type { MutableRefObject } from 'react';

import type { WebmailLink } from '../../_api/generated/types.gen';

export type { WebmailLink };

// ─────────────────────────────────────────────────────────────────────────────
// Step Types
// ─────────────────────────────────────────────────────────────────────────────

export type AuthStep = 'identifier' | 'otp' | '2fa' | '2fa-setup' | 'success';

// ─────────────────────────────────────────────────────────────────────────────
// OTP Result Types
// ─────────────────────────────────────────────────────────────────────────────

export interface OTPRequestResult {
  success: boolean;
  message: string;
  statusCode?: number;
  retryAfter?: number;
  /** Webmail deep-link for the recipient's provider, or null if unknown. */
  webmail?: WebmailLink | null;
}

// ─────────────────────────────────────────────────────────────────────────────
// Form State
// ─────────────────────────────────────────────────────────────────────────────

export interface AuthFormState {
  /** Email address */
  identifier: string;
  /** OTP code input */
  otp: string;
  /** Loading state */
  isLoading: boolean;
  /** Terms acceptance state */
  acceptedTerms: boolean;
  /** Current form step */
  step: AuthStep;
  /** Error message */
  error: string;
  /** 2FA session ID from OTP/OAuth verification */
  twoFactorSessionId: string | null;
  /** Whether user should be prompted to enable 2FA */
  shouldPrompt2FA: boolean;
  /** 2FA code input */
  twoFactorCode: string;
  /** Using backup code instead of TOTP */
  useBackupCode: boolean;
  /** Seconds remaining until rate limit lifts (0 = not rate limited) */
  rateLimitSeconds: number;
  /** True when rateLimitSeconds > 0 — submit should be disabled */
  isRateLimited: boolean;
  /** Formatted countdown label, e.g. "19:00" or "42s" */
  rateLimitLabel: string;
  /** Webmail deep-link for the current identifier's provider (null = no button). */
  webmail: WebmailLink | null;
}

// ─────────────────────────────────────────────────────────────────────────────
// Form Handlers
// ─────────────────────────────────────────────────────────────────────────────

export interface AuthFormStateHandlers {
  setIdentifier: (identifier: string) => void;
  setOtp: (otp: string) => void;
  setAcceptedTerms: (accepted: boolean) => void;
  setError: (error: string) => void;
  clearError: () => void;
  setStep: (step: AuthStep) => void;
  setIsLoading: (loading: boolean) => void;
  setTwoFactorSessionId: (sessionId: string | null) => void;
  setShouldPrompt2FA: (prompt: boolean) => void;
  setTwoFactorCode: (code: string) => void;
  setUseBackupCode: (useBackup: boolean) => void;
  /** Start a countdown timer that disables submit for `seconds` seconds */
  startRateLimitCountdown: (seconds: number) => void;
  /** Set (or clear) the webmail deep-link for the current identifier */
  setWebmail: (webmail: WebmailLink | null) => void;
}

export interface AuthFormSubmitHandlers {
  handleIdentifierSubmit: (e: React.FormEvent) => Promise<void>;
  handleOTPSubmit: (e: React.FormEvent) => Promise<void>;
  handleResendOTP: () => Promise<void>;
  handleBackToIdentifier: () => void;
  forceOTPStep: () => void;
  /** Handle 2FA TOTP/backup code verification */
  handle2FASubmit: (e: React.FormEvent) => Promise<void>;
  /** Switch to backup code input */
  handleUseBackupCode: () => void;
  /** Switch back to TOTP input */
  handleUseTOTP: () => void;
}

// ─────────────────────────────────────────────────────────────────────────────
// Validation
// ─────────────────────────────────────────────────────────────────────────────

export interface AuthFormValidation {
  /** Validate identifier format */
  validateIdentifier: (identifier: string) => boolean;
}

// ─────────────────────────────────────────────────────────────────────────────
// Auto-submit (for URL-based OTP)
// ─────────────────────────────────────────────────────────────────────────────

export interface AuthFormAutoSubmit {
  /** Ref to track if auto-submit from URL is in progress */
  isAutoSubmittingFromUrl: MutableRefObject<boolean>;
}

// ─────────────────────────────────────────────────────────────────────────────
// 2FA State (from useTwoFactor hook)
// ─────────────────────────────────────────────────────────────────────────────

export interface AuthForm2FAState {
  /** Loading state for 2FA verification */
  is2FALoading: boolean;
  /** Warning message from 2FA (e.g., low backup codes) */
  twoFactorWarning: string | null;
  /** Remaining attempts before 2FA lockout (null = unknown) */
  twoFactorAttemptsRemaining: number | null;
}

// ─────────────────────────────────────────────────────────────────────────────
// Combined Form Interface
// ─────────────────────────────────────────────────────────────────────────────

export interface AuthFormReturn extends
  AuthFormState,
  AuthFormStateHandlers,
  AuthFormSubmitHandlers,
  AuthFormValidation,
  AuthFormAutoSubmit,
  AuthForm2FAState {}

// ─────────────────────────────────────────────────────────────────────────────
// Hook Options
// ─────────────────────────────────────────────────────────────────────────────

export interface UseAuthFormOptions {
  /** Callback when identifier step succeeds */
  onIdentifierSuccess?: (identifier: string) => void;
  /** Callback when OTP verification succeeds */
  onOTPSuccess?: () => void;
  /** Callback on any error */
  onError?: (message: string) => void;
  /** Source URL for tracking */
  sourceUrl: string;
  /** URL to redirect after successful OTP verification */
  redirectUrl?: string;
  /** If true, user must accept terms before submitting. Default: false */
  requireTermsAcceptance?: boolean;
  /** Path to auth page for auto-OTP detection. Default: '/auth' */
  authPath?: string;
}

