interface User {
  /** Unique user identifier (e.g., "usr_abc123") */
  id: string;

  /** Primary email address */
  email: string;

  /** Whether the email has been verified */
  emailVerified: boolean;

  /** Phone number in E.164 format (e.g., "+15550100") */
  phone: string | null;

  /** Whether the phone has been verified */
  phoneVerified: boolean;

  /** User's display name */
  name: UserName | null;

  /** Profile avatar URL */
  avatarUrl: string | null;

  /** Account status */
  status: "active" | "disabled" | "pending_deletion";

  /** Organization the user belongs to (if any) */
  organizationId: string | null;

  /** Preferred locale (e.g., "en-US") */
  locale: string | null;

  /** IANA timezone (e.g., "America/New_York") */
  timezone: string | null;

  /** Whether any MFA method is enrolled */
  mfaEnabled: boolean;

  /** Enrolled MFA methods */
  mfaMethods: MfaMethod[];

  /** Registered passkeys/security keys */
  credentials: Credential[];

  /** Linked social provider accounts */
  linkedProviders: LinkedProvider[];

  /** Custom metadata (public visible to user, admin visible to admins only) */
  metadata: UserMetadata;

  /** ISO 8601 timestamp of account creation */
  createdAt: string;

  /** ISO 8601 timestamp of last profile update */
  updatedAt: string;

  /** ISO 8601 timestamp of last login (null if never) */
  lastLoginAt: string | null;

  /** ISO 8601 timestamp of email verification (null if unverified) */
  verifiedAt: string | null;
}

interface UserName {
  first: string;
  last: string;
}

interface UserTraits {
  name?: UserName;
  phone?: string;        // E.164 format
  locale?: string;       // BCP 47 locale tag
  timezone?: string;     // IANA timezone identifier
  avatarUrl?: string;    // Profile picture URL
}

interface UserMetadata {
  /** Visible to the user and external APIs */
  public: Record<string, unknown>;

  /** Visible only to admin API consumers */
  admin: Record<string, unknown>;
}

type MfaMethod = "totp" | "webauthn" | "recovery_code" | "sms";

interface Credential {
  id: string;
  type: "webauthn" | "password";
  displayName: string;
  createdAt: string;
  lastUsedAt: string | null;
  aaguid: string;
  transports: ("internal" | "hybrid" | "usb" | "ble" | "nfc")[];
}

interface LinkedProvider {
  provider: string;       // "google", "github", "microsoft", "apple"
  providerId: string;     // Provider's unique user ID
  email: string;          // Email from the provider
  linkedAt: string;       // ISO 8601 timestamp
}

interface UserList {
  users: User[];
  nextPageToken: string | null;
  totalSize: number;
}