export interface CodexAccount {
  id: string;
  email: string;
  /** User-owned display label; never participates in routing or identity checks. */
  alias?: string;
  plan?: string;
  /**
   * Provenance of `plan`. WHAM (live quota API) is authoritative; the JWT
   * `chatgpt_plan_type` claim is a fallback that may lag a plan change. A JWT write
   * must never overwrite a WHAM-sourced plan observed for the same credential
   * generation — only a newer generation (token refresh after the WHAM read) may.
   */
  planSource?: "jwt" | "wham";
  /** Credential generation at which `plan`/`planSource` was recorded. */
  planCredentialGeneration?: number;
  chatgptAccountId?: string;
  logLabel?: string;
  isMain: boolean;
}

export interface CodexAccountCredentials {
  /** Read-only Orca auth.json link; Orca exclusively owns OAuth refresh. */
  sourceAuthPath?: string;
  /** Bind the link to the originally imported OAuth subject. */
  sourceSubject?: string;
  accessToken: string;
  refreshToken: string;
  expiresAt: number;
  chatgptAccountId: string;
}

export interface CodexAccountCredentialRecord {
  credential?: CodexAccountCredentials;
  generation: number;
  refreshGrantFingerprint?: string;
  /** Private non-secret publication identity, stable across same-account token refresh. */
  quotaHistoryIdentity?: string;
  deletedAt?: number;
  replacedAt?: number;
  lastCodexValidatedAt?: number;
  lastCodexValidationStatus?: "ok" | "failed";
  lastCodexValidationError?: string;
  /** OAuth succeeded while quota was exhausted; never route until deferred validation succeeds. */
  codexValidationPending?: boolean;
  /**
   * Set when the recorded failure is TERMINAL: the OAuth grant itself was revoked or has
   * expired, so no retry can recover it and only a re-login will. It distinguishes a dead
   * credential from a transient warmup or probe failure that may clear on its own.
   *
   * Deliberately a separate optional key rather than a third value in
   * `lastCodexValidationStatus`: `isCredentialRecord` admits only `"ok" | "failed"`, so a
   * record carrying an unrecognized status fails validation and is DROPPED from the store
   * on load. An unknown extra key is carried through untouched instead, which keeps a
   * downgrade from deleting the account entry and its credential.
   *
   * Cleared by `markCodexAccountValidated` and — because it is absent from
   * `preservedValidationMetadata` — by every credential write. A refresh that succeeds
   * disproves "the grant was revoked", so the verdict must not outlive it.
   */
  lastCodexValidationTerminal?: boolean;
}

/** `codexAuthMethod`: "auto" keeps the caller's choice; "device-only" forces the device grant. */
export type CodexAuthMethod = "auto" | "device-only";

/**
 * Codex pool login settings of `OcxConfig`, kept here because `config.ts` sits at its
 * file-size cap.
 */
export interface CodexAccountLoginConfig {
  /**
   * How Codex (ChatGPT) pool account logins authorize.
   *
   * Absent and `"auto"` keep the historical behavior: a browser login with a
   * localhost callback unless the caller explicitly asks for the device grant.
   * `"device-only"` makes every pool add and reauthentication use the device
   * grant, whatever the dashboard or CLI requested, so a headless hub never
   * starts a localhost callback listener. Same-account checks for
   * reauthentication are unchanged, and other providers are not affected.
   */
  codexAuthMethod?: CodexAuthMethod;
}
