/**
 * IAuthRepository 接口
 *
 * 对齐 Dart 端 `AuthRepository` 抽象（lib/data/repositories/auth_repository.dart）：
 *   - 登录 / 登出 / 刷新 token / 第三方 OAuth 登录的公共契约
 *   - 登出强制清本地态（无论 API 成败）
 *   - `getCurrentUser` 成功后尽力写本地 User 缓存（best-effort）
 *   - 所有方法返回 `Promise<Result<T>>`，与 Dart `Future<Result<T>>` 对齐
 *
 * 注：仓库内私有方法（`_socialLogin` / `_saveLoginData`）不暴露在接口上。
 * 
 */

import type { Result } from "@/utils/result";
import type {
  CheckoutHandoffCreateResponse,
  CheckoutIntent,
  GuestLoginResponse,
  LoginStatus,
  LoginResponse,
  RefreshTokenResponse,
} from "@/data/schemas/auth";
import type { User } from "@/data/schemas/user";

export interface IAuthRepository {
  /** 用户注册。注册成功不会自动登录（与 Dart 行为一致）。 */
  register(input: {
    username: string;
    email: string;
    password: string;
    guestId?: string;
  }): Promise<Result<void>>;

  /** 邮箱/用户名 + 密码登录。 */
  emailLogin(input: {
    email?: string;
    username?: string;
    password: string;
    guestId?: string;
    psid?: string;
  }): Promise<Result<LoginResponse>>;

  /** 退出真实用户登录并恢复游客态。 */
  logout(): Promise<Result<void>>;

  /** 游客登录：使用 deviceId 换取 guest token。 */
  guestLogin(deviceId: string): Promise<Result<GuestLoginResponse>>;

  /** Google 登录。 */
  googleLogin(input: {
    idToken: string;
    guestId?: string;
    psid?: string;
  }): Promise<Result<LoginResponse>>;

  /** Facebook 登录（accessToken 流程）。 */
  facebookLogin(input: {
    accessToken: string;
    guestId?: string;
    psid?: string;
  }): Promise<Result<LoginResponse>>;

  /** 通过 ASID 登录。 */
  facebookAsidLogin(input: {
    asid: string;
    avatarUrl?: string;
    psid?: string;
  }): Promise<Result<LoginResponse>>;

  /** 绑定 Facebook ASID / PSID 到当前登录用户。 */
  bindFacebookIdentity(input: {
    asid?: string;
    psid?: string;
  }): Promise<Result<void>>;

  /** 消费一次性充值登录凭证并建立正式会话。 */
  consumeTopUpHandoff(handoffToken: string): Promise<Result<LoginStatus>>;

  /** 在创建订单前生成10分钟有效的外部浏览器支付链接。 */
  createCheckoutHandoff(
    checkoutIntent: CheckoutIntent,
  ): Promise<Result<CheckoutHandoffCreateResponse>>;

  /** 消费单次支付交接凭证并保存正式登录态。 */
  consumeCheckoutHandoff(
    handoffToken: string,
  ): Promise<Result<CheckoutIntent>>;

  /** 刷新 token：先读本地的 refresh token，空则返回错误。 */
  refreshToken(): Promise<Result<RefreshTokenResponse>>;

  /** 获取当前登录用户。成功后尽力写本地 User 缓存。 */
  getCurrentUser(): Promise<Result<User>>;
}
