@routstr/sdk 0.1.0 → 0.1.2

package/dist/wallet/index.d.mts

@@ -0,0 +1,218 @@
+import { W as WalletAdapter, S as StorageAdapter, P as ProviderRegistry } from '../interfaces-B85Wx7ni.mjs';
+export { A as ApiKeyEntry, C as ChildKeyEntry, R as RoutstrClientOptions, a as StreamingCallbacks } from '../interfaces-B85Wx7ni.mjs';
+import { R as RefundResult, m as TopUpResult, S as SpendResult } from '../types-BlHjmWRK.mjs';
+export { P as ProviderInfo } from '../types-BlHjmWRK.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 tokens
+ */
+interface RefundOptions {
+    /** The mint URL (for NIP-60 wallet operations) */
+    mintUrl: string;
+    /** The provider base URL */
+    baseUrl: string;
+    /** Optional specific token to refund (if not provided, uses stored token) */
+    token?: string;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * BalanceManager handles token refunds and topups from providers
+ */
+declare class BalanceManager {
+    private walletAdapter;
+    private storageAdapter;
+    private providerRegistry?;
+    private cashuSpender;
+    constructor(walletAdapter: WalletAdapter, storageAdapter: StorageAdapter, providerRegistry?: ProviderRegistry | undefined, cashuSpender?: CashuSpender);
+    /**
+     * Unified refund - handles both NIP-60 and legacy wallet refunds
+     */
+    refund(options: RefundOptions): Promise<RefundResult>;
+    /**
+     * Refund API key balance - convert remaining API key balance to cashu token
+     */
+    refundApiKey(options: RefundApiKeyOptions): Promise<RefundResult>;
+    /**
+     * Fetch refund token from provider API using API key authentication
+     */
+    private _fetchRefundTokenWithApiKey;
+    /**
+     * Top up API key balance with a cashu token
+     */
+    topUp(options: TopUpOptions): Promise<TopUpResult>;
+    createProviderToken(options: CreateProviderTokenOptions): Promise<ProviderTokenResult>;
+    private _selectCandidateMints;
+    private _refundOtherProvidersForTopUp;
+    /**
+     * Fetch refund token from provider API
+     */
+    private _fetchRefundToken;
+    /**
+     * 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;
+    }>;
+    /**
+     * 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;
+    constructor(walletAdapter: WalletAdapter, storageAdapter: StorageAdapter, _providerRegistry?: unknown | undefined, balanceManager?: BalanceManager | undefined);
+    receiveToken(token: string): Promise<{
+        success: boolean;
+        amount: number;
+        unit: "sat" | "msat";
+        message?: string;
+    }>;
+    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 token
+     */
+    private _tryReuseToken;
+    /**
+     * Refund specific providers without retrying spend
+     */
+    refundProviders(baseUrls: string[], mintUrl: string, refundApiKeys?: boolean): Promise<{
+        baseUrl: string;
+        success: boolean;
+    }[]>;
+    /**
+     * Create an insufficient balance error result
+     */
+    private _createInsufficientBalanceError;
+    private _getProviderTokenBalance;
+}
+
+export { BalanceManager, CashuSpender, type CreateProviderTokenOptions, ProviderRegistry, type ProviderTokenResult, type RefundApiKeyOptions, type RefundOptions, type SpendOptions, StorageAdapter, type TopUpOptions, WalletAdapter };

package/dist/wallet/index.d.ts

@@ -0,0 +1,218 @@
+import { W as WalletAdapter, S as StorageAdapter, P as ProviderRegistry } from '../interfaces-BVNyAmKu.js';
+export { A as ApiKeyEntry, C as ChildKeyEntry, R as RoutstrClientOptions, a as StreamingCallbacks } from '../interfaces-BVNyAmKu.js';
+import { R as RefundResult, m as TopUpResult, S as SpendResult } from '../types-BlHjmWRK.js';
+export { P as ProviderInfo } from '../types-BlHjmWRK.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 tokens
+ */
+interface RefundOptions {
+    /** The mint URL (for NIP-60 wallet operations) */
+    mintUrl: string;
+    /** The provider base URL */
+    baseUrl: string;
+    /** Optional specific token to refund (if not provided, uses stored token) */
+    token?: string;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * BalanceManager handles token refunds and topups from providers
+ */
+declare class BalanceManager {
+    private walletAdapter;
+    private storageAdapter;
+    private providerRegistry?;
+    private cashuSpender;
+    constructor(walletAdapter: WalletAdapter, storageAdapter: StorageAdapter, providerRegistry?: ProviderRegistry | undefined, cashuSpender?: CashuSpender);
+    /**
+     * Unified refund - handles both NIP-60 and legacy wallet refunds
+     */
+    refund(options: RefundOptions): Promise<RefundResult>;
+    /**
+     * Refund API key balance - convert remaining API key balance to cashu token
+     */
+    refundApiKey(options: RefundApiKeyOptions): Promise<RefundResult>;
+    /**
+     * Fetch refund token from provider API using API key authentication
+     */
+    private _fetchRefundTokenWithApiKey;
+    /**
+     * Top up API key balance with a cashu token
+     */
+    topUp(options: TopUpOptions): Promise<TopUpResult>;
+    createProviderToken(options: CreateProviderTokenOptions): Promise<ProviderTokenResult>;
+    private _selectCandidateMints;
+    private _refundOtherProvidersForTopUp;
+    /**
+     * Fetch refund token from provider API
+     */
+    private _fetchRefundToken;
+    /**
+     * 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;
+    }>;
+    /**
+     * 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;
+    constructor(walletAdapter: WalletAdapter, storageAdapter: StorageAdapter, _providerRegistry?: unknown | undefined, balanceManager?: BalanceManager | undefined);
+    receiveToken(token: string): Promise<{
+        success: boolean;
+        amount: number;
+        unit: "sat" | "msat";
+        message?: string;
+    }>;
+    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 token
+     */
+    private _tryReuseToken;
+    /**
+     * Refund specific providers without retrying spend
+     */
+    refundProviders(baseUrls: string[], mintUrl: string, refundApiKeys?: boolean): Promise<{
+        baseUrl: string;
+        success: boolean;
+    }[]>;
+    /**
+     * Create an insufficient balance error result
+     */
+    private _createInsufficientBalanceError;
+    private _getProviderTokenBalance;
+}
+
+export { BalanceManager, CashuSpender, type CreateProviderTokenOptions, ProviderRegistry, type ProviderTokenResult, type RefundApiKeyOptions, type RefundOptions, type SpendOptions, StorageAdapter, type TopUpOptions, WalletAdapter };