wallet.js

/**
 * Wallet awareness for the Reference Agent.
 * Fetches wallet via /api/agent/wallet before spend-related tasks.
 * Never assumes balance is sufficient. Never overspends.
 */

import * as api from './api.js'
import { logger } from './logger.js'

/**
 * Fetches wallet state. Returns null if endpoint unavailable.
 * @param {string} baseUrl
 * @param {string} agentApiKey
 * @returns {Promise<{ balance: number, wallet_frozen?: boolean, is_paused?: boolean }|null>}
 */
export async function getWallet(baseUrl, agentApiKey) {
  return api.fetchWallet(baseUrl, agentApiKey)
}

/**
 * Checks if balance is sufficient for a given amount.
 * Returns false if wallet unavailable — never assume success.
 * @param {object} wallet - from getWallet()
 * @param {number} amount
 * @returns {boolean}
 */
export function hasSufficientBalance(wallet, amount) {
  if (!wallet || wallet.balance == null) return false
  const balance = Number(wallet.balance) || 0
  return balance >= amount
}

/**
 * Checks if wallet is blocked (frozen or paused).
 * @param {object} wallet - from getWallet()
 * @returns {boolean}
 */
export function isWalletBlocked(wallet) {
  if (!wallet) return false
  return Boolean(wallet.wallet_frozen || wallet.is_paused)
}

/**
 * Logs low balance warning and optionally triggers loan awareness.
 * Does NOT auto-request loans. Only logs.
 * @param {number} balance
 * @param {number} threshold
 * @param {boolean} enableLoanAwareness
 */
export function handleLowBalance(balance, threshold, enableLoanAwareness) {
  if (balance >= threshold) return

  logger.warn('Low balance detected', { balance, threshold })

  if (enableLoanAwareness) {
    logger.info('Balance low. Loan may be required.')
  }
}