// ================================================================
// frontend/src/api/types/auth.ts
// ================================================================
/**
 * Authentication Type Definitions
 *
 * Aligned with backend schemas:
 * - services/auth/app/schemas/auth.py
 * - services/auth/app/schemas/users.py
 *
 * Last Updated: 2025-10-05
 * Status: ✅ Complete - Zero drift with backend
 */

// ================================================================
// REQUEST TYPES
// ================================================================

/**
 * User registration request
 * Backend: services/auth/app/schemas/auth.py:15-29 (UserRegistration)
 */
export interface UserRegistration {
  email: string;  // EmailStr - validated email format
  password: string;  // min_length=8, max_length=128
  full_name: string;  // min_length=1, max_length=255
  tenant_name?: string | null;  // max_length=255
  role?: string | null;  // Default: "admin", pattern: ^(user|admin|manager|super_admin)$
  subscription_plan?: string | null;  // Default: "starter", options: starter, professional, enterprise
  use_trial?: boolean | null;  // Default: false - Whether to use trial period
  payment_method_id?: string | null;  // Stripe payment method ID
  coupon_code?: string | null;  // Promotional coupon code for discounts/trial extensions
  // GDPR Consent fields
  terms_accepted?: boolean;  // Default: true - Accept terms of service
  privacy_accepted?: boolean;  // Default: true - Accept privacy policy
  marketing_consent?: boolean;  // Default: false - Consent to marketing communications
  analytics_consent?: boolean;  // Default: false - Consent to analytics cookies
}

/**
 * User login request
 * Backend: services/auth/app/schemas/auth.py:26-29 (UserLogin)
 */
export interface UserLogin {
  email: string;  // EmailStr - validated email format
  password: string;
}

/**
 * Refresh token request
 * Backend: services/auth/app/schemas/auth.py:31-33 (RefreshTokenRequest)
 */
export interface RefreshTokenRequest {
  refresh_token: string;
}

/**
 * Password change request
 * Backend: services/auth/app/schemas/auth.py:35-38 (PasswordChange)
 */
export interface PasswordChange {
  current_password: string;
  new_password: string;  // min_length=8, max_length=128
}

/**
 * Password reset request (initiate reset)
 * Backend: services/auth/app/schemas/auth.py:40-42 (PasswordReset)
 */
export interface PasswordReset {
  email: string;  // EmailStr - validated email format
}

/**
 * Password reset confirmation (complete reset)
 * Backend: services/auth/app/schemas/auth.py:44-47 (PasswordResetConfirm)
 */
export interface PasswordResetConfirm {
  token: string;
  new_password: string;  // min_length=8, max_length=128
}

/**
 * Email verification request
 * Backend: services/auth/app/schemas/auth.py:173-175 (EmailVerificationRequest)
 */
export interface EmailVerificationRequest {
  email: string;  // EmailStr - validated email format
}

/**
 * Email verification confirmation
 * Backend: services/auth/app/schemas/auth.py:177-179 (EmailVerificationConfirm)
 */
export interface EmailVerificationConfirm {
  token: string;
}

/**
 * Profile update request
 * Backend: services/auth/app/schemas/auth.py:181-184 (ProfileUpdate)
 */
export interface ProfileUpdate {
  full_name?: string | null;  // min_length=1, max_length=255
  email?: string | null;  // EmailStr - validated email format
}

/**
 * User update schema
 * Backend: services/auth/app/schemas/users.py:14-26 (UserUpdate)
 */
export interface UserUpdate {
  full_name?: string | null;  // min_length=2, max_length=100
  phone?: string | null;  // Spanish phone validation applied on backend
  language?: string | null;  // pattern: ^(es|en)$
  timezone?: string | null;
}

// ================================================================
// RESPONSE TYPES
// ================================================================

/**
 * User data embedded in token responses
 * Backend: services/auth/app/schemas/auth.py:53-62 (UserData)
 */
export interface UserData {
  id: string;
  email: string;
  full_name: string;
  is_active: boolean;
  is_verified: boolean;
  created_at: string;  // ISO format datetime string
  tenant_id?: string | null;
  role?: string | null;  // Default: "admin"
}

/**
 * Unified token response for both registration and login
 * Follows industry standards (Firebase, AWS Cognito, etc.)
 * Backend: services/auth/app/schemas/auth.py:64-92 (TokenResponse)
 */
export interface TokenResponse {
  access_token: string;
  refresh_token?: string | null;
  token_type: string;  // Default: "bearer"
  expires_in: number;  // Default: 3600 seconds
  user?: UserData | null;
}

/**
 * User response for user management endpoints
 * Backend: services/auth/app/schemas/auth.py:94-110 (UserResponse)
 */
export interface UserResponse {
  id: string;
  email: string;
  full_name: string;
  is_active: boolean;
  is_verified: boolean;
  created_at: string;  // ISO datetime string
  last_login?: string | null;  // ISO datetime string
  phone?: string | null;
  language?: string | null;
  timezone?: string | null;
  tenant_id?: string | null;
  role?: string | null;  // Default: "admin"
}

/**
 * User profile schema
 * Backend: services/auth/app/schemas/users.py:28-42 (UserProfile)
 */
export interface UserProfile {
  id: string;
  email: string;
  full_name: string;
  phone?: string | null;
  language: string;
  timezone: string;
  is_active: boolean;
  is_verified: boolean;
  created_at: string;  // ISO datetime string
  last_login?: string | null;  // ISO datetime string
}

/**
 * Token verification response
 * Backend: services/auth/app/schemas/auth.py:123-129 (TokenVerification)
 */
export interface TokenVerification {
  valid: boolean;
  user_id?: string | null;
  email?: string | null;
  exp?: number | null;  // Expiration timestamp
  message?: string | null;
}

/**
 * Password reset response
 * Backend: services/auth/app/schemas/auth.py:131-134 (PasswordResetResponse)
 */
export interface PasswordResetResponse {
  message: string;
  reset_token?: string | null;
}

/**
 * Logout response
 * Backend: services/auth/app/schemas/auth.py:136-139 (LogoutResponse)
 */
export interface LogoutResponse {
  message: string;
  success: boolean;  // Default: true
}

// ================================================================
// ERROR TYPES
// ================================================================

/**
 * Error detail for API responses
 * Backend: services/auth/app/schemas/auth.py:145-149 (ErrorDetail)
 */
export interface ErrorDetail {
  message: string;
  code?: string | null;
  field?: string | null;
}

/**
 * Standardized error response
 * Backend: services/auth/app/schemas/auth.py:151-167 (ErrorResponse)
 */
export interface ErrorResponse {
  success: boolean;  // Default: false
  error: ErrorDetail;
  timestamp: string;  // ISO datetime string
}

// ================================================================
// INTERNAL TYPES (for service communication)
// ================================================================

/**
 * User context for internal service communication
 * Backend: services/auth/app/schemas/auth.py:190-196 (UserContext)
 */
export interface UserContext {
  user_id: string;
  email: string;
  tenant_id?: string | null;
  roles: string[];  // Default: ["admin"]
  is_verified: boolean;  // Default: false
}

/**
 * JWT token claims structure
 * Backend: services/auth/app/schemas/auth.py:198-208 (TokenClaims)
 */
export interface TokenClaims {
  sub: string;  // subject (user_id)
  email: string;
  full_name: string;
  user_id: string;
  is_verified: boolean;
  tenant_id?: string | null;
  iat: number;  // issued at timestamp
  exp: number;  // expires at timestamp
  iss: string;  // issuer - Default: "bakery-auth"
}
