@unicitylabs/sphere-sdk 0.5.0 → 0.5.2

package/dist/core/index.d.cts

@@ -465,6 +465,8 @@ interface Asset {
     readonly confirmedTokenCount: number;
     /** Number of unconfirmed tokens aggregated */
     readonly unconfirmedTokenCount: number;
+    /** Number of tokens currently being sent */
+    readonly transferringTokenCount: number;
     /** Price per whole unit in USD (null if PriceProvider not configured) */
     readonly priceUsd: number | null;
     /** Price per whole unit in EUR (null if PriceProvider not configured) */
@@ -989,6 +991,12 @@ interface HistoryRecord {
     recipientNametag?: string;
     /** Optional memo/message attached to the transfer */
     memo?: string;
+    /** All token IDs in a combined transfer (V6 bundle breakdown) */
+    tokenIds?: Array<{
+        id: string;
+        amount: string;
+        source: 'split' | 'direct';
+    }>;
 }
 /**
  * Storage result types
@@ -1928,6 +1936,12 @@ declare class PaymentsModule {
     private proofPollingInterval;
     private static readonly PROOF_POLLING_INTERVAL_MS;
     private static readonly PROOF_POLLING_MAX_ATTEMPTS;
+    private resolveUnconfirmedTimer;
+    private static readonly RESOLVE_UNCONFIRMED_INTERVAL_MS;
+    private loadedPromise;
+    private loaded;
+    private processedSplitGroupIds;
+    private processedCombinedTransferIds;
     private storageEventUnsubscribers;
     private syncDebounceTimer;
     private static readonly SYNC_DEBOUNCE_MS;
@@ -1997,6 +2011,43 @@ declare class PaymentsModule {
      * @returns InstantSplitResult with timing info
      */
     sendInstant(request: TransferRequest, options?: InstantSplitOptions): Promise<InstantSplitResult>;
+    /**
+     * Save a V5 split bundle as an unconfirmed token (shared by V5 standalone and V6 combined).
+     * Returns the created UI token, or null if deduped.
+     *
+     * @param deferPersistence - If true, skip addToken/save calls (caller batches them).
+     *   The token is still added to the in-memory map for dedup; caller must call save().
+     */
+    private saveUnconfirmedV5Token;
+    /**
+     * Save a commitment-only (NOSTR-FIRST) token and start proof polling.
+     * Shared by standalone NOSTR-FIRST handler and V6 combined handler.
+     * Returns the created UI token, or null if deduped/tombstoned.
+     *
+     * @param deferPersistence - If true, skip save() and commitment submission
+     *   (caller batches them). Token is added to in-memory map + proof polling is queued.
+     * @param skipGenesisDedup - If true, skip genesis-ID-only dedup. V6 handler sets this
+     *   because bundle-level dedup protects against replays, and split children share genesis IDs.
+     */
+    private saveCommitmentOnlyToken;
+    /**
+     * Process a received COMBINED_TRANSFER V6 bundle.
+     *
+     * Unpacks a single Nostr message into its component tokens:
+     * - Optional V5 split bundle (saved as unconfirmed, resolved lazily)
+     * - Zero or more direct tokens (saved as unconfirmed, proof-polled)
+     *
+     * Emits ONE transfer:incoming event and records ONE history entry.
+     */
+    private processCombinedTransferBundle;
+    /**
+     * Persist processed combined transfer IDs to KV storage.
+     */
+    private saveProcessedCombinedTransferIds;
+    /**
+     * Load processed combined transfer IDs from KV storage.
+     */
+    private loadProcessedCombinedTransferIds;
     /**
      * Process a received INSTANT_SPLIT bundle.
      *
@@ -2187,7 +2238,8 @@ declare class PaymentsModule {
     getAssets(coinId?: string): Promise<Asset[]>;
     /**
      * Aggregate tokens by coinId with confirmed/unconfirmed breakdown.
-     * Excludes tokens with status 'spent', 'invalid', or 'transferring'.
+     * Excludes tokens with status 'spent' or 'invalid'.
+     * Tokens with status 'transferring' are counted as unconfirmed (visible in UI as "Sending").
      */
     private aggregateTokens;
     /**
@@ -2225,6 +2277,13 @@ declare class PaymentsModule {
      * @returns Summary with counts of resolved, still-pending, and failed tokens plus per-token details.
      */
     resolveUnconfirmed(): Promise<UnconfirmedResolutionResult>;
+    /**
+     * Start a periodic interval that retries resolveUnconfirmed() until all
+     * tokens are confirmed or failed.  Stops automatically when nothing is
+     * pending and is cleaned up by destroy().
+     */
+    private scheduleResolveUnconfirmed;
+    private stopResolveUnconfirmedPolling;
     /**
      * Process a single V5 token through its finalization stages with quick-timeout proof checks.
      */
@@ -2258,6 +2317,16 @@ declare class PaymentsModule {
      * Called during load() to restore tokens that TXF format can't represent.
      */
     private loadPendingV5Tokens;
+    /**
+     * Persist the set of processed splitGroupIds to KV storage.
+     * This ensures Nostr re-deliveries are ignored across page reloads,
+     * even when the confirmed token's in-memory ID differs from v5split_{id}.
+     */
+    private saveProcessedSplitGroupIds;
+    /**
+     * Load processed splitGroupIds from KV storage.
+     */
+    private loadProcessedSplitGroupIds;
     /**
      * Add a token to the wallet.
      *
@@ -2570,7 +2639,7 @@ declare class PaymentsModule {
     /**
      * Handle NOSTR-FIRST commitment-only transfer (recipient side)
      * This is called when receiving a transfer with only commitmentData and no proof yet.
-     * We create the token as 'submitted', submit commitment (idempotent), and poll for proof.
+     * Delegates to saveCommitmentOnlyToken() helper, then emits event + records history.
      */
     private handleCommitmentOnlyTransfer;
     /**

package/dist/core/index.d.ts

@@ -465,6 +465,8 @@ interface Asset {
     readonly confirmedTokenCount: number;
     /** Number of unconfirmed tokens aggregated */
     readonly unconfirmedTokenCount: number;
+    /** Number of tokens currently being sent */
+    readonly transferringTokenCount: number;
     /** Price per whole unit in USD (null if PriceProvider not configured) */
     readonly priceUsd: number | null;
     /** Price per whole unit in EUR (null if PriceProvider not configured) */
@@ -989,6 +991,12 @@ interface HistoryRecord {
     recipientNametag?: string;
     /** Optional memo/message attached to the transfer */
     memo?: string;
+    /** All token IDs in a combined transfer (V6 bundle breakdown) */
+    tokenIds?: Array<{
+        id: string;
+        amount: string;
+        source: 'split' | 'direct';
+    }>;
 }
 /**
  * Storage result types
@@ -1928,6 +1936,12 @@ declare class PaymentsModule {
     private proofPollingInterval;
     private static readonly PROOF_POLLING_INTERVAL_MS;
     private static readonly PROOF_POLLING_MAX_ATTEMPTS;
+    private resolveUnconfirmedTimer;
+    private static readonly RESOLVE_UNCONFIRMED_INTERVAL_MS;
+    private loadedPromise;
+    private loaded;
+    private processedSplitGroupIds;
+    private processedCombinedTransferIds;
     private storageEventUnsubscribers;
     private syncDebounceTimer;
     private static readonly SYNC_DEBOUNCE_MS;
@@ -1997,6 +2011,43 @@ declare class PaymentsModule {
      * @returns InstantSplitResult with timing info
      */
     sendInstant(request: TransferRequest, options?: InstantSplitOptions): Promise<InstantSplitResult>;
+    /**
+     * Save a V5 split bundle as an unconfirmed token (shared by V5 standalone and V6 combined).
+     * Returns the created UI token, or null if deduped.
+     *
+     * @param deferPersistence - If true, skip addToken/save calls (caller batches them).
+     *   The token is still added to the in-memory map for dedup; caller must call save().
+     */
+    private saveUnconfirmedV5Token;
+    /**
+     * Save a commitment-only (NOSTR-FIRST) token and start proof polling.
+     * Shared by standalone NOSTR-FIRST handler and V6 combined handler.
+     * Returns the created UI token, or null if deduped/tombstoned.
+     *
+     * @param deferPersistence - If true, skip save() and commitment submission
+     *   (caller batches them). Token is added to in-memory map + proof polling is queued.
+     * @param skipGenesisDedup - If true, skip genesis-ID-only dedup. V6 handler sets this
+     *   because bundle-level dedup protects against replays, and split children share genesis IDs.
+     */
+    private saveCommitmentOnlyToken;
+    /**
+     * Process a received COMBINED_TRANSFER V6 bundle.
+     *
+     * Unpacks a single Nostr message into its component tokens:
+     * - Optional V5 split bundle (saved as unconfirmed, resolved lazily)
+     * - Zero or more direct tokens (saved as unconfirmed, proof-polled)
+     *
+     * Emits ONE transfer:incoming event and records ONE history entry.
+     */
+    private processCombinedTransferBundle;
+    /**
+     * Persist processed combined transfer IDs to KV storage.
+     */
+    private saveProcessedCombinedTransferIds;
+    /**
+     * Load processed combined transfer IDs from KV storage.
+     */
+    private loadProcessedCombinedTransferIds;
     /**
      * Process a received INSTANT_SPLIT bundle.
      *
@@ -2187,7 +2238,8 @@ declare class PaymentsModule {
     getAssets(coinId?: string): Promise<Asset[]>;
     /**
      * Aggregate tokens by coinId with confirmed/unconfirmed breakdown.
-     * Excludes tokens with status 'spent', 'invalid', or 'transferring'.
+     * Excludes tokens with status 'spent' or 'invalid'.
+     * Tokens with status 'transferring' are counted as unconfirmed (visible in UI as "Sending").
      */
     private aggregateTokens;
     /**
@@ -2225,6 +2277,13 @@ declare class PaymentsModule {
      * @returns Summary with counts of resolved, still-pending, and failed tokens plus per-token details.
      */
     resolveUnconfirmed(): Promise<UnconfirmedResolutionResult>;
+    /**
+     * Start a periodic interval that retries resolveUnconfirmed() until all
+     * tokens are confirmed or failed.  Stops automatically when nothing is
+     * pending and is cleaned up by destroy().
+     */
+    private scheduleResolveUnconfirmed;
+    private stopResolveUnconfirmedPolling;
     /**
      * Process a single V5 token through its finalization stages with quick-timeout proof checks.
      */
@@ -2258,6 +2317,16 @@ declare class PaymentsModule {
      * Called during load() to restore tokens that TXF format can't represent.
      */
     private loadPendingV5Tokens;
+    /**
+     * Persist the set of processed splitGroupIds to KV storage.
+     * This ensures Nostr re-deliveries are ignored across page reloads,
+     * even when the confirmed token's in-memory ID differs from v5split_{id}.
+     */
+    private saveProcessedSplitGroupIds;
+    /**
+     * Load processed splitGroupIds from KV storage.
+     */
+    private loadProcessedSplitGroupIds;
     /**
      * Add a token to the wallet.
      *
@@ -2570,7 +2639,7 @@ declare class PaymentsModule {
     /**
      * Handle NOSTR-FIRST commitment-only transfer (recipient side)
      * This is called when receiving a transfer with only commitmentData and no proof yet.
-     * We create the token as 'submitted', submit commitment (idempotent), and poll for proof.
+     * Delegates to saveCommitmentOnlyToken() helper, then emits event + records history.
      */
     private handleCommitmentOnlyTransfer;
     /**