@routstr/sdk 0.3.7 → 0.3.9

package/dist/wallet/index.d.mts

@@ -0,0 +1,249 @@
+import { W as WalletAdapter, S as StorageAdapter, P as ProviderRegistry } from '../interfaces-Csn8Uq04.mjs';
+export { A as ApiKeyEntry, C as ChildKeyEntry, R as RoutstrClientOptions, a as StreamingCallbacks, X as XCashuTokenEntry } from '../interfaces-Csn8Uq04.mjs';
+import { S as SdkLogger, R as RefundResult, T as TopUpResult, l as SpendResult } from '../types-_21yYFZG.mjs';
+export { k as ProviderInfo } from '../types-_21yYFZG.mjs';
+
+/**
+ * BalanceManager - Handles refunding and topping up tokens from providers
+ *
+ * Handles:
+ * - Fetching refund tokens from provider API
+ * - Receiving/storing refunded tokens
+ * - Topping up API key balances with cashu tokens
+ * - Error handling for various refund/topup failure modes
+ *
+ * Extracted from utils/cashuUtils.ts
+ */
+
+/**
+ * Options for refunding API key balance
+ */
+interface RefundApiKeyOptions {
+    /** The mint URL (for NIP-60 wallet operations) */
+    mintUrl: string;
+    /** The provider base URL */
+    baseUrl: string;
+    /** The API key to use for authentication */
+    apiKey: string;
+    /** If true, forces refund even if the API key was used recently */
+    forceRefund?: boolean;
+}
+/**
+ * Options for topping up API key balance
+ */
+interface TopUpOptions {
+    /** The mint URL to spend from */
+    mintUrl: string;
+    /** The provider base URL */
+    baseUrl: string;
+    /** Amount to top up in sats */
+    amount: number;
+    /** Optional specific API key to top up (if not provided, uses stored token) */
+    token?: string;
+}
+interface CreateProviderTokenOptions {
+    mintUrl: string;
+    baseUrl: string;
+    amount: number;
+    p2pkPubkey?: string;
+    excludeMints?: string[];
+    retryCount?: number;
+}
+interface ProviderTokenResult {
+    success: boolean;
+    token?: string;
+    error?: string;
+    selectedMintUrl?: string;
+    amountSpent?: number;
+}
+interface BalanceState {
+    totalBalance: number;
+    providerBalances: Record<string, number>;
+    mintBalances: Record<string, number>;
+}
+/**
+ * BalanceManager handles token refunds and topups from providers
+ */
+declare class BalanceManager {
+    private walletAdapter;
+    private storageAdapter;
+    private providerRegistry?;
+    private cashuSpender;
+    /** In-memory guard for per-provider wallet mutations (topup / refund) */
+    private providerWalletOps;
+    /** Cooldown (ms) between opposite operations on the same provider */
+    private static readonly PROVIDER_WALLET_COOLDOWN_MS;
+    private readonly logger;
+    constructor(walletAdapter: WalletAdapter, storageAdapter: StorageAdapter, providerRegistry?: ProviderRegistry | undefined, cashuSpender?: CashuSpender, logger?: SdkLogger);
+    /**
+     * Check whether a wallet operation (topup/refund) may run for a provider.
+     * Returns the reason when blocked.
+     */
+    private _canRunProviderWalletOperation;
+    private _beginProviderWalletOperation;
+    private _endProviderWalletOperation;
+    getBalanceState(): Promise<BalanceState>;
+    /**
+     * Refund API key balance - convert remaining API key balance to cashu token
+     * @param options - Refund options including forceRefund flag
+     * @returns Refund result
+     */
+    refundApiKey(options: RefundApiKeyOptions): Promise<RefundResult>;
+    private _refundApiKeyImpl;
+    /**
+     * Fetch refund token from provider API using API key (or xcashu token) authentication
+     */
+    fetchRefundToken(baseUrl: string, apiKeyOrToken: string, xCashu?: boolean): Promise<{
+        success: boolean;
+        token?: string;
+        requestId?: string;
+        error?: string;
+    }>;
+    /**
+     * Top up API key balance with a cashu token
+     */
+    topUp(options: TopUpOptions): Promise<TopUpResult>;
+    private _topUpImpl;
+    createProviderToken(options: CreateProviderTokenOptions): Promise<ProviderTokenResult>;
+    private _selectCandidateMints;
+    private _refundOtherProvidersForTopUp;
+    /**
+     * Post topup request to provider API
+     */
+    private _postTopUp;
+    /**
+     * Attempt to receive token back after failed top up
+     */
+    private _recoverFailedTopUp;
+    /**
+     * Handle refund errors with specific error types
+     */
+    private _handleRefundError;
+    /**
+     * Get token balance from provider
+     */
+    getTokenBalance(token: string, baseUrl: string): Promise<{
+        amount: number;
+        reserved: number;
+        unit: "sat" | "msat";
+        apiKey: string;
+        isInvalidApiKey?: boolean;
+        /** True when the balance could not be determined (network error, non-OK
+         *  response, etc.).  Callers MUST NOT use `amount` in arithmetic when
+         *  this flag is set — it is 0, not a real balance. */
+        balanceUnknown?: boolean;
+    }>;
+    /**
+     * Handle topup errors with specific error types
+     */
+    private _handleTopUpError;
+}
+
+/**
+ * CashuSpender - Core spending logic for Cashu tokens
+ *
+ * Handles:
+ * - Mint selection with sufficient balance
+ * - Provider mint compatibility checks
+ * - Retry logic with alternate mints
+ * - Critical section management (busy state)
+ *
+ * Extracted from hooks/useCashuWithXYZ.ts
+ */
+
+/**
+ * Options for spending cashu tokens
+ */
+interface SpendOptions {
+    /** The mint URL to send from (can be overridden if insufficient balance) */
+    mintUrl: string;
+    /** The amount to spend in sats */
+    amount: number;
+    /** The provider base URL (for token storage and provider mint checks) */
+    baseUrl: string;
+    /** Whether to reuse an existing token if available */
+    reuseToken?: boolean;
+    /** Optional P2PK public key */
+    p2pkPubkey?: string;
+    /** Array of mint URLs to exclude (for retry logic) */
+    excludeMints?: string[];
+    /** Current retry count (for internal recursion) */
+    retryCount?: number;
+    /** Specific provider baseUrls to refund (if not provided, refunds all except current) */
+    refundBaseUrls?: string[];
+}
+type DebugLevel = "DEBUG" | "WARN" | "ERROR";
+/**
+ * CashuSpender manages the spending of Cashu tokens
+ */
+declare class CashuSpender {
+    private walletAdapter;
+    private storageAdapter;
+    private _providerRegistry?;
+    private balanceManager?;
+    private _isBusy;
+    private debugLevel;
+    private readonly logger;
+    constructor(walletAdapter: WalletAdapter, storageAdapter: StorageAdapter, _providerRegistry?: unknown | undefined, balanceManager?: BalanceManager | undefined, logger?: SdkLogger);
+    receiveToken(token: string): Promise<{
+        success: boolean;
+        amount: number;
+        unit: "sat" | "msat";
+        message?: string;
+    }>;
+    private _decodeTokenAmount;
+    private _getBalanceState;
+    private _logTransaction;
+    /**
+     * Check if the spender is currently in a critical operation
+     */
+    get isBusy(): boolean;
+    getDebugLevel(): DebugLevel;
+    setDebugLevel(level: DebugLevel): void;
+    private _log;
+    /**
+     * Spend Cashu tokens with automatic mint selection and retry logic
+     * Throws errors on failure instead of returning failed SpendResult
+     */
+    spend(options: SpendOptions): Promise<SpendResult>;
+    /**
+     * Check if error message indicates a network error
+     */
+    private _isNetworkError;
+    /**
+     * Internal spending logic
+     */
+    private _spendInternal;
+    /**
+     * Try to reuse an existing API key
+     */
+    private _tryReuseToken;
+    /**
+     * 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
+     */
+    refundXcashuTokens(mintUrl: string, excludeBaseUrls?: string[]): Promise<{
+        baseUrl: string;
+        token: string;
+        success: boolean;
+        error?: string;
+    }[]>;
+    /**
+     * Refund specific providers without retrying spend
+     */
+    refundProviders(mintUrl: string, forceRefund?: boolean): Promise<{
+        baseUrl: string;
+        success: boolean;
+    }[]>;
+    /**
+     * Create an insufficient balance error result
+     */
+    private _createInsufficientBalanceError;
+    private _getProviderTokenBalance;
+}
+
+export { BalanceManager, type BalanceState, CashuSpender, type CreateProviderTokenOptions, ProviderRegistry, type ProviderTokenResult, type RefundApiKeyOptions, type SpendOptions, StorageAdapter, type TopUpOptions, WalletAdapter };

