@routstr/sdk 0.3.7 → 0.3.8

package/dist/wallet/index.mjs

@@ -0,0 +1,1373 @@
+import { getDecodedToken } from '@cashu/cashu-ts';
+
+// core/types.ts
+function makeConsoleLogger(prefix) {
+  const fmt = (args) => prefix ? [prefix, ...args] : args;
+  return {
+    log: (...args) => console.log(...fmt(args)),
+    warn: (...args) => console.warn(...fmt(args)),
+    error: (...args) => console.error(...fmt(args)),
+    debug: (...args) => console.log(...fmt(args)),
+    child: (p) => makeConsoleLogger(prefix ? `${prefix}:${p}` : p)
+  };
+}
+var consoleLogger = makeConsoleLogger();
+
+// core/errors.ts
+var InsufficientBalanceError = class extends Error {
+  constructor(required, available, maxMintBalance = 0, maxMintUrl = "", customMessage) {
+    super(
+      customMessage ?? `Insufficient balance: need ${required} sats, have ${available} sats available. ` + (maxMintBalance > 0 ? `Largest mint balance: ${maxMintBalance} sats from ${maxMintUrl}` : "")
+    );
+    this.required = required;
+    this.available = available;
+    this.maxMintBalance = maxMintBalance;
+    this.maxMintUrl = maxMintUrl;
+    this.name = "InsufficientBalanceError";
+  }
+  required;
+  available;
+  maxMintBalance;
+  maxMintUrl;
+};
+
+// wallet/AuditLogger.ts
+var AuditLogger = class _AuditLogger {
+  static instance = null;
+  static getInstance() {
+    if (!_AuditLogger.instance) {
+      _AuditLogger.instance = new _AuditLogger();
+    }
+    return _AuditLogger.instance;
+  }
+  async log(entry) {
+    const fullEntry = {
+      ...entry,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const logLine = JSON.stringify(fullEntry) + "\n";
+    if (typeof window === "undefined") {
+      try {
+        const fs = await import('fs');
+        const path = await import('path');
+        const logPath = path.join(process.cwd(), "audit.log");
+        fs.appendFileSync(logPath, logLine);
+      } catch (error) {
+        console.error("[AuditLogger] Failed to write to file:", error);
+      }
+    } else {
+      console.log("[AUDIT]", logLine.trim());
+    }
+  }
+  async logBalanceSnapshot(action, amounts, options) {
+    await this.log({
+      action,
+      totalBalance: amounts.totalBalance,
+      providerBalances: amounts.providerBalances,
+      mintBalances: amounts.mintBalances,
+      amount: options?.amount,
+      mintUrl: options?.mintUrl,
+      baseUrl: options?.baseUrl,
+      status: options?.status ?? "success",
+      details: options?.details
+    });
+  }
+};
+var auditLogger = AuditLogger.getInstance();
+
+// wallet/tokenUtils.ts
+function isNetworkErrorMessage(message) {
+  return message.includes("NetworkError when attempting to fetch resource") || message.includes("Failed to fetch") || message.includes("Load failed") || message.includes("ERR_TLS_CERT_ALTNAME_INVALID") || message.includes("ERR_TLS_CERT_NOT_YET_VALID") || message.includes("ERR_TLS_CERT_EXPIRED") || message.includes("UNABLE_TO_VERIFY_LEAF_SIGNATURE") || message.includes("SELF_SIGNED_CERT_IN_CHAIN");
+}
+function getBalanceInSats(balance, unit) {
+  return unit === "msat" ? balance / 1e3 : balance;
+}
+function selectMintWithBalance(balances, units, amount, excludeMints = []) {
+  for (const mintUrl in balances) {
+    if (excludeMints.includes(mintUrl)) {
+      continue;
+    }
+    const balanceInSats = getBalanceInSats(balances[mintUrl], units[mintUrl]);
+    if (balanceInSats >= amount) {
+      return { selectedMintUrl: mintUrl, selectedMintBalance: balanceInSats };
+    }
+  }
+  return { selectedMintUrl: null, selectedMintBalance: 0 };
+}
+var CashuSpender = class {
+  constructor(walletAdapter, storageAdapter, _providerRegistry, balanceManager, logger) {
+    this.walletAdapter = walletAdapter;
+    this.storageAdapter = storageAdapter;
+    this._providerRegistry = _providerRegistry;
+    this.balanceManager = balanceManager;
+    this.logger = (logger ?? consoleLogger).child("CashuSpender");
+  }
+  walletAdapter;
+  storageAdapter;
+  _providerRegistry;
+  balanceManager;
+  _isBusy = false;
+  debugLevel = "WARN";
+  logger;
+  async receiveToken(token) {
+    try {
+      const result = await this.walletAdapter.receiveToken(token);
+      return result;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      if (errorMessage.includes("Failed to fetch mint")) {
+        const cachedTokens = this.storageAdapter.getCachedReceiveTokens();
+        const existingIndex = cachedTokens.findIndex((t) => t.token === token);
+        if (existingIndex === -1) {
+          const { amount: amount2, unit: unit2 } = this._decodeTokenAmount(token);
+          this.storageAdapter.setCachedReceiveTokens([
+            ...cachedTokens,
+            {
+              token,
+              amount: amount2,
+              unit: unit2,
+              createdAt: Date.now()
+            }
+          ]);
+        }
+      }
+      const { amount, unit } = this._decodeTokenAmount(token);
+      return { success: false, amount, unit, message: errorMessage };
+    }
+  }
+  _decodeTokenAmount(token) {
+    try {
+      const decoded = getDecodedToken(token);
+      const amount = decoded.proofs.reduce(
+        (acc, proof) => acc + proof.amount,
+        0
+      );
+      const unit = decoded.unit || "sat";
+      return { amount, unit };
+    } catch {
+      return { amount: 0, unit: "sat" };
+    }
+  }
+  async _getBalanceState() {
+    if (this.balanceManager) {
+      return this.balanceManager.getBalanceState();
+    }
+    const mintBalances = await this.walletAdapter.getBalances();
+    const units = this.walletAdapter.getMintUnits();
+    let totalMintBalance = 0;
+    const normalizedMintBalances = {};
+    for (const url in mintBalances) {
+      const balance = mintBalances[url];
+      const unit = units[url];
+      const balanceInSats = getBalanceInSats(balance, unit);
+      normalizedMintBalances[url] = balanceInSats;
+      totalMintBalance += balanceInSats;
+    }
+    const providerBalances = {};
+    let totalProviderBalance = 0;
+    const apiKeys = this.storageAdapter.getAllApiKeys();
+    for (const apiKey of apiKeys) {
+      if (!providerBalances[apiKey.baseUrl]) {
+        providerBalances[apiKey.baseUrl] = 0;
+      }
+      providerBalances[apiKey.baseUrl] += apiKey.balance;
+      totalProviderBalance += apiKey.balance;
+    }
+    return {
+      totalBalance: totalMintBalance + totalProviderBalance,
+      providerBalances,
+      mintBalances: normalizedMintBalances
+    };
+  }
+  async _logTransaction(action, options) {
+    const balanceState = await this._getBalanceState();
+    await auditLogger.logBalanceSnapshot(action, balanceState, options);
+  }
+  /**
+   * Check if the spender is currently in a critical operation
+   */
+  get isBusy() {
+    return this._isBusy;
+  }
+  getDebugLevel() {
+    return this.debugLevel;
+  }
+  setDebugLevel(level) {
+    this.debugLevel = level;
+  }
+  _log(level, ...args) {
+    const levelPriority = {
+      DEBUG: 0,
+      WARN: 1,
+      ERROR: 2
+    };
+    if (levelPriority[level] >= levelPriority[this.debugLevel]) {
+      switch (level) {
+        case "DEBUG":
+          this.logger.log(...args);
+          break;
+        case "WARN":
+          this.logger.warn(...args);
+          break;
+        case "ERROR":
+          this.logger.error(...args);
+          break;
+      }
+    }
+  }
+  /**
+   * Spend Cashu tokens with automatic mint selection and retry logic
+   * Throws errors on failure instead of returning failed SpendResult
+   */
+  async spend(options) {
+    const {
+      mintUrl,
+      amount,
+      baseUrl,
+      reuseToken = false,
+      p2pkPubkey,
+      excludeMints = [],
+      retryCount = 0
+    } = options;
+    this._isBusy = true;
+    try {
+      const result = await this._spendInternal({
+        mintUrl,
+        amount,
+        baseUrl,
+        reuseToken,
+        p2pkPubkey,
+        excludeMints,
+        retryCount
+      });
+      if (result.status === "failed" || !result.token) {
+        const errorMsg = result.error || `Insufficient balance. Need ${amount} sats.`;
+        if (this._isNetworkError(errorMsg)) {
+          throw new Error(
+            `Your mint ${mintUrl} is unreachable or is blocking your IP. Please try again later or switch mints.`
+          );
+        }
+        if (result.errorDetails) {
+          throw new InsufficientBalanceError(
+            result.errorDetails.required,
+            result.errorDetails.available,
+            result.errorDetails.maxMintBalance,
+            result.errorDetails.maxMintUrl
+          );
+        }
+        throw new Error(errorMsg);
+      }
+      return result;
+    } finally {
+      this._isBusy = false;
+    }
+  }
+  /**
+   * Check if error message indicates a network error
+   */
+  _isNetworkError(message) {
+    return isNetworkErrorMessage(message) || message.includes("Your mint") && message.includes("unreachable");
+  }
+  /**
+   * Internal spending logic
+   */
+  async _spendInternal(options) {
+    let {
+      mintUrl,
+      amount,
+      baseUrl,
+      reuseToken,
+      p2pkPubkey,
+      excludeMints,
+      retryCount
+    } = options;
+    this._log(
+      "DEBUG",
+      `[CashuSpender] _spendInternal: amount=${amount}, mintUrl=${mintUrl}, baseUrl=${baseUrl}, reuseToken=${reuseToken}`
+    );
+    let adjustedAmount = Math.ceil(amount);
+    if (!adjustedAmount || isNaN(adjustedAmount)) {
+      this._log(
+        "ERROR",
+        `[CashuSpender] _spendInternal: Invalid amount: ${amount}`
+      );
+      return {
+        token: null,
+        status: "failed",
+        balance: 0,
+        error: "Please enter a valid amount"
+      };
+    }
+    if (reuseToken && baseUrl) {
+      this._log(
+        "DEBUG",
+        `[CashuSpender] _spendInternal: Attempting to reuse token for ${baseUrl}`
+      );
+      const existingResult = await this._tryReuseToken(
+        baseUrl,
+        adjustedAmount,
+        mintUrl
+      );
+      if (existingResult) {
+        this._log(
+          "DEBUG",
+          `[CashuSpender] _spendInternal: Successfully reused token, balance: ${existingResult.balance}`
+        );
+        return existingResult;
+      }
+      this._log(
+        "DEBUG",
+        `[CashuSpender] _spendInternal: Could not reuse token, will create new token`
+      );
+    }
+    const balanceState = await this._getBalanceState();
+    const totalAvailableBalance = balanceState.totalBalance;
+    this._log(
+      "DEBUG",
+      `[CashuSpender] _spendInternal: totalAvailableBalance=${totalAvailableBalance}, adjustedAmount=${adjustedAmount}`
+    );
+    if (totalAvailableBalance < adjustedAmount) {
+      this._log(
+        "ERROR",
+        `[CashuSpender] _spendInternal: Insufficient balance, have=${totalAvailableBalance}, need=${adjustedAmount}`
+      );
+      return this._createInsufficientBalanceError(
+        adjustedAmount,
+        balanceState.mintBalances,
+        totalAvailableBalance
+      );
+    }
+    let token = null;
+    let selectedMintUrl;
+    let spentAmount = adjustedAmount;
+    if (this.balanceManager) {
+      const tokenResult = await this.balanceManager.createProviderToken({
+        mintUrl,
+        baseUrl,
+        amount: adjustedAmount,
+        p2pkPubkey,
+        excludeMints,
+        retryCount
+      });
+      if (!tokenResult.success || !tokenResult.token) {
+        if ((tokenResult.error || "").includes("Insufficient balance")) {
+          return this._createInsufficientBalanceError(
+            adjustedAmount,
+            balanceState.mintBalances,
+            totalAvailableBalance
+          );
+        }
+        return {
+          token: null,
+          status: "failed",
+          balance: 0,
+          error: tokenResult.error || "Failed to create token"
+        };
+      }
+      token = tokenResult.token;
+      selectedMintUrl = tokenResult.selectedMintUrl;
+      spentAmount = tokenResult.amountSpent || adjustedAmount;
+    } else {
+      try {
+        token = await this.walletAdapter.sendToken(
+          mintUrl,
+          adjustedAmount,
+          p2pkPubkey
+        );
+        selectedMintUrl = mintUrl;
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        return {
+          token: null,
+          status: "failed",
+          balance: 0,
+          error: `Error generating token: ${errorMsg}`
+        };
+      }
+    }
+    if (token) {
+      this._log(
+        "DEBUG",
+        `[CashuSpender] _spendInternal: Successfully spent ${spentAmount}, returning token with balance=${spentAmount}`
+      );
+    }
+    this._logTransaction("spend", {
+      amount: spentAmount,
+      mintUrl: selectedMintUrl || mintUrl,
+      baseUrl,
+      status: "success"
+    });
+    this._log(
+      "DEBUG",
+      `[CashuSpender] _spendInternal: Successfully spent ${spentAmount}, returning token with balance=${spentAmount}`
+    );
+    const units = this.walletAdapter.getMintUnits();
+    return {
+      token,
+      status: "success",
+      balance: spentAmount,
+      unit: (selectedMintUrl ? units[selectedMintUrl] : units[mintUrl]) || "sat"
+    };
+  }
+  /**
+   * Try to reuse an existing API key
+   */
+  async _tryReuseToken(baseUrl, amount, mintUrl) {
+    const apiKeyEntry = this.storageAdapter.getApiKey(baseUrl);
+    if (!apiKeyEntry) return null;
+    const apiKeyDistribution = this.storageAdapter.getApiKeyDistribution();
+    const balanceForBaseUrl = apiKeyDistribution.find((b) => b.baseUrl === baseUrl)?.amount || 0;
+    this._log("DEBUG", "Reusing API key", balanceForBaseUrl, amount);
+    if (balanceForBaseUrl > amount) {
+      const units = this.walletAdapter.getMintUnits();
+      const unit = units[mintUrl] || "sat";
+      return {
+        token: apiKeyEntry.key,
+        status: "success",
+        balance: balanceForBaseUrl,
+        unit
+      };
+    }
+    if (this.balanceManager) {
+      const topUpAmount = Math.ceil(amount * 1.2 - balanceForBaseUrl);
+      const topUpResult = await this.balanceManager.topUp({
+        mintUrl,
+        baseUrl,
+        amount: topUpAmount,
+        token: apiKeyEntry.key
+      });
+      this._log("DEBUG", "TOPUP ", topUpResult);
+      if (topUpResult.success && topUpResult.toppedUpAmount) {
+        const newBalance = balanceForBaseUrl + topUpResult.toppedUpAmount;
+        const units = this.walletAdapter.getMintUnits();
+        const unit = units[mintUrl] || "sat";
+        this._logTransaction("topup", {
+          amount: topUpResult.toppedUpAmount,
+          mintUrl,
+          baseUrl,
+          status: "success"
+        });
+        return {
+          token: apiKeyEntry.key,
+          status: "success",
+          balance: newBalance,
+          unit
+        };
+      }
+      const providerBalance = await this._getProviderTokenBalance(
+        baseUrl,
+        apiKeyEntry.key
+      );
+      this._log("DEBUG", providerBalance);
+      if (providerBalance <= 0) {
+        this.storageAdapter.removeApiKey(baseUrl);
+      }
+    }
+    return null;
+  }
+  /**
+   * Refund all xcashu tokens from storage by calling the provider's refund endpoint.
+   * The xcashu token acts as an API key to claim the refund, and the response contains
+   * the actual refunded Cashu token which is then received into the wallet.
+   * @param mintUrl - The mint URL for receiving tokens
+   * @param excludeBaseUrls - Base URLs to exclude from refund (optional)
+   * @returns Results for each xcashu token refund attempt
+   */
+  async refundXcashuTokens(mintUrl, excludeBaseUrls) {
+    const results = [];
+    const xcashuTokens = this.storageAdapter.getXcashuTokens();
+    const excludedUrls = new Set(excludeBaseUrls || []);
+    for (const [baseUrl, tokens] of Object.entries(xcashuTokens)) {
+      if (excludedUrls.has(baseUrl)) continue;
+      for (const xcashuToken of tokens) {
+        try {
+          if (!this.balanceManager) {
+            throw new Error("BalanceManager not available for xcashu refund");
+          }
+          const fetchResult = await this.balanceManager.fetchRefundToken(
+            baseUrl,
+            xcashuToken.token,
+            true
+          );
+          if (!fetchResult.success || !fetchResult.token) {
+            throw new Error(
+              fetchResult.error || "Failed to fetch refund token from provider"
+            );
+          }
+          const receiveResult = await this.receiveToken(fetchResult.token);
+          if (receiveResult.success) {
+            this.storageAdapter.removeXcashuToken(baseUrl, xcashuToken.token);
+            results.push({
+              baseUrl,
+              token: xcashuToken.token,
+              success: true
+            });
+            this._log(
+              "DEBUG",
+              `[CashuSpender] refundXcashuTokens: Successfully refunded xcashu token for ${baseUrl}, amount=${receiveResult.amount}`
+            );
+          } else {
+            const currentTryCount = xcashuToken.tryCount ?? 0;
+            const newTryCount = currentTryCount + 1;
+            this.storageAdapter.updateXcashuTokenTryCount(
+              xcashuToken.token,
+              newTryCount
+            );
+            results.push({
+              baseUrl,
+              token: xcashuToken.token,
+              success: false,
+              error: receiveResult.message ?? "Refund failed"
+            });
+            this._log(
+              "DEBUG",
+              `[CashuSpender] refundXcashuTokens: Failed to receive refund token for ${baseUrl}, incremented tryCount to ${newTryCount}: ${receiveResult.message}`
+            );
+          }
+        } catch (error) {
+          const currentTryCount = xcashuToken.tryCount ?? 0;
+          const newTryCount = currentTryCount + 1;
+          this.storageAdapter.updateXcashuTokenTryCount(
+            xcashuToken.token,
+            newTryCount
+          );
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          results.push({
+            baseUrl,
+            token: xcashuToken.token,
+            success: false,
+            error: errorMessage
+          });
+          this._log(
+            "ERROR",
+            `[CashuSpender] refundXcashuTokens: Exception during refund for ${baseUrl}: ${errorMessage}, incremented tryCount to ${newTryCount}`
+          );
+        }
+      }
+    }
+    return results;
+  }
+  /**
+   * Refund specific providers without retrying spend
+   */
+  async refundProviders(mintUrl, forceRefund) {
+    const results = [];
+    const apiKeyDistribution = this.storageAdapter.getApiKeyDistribution();
+    for (const apiKeyEntry of apiKeyDistribution) {
+      const apiKeyEntryFull = this.storageAdapter.getApiKey(
+        apiKeyEntry.baseUrl
+      );
+      if (apiKeyEntryFull && this.balanceManager) {
+        try {
+          const balanceResult = await this.balanceManager.getTokenBalance(
+            apiKeyEntryFull.key,
+            apiKeyEntry.baseUrl
+          );
+          if (balanceResult.isInvalidApiKey) {
+            this.logger.warn(
+              `refundProviders: ${apiKeyEntry.baseUrl} returned invalid API key; removing local key and treating as success`
+            );
+            this.storageAdapter.removeApiKey(apiKeyEntry.baseUrl);
+            results.push({
+              baseUrl: apiKeyEntry.baseUrl,
+              success: true
+            });
+            continue;
+          }
+          if (balanceResult.amount >= 0) {
+            const balanceSat = balanceResult.unit === "msat" ? Math.floor(balanceResult.amount / 1e3) : balanceResult.amount;
+            this.storageAdapter.updateApiKeyBalance(
+              apiKeyEntry.baseUrl,
+              balanceSat
+            );
+          } else {
+            this.logger.warn(
+              `refundProviders: balance refresh for ${apiKeyEntry.baseUrl} returned negative amount; keeping stale local balance=${apiKeyEntryFull.balance}`
+            );
+          }
+        } catch (error) {
+          this.logger.warn(
+            `refundProviders: balance refresh threw for ${apiKeyEntry.baseUrl}; proceeding with stale local balance`,
+            error
+          );
+        }
+        const refreshedEntry = this.storageAdapter.getApiKey(
+          apiKeyEntry.baseUrl
+        );
+        if (!refreshedEntry) {
+          continue;
+        }
+        const refundResult = await this.balanceManager.refundApiKey({
+          mintUrl,
+          baseUrl: apiKeyEntry.baseUrl,
+          apiKey: refreshedEntry.key,
+          forceRefund
+        });
+        if (refundResult.success) {
+          this.storageAdapter.removeApiKey(apiKeyEntry.baseUrl);
+        } else {
+          const currentEntry = this.storageAdapter.getApiKey(
+            apiKeyEntry.baseUrl
+          );
+          this.logger.warn(
+            `refundProviders: refund failed for ${apiKeyEntry.baseUrl}; currentEntry=${Boolean(currentEntry)} balance=${currentEntry?.balance ?? "none"}. Touching lastUsed to rate-limit retries.`
+          );
+          if (currentEntry) {
+            this.storageAdapter.updateApiKeyBalance(
+              apiKeyEntry.baseUrl,
+              currentEntry.balance
+            );
+          }
+        }
+        results.push({
+          baseUrl: apiKeyEntry.baseUrl,
+          success: refundResult.success
+        });
+      } else {
+        this.logger.warn(
+          `refundProviders: cannot refund ${apiKeyEntry.baseUrl}; apiKeyEntryFull=${Boolean(apiKeyEntryFull)} balanceManager=${Boolean(this.balanceManager)}`
+        );
+        results.push({
+          baseUrl: apiKeyEntry.baseUrl,
+          success: false
+        });
+      }
+    }
+    return results;
+  }
+  /**
+   * Create an insufficient balance error result
+   */
+  _createInsufficientBalanceError(required, normalizedBalances, availableBalance) {
+    let maxBalance = 0;
+    let maxMintUrl = "";
+    for (const mintUrl in normalizedBalances) {
+      const balanceInSats = normalizedBalances[mintUrl];
+      if (balanceInSats > maxBalance) {
+        maxBalance = balanceInSats;
+        maxMintUrl = mintUrl;
+      }
+    }
+    const error = new InsufficientBalanceError(
+      required,
+      availableBalance ?? maxBalance,
+      maxBalance,
+      maxMintUrl
+    );
+    return {
+      token: null,
+      status: "failed",
+      balance: 0,
+      error: error.message,
+      errorDetails: {
+        required,
+        available: availableBalance ?? maxBalance,
+        maxMintBalance: maxBalance,
+        maxMintUrl
+      }
+    };
+  }
+  async _getProviderTokenBalance(baseUrl, token) {
+    try {
+      const response = await fetch(`${baseUrl}v1/wallet/info`, {
+        headers: {
+          Authorization: `Bearer ${token}`
+        }
+      });
+      if (response.ok) {
+        const data = await response.json();
+        return data.balance / 1e3;
+      }
+    } catch {
+      return 0;
+    }
+    return 0;
+  }
+};
+
+// wallet/BalanceManager.ts
+var BalanceManager = class _BalanceManager {
+  constructor(walletAdapter, storageAdapter, providerRegistry, cashuSpender, logger) {
+    this.walletAdapter = walletAdapter;
+    this.storageAdapter = storageAdapter;
+    this.providerRegistry = providerRegistry;
+    this.logger = (logger ?? consoleLogger).child("BalanceManager");
+    if (cashuSpender) {
+      this.cashuSpender = cashuSpender;
+    } else {
+      this.cashuSpender = new CashuSpender(
+        walletAdapter,
+        storageAdapter,
+        providerRegistry,
+        this,
+        this.logger
+      );
+    }
+  }
+  walletAdapter;
+  storageAdapter;
+  providerRegistry;
+  cashuSpender;
+  /** In-memory guard for per-provider wallet mutations (topup / refund) */
+  providerWalletOps = /* @__PURE__ */ new Map();
+  /** Cooldown (ms) between opposite operations on the same provider */
+  static PROVIDER_WALLET_COOLDOWN_MS = 1e4;
+  logger;
+  /**
+   * Check whether a wallet operation (topup/refund) may run for a provider.
+   * Returns the reason when blocked.
+   */
+  _canRunProviderWalletOperation(baseUrl, type) {
+    const existing = this.providerWalletOps.get(baseUrl);
+    if (!existing) {
+      return { allowed: true };
+    }
+    if (existing.type === type) {
+      return { allowed: true };
+    }
+    if (!existing.endTime) {
+      return {
+        allowed: false,
+        reason: `Provider wallet operation locked; ${existing.type} in progress`
+      };
+    }
+    const elapsed = Date.now() - existing.endTime;
+    if (elapsed < _BalanceManager.PROVIDER_WALLET_COOLDOWN_MS) {
+      return {
+        allowed: false,
+        reason: `Provider wallet operation locked; recent ${existing.type} completed ${Math.round(elapsed / 1e3)}s ago`
+      };
+    }
+    this.providerWalletOps.delete(baseUrl);
+    return { allowed: true };
+  }
+  _beginProviderWalletOperation(baseUrl, type) {
+    this.providerWalletOps.set(baseUrl, { type, startTime: Date.now() });
+  }
+  _endProviderWalletOperation(baseUrl, type) {
+    const existing = this.providerWalletOps.get(baseUrl);
+    if (existing && existing.type === type) {
+      existing.endTime = Date.now();
+    }
+  }
+  async getBalanceState() {
+    const mintBalances = await this.walletAdapter.getBalances();
+    const units = this.walletAdapter.getMintUnits();
+    let totalMintBalance = 0;
+    const normalizedMintBalances = {};
+    for (const url in mintBalances) {
+      const balance = mintBalances[url];
+      const unit = units[url];
+      const balanceInSats = getBalanceInSats(balance, unit);
+      normalizedMintBalances[url] = balanceInSats;
+      totalMintBalance += balanceInSats;
+    }
+    const providerBalances = {};
+    let totalProviderBalance = 0;
+    const apiKeys = this.storageAdapter.getAllApiKeys();
+    for (const apiKey of apiKeys) {
+      if (!providerBalances[apiKey.baseUrl]) {
+        providerBalances[apiKey.baseUrl] = 0;
+      }
+      providerBalances[apiKey.baseUrl] += apiKey.balance;
+      totalProviderBalance += apiKey.balance;
+    }
+    return {
+      totalBalance: totalMintBalance + totalProviderBalance,
+      providerBalances,
+      mintBalances: normalizedMintBalances
+    };
+  }
+  /**
+   * Refund API key balance - convert remaining API key balance to cashu token
+   * @param options - Refund options including forceRefund flag
+   * @returns Refund result
+   */
+  async refundApiKey(options) {
+    const { mintUrl, baseUrl, apiKey, forceRefund } = options;
+    const guard = this._canRunProviderWalletOperation(baseUrl, "refund");
+    if (!guard.allowed) {
+      this.logger.log(`Skipping refund for ${baseUrl} - ${guard.reason}`);
+      return { success: false, message: guard.reason };
+    }
+    this._beginProviderWalletOperation(baseUrl, "refund");
+    try {
+      return await this._refundApiKeyImpl({ mintUrl, baseUrl, apiKey, forceRefund });
+    } finally {
+      this._endProviderWalletOperation(baseUrl, "refund");
+    }
+  }
+  async _refundApiKeyImpl(options) {
+    const { mintUrl, baseUrl, apiKey, forceRefund } = options;
+    if (!apiKey) {
+      this.logger.warn(`refundApiKey: aborting for ${baseUrl} - no API key`);
+      return { success: false, message: "No API key to refund" };
+    }
+    if (!forceRefund) {
+      const apiKeyEntry = this.storageAdapter.getApiKey(baseUrl);
+      if (apiKeyEntry?.lastUsed) {
+        const fiveMinutesAgo = Date.now() - 5 * 60 * 1e3;
+        if (apiKeyEntry.lastUsed > fiveMinutesAgo) {
+          this.logger.log(
+            `refundApiKey: skipping ${baseUrl} - used ${Math.round((Date.now() - apiKeyEntry.lastUsed) / 1e3)}s ago`
+          );
+          return {
+            success: false,
+            message: "API key was used recently, skipping refund"
+          };
+        }
+      }
+    }
+    let fetchResult;
+    try {
+      fetchResult = await this.fetchRefundToken(baseUrl, apiKey);
+      if (fetchResult.error === "No balance to refund") {
+        this.logger.log(`refundApiKey: provider says no balance for ${baseUrl}; removing API key`);
+        this.storageAdapter.removeApiKey(baseUrl);
+        return { success: true, message: "No balance to refund, key cleaned up" };
+      }
+      if (!fetchResult.success) {
+        this.logger.warn(
+          `refundApiKey: fetch failed for ${baseUrl}: ${fetchResult.error || "API key refund failed"}`
+        );
+        return {
+          success: false,
+          message: fetchResult.error || "API key refund failed",
+          requestId: fetchResult.requestId
+        };
+      }
+      if (!fetchResult.token) {
+        this.logger.warn(`refundApiKey: no token received for ${baseUrl}`);
+        return {
+          success: false,
+          message: "No token received from API key refund",
+          requestId: fetchResult.requestId
+        };
+      }
+      const receiveResult = await this.cashuSpender.receiveToken(
+        fetchResult.token
+      );
+      const totalAmountMsat = receiveResult.unit === "msat" ? receiveResult.amount : receiveResult.amount * 1e3;
+      if (receiveResult.success) {
+        this.storageAdapter.removeApiKey(baseUrl);
+      } else {
+        this.logger.warn(
+          `refundApiKey: receive failed for ${baseUrl}; keeping API key. message=${receiveResult.message ?? "none"}`
+        );
+      }
+      return {
+        success: receiveResult.success,
+        refundedAmount: totalAmountMsat,
+        message: receiveResult.message,
+        requestId: fetchResult.requestId
+      };
+    } catch (error) {
+      this.logger.error("API key refund error", error);
+      return this._handleRefundError(error, mintUrl, fetchResult?.requestId);
+    }
+  }
+  /**
+   * Fetch refund token from provider API using API key (or xcashu token) authentication
+   */
+  async fetchRefundToken(baseUrl, apiKeyOrToken, xCashu = false) {
+    if (!baseUrl) {
+      return {
+        success: false,
+        error: "No base URL configured"
+      };
+    }
+    const normalizedBaseUrl = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+    const url = `${normalizedBaseUrl}v1/wallet/refund`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+      controller.abort();
+    }, 6e4);
+    try {
+      const headers = {
+        "Content-Type": "application/json"
+      };
+      if (xCashu) {
+        headers["X-Cashu"] = apiKeyOrToken;
+      } else {
+        headers["Authorization"] = `Bearer ${apiKeyOrToken}`;
+      }
+      const response = await fetch(url, {
+        method: "POST",
+        headers,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      const requestId = response.headers.get("x-routstr-request-id") || void 0;
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        this.logger.warn(
+          `fetchRefundToken: non-ok response for ${url} status=${response.status} statusText=${response.statusText}`,
+          errorData
+        );
+        return {
+          success: false,
+          requestId,
+          error: `API key refund failed: ${errorData?.detail || response.statusText}`
+        };
+      }
+      const data = await response.json();
+      return {
+        success: true,
+        token: data.token,
+        requestId
+      };
+    } catch (error) {
+      clearTimeout(timeoutId);
+      this.logger.error("fetchRefundToken fetch error", error);
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          return {
+            success: false,
+            error: "Request timed out after 1 minute"
+          };
+        }
+        return {
+          success: false,
+          error: error.message
+        };
+      }
+      return {
+        success: false,
+        error: "Unknown error occurred during API key refund request"
+      };
+    }
+  }
+  /**
+   * Top up API key balance with a cashu token
+   */
+  async topUp(options) {
+    const { mintUrl, baseUrl, amount, token: providedToken } = options;
+    const guard = this._canRunProviderWalletOperation(baseUrl, "topup");
+    if (!guard.allowed) {
+      this.logger.log(`Skipping topup for ${baseUrl} - ${guard.reason}`);
+      return { success: false, message: guard.reason };
+    }
+    this._beginProviderWalletOperation(baseUrl, "topup");
+    try {
+      return await this._topUpImpl({ mintUrl, baseUrl, amount, token: providedToken });
+    } finally {
+      this._endProviderWalletOperation(baseUrl, "topup");
+    }
+  }
+  async _topUpImpl(options) {
+    const { mintUrl, baseUrl, amount, token: providedToken } = options;
+    if (!amount || amount <= 0) {
+      return { success: false, message: "Invalid top up amount" };
+    }
+    const apiKeyEntry = providedToken ? null : this.storageAdapter.getApiKey(baseUrl);
+    const apiKey = providedToken || apiKeyEntry?.key;
+    if (!apiKey) {
+      return { success: false, message: "No API key available for top up" };
+    }
+    let cashuToken = null;
+    let requestId;
+    try {
+      const tokenResult = await this.createProviderToken({
+        mintUrl,
+        baseUrl,
+        amount
+      });
+      if (!tokenResult.success || !tokenResult.token) {
+        return {
+          success: false,
+          message: tokenResult.error || "Unable to create top up token"
+        };
+      }
+      cashuToken = tokenResult.token;
+      const topUpResult = await this._postTopUp(baseUrl, apiKey, cashuToken);
+      requestId = topUpResult.requestId;
+      this.logger.log("topUpResult:", topUpResult);
+      if (!topUpResult.success) {
+        await this._recoverFailedTopUp(cashuToken);
+        return {
+          success: false,
+          message: topUpResult.error || "Top up failed",
+          requestId,
+          recoveredToken: true
+        };
+      }
+      return {
+        success: true,
+        toppedUpAmount: amount,
+        requestId
+      };
+    } catch (error) {
+      this.logger.log(`topup error for ${baseUrl}: ${error}`);
+      if (cashuToken) {
+        await this._recoverFailedTopUp(cashuToken);
+      }
+      return this._handleTopUpError(error, mintUrl, requestId);
+    }
+  }
+  async createProviderToken(options) {
+    const {
+      mintUrl,
+      baseUrl,
+      amount,
+      retryCount = 0,
+      excludeMints = [],
+      p2pkPubkey
+    } = options;
+    const adjustedAmount = Math.ceil(amount);
+    this.logger.log(`createProviderToken: baseUrl=${baseUrl} mintUrl=${mintUrl} amount=${amount} adjustedAmount=${adjustedAmount} retryCount=${retryCount}`);
+    if (!adjustedAmount || isNaN(adjustedAmount)) {
+      this.logger.error(`createProviderToken: invalid amount=${amount}`);
+      return { success: false, error: "Invalid top up amount" };
+    }
+    const balanceState = await this.getBalanceState();
+    const balances = await this.walletAdapter.getBalances();
+    const units = this.walletAdapter.getMintUnits();
+    const totalMintBalance = Object.values(balanceState.mintBalances).reduce(
+      (sum, value) => sum + value,
+      0
+    );
+    const targetProviderBalance = balanceState.providerBalances[baseUrl] || 0;
+    const refundableProviderBalance = Object.entries(
+      balanceState.providerBalances
+    ).filter(([providerBaseUrl]) => providerBaseUrl !== baseUrl).reduce((sum, [, value]) => sum + value, 0);
+    if (totalMintBalance + targetProviderBalance < adjustedAmount && totalMintBalance + targetProviderBalance + refundableProviderBalance >= adjustedAmount && retryCount < 2) {
+      await this._refundOtherProvidersForTopUp(baseUrl, mintUrl, retryCount);
+      return this.createProviderToken({
+        ...options,
+        retryCount: retryCount + 1
+      });
+    }
+    if (totalMintBalance + targetProviderBalance < adjustedAmount) {
+      const error = new InsufficientBalanceError(
+        adjustedAmount,
+        totalMintBalance + targetProviderBalance,
+        totalMintBalance,
+        Object.entries(balanceState.mintBalances).reduce(
+          (max, [url, balance]) => balance > max.balance ? { url, balance } : max,
+          { url: "", balance: 0 }
+        ).url
+      );
+      this.logger.error(`createProviderToken: insufficient balance required=${adjustedAmount} available=${totalMintBalance + targetProviderBalance} totalMint=${totalMintBalance} targetProvider=${targetProviderBalance}`);
+      return { success: false, error: error.message };
+    }
+    const providerMints = baseUrl && this.providerRegistry ? this.providerRegistry.getProviderMints(baseUrl) : [];
+    let requiredAmount = adjustedAmount;
+    const supportedMintsOnly = providerMints.length > 0;
+    let candidates = this._selectCandidateMints({
+      balances,
+      units,
+      amount: requiredAmount,
+      preferredMintUrl: mintUrl,
+      excludeMints,
+      allowedMints: supportedMintsOnly ? providerMints : void 0
+    });
+    if (candidates.length === 0 && supportedMintsOnly) {
+      requiredAmount += 2;
+      candidates = this._selectCandidateMints({
+        balances,
+        units,
+        amount: requiredAmount,
+        preferredMintUrl: mintUrl,
+        excludeMints
+      });
+    }
+    if (candidates.length === 0) {
+      let maxBalance = 0;
+      let maxMintUrl = "";
+      for (const mintUrl2 in balances) {
+        const balance = balances[mintUrl2];
+        const unit = units[mintUrl2];
+        const balanceInSats = getBalanceInSats(balance, unit);
+        if (balanceInSats > maxBalance) {
+          maxBalance = balanceInSats;
+          maxMintUrl = mintUrl2;
+        }
+      }
+      this.logger.error(`createProviderToken: no candidate mints required=${requiredAmount} totalMint=${totalMintBalance} maxBalance=${maxBalance} maxMint=${maxMintUrl}`);
+      const error = new InsufficientBalanceError(
+        adjustedAmount,
+        totalMintBalance,
+        maxBalance,
+        maxMintUrl
+      );
+      return { success: false, error: error.message };
+    }
+    let lastError;
+    for (const candidateMint of candidates) {
+      try {
+        this.logger.log(`createProviderToken: attempting mint=${candidateMint} amount=${requiredAmount}`);
+        const token = await this.walletAdapter.sendToken(
+          candidateMint,
+          requiredAmount,
+          p2pkPubkey
+        );
+        this.logger.log(`createProviderToken: success from mint=${candidateMint}`);
+        return {
+          success: true,
+          token,
+          selectedMintUrl: candidateMint,
+          amountSpent: requiredAmount
+        };
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        this.logger.error(`createProviderToken: mint=${candidateMint} failed: ${errorMsg}`);
+        if (error instanceof Error) {
+          lastError = errorMsg;
+          if (isNetworkErrorMessage(error.message)) {
+            this.logger.warn(`createProviderToken: network error from ${candidateMint}, trying next mint...`);
+            continue;
+          }
+        }
+        return {
+          success: false,
+          error: lastError || "Failed to create top up token"
+        };
+      }
+    }
+    this.logger.error(`createProviderToken: all candidate mints exhausted lastError=${lastError}`);
+    return {
+      success: false,
+      error: lastError || "All candidate mints failed while creating top up token"
+    };
+  }
+  _selectCandidateMints(options) {
+    const {
+      balances,
+      units,
+      amount,
+      preferredMintUrl,
+      excludeMints,
+      allowedMints
+    } = options;
+    const candidates = [];
+    const { selectedMintUrl: firstMint } = selectMintWithBalance(
+      balances,
+      units,
+      amount,
+      excludeMints
+    );
+    if (firstMint && (!allowedMints || allowedMints.length === 0 || allowedMints.includes(firstMint))) {
+      candidates.push(firstMint);
+    }
+    const canUseMint = (mint) => {
+      if (excludeMints.includes(mint)) return false;
+      if (allowedMints && allowedMints.length > 0 && !allowedMints.includes(mint)) {
+        return false;
+      }
+      const rawBalance = balances[mint] || 0;
+      const unit = units[mint];
+      const balanceInSats = getBalanceInSats(rawBalance, unit);
+      return balanceInSats >= amount;
+    };
+    if (preferredMintUrl && canUseMint(preferredMintUrl) && !candidates.includes(preferredMintUrl)) {
+      candidates.push(preferredMintUrl);
+    }
+    for (const mint in balances) {
+      if (mint === preferredMintUrl || candidates.includes(mint)) continue;
+      if (canUseMint(mint)) {
+        candidates.push(mint);
+      }
+    }
+    return candidates;
+  }
+  async _refundOtherProvidersForTopUp(baseUrl, mintUrl, retryCount) {
+    const apiKeyDistribution = this.storageAdapter.getApiKeyDistribution();
+    const forceRefund = retryCount >= 2;
+    const apiKeysToRefund = apiKeyDistribution.filter(
+      (apiKey) => apiKey.baseUrl !== baseUrl && apiKey.amount > 0
+    );
+    const apiKeyRefundResults = await Promise.allSettled(
+      apiKeysToRefund.map(async (apiKeyEntry) => {
+        const fullApiKeyEntry = this.storageAdapter.getApiKey(
+          apiKeyEntry.baseUrl
+        );
+        if (!fullApiKeyEntry) {
+          return { baseUrl: apiKeyEntry.baseUrl, success: false };
+        }
+        const result = await this.refundApiKey({
+          mintUrl,
+          baseUrl: apiKeyEntry.baseUrl,
+          apiKey: fullApiKeyEntry.key,
+          forceRefund
+        });
+        return { baseUrl: apiKeyEntry.baseUrl, success: result.success };
+      })
+    );
+    for (const result of apiKeyRefundResults) {
+      if (result.status === "fulfilled" && result.value.success) {
+        this.storageAdapter.updateApiKeyBalance(result.value.baseUrl, 0);
+      }
+    }
+  }
+  /**
+   * Post topup request to provider API
+   */
+  async _postTopUp(baseUrl, storedToken, cashuToken) {
+    if (!baseUrl) {
+      return {
+        success: false,
+        error: "No base URL configured"
+      };
+    }
+    const normalizedBaseUrl = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+    const url = `${normalizedBaseUrl}v1/wallet/topup?cashu_token=${encodeURIComponent(
+      cashuToken
+    )}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+      controller.abort();
+    }, 6e4);
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${storedToken}`,
+          "Content-Type": "application/json"
+        },
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      const requestId = response.headers.get("x-routstr-request-id") || void 0;
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        return {
+          success: false,
+          requestId,
+          error: errorData?.detail || `Top up failed with status ${response.status}`
+        };
+      }
+      return { success: true, requestId };
+    } catch (error) {
+      clearTimeout(timeoutId);
+      this.logger.error("_postTopUp fetch error", error);
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          return {
+            success: false,
+            error: "Request timed out after 1 minute"
+          };
+        }
+        return {
+          success: false,
+          error: error.message
+        };
+      }
+      return {
+        success: false,
+        error: "Unknown error occurred during top up request"
+      };
+    }
+  }
+  /**
+   * Attempt to receive token back after failed top up
+   */
+  async _recoverFailedTopUp(cashuToken) {
+    try {
+      await this.cashuSpender.receiveToken(cashuToken);
+    } catch (error) {
+      this.logger.error("_recoverFailedTopUp: failed to recover token", error);
+    }
+  }
+  /**
+   * Handle refund errors with specific error types
+   */
+  _handleRefundError(error, mintUrl, requestId) {
+    if (error instanceof Error) {
+      if (isNetworkErrorMessage(error.message)) {
+        return {
+          success: false,
+          message: `Failed to connect to the mint: ${mintUrl}`,
+          requestId
+        };
+      }
+      if (error.message.includes("Wallet not found")) {
+        return {
+          success: false,
+          message: `Wallet couldn't be loaded. Please save this refunded cashu token manually.`,
+          requestId
+        };
+      }
+      return {
+        success: false,
+        message: error.message,
+        requestId
+      };
+    }
+    return {
+      success: false,
+      message: "Refund failed",
+      requestId
+    };
+  }
+  /**
+   * Get token balance from provider
+   */
+  async getTokenBalance(token, baseUrl) {
+    try {
+      const response = await fetch(`${baseUrl}v1/wallet/info`, {
+        headers: {
+          Authorization: `Bearer ${token}`
+        }
+      });
+      if (response.ok) {
+        const data = await response.json();
+        return {
+          amount: data.balance,
+          reserved: data.reserved ?? 0,
+          unit: "msat",
+          apiKey: data.api_key
+        };
+      } else {
+        this.logger.warn(`getTokenBalance: status=${response.status}`);
+        const data = await response.json();
+        this.logger.warn("getTokenBalance: FAILED", data);
+        const isInvalidApiKey = response.status === 401 && data?.detail?.error?.code === "invalid_api_key" && data?.detail?.error?.message?.includes("proofs already spent");
+        return {
+          amount: -1,
+          reserved: data.reserved ?? 0,
+          unit: "msat",
+          apiKey: data.api_key,
+          isInvalidApiKey
+        };
+      }
+    } catch (error) {
+      this.logger.error("getTokenBalance error", error);
+    }
+    return { amount: -1, reserved: 0, unit: "sat", apiKey: "" };
+  }
+  /**
+   * Handle topup errors with specific error types
+   */
+  _handleTopUpError(error, mintUrl, requestId) {
+    if (error instanceof Error) {
+      if (isNetworkErrorMessage(error.message)) {
+        return {
+          success: false,
+          message: `Failed to connect to the mint: ${mintUrl}`,
+          requestId
+        };
+      }
+      if (error.message.includes("Wallet not found")) {
+        return {
+          success: false,
+          message: "Wallet couldn't be loaded. The cashu token was recovered locally.",
+          requestId
+        };
+      }
+      return {
+        success: false,
+        message: error.message,
+        requestId
+      };
+    }
+    return {
+      success: false,
+      message: "Top up failed",
+      requestId
+    };
+  }
+};
+
+export { BalanceManager, CashuSpender };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map