/**
 * 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';

// ─────────────────────────────────────────────────────────────────────────────
// Channel & Step Types
// ─────────────────────────────────────────────────────────────────────────────

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

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

export interface AuthFormState {
  /** Email or phone number */
  identifier: string;
  /** Current auth channel */
  channel: AuthChannel;
  /** 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;
}

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

export interface AuthFormStateHandlers {
  setIdentifier: (identifier: string) => void;
  setChannel: (channel: AuthChannel) => 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;
}

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 {
  /** Detect channel from identifier string */
  detectChannelFromIdentifier: (identifier: string) => AuthChannel | null;
  /** Validate identifier format */
  validateIdentifier: (identifier: string, channel?: AuthChannel) => 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;
}

// ─────────────────────────────────────────────────────────────────────────────
// 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, channel: AuthChannel) => 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;
  /**
   * Enable 2FA setup prompt after successful authentication.
   * When true (default), users without 2FA will see a setup prompt after login.
   * When false, users go directly to success without 2FA setup prompt.
   * @default true
   */
  enable2FASetup?: boolean;
}

// ─────────────────────────────────────────────────────────────────────────────
// Layout Context (UI-specific additions)
// ─────────────────────────────────────────────────────────────────────────────

export interface AuthLayoutConfig {
  /** Support page URL */
  supportUrl?: string;
  /** Terms of service URL */
  termsUrl?: string;
  /** Privacy policy URL */
  privacyUrl?: string;
  /** Source URL for tracking */
  sourceUrl: string;
  /** Enable phone authentication tab */
  enablePhoneAuth?: boolean;
  /** Enable GitHub OAuth button */
  enableGithubAuth?: boolean;
  /** Logo URL for success screen (SVG recommended) */
  logoUrl?: string;
  /** URL to redirect after successful auth (default: /dashboard) */
  redirectUrl?: string;
  /**
   * Enable 2FA setup prompt after successful authentication.
   * When true (default), users without 2FA will see a setup prompt after login.
   * When false, users go directly to success without 2FA setup prompt.
   * Note: This only affects the setup prompt - existing 2FA verification still works.
   * @default true
   */
  enable2FASetup?: boolean;
}

export interface AuthFormContextType extends AuthFormReturn, AuthLayoutConfig {}

// ─────────────────────────────────────────────────────────────────────────────
// Layout Props
// ─────────────────────────────────────────────────────────────────────────────

export interface AuthLayoutProps extends AuthLayoutConfig {
  children?: React.ReactNode;
  className?: string;
  /** URL to redirect after successful auth (default: /dashboard) */
  redirectUrl?: string;
  /** Callback when identifier step succeeds */
  onIdentifierSuccess?: (identifier: string, channel: AuthChannel) => void;
  /** Callback when OTP verification succeeds */
  onOTPSuccess?: () => void;
  /** Callback when OAuth succeeds */
  onOAuthSuccess?: (user: any, isNewUser: boolean, provider: string) => void;
  /** Callback on any error */
  onError?: (message: string) => void;
}

// ─────────────────────────────────────────────────────────────────────────────
// Help Component Props
// ─────────────────────────────────────────────────────────────────────────────

export interface AuthHelpProps {
  className?: string;
  variant?: 'default' | 'compact';
}