package/dist/wallet/index.d.ts

@@ -0,0 +1,249 @@
+import { W as WalletAdapter, S as StorageAdapter, P as ProviderRegistry } from '../interfaces-C-DYd9Jy.js';
+export { A as ApiKeyEntry, C as ChildKeyEntry, R as RoutstrClientOptions, a as StreamingCallbacks, X as XCashuTokenEntry } from '../interfaces-C-DYd9Jy.js';
+import { S as SdkLogger, R as RefundResult, T as TopUpResult, l as SpendResult } from '../types-_21yYFZG.js';
+export { k as ProviderInfo } from '../types-_21yYFZG.js';
+
+/**
+ * BalanceManager - Handles refunding and topping up tokens from providers
+ *
+ * Handles:
+ * - Fetching refund tokens from provider API
+ * - Receiving/storing refunded tokens
+ * - Topping up API key balances with cashu tokens
+ * - Error handling for various refund/topup failure modes
+ *
+ * Extracted from utils/cashuUtils.ts
+ */
+
+/**
+ * Options for refunding API key balance
+ */
+interface RefundApiKeyOptions {
+    /** The mint URL (for NIP-60 wallet operations) */
+    mintUrl: string;
+    /** The provider base URL */
+    baseUrl: string;
+    /** The API key to use for authentication */
+    apiKey: string;
+    /** If true, forces refund even if the API key was used recently */
+    forceRefund?: boolean;
+}
+/**
+ * Options for topping up API key balance
+ */
+interface TopUpOptions {
+    /** The mint URL to spend from */
+    mintUrl: string;
+    /** The provider base URL */
+    baseUrl: string;
+    /** Amount to top up in sats */
+    amount: number;
+    /** Optional specific API key to top up (if not provided, uses stored token) */
+    token?: string;
+}
+interface CreateProviderTokenOptions {
+    mintUrl: string;
+    baseUrl: string;
+    amount: number;
+    p2pkPubkey?: string;
+    excludeMints?: string[];
+    retryCount?: number;
+}
+interface ProviderTokenResult {
+    success: boolean;
+    token?: string;
+    error?: string;
+    selectedMintUrl?: string;
+    amountSpent?: number;
+}
+interface BalanceState {
+    totalBalance: number;
+    providerBalances: Record<string, number>;
+    mintBalances: Record<string, number>;
+}
+/**
+ * BalanceManager handles token refunds and topups from providers
+ */
+declare class BalanceManager {
+    private walletAdapter;
+    private storageAdapter;
+    private providerRegistry?;
+    private cashuSpender;
+    /** In-memory guard for per-provider wallet mutations (topup / refund) */
+    private providerWalletOps;
+    /** Cooldown (ms) between opposite operations on the same provider */
+    private static readonly PROVIDER_WALLET_COOLDOWN_MS;
+    private readonly logger;
+    constructor(walletAdapter: WalletAdapter, storageAdapter: StorageAdapter, providerRegistry?: ProviderRegistry | undefined, cashuSpender?: CashuSpender, logger?: SdkLogger);
+    /**
+     * Check whether a wallet operation (topup/refund) may run for a provider.
+     * Returns the reason when blocked.
+     */
+    private _canRunProviderWalletOperation;
+    private _beginProviderWalletOperation;
+    private _endProviderWalletOperation;
+    getBalanceState(): Promise<BalanceState>;
+    /**
+     * Refund API key balance - convert remaining API key balance to cashu token
+     * @param options - Refund options including forceRefund flag
+     * @returns Refund result
+     */
+    refundApiKey(options: RefundApiKeyOptions): Promise<RefundResult>;
+    private _refundApiKeyImpl;
+    /**
+     * Fetch refund token from provider API using API key (or xcashu token) authentication
+     */
+    fetchRefundToken(baseUrl: string, apiKeyOrToken: string, xCashu?: boolean): Promise<{
+        success: boolean;
+        token?: string;
+        requestId?: string;
+        error?: string;
+    }>;
+    /**
+     * Top up API key balance with a cashu token
+     */
+    topUp(options: TopUpOptions): Promise<TopUpResult>;
+    private _topUpImpl;
+    createProviderToken(options: CreateProviderTokenOptions): Promise<ProviderTokenResult>;
+    private _selectCandidateMints;
+    private _refundOtherProvidersForTopUp;
+    /**
+     * Post topup request to provider API
+     */
+    private _postTopUp;
+    /**
+     * Attempt to receive token back after failed top up
+     */
+    private _recoverFailedTopUp;
+    /**
+     * Handle refund errors with specific error types
+     */
+    private _handleRefundError;
+    /**
+     * Get token balance from provider
+     */
+    getTokenBalance(token: string, baseUrl: string): Promise<{
+        amount: number;
+        reserved: number;
+        unit: "sat" | "msat";
+        apiKey: string;
+        isInvalidApiKey?: boolean;
+        /** True when the balance could not be determined (network error, non-OK
+         *  response, etc.).  Callers MUST NOT use `amount` in arithmetic when
+         *  this flag is set — it is 0, not a real balance. */
+        balanceUnknown?: boolean;
+    }>;
+    /**
+     * Handle topup errors with specific error types
+     */
+    private _handleTopUpError;
+}
+
+/**
+ * CashuSpender - Core spending logic for Cashu tokens
+ *
+ * Handles:
+ * - Mint selection with sufficient balance
+ * - Provider mint compatibility checks
+ * - Retry logic with alternate mints
+ * - Critical section management (busy state)
+ *
+ * Extracted from hooks/useCashuWithXYZ.ts
+ */
+
+/**
+ * Options for spending cashu tokens
+ */
+interface SpendOptions {
+    /** The mint URL to send from (can be overridden if insufficient balance) */
+    mintUrl: string;
+    /** The amount to spend in sats */
+    amount: number;
+    /** The provider base URL (for token storage and provider mint checks) */
+    baseUrl: string;
+    /** Whether to reuse an existing token if available */
+    reuseToken?: boolean;
+    /** Optional P2PK public key */
+    p2pkPubkey?: string;
+    /** Array of mint URLs to exclude (for retry logic) */
+    excludeMints?: string[];
+    /** Current retry count (for internal recursion) */
+    retryCount?: number;
+    /** Specific provider baseUrls to refund (if not provided, refunds all except current) */
+    refundBaseUrls?: string[];
+}
+type DebugLevel = "DEBUG" | "WARN" | "ERROR";
+/**
+ * CashuSpender manages the spending of Cashu tokens
+ */
+declare class CashuSpender {
+    private walletAdapter;
+    private storageAdapter;
+    private _providerRegistry?;
+    private balanceManager?;
+    private _isBusy;
+    private debugLevel;
+    private readonly logger;
+    constructor(walletAdapter: WalletAdapter, storageAdapter: StorageAdapter, _providerRegistry?: unknown | undefined, balanceManager?: BalanceManager | undefined, logger?: SdkLogger);
+    receiveToken(token: string): Promise<{
+        success: boolean;
+        amount: number;
+        unit: "sat" | "msat";
+        message?: string;
+    }>;
+    private _decodeTokenAmount;
+    private _getBalanceState;
+    private _logTransaction;
+    /**
+     * Check if the spender is currently in a critical operation
+     */
+    get isBusy(): boolean;
+    getDebugLevel(): DebugLevel;
+    setDebugLevel(level: DebugLevel): void;
+    private _log;
+    /**
+     * Spend Cashu tokens with automatic mint selection and retry logic
+     * Throws errors on failure instead of returning failed SpendResult
+     */
+    spend(options: SpendOptions): Promise<SpendResult>;
+    /**
+     * Check if error message indicates a network error
+     */
+    private _isNetworkError;
+    /**
+     * Internal spending logic
+     */
+    private _spendInternal;
+    /**
+     * Try to reuse an existing API key
+     */
+    private _tryReuseToken;
+    /**
+     * 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
+     */
+    refundXcashuTokens(mintUrl: string, excludeBaseUrls?: string[]): Promise<{
+        baseUrl: string;
+        token: string;
+        success: boolean;
+        error?: string;
+    }[]>;
+    /**
+     * Refund specific providers without retrying spend
+     */
+    refundProviders(mintUrl: string, forceRefund?: boolean): Promise<{
+        baseUrl: string;
+        success: boolean;
+    }[]>;
+    /**
+     * Create an insufficient balance error result
+     */
+    private _createInsufficientBalanceError;
+    private _getProviderTokenBalance;
+}
+
+export { BalanceManager, type BalanceState, CashuSpender, type CreateProviderTokenOptions, ProviderRegistry, type ProviderTokenResult, type RefundApiKeyOptions, type SpendOptions, StorageAdapter, type TopUpOptions, WalletAdapter };