@unicitylabs/sphere-sdk 0.5.1 → 0.5.3

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
@@ -1080,6 +1088,7 @@ interface TxfStorageDataBase {
     _outbox?: TxfOutboxEntry[];
     _sent?: TxfSentEntry[];
     _invalid?: TxfInvalidEntry[];
+    _history?: HistoryRecord[];
     [key: `_${string}`]: unknown;
 }
 interface TxfMeta {
@@ -1933,6 +1942,7 @@ declare class PaymentsModule {
     private loadedPromise;
     private loaded;
     private processedSplitGroupIds;
+    private processedCombinedTransferIds;
     private storageEventUnsubscribers;
     private syncDebounceTimer;
     private static readonly SYNC_DEBOUNCE_MS;
@@ -2002,6 +2012,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.
      *
@@ -2192,7 +2239,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;
     /**
@@ -2443,6 +2491,13 @@ declare class PaymentsModule {
      * Also performs one-time migration from legacy KV storage.
      */
     loadHistory(): Promise<void>;
+    /**
+     * Import history entries from remote TXF data into local store.
+     * Delegates to the local TokenStorageProvider's importHistoryEntries() for
+     * persistent storage, with in-memory fallback.
+     * Reused by both load() (initial IPFS fetch) and _doSync() (merge result).
+     */
+    private importRemoteHistoryEntries;
     /**
      * Get the first local token storage provider (for history operations).
      */
@@ -2592,7 +2647,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
@@ -1080,6 +1088,7 @@ interface TxfStorageDataBase {
     _outbox?: TxfOutboxEntry[];
     _sent?: TxfSentEntry[];
     _invalid?: TxfInvalidEntry[];
+    _history?: HistoryRecord[];
     [key: `_${string}`]: unknown;
 }
 interface TxfMeta {
@@ -1933,6 +1942,7 @@ declare class PaymentsModule {
     private loadedPromise;
     private loaded;
     private processedSplitGroupIds;
+    private processedCombinedTransferIds;
     private storageEventUnsubscribers;
     private syncDebounceTimer;
     private static readonly SYNC_DEBOUNCE_MS;
@@ -2002,6 +2012,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.
      *
@@ -2192,7 +2239,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;
     /**
@@ -2443,6 +2491,13 @@ declare class PaymentsModule {
      * Also performs one-time migration from legacy KV storage.
      */
     loadHistory(): Promise<void>;
+    /**
+     * Import history entries from remote TXF data into local store.
+     * Delegates to the local TokenStorageProvider's importHistoryEntries() for
+     * persistent storage, with in-memory fallback.
+     * Reused by both load() (initial IPFS fetch) and _doSync() (merge result).
+     */
+    private importRemoteHistoryEntries;
     /**
      * Get the first local token storage provider (for history operations).
      */
@@ -2592,7 +2647,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;
     /**