import type { Address, Chain, PublicClient, WalletClient } from 'viem'
import type { LocalAccount } from 'viem/accounts'
import type { AnimaNetwork } from '../config'

/**
 * The operator is the human (or organization) behind an anima agent. Per
 * project-anima.md section 22.1, the operator's wallet is what OWNS the
 * ERC-7857 iNFT. A separate agent EOA (generated by `anima init`) is a
 * pay-for-infra key that the operator approves via `setApprovalForAll`.
 *
 * Operator signing material can come from many sources. First-class sources:
 * - WalletConnect v2 (QR pair to any WC-compatible mobile wallet)
 * - OS keychain (macOS Keychain, later libsecret and Credential Manager)
 * - Encrypted keystore file (geth-format JSON)
 * - Raw private key (CLI/scripting, env var, or stdin prompt)
 *
 * This interface is the abstraction a caller uses without caring which source
 * is behind it. All four implementations satisfy the same contract, so init
 * flow, topup flow, and future governance flows can pick at runtime.
 */
export interface OperatorSigner {
  /** Source label for logs + UI ("keychain:<service>", "walletconnect:<peer>", "keystore:<path>", ...). */
  readonly source: string
  /** Operator's on-chain address. Becomes the iNFT owner. */
  address(): Promise<Address>
  /**
   * viem LocalAccount for composing with wallet clients. For privkey-based
   * sources (keychain, keystore file, raw) this is a `PrivateKeyAccount`. For
   * WalletConnect it's a custom local account whose sign methods delegate to
   * the paired mobile wallet over the WC relay. Keeping the return type as
   * `LocalAccount` (not the broader `Account`) guarantees `signTypedData` is
   * reachable, which Phase 6.6 needs for the sign-derived-key keystore.
   */
  account(): Promise<LocalAccount>
  /** A wallet client bound to `network` that signs from the operator's address. */
  walletClient(network: AnimaNetwork): Promise<WalletClient>
  /** A public client for the same network (reads only). */
  publicClient(network: AnimaNetwork): Promise<PublicClient>
  /** Chain metadata as viem Chain, per network. */
  chain(network: AnimaNetwork): Chain
  /**
   * Optional teardown. WalletConnect uses this to close the session cleanly;
   * privkey-based sources have nothing to release. Safe to call unconditionally.
   */
  close?(): Promise<void>
}