applesauce-wallet 6.2.0 → 7.1.0

package/README.md

@@ -1,3 +1,11 @@
 # Applesauce Wallet
 
 The `applesauce-wallet` package is a package of helpers, models, blueprints and other useful stuff for [NIP-60](https://github.com/nostr-protocol/nips/blob/master/60.md) wallets and [NIP-61](https://github.com/nostr-protocol/nips/blob/master/61.md) nutzaps
+
+Start with [NutWallet](https://applesauce.build/money/wallet/nut-wallet) for balance, token transfers, Lightning deposits and withdrawals over your application's signer, EventStore and RelayPool.
+
+- [Durable deposit recovery](https://applesauce.build/money/wallet/nut-wallet#resuming-interrupted-deposits): reopen account-scoped encrypted storage and explicitly resume pending operations after restart.
+- [Invoice-funded nutzaps](https://applesauce.build/money/wallet/nut-wallet#invoice-funded-nutzaps): use `MintRecovery` without a full wallet.
+- [KeyValueCouch and migration](https://applesauce.build/money/wallet/nut-wallet#migrating-existing-consumers): persist tokens in consumer-provided storage and migrate with copy-before-delete semantics.
+
+The [wallet guides](https://applesauce.build/money/wallet/package) also cover lower-level actions, casts and models.

package/dist/actions/mint-recomendation.js

@@ -6,7 +6,7 @@ import { MINT_RECOMMENDATION_KIND, getRecommendationMintPubkey, isValidMintRecom
 async function fetchMintPubkey(mintUrl) {
     // Fetch mint info directly from the /v1/info endpoint
     const infoUrl = new URL("/v1/info", mintUrl).toString();
-    const response = await fetch(infoUrl);
+    const response = await fetch(infoUrl, { signal: AbortSignal.timeout(10_000) });
     if (!response.ok) {
         throw new Error(`Failed to fetch mint info from ${mintUrl}: ${response.statusText}`);
     }

package/dist/casts/nutzap.d.ts

@@ -11,7 +11,7 @@ export declare class Nutzap extends EventCast<NutzapEvent> {
     get sender(): import("applesauce-core/casts").User;
     get comment(): string | undefined;
     /** The pointer to the event that was zapped */
-    get zapPointer(): import("nostr-tools/nip19").EventPointer | import("nostr-tools/nip19").AddressPointer | undefined;
+    get zapPointer(): import("nostr-tools/nip19").AddressPointer | import("nostr-tools/nip19").EventPointer | undefined;
     /** The event that was zapped */
     get zapped$(): import("applesauce-core").ChainableObservable<NostrEvent | undefined>;
 }

package/dist/helpers/animated-qr.js

@@ -1,6 +1,5 @@
 import { getEncodedToken } from "@cashu/cashu-ts";
-import { UR, URDecoder, UREncoder } from "@gandlaf21/bc-ur/dist/lib/es6/index.js";
-import { defer, filter, interval, map, Observable, shareReplay } from "rxjs";
+import { defer, filter, interval, map, Observable, shareReplay, switchMap } from "rxjs";
 /** Preset speeds for the animated qr code */
 export const ANIMATED_QR_INTERVAL = {
     SLOW: 500,
@@ -16,45 +15,134 @@ export const ANIMATED_QR_FRAGMENTS = {
 /** Creates an observable that iterates through a multi-part animated qr code */
 export function sendAnimated(token, options) {
     // start the stream as soon as there is subscriber
-    return defer(() => {
+    return defer(() => import("@gandlaf21/bc-ur/dist/lib/es6/index.js")).pipe(switchMap(({ UR, UREncoder }) => {
         let str = typeof token === "string" ? token : getEncodedToken(token);
         let utf8 = new TextEncoder();
         let buffer = utf8.encode(str);
         let ur = UR.from(buffer);
         let encoder = new UREncoder(ur, options?.fragmentLength ?? 100, 0);
         return interval(options?.interval ?? ANIMATED_QR_INTERVAL.FAST).pipe(map(() => encoder.nextPart()));
-    });
+    }));
 }
-/** An operator that decodes UR, emits progress percent and completes with final result or error */
+/**
+ * An operator that decodes UR, emits progress percent and completes with final result or error.
+ * Subscribes to its source synchronously so fragments/terminal signals emitted by a hot source
+ * while bc-ur is still loading are buffered in order and drained into one decoder once ready.
+ */
 function urDecoder() {
     return (source) => new Observable((observer) => {
-        const decoder = new URDecoder();
-        return source.subscribe((part) => {
-            decoder.receivePart(part);
-            if (decoder.isComplete() && decoder.isSuccess()) {
-                // emit progress
-                const progress = decoder.estimatedPercentComplete();
-                observer.next(progress);
-                // emit result
-                const ur = decoder.resultUR();
-                const decoded = ur.decodeCBOR();
-                const utf8 = new TextDecoder();
-                const tokenStr = utf8.decode(decoded);
-                observer.next(tokenStr);
-                // complete
-                observer.complete();
+        let cancelled = false;
+        let settled = false;
+        let decoder = null;
+        const queue = [];
+        const decode = (part) => {
+            if (settled || !decoder)
+                return;
+            try {
+                decoder.receivePart(part);
+                if (decoder.isComplete() && decoder.isSuccess()) {
+                    settled = true;
+                    // emit progress
+                    const progress = decoder.estimatedPercentComplete();
+                    observer.next(progress);
+                    // emit result
+                    const ur = decoder.resultUR();
+                    const decoded = ur.decodeCBOR();
+                    const utf8 = new TextDecoder();
+                    const tokenStr = utf8.decode(decoded);
+                    observer.next(tokenStr);
+                    // complete
+                    observer.complete();
+                }
+                else if (decoder.isError()) {
+                    settled = true;
+                    // emit error
+                    const reason = decoder.resultError();
+                    observer.error(new Error(reason));
+                }
+                else {
+                    // emit progress
+                    const progress = decoder.estimatedPercentComplete();
+                    observer.next(progress);
+                }
+            }
+            catch (error) {
+                settled = true;
+                observer.error(error);
             }
-            else if (decoder.isError()) {
-                // emit error
-                const reason = decoder.resultError();
-                observer.error(new Error(reason));
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            observer.error(error);
+        };
+        const complete = () => {
+            if (settled)
+                return;
+            settled = true;
+            observer.error(new Error("Animated QR input completed before a complete UR was decoded"));
+        };
+        const drain = (signal) => {
+            if (signal.kind === "next")
+                decode(signal.value);
+            else if (signal.kind === "error")
+                fail(signal.error);
+            else
+                complete();
+        };
+        // subscribe to the (possibly hot) source synchronously, before bc-ur has loaded
+        const sourceSubscription = source.subscribe({
+            next: (part) => {
+                if (cancelled || settled)
+                    return;
+                if (decoder)
+                    decode(part);
+                else
+                    queue.push({ kind: "next", value: part });
+            },
+            error: (error) => {
+                if (cancelled || settled)
+                    return;
+                if (decoder)
+                    fail(error);
+                else
+                    queue.push({ kind: "error", error });
+            },
+            complete: () => {
+                if (cancelled || settled)
+                    return;
+                if (decoder)
+                    complete();
+                else
+                    queue.push({ kind: "complete" });
+            },
+        });
+        // start loading without awaiting, so the source subscription above happens synchronously
+        import("@gandlaf21/bc-ur/dist/lib/es6/index.js").then(({ URDecoder }) => {
+            if (cancelled || settled)
+                return;
+            try {
+                decoder = new URDecoder();
+                // drain buffered fragments/terminal signal in original arrival order
+                while (queue.length > 0 && !settled)
+                    drain(queue.shift());
             }
-            else {
-                // emit progress
-                const progress = decoder.estimatedPercentComplete();
-                observer.next(progress);
+            catch (error) {
+                // a throw here (e.g. a module-shape mismatch) would otherwise escape as an
+                // unhandled rejection, since promise.then(onFulfilled) never forwards its own throw
+                fail(error);
             }
+        }, (error) => {
+            if (cancelled || settled)
+                return;
+            fail(error);
         });
+        return () => {
+            cancelled = true;
+            queue.length = 0;
+            sourceSubscription.unsubscribe();
+        };
     });
 }
 /** Creates an observable that completes with decoded token */
@@ -67,5 +155,5 @@ export function receiveAnimated(input) {
     // decode UR and complete
     urDecoder(), 
     // only run one decoder
-    shareReplay(1));
+    shareReplay({ bufferSize: 1, refCount: true }));
 }

package/dist/helpers/cashu.d.ts

@@ -24,10 +24,11 @@ export declare function getProofP2PKPubkey(proof: ProofLike): string | undefined
 /** Internal method to filter out duplicate proofs */
 export declare function ignoreDuplicateProofs(seen?: Set<string>): (proof: ProofLike) => boolean;
 /**
- * Returns a decoded cashu token inside an unicode emoji
+ * Returns a decoded cashu token inside a Unicode emoji
+ * @param keysetIds Full mint keyset IDs used to resolve shortened v2 IDs
  * @see https://github.com/cashubtc/cashu.me/blob/1194a7b9ee2f43305e38304de7bef8839601ff4d/src/components/ReceiveTokenDialog.vue#L387
  */
-export declare function decodeTokenFromEmojiString(str: string): Token | undefined;
+export declare function decodeTokenFromEmojiString(str: string, keysetIds?: string[]): Token | undefined;
 /**
  * Encodes a token into an emoji char
  * @see https://github.com/cashubtc/cashu.me/blob/1194a7b9ee2f43305e38304de7bef8839601ff4d/src/components/SendTokenDialog.vue#L710

package/dist/helpers/cashu.js

@@ -42,10 +42,11 @@ export function ignoreDuplicateProofs(seen = new Set()) {
     };
 }
 /**
- * Returns a decoded cashu token inside an unicode emoji
+ * Returns a decoded cashu token inside a Unicode emoji
+ * @param keysetIds Full mint keyset IDs used to resolve shortened v2 IDs
  * @see https://github.com/cashubtc/cashu.me/blob/1194a7b9ee2f43305e38304de7bef8839601ff4d/src/components/ReceiveTokenDialog.vue#L387
  */
-export function decodeTokenFromEmojiString(str) {
+export function decodeTokenFromEmojiString(str, keysetIds = []) {
     try {
         let decoded = [];
         const chars = Array.from(str);
@@ -83,8 +84,7 @@ export function decodeTokenFromEmojiString(str) {
         }
         // Switch out token if we found peanut data
         let decodedString = decoded.join("");
-        // Pass an empty keyset list — works for tokens with standard hex keyset ids
-        return getDecodedToken(decodedString, []);
+        return getDecodedToken(decodedString, keysetIds);
     }
     catch (error) {
         return undefined;

package/dist/helpers/history.js

@@ -1,4 +1,4 @@
-import { getHiddenTags, hasHiddenTags, isETag, isHiddenTagsUnlocked, lockHiddenTags, notifyEventUpdate, setHiddenTagsEncryptionMethod, unlockHiddenTags, } from "applesauce-core/helpers";
+import { getHiddenTags, hasHiddenTags, isETag, isHiddenTagsUnlocked, lockHiddenTags, notifyEventUpdate, setCachedValue, setHiddenTagsEncryptionMethod, unlockHiddenTags, } from "applesauce-core/helpers";
 export const WALLET_HISTORY_KIND = 7376;
 /** Checks if an event is a valid wallet history event */
 export function isValidWalletHistory(event) {
@@ -13,12 +13,11 @@ export function getHistoryRedeemed(history) {
 }
 /** Checks if the history contents are locked */
 export function isHistoryContentUnlocked(history) {
-    // Wrap in try catch to avoid throwing validation errors
-    try {
-        return (HistoryContentSymbol in history || (isHiddenTagsUnlocked(history) && getHistoryContent(history) !== undefined));
-    }
-    catch { }
-    return false;
+    // No try/catch needed: `history` is typed so the `in` test cannot throw, getHiddenTags stopped
+    // throwing on malformed content, and getHistoryContent now returns undefined rather than
+    // raising. The defensive catch this used to carry was masking those throws and silently
+    // reporting a malformed history event as merely locked.
+    return HistoryContentSymbol in history || (isHiddenTagsUnlocked(history) && getHistoryContent(history) !== undefined);
 }
 export function getHistoryContent(history) {
     // Return cached value if it exists
@@ -28,23 +27,26 @@ export function getHistoryContent(history) {
     const tags = getHiddenTags(history);
     if (!tags)
         return;
-    // Read tags
+    // Read tags. A history event missing its required tags, or carrying an unparseable amount, is
+    // unusable — return undefined rather than throwing, consistent with the locked case above and
+    // with what this getter's own return type already promises. The rejection is not cached, so the
+    // event stays readable if correct tags are decrypted in later.
     const direction = tags.find((t) => t[0] === "direction")?.[1];
     if (!direction)
-        throw new Error("History event missing direction");
+        return undefined;
     const amountStr = tags.find((t) => t[0] === "amount")?.[1];
     if (!amountStr)
-        throw new Error("History event missing amount");
+        return undefined;
     const amount = parseInt(amountStr);
     if (!Number.isFinite(amount))
-        throw new Error("Failed to parse amount");
+        return undefined;
     const mint = tags.find((t) => t[0] === "mint")?.[1];
     const feeStr = tags.find((t) => t[0] === "fee")?.[1];
     const fee = feeStr ? parseInt(feeStr) : undefined;
     const created = tags.filter((t) => isETag(t) && t[3] === "created").map((t) => t[1]);
     const content = { direction, amount, created, mint, fee };
-    // Set the cached value
-    Reflect.set(history, HistoryContentSymbol, content);
+    // Set the cached value (identity memo, non-enumerable so a spread drops it)
+    setCachedValue(history, HistoryContentSymbol, content);
     return content;
 }
 /** Decrypts a wallet history event */

package/dist/helpers/index.d.ts

@@ -10,3 +10,6 @@ export * from "./local-storage-couch.js";
 export * from "./indexed-db-couch.js";
 export * from "./mint-info.js";
 export * from "./mint-recommendation.js";
+export type { RecoveryStorage } from "./recovery-storage.js";
+export * from "./mint-recovery.js";
+export * from "./key-value-couch.js";

package/dist/helpers/index.js

@@ -10,3 +10,5 @@ export * from "./local-storage-couch.js";
 export * from "./indexed-db-couch.js";
 export * from "./mint-info.js";
 export * from "./mint-recommendation.js";
+export * from "./mint-recovery.js";
+export * from "./key-value-couch.js";

package/dist/helpers/indexed-db-couch.js

@@ -57,10 +57,12 @@ export class IndexedDBCouch {
         const db = await this.init();
         const id = this.generateId();
         const encodedToken = getEncodedToken(token);
+        // Token encoding shortens v2 IDs; keep full IDs for offline recovery.
+        const keysetIds = [...new Set(token.proofs.map((proof) => proof.id))];
         return new Promise((resolve, reject) => {
             const transaction = db.transaction([this.storeName], "readwrite");
             const store = transaction.objectStore(this.storeName);
-            const request = store.add({ id, encodedToken });
+            const request = store.add({ id, encodedToken, keysetIds });
             request.onsuccess = () => {
                 // Return a function to remove this specific token by ID
                 resolve(async () => {
@@ -98,7 +100,7 @@ export class IndexedDBCouch {
         return stored
             .map((item) => {
             try {
-                return getDecodedToken(item.encodedToken, []);
+                return getDecodedToken(item.encodedToken, item.keysetIds ?? []);
             }
             catch {
                 return null;

package/dist/helpers/key-value-couch.d.ts

@@ -0,0 +1,45 @@
+import { type Token } from "@cashu/cashu-ts";
+import type { Couch } from "./couch.js";
+import { type RecoveryStorage } from "./recovery-storage.js";
+/** Identifies a token by its normalized mint, unit, and unordered proof identities */
+export declare function tokenIdentity(token: Token): string;
+/** Stores couch tokens in a consumer-provided string store, which can encrypt values */
+export declare class KeyValueCouch implements Couch {
+    private readonly storage;
+    /** Creates a couch using app-scoped storage, optionally resolving the current account's storage */
+    constructor(storage: RecoveryStorage | (() => RecoveryStorage | null | undefined));
+    private context;
+    private serialize;
+    private read;
+    private decode;
+    /**
+     * Persists a token and returns cleanup bound to the original storage and account
+     * @throws if the storage scope is missing, unreadable, or cannot be persisted
+     */
+    store(token: Token): Promise<() => Promise<void>>;
+    /**
+     * Returns all tokens in this couch
+     * @throws if the storage scope is missing or its contents cannot be read
+     */
+    getAll(): Promise<Token[]>;
+    /**
+     * Removes one matching token regardless of proof order
+     * @throws if the storage scope is missing, unreadable, or cannot be persisted
+     */
+    remove(token: Token): Promise<void>;
+    /**
+     * Removes every token in this couch
+     * @throws if the storage scope is missing or cannot be persisted
+     */
+    clear(): Promise<void>;
+    /**
+     * Imports an earlier array-based couch record from explicitly selected legacy storage
+     * @throws if source and target overlap or persistence or cleanup fails
+     */
+    importLegacy(source: RecoveryStorage, key: string): Promise<number>;
+}
+/**
+ * Copies tokens into an explicitly selected couch before removing each source token
+ * @throws if either couch cannot be read or mutated
+ */
+export declare function migrateCouch(source: Couch, target: Couch): Promise<number>;

package/dist/helpers/key-value-couch.js

@@ -0,0 +1,140 @@
+import { deserializeProofs, serializeProofs } from "@cashu/cashu-ts";
+import { getProofUID } from "./cashu.js";
+import { saveRecovery, withRecoveryLock } from "./recovery-storage.js";
+const queues = new WeakMap();
+const tokensKey = "tokens";
+/** Identifies a token by its normalized mint, unit, and unordered proof identities */
+export function tokenIdentity(token) {
+    return JSON.stringify([token.mint.replace(/\/+$/, ""), token.unit ?? "sat", token.proofs.map(getProofUID).sort()]);
+}
+/** Stores couch tokens in a consumer-provided string store, which can encrypt values */
+export class KeyValueCouch {
+    storage;
+    /** Creates a couch using app-scoped storage, optionally resolving the current account's storage */
+    constructor(storage) {
+        this.storage = storage;
+    }
+    context() {
+        const storage = typeof this.storage === "function" ? this.storage() : this.storage;
+        if (!storage)
+            throw new Error("Unlock recovery storage before using the wallet");
+        return { storage, key: tokensKey };
+    }
+    serialize(storage, key, operation) {
+        const previous = queues.get(storage) ?? Promise.resolve();
+        const result = previous.then(() => withRecoveryLock(storage, `applesauce-couch:${key}`, operation));
+        const settled = result.then(() => undefined, () => undefined);
+        queues.set(storage, settled);
+        void settled.then(() => {
+            if (queues.get(storage) === settled)
+                queues.delete(storage);
+        });
+        return result;
+    }
+    async read(storage, key) {
+        const value = await storage.getItem(key);
+        if (value === null)
+            return [];
+        const records = JSON.parse(value);
+        if (!Array.isArray(records) ||
+            records.some((record) => !record.id || !record.token?.mint || !Array.isArray(record.token.proofs)))
+            throw new Error("Invalid couch record; preserve the stored value");
+        return records;
+    }
+    decode(record) {
+        return { ...record.token, proofs: deserializeProofs(record.token.proofs) };
+    }
+    /**
+     * Persists a token and returns cleanup bound to the original storage and account
+     * @throws if the storage scope is missing, unreadable, or cannot be persisted
+     */
+    async store(token) {
+        const { storage, key } = this.context();
+        const id = crypto.randomUUID();
+        await this.serialize(storage, key, async () => {
+            const records = await this.read(storage, key);
+            records.push({ id, token: { ...token, proofs: serializeProofs(token.proofs) } });
+            await saveRecovery(storage, key, records);
+        });
+        return () => this.serialize(storage, key, async () => {
+            const records = await this.read(storage, key);
+            await saveRecovery(storage, key, records.filter((record) => record.id !== id));
+        });
+    }
+    /**
+     * Returns all tokens in this couch
+     * @throws if the storage scope is missing or its contents cannot be read
+     */
+    async getAll() {
+        const { storage, key } = this.context();
+        return this.serialize(storage, key, async () => (await this.read(storage, key)).map((record) => this.decode(record)));
+    }
+    /**
+     * Removes one matching token regardless of proof order
+     * @throws if the storage scope is missing, unreadable, or cannot be persisted
+     */
+    async remove(token) {
+        const { storage, key } = this.context();
+        await this.serialize(storage, key, async () => {
+            const records = await this.read(storage, key);
+            const index = records.findIndex((record) => tokenIdentity(this.decode(record)) === tokenIdentity(token));
+            if (index >= 0)
+                await saveRecovery(storage, key, records.filter((_, position) => position !== index));
+        });
+    }
+    /**
+     * Removes every token in this couch
+     * @throws if the storage scope is missing or cannot be persisted
+     */
+    async clear() {
+        const { storage, key } = this.context();
+        await this.serialize(storage, key, () => saveRecovery(storage, key, []));
+    }
+    /**
+     * Imports an earlier array-based couch record from explicitly selected legacy storage
+     * @throws if source and target overlap or persistence or cleanup fails
+     */
+    async importLegacy(source, key) {
+        const { storage } = this.context();
+        if (source === storage && key === tokensKey)
+            throw new Error("Source and target couches must use independent storage scopes");
+        const target = new KeyValueCouch(storage);
+        return withRecoveryLock(source, `applesauce-couch:${key}`, async () => {
+            const value = await source.getItem(key);
+            if (value === null)
+                return 0;
+            const records = await this.read(source, key);
+            const copied = new Set((await target.getAll()).map(tokenIdentity));
+            for (const record of records) {
+                const token = this.decode(record);
+                const identity = tokenIdentity(token);
+                if (copied.has(identity))
+                    continue;
+                await target.store(token);
+                copied.add(identity);
+            }
+            await source.removeItem(key);
+            return records.length;
+        });
+    }
+}
+/**
+ * Copies tokens into an explicitly selected couch before removing each source token
+ * @throws if either couch cannot be read or mutated
+ */
+export async function migrateCouch(source, target) {
+    if (source === target)
+        throw new Error("Source and target couches must use independent storage scopes");
+    const copied = new Set((await target.getAll()).map(tokenIdentity));
+    let count = 0;
+    for (const token of await source.getAll()) {
+        const identity = tokenIdentity(token);
+        if (!copied.has(identity)) {
+            await target.store(token);
+            copied.add(identity);
+        }
+        await source.remove(token);
+        count++;
+    }
+    return count;
+}

package/dist/helpers/local-storage-couch.js

@@ -22,8 +22,10 @@ export class LocalStorageCouch {
     store(token) {
         const id = this.generateId();
         const encodedToken = getEncodedToken(token);
+        // Token encoding shortens v2 IDs; keep full IDs for offline recovery.
+        const keysetIds = [...new Set(token.proofs.map((proof) => proof.id))];
         const stored = this.getStoredTokens();
-        stored.push({ id, encodedToken });
+        stored.push({ id, encodedToken, keysetIds });
         this.saveStoredTokens(stored);
         // Return a function to remove this specific token by ID
         return () => {
@@ -47,7 +49,7 @@ export class LocalStorageCouch {
         return this.getStoredTokens()
             .map((item) => {
             try {
-                return getDecodedToken(item.encodedToken, []);
+                return getDecodedToken(item.encodedToken, item.keysetIds ?? []);
             }
             catch {
                 return null;

package/dist/helpers/mint-recovery.d.ts

@@ -0,0 +1,106 @@
+import { Wallet, type MintQuoteBolt11Response } from "@cashu/cashu-ts";
+import type { NostrEvent } from "applesauce-core/helpers";
+import type { ISigner } from "applesauce-signers";
+import { type RecoveryStorage } from "./recovery-storage.js";
+import type { Couch } from "./couch.js";
+/** Options for preparing a durable bolt11 deposit or invoice-funded nutzap */
+export interface PrepareMintOptions {
+    /** The mint URL */
+    mint: string;
+    /** The positive integer amount in sats */
+    amount: number;
+    /** The optional invoice description */
+    description?: string;
+    /** The nutzap destination; omitted for a wallet deposit */
+    nutzap?: {
+        /** The recipient's Nostr public key */
+        recipient: string;
+        /** The recipient's Cashu P2PK key */
+        p2pk: string;
+        /** The recipient's delivery relays */
+        relays: string[];
+        /** The optional comment */
+        comment?: string;
+        /** The optional event being zapped */
+        event?: NostrEvent;
+    };
+}
+/** Public metadata for a pending mint, without secrets, proofs, or private wallet events */
+export interface PendingMint extends PrepareMintOptions {
+    /** The stable operation identifier */
+    id: string;
+    /** The operation owner's public key */
+    owner: string;
+    /** The persisted invoice */
+    quote: MintQuoteBolt11Response;
+    /** The last durable stage */
+    stage: "quote" | "outputs" | "proofs" | "events";
+}
+/** Options for explicitly resuming a persisted mint */
+export interface ResumeMintOptions {
+    /** Called after the invoice has been persisted, including on resume */
+    onQuote?: (quote: MintQuoteBolt11Response) => void | Promise<void>;
+    /** Stops execution without deleting recovery state */
+    signal?: AbortSignal;
+    /** The maximum time to wait for payment */
+    timeoutMs?: number;
+}
+/** Dependencies for durable minting and idempotent Nostr publication */
+export interface MintRecoveryOptions {
+    /** The app-scoped durable storage, preferably encrypted */
+    storage: RecoveryStorage;
+    /** The immutable operation owner's public key */
+    owner: string;
+    /** The signer for this owner */
+    signer: ISigner;
+    /** Publishes an event and rejects unless a relay explicitly accepts it */
+    publish: (event: NostrEvent, relays?: string[]) => Promise<void>;
+    /** Inserts accepted events into the current session's event store, including after restart */
+    onAccepted?: (event: NostrEvent) => void;
+    /** Returns a loaded Cashu wallet, allowing reuse of cached wallets */
+    getCashuWallet?: (mint: string) => Promise<Wallet>;
+    /** Waits for payment using the application's preferred transport */
+    waitForQuote?: (mint: string, quote: string, options: ResumeMintOptions) => Promise<unknown>;
+}
+/** Persists exact mint outputs and signed events so interrupted minting can be resumed safely */
+export declare class MintRecovery {
+    private readonly options;
+    private readonly prefix;
+    /** Creates a recovery journal without reading storage, signing, or publishing */
+    constructor(options: MintRecoveryOptions);
+    private key;
+    private wallet;
+    private waitForQuote;
+    private read;
+    private metadata;
+    /**
+     * Lists this owner's pending operations without signing or resuming them
+     * @throws if storage is unavailable or a saved record is invalid
+     */
+    getPending(): Promise<PendingMint[]>;
+    /**
+     * Creates and durably stores a quote before returning its invoice
+     * @throws if the amount or destination is invalid, recovery is unsupported, or persistence fails
+     */
+    prepare(input: PrepareMintOptions): Promise<PendingMint>;
+    /**
+     * Persists an externally created quote before redemption; issued quotes still require saved outputs
+     * @throws if the quote conflicts with its operation or cannot be persisted
+     */
+    adoptQuote(input: PrepareMintOptions, quote: MintQuoteBolt11Response): Promise<PendingMint>;
+    /**
+     * Imports an owner-tagged deposit from the earlier example journal without discarding its saved outputs
+     * @throws if ownership, saved state, storage, or couch cleanup cannot be verified
+     */
+    importLegacyDeposit(key: string, couch: Couch, source?: RecoveryStorage): Promise<PendingMint | undefined>;
+    /**
+     * Imports an unowned legacy nutzap only after the consumer explicitly selects its owner and delivery relays
+     * @throws if the legacy record is invalid or relay discovery or persistence fails
+     */
+    importLegacyNutzap(key: string, getRelays: (recipient: string) => Promise<string[]>, source?: RecoveryStorage): Promise<PendingMint | undefined>;
+    /**
+     * Resumes a saved operation, retaining its state on cancellation or any failure
+     * @throws if cancelled, already running, invalid, or unable to mint, sign, persist, or publish
+     */
+    resume(id: string, options?: ResumeMintOptions): Promise<void>;
+}