@unicitylabs/sphere-sdk 0.4.9 → 0.5.1

package/dist/core/index.d.cts

@@ -362,6 +362,8 @@ interface InstantSplitResult {
  * Options for instant split send operation
  */
 interface InstantSplitOptions {
+    /** Optional memo/message to include with the transfer */
+    memo?: string;
     /** Timeout for Nostr delivery in ms (default: 30000) */
     nostrTimeoutMs?: number;
     /** Timeout for burn proof wait in ms (default: 60000) */
@@ -690,7 +692,7 @@ interface TrackedAddress extends TrackedAddressEntry {
     /** Primary nametag (from nametag cache, without @ prefix) */
     readonly nametag?: string;
 }
-type SphereEventType = 'transfer:incoming' | 'transfer:confirmed' | 'transfer:failed' | 'payment_request:incoming' | 'payment_request:accepted' | 'payment_request:rejected' | 'payment_request:paid' | 'payment_request:response' | 'message:dm' | 'message:read' | 'message:typing' | 'composing:started' | 'message:broadcast' | 'sync:started' | 'sync:completed' | 'sync:provider' | 'sync:error' | 'connection:changed' | 'nametag:registered' | 'nametag:recovered' | 'identity:changed' | 'address:activated' | 'address:hidden' | 'address:unhidden' | 'sync:remote-update' | 'groupchat:message' | 'groupchat:joined' | 'groupchat:left' | 'groupchat:kicked' | 'groupchat:group_deleted' | 'groupchat:updated' | 'groupchat:connection';
+type SphereEventType = 'transfer:incoming' | 'transfer:confirmed' | 'transfer:failed' | 'payment_request:incoming' | 'payment_request:accepted' | 'payment_request:rejected' | 'payment_request:paid' | 'payment_request:response' | 'message:dm' | 'message:read' | 'message:typing' | 'composing:started' | 'message:broadcast' | 'sync:started' | 'sync:completed' | 'sync:provider' | 'sync:error' | 'connection:changed' | 'nametag:registered' | 'nametag:recovered' | 'identity:changed' | 'address:activated' | 'address:hidden' | 'address:unhidden' | 'sync:remote-update' | 'groupchat:message' | 'groupchat:joined' | 'groupchat:left' | 'groupchat:kicked' | 'groupchat:group_deleted' | 'groupchat:updated' | 'groupchat:connection' | 'history:updated';
 interface SphereEventMap {
     'transfer:incoming': IncomingTransfer;
     'transfer:confirmed': TransferResult;
@@ -790,6 +792,7 @@ interface SphereEventMap {
     'groupchat:connection': {
         connected: boolean;
     };
+    'history:updated': TransactionHistoryEntry;
 }
 type SphereEventHandler<T extends SphereEventType> = (data: SphereEventMap[T]) => void;
 /**
@@ -918,6 +921,199 @@ interface SphereStatus {
     price: ProviderStatusInfo[];
 }
 
+/**
+ * Storage Provider Interface
+ * Platform-independent storage abstraction
+ */
+
+/**
+ * Basic key-value storage provider
+ * All operations are async for platform flexibility
+ */
+interface StorageProvider extends BaseProvider {
+    /**
+     * Set identity for scoped storage
+     */
+    setIdentity(identity: FullIdentity): void;
+    /**
+     * Get value by key
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Set value by key
+     */
+    set(key: string, value: string): Promise<void>;
+    /**
+     * Remove key
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * Check if key exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Get all keys with optional prefix filter
+     */
+    keys(prefix?: string): Promise<string[]>;
+    /**
+     * Clear all keys with optional prefix filter
+     */
+    clear(prefix?: string): Promise<void>;
+    /**
+     * Save tracked addresses (only user state: index, hidden, timestamps)
+     */
+    saveTrackedAddresses(entries: TrackedAddressEntry[]): Promise<void>;
+    /**
+     * Load tracked addresses
+     */
+    loadTrackedAddresses(): Promise<TrackedAddressEntry[]>;
+}
+interface HistoryRecord {
+    /** Composite dedup key (primary key) — e.g. "RECEIVED_v5split_abc123" */
+    dedupKey: string;
+    /** UUID for public API consumption */
+    id: string;
+    type: 'SENT' | 'RECEIVED' | 'SPLIT' | 'MINT';
+    amount: string;
+    coinId: string;
+    symbol: string;
+    timestamp: number;
+    transferId?: string;
+    /** Genesis tokenId this entry relates to (used for dedup) */
+    tokenId?: string;
+    senderPubkey?: string;
+    senderAddress?: string;
+    senderNametag?: string;
+    recipientPubkey?: string;
+    recipientAddress?: string;
+    recipientNametag?: string;
+    /** Optional memo/message attached to the transfer */
+    memo?: string;
+}
+/**
+ * Storage result types
+ */
+interface SaveResult {
+    success: boolean;
+    cid?: string;
+    error?: string;
+    timestamp: number;
+}
+interface LoadResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    source: 'local' | 'remote' | 'cache';
+    timestamp: number;
+}
+interface SyncResult<T = unknown> {
+    success: boolean;
+    merged?: T;
+    added: number;
+    removed: number;
+    conflicts: number;
+    error?: string;
+}
+/**
+ * Token-specific storage provider
+ * Handles token persistence with sync capabilities
+ */
+interface TokenStorageProvider<TData = unknown> extends BaseProvider {
+    /**
+     * Set identity for storage scope
+     */
+    setIdentity(identity: FullIdentity): void;
+    /**
+     * Initialize provider (called once after identity is set)
+     */
+    initialize(): Promise<boolean>;
+    /**
+     * Shutdown provider
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Save token data
+     */
+    save(data: TData): Promise<SaveResult>;
+    /**
+     * Load token data
+     */
+    load(identifier?: string): Promise<LoadResult<TData>>;
+    /**
+     * Sync local data with remote
+     */
+    sync(localData: TData): Promise<SyncResult<TData>>;
+    /**
+     * Check if data exists
+     */
+    exists?(identifier?: string): Promise<boolean>;
+    /**
+     * Clear all data
+     */
+    clear?(): Promise<boolean>;
+    /**
+     * Subscribe to storage events
+     */
+    onEvent?(callback: StorageEventCallback): () => void;
+    /** Store a history entry (upsert by dedupKey) */
+    addHistoryEntry?(entry: HistoryRecord): Promise<void>;
+    /** Get all history entries sorted by timestamp descending */
+    getHistoryEntries?(): Promise<HistoryRecord[]>;
+    /** Check if a history entry exists by dedupKey */
+    hasHistoryEntry?(dedupKey: string): Promise<boolean>;
+    /** Clear all history entries */
+    clearHistory?(): Promise<void>;
+    /** Bulk import history entries (skip existing dedupKeys). Returns count of newly imported. */
+    importHistoryEntries?(entries: HistoryRecord[]): Promise<number>;
+}
+type StorageEventType = 'storage:saving' | 'storage:saved' | 'storage:loading' | 'storage:loaded' | 'storage:error' | 'storage:remote-updated' | 'sync:started' | 'sync:completed' | 'sync:conflict' | 'sync:error';
+interface StorageEvent {
+    type: StorageEventType;
+    timestamp: number;
+    data?: unknown;
+    error?: string;
+}
+type StorageEventCallback = (event: StorageEvent) => void;
+interface TxfStorageDataBase {
+    _meta: TxfMeta;
+    _tombstones?: TxfTombstone[];
+    _outbox?: TxfOutboxEntry[];
+    _sent?: TxfSentEntry[];
+    _invalid?: TxfInvalidEntry[];
+    [key: `_${string}`]: unknown;
+}
+interface TxfMeta {
+    version: number;
+    address: string;
+    ipnsName?: string;
+    formatVersion: string;
+    updatedAt: number;
+}
+interface TxfTombstone {
+    tokenId: string;
+    stateHash: string;
+    timestamp: number;
+}
+interface TxfOutboxEntry {
+    id: string;
+    status: string;
+    tokenId: string;
+    recipient: string;
+    createdAt: number;
+    data: unknown;
+}
+interface TxfSentEntry {
+    tokenId: string;
+    recipient: string;
+    txHash: string;
+    sentAt: number;
+}
+interface TxfInvalidEntry {
+    tokenId: string;
+    reason: string;
+    detectedAt: number;
+}
+
 /**
  * Transport Provider Interface
  * Platform-independent P2P messaging abstraction
@@ -1460,167 +1656,6 @@ interface MintNametagResult {
     error?: string;
 }
 
-/**
- * Storage Provider Interface
- * Platform-independent storage abstraction
- */
-
-/**
- * Basic key-value storage provider
- * All operations are async for platform flexibility
- */
-interface StorageProvider extends BaseProvider {
-    /**
-     * Set identity for scoped storage
-     */
-    setIdentity(identity: FullIdentity): void;
-    /**
-     * Get value by key
-     */
-    get(key: string): Promise<string | null>;
-    /**
-     * Set value by key
-     */
-    set(key: string, value: string): Promise<void>;
-    /**
-     * Remove key
-     */
-    remove(key: string): Promise<void>;
-    /**
-     * Check if key exists
-     */
-    has(key: string): Promise<boolean>;
-    /**
-     * Get all keys with optional prefix filter
-     */
-    keys(prefix?: string): Promise<string[]>;
-    /**
-     * Clear all keys with optional prefix filter
-     */
-    clear(prefix?: string): Promise<void>;
-    /**
-     * Save tracked addresses (only user state: index, hidden, timestamps)
-     */
-    saveTrackedAddresses(entries: TrackedAddressEntry[]): Promise<void>;
-    /**
-     * Load tracked addresses
-     */
-    loadTrackedAddresses(): Promise<TrackedAddressEntry[]>;
-}
-/**
- * Storage result types
- */
-interface SaveResult {
-    success: boolean;
-    cid?: string;
-    error?: string;
-    timestamp: number;
-}
-interface LoadResult<T = unknown> {
-    success: boolean;
-    data?: T;
-    error?: string;
-    source: 'local' | 'remote' | 'cache';
-    timestamp: number;
-}
-interface SyncResult<T = unknown> {
-    success: boolean;
-    merged?: T;
-    added: number;
-    removed: number;
-    conflicts: number;
-    error?: string;
-}
-/**
- * Token-specific storage provider
- * Handles token persistence with sync capabilities
- */
-interface TokenStorageProvider<TData = unknown> extends BaseProvider {
-    /**
-     * Set identity for storage scope
-     */
-    setIdentity(identity: FullIdentity): void;
-    /**
-     * Initialize provider (called once after identity is set)
-     */
-    initialize(): Promise<boolean>;
-    /**
-     * Shutdown provider
-     */
-    shutdown(): Promise<void>;
-    /**
-     * Save token data
-     */
-    save(data: TData): Promise<SaveResult>;
-    /**
-     * Load token data
-     */
-    load(identifier?: string): Promise<LoadResult<TData>>;
-    /**
-     * Sync local data with remote
-     */
-    sync(localData: TData): Promise<SyncResult<TData>>;
-    /**
-     * Check if data exists
-     */
-    exists?(identifier?: string): Promise<boolean>;
-    /**
-     * Clear all data
-     */
-    clear?(): Promise<boolean>;
-    /**
-     * Subscribe to storage events
-     */
-    onEvent?(callback: StorageEventCallback): () => void;
-}
-type StorageEventType = 'storage:saving' | 'storage:saved' | 'storage:loading' | 'storage:loaded' | 'storage:error' | 'storage:remote-updated' | 'sync:started' | 'sync:completed' | 'sync:conflict' | 'sync:error';
-interface StorageEvent {
-    type: StorageEventType;
-    timestamp: number;
-    data?: unknown;
-    error?: string;
-}
-type StorageEventCallback = (event: StorageEvent) => void;
-interface TxfStorageDataBase {
-    _meta: TxfMeta;
-    _tombstones?: TxfTombstone[];
-    _outbox?: TxfOutboxEntry[];
-    _sent?: TxfSentEntry[];
-    _invalid?: TxfInvalidEntry[];
-    [key: `_${string}`]: unknown;
-}
-interface TxfMeta {
-    version: number;
-    address: string;
-    ipnsName?: string;
-    formatVersion: string;
-    updatedAt: number;
-}
-interface TxfTombstone {
-    tokenId: string;
-    stateHash: string;
-    timestamp: number;
-}
-interface TxfOutboxEntry {
-    id: string;
-    status: string;
-    tokenId: string;
-    recipient: string;
-    createdAt: number;
-    data: unknown;
-}
-interface TxfSentEntry {
-    tokenId: string;
-    recipient: string;
-    txHash: string;
-    sentAt: number;
-}
-interface TxfInvalidEntry {
-    tokenId: string;
-    reason: string;
-    detectedAt: number;
-}
-
 /**
  * Oracle Provider Interface
  * Platform-independent Unicity oracle abstraction
@@ -1809,30 +1844,10 @@ interface PriceProvider {
 }
 
 /**
- * Payments Module
- * Platform-independent token operations with full wallet repository functionality
- *
- * Includes:
- * - Token CRUD operations
- * - Tombstones for sync
- * - Archived tokens (spent history)
- * - Forked tokens (alternative histories)
- * - Transaction history
- * - Nametag storage
+ * Public history entry type — re-exported from the shared storage layer.
+ * Single source of truth: {@link HistoryRecord} in `storage/storage-provider.ts`.
  */
-
-interface TransactionHistoryEntry {
-    id: string;
-    type: 'SENT' | 'RECEIVED' | 'SPLIT' | 'MINT';
-    amount: string;
-    coinId: string;
-    symbol: string;
-    timestamp: number;
-    recipientNametag?: string;
-    senderPubkey?: string;
-    /** TransferResult.id that created this entry (links history to transfer operation) */
-    transferId?: string;
-}
+type TransactionHistoryEntry = HistoryRecord;
 interface ReceiveOptions {
     /** Wait for all unconfirmed tokens to be finalized (default: false).
      *  When false, calls resolveUnconfirmed() once to submit pending commitments.
@@ -1899,7 +1914,7 @@ declare class PaymentsModule {
     private tombstones;
     private archivedTokens;
     private forkedTokens;
-    private transactionHistory;
+    private _historyCache;
     private nametags;
     private paymentRequests;
     private paymentRequestHandlers;
@@ -1913,6 +1928,11 @@ 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 storageEventUnsubscribers;
     private syncDebounceTimer;
     private static readonly SYNC_DEBOUNCE_MS;
@@ -2210,6 +2230,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.
      */
@@ -2243,6 +2270,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.
      *
@@ -2254,10 +2291,9 @@ declare class PaymentsModule {
      *   the old state is archived and replaced with the incoming one.
      *
      * @param token - The token to add.
-     * @param skipHistory - When `true`, do not create a `RECEIVED` transaction history entry (default `false`).
      * @returns `true` if the token was added, `false` if rejected as duplicate or tombstoned.
      */
-    addToken(token: Token, skipHistory?: boolean): Promise<boolean>;
+    addToken(token: Token): Promise<boolean>;
     /**
      * Update an existing token or add it if not found.
      *
@@ -2275,10 +2311,8 @@ declare class PaymentsModule {
      * entry is created unless `skipHistory` is `true`.
      *
      * @param tokenId - Local UUID of the token to remove.
-     * @param recipientNametag - Optional nametag of the transfer recipient (for history).
-     * @param skipHistory - When `true`, skip creating a transaction history entry (default `false`).
      */
-    removeToken(tokenId: string, recipientNametag?: string, skipHistory?: boolean): Promise<void>;
+    removeToken(tokenId: string): Promise<void>;
     /**
      * Get all tombstone entries.
      *
@@ -2389,14 +2423,30 @@ declare class PaymentsModule {
      * @returns Array of {@link TransactionHistoryEntry} objects in descending timestamp order.
      */
     getHistory(): TransactionHistoryEntry[];
+    /**
+     * Best-effort resolve sender's DIRECT address and nametag from their transport pubkey.
+     * Returns empty object if transport doesn't support resolution or lookup fails.
+     */
+    private resolveSenderInfo;
     /**
      * Append an entry to the transaction history.
      *
-     * A unique `id` is auto-generated. The entry is immediately persisted to storage.
+     * A unique `id` and `dedupKey` are auto-generated. The entry is persisted to
+     * the local token storage provider's `history` store (IndexedDB / file).
+     * Duplicate entries with the same `dedupKey` are silently ignored (upsert).
      *
-     * @param entry - History entry fields (without `id`).
+     * @param entry - History entry fields (without `id` and `dedupKey`).
+     */
+    addToHistory(entry: Omit<TransactionHistoryEntry, 'id' | 'dedupKey'>): Promise<void>;
+    /**
+     * Load history from the local token storage provider into the in-memory cache.
+     * Also performs one-time migration from legacy KV storage.
+     */
+    loadHistory(): Promise<void>;
+    /**
+     * Get the first local token storage provider (for history operations).
      */
-    addToHistory(entry: Omit<TransactionHistoryEntry, 'id'>): Promise<void>;
+    private getLocalTokenStorageProvider;
     /**
      * Set the nametag data for the current identity.
      *