@unicitylabs/sphere-sdk 0.13.2-dev.1 → 0.13.2-dev.2

package/dist/impl/nodejs/index.d.cts

@@ -1490,8 +1490,9 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
     createForAddress?(sharedClient?: unknown): TokenStorageProvider<TData>;
     /**
      * Subscribe to storage events
-     */
-    onEvent?(callback: StorageEventCallback): () => void;
+  
+    // --- History operations (optional — not supported by all providers, e.g. IPFS) ---
+  
     /** Store a history entry (upsert by dedupKey) */
     addHistoryEntry?(entry: HistoryRecord): Promise<void>;
     /** Get all history entries sorted by timestamp descending */
@@ -1503,14 +1504,6 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
     /** 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[];

package/dist/impl/nodejs/index.d.ts

@@ -1490,8 +1490,9 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
     createForAddress?(sharedClient?: unknown): TokenStorageProvider<TData>;
     /**
      * Subscribe to storage events
-     */
-    onEvent?(callback: StorageEventCallback): () => void;
+  
+    // --- History operations (optional — not supported by all providers, e.g. IPFS) ---
+  
     /** Store a history entry (upsert by dedupKey) */
     addHistoryEntry?(entry: HistoryRecord): Promise<void>;
     /** Get all history entries sorted by timestamp descending */
@@ -1503,14 +1504,6 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
     /** 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[];

package/dist/impl/shared/wallet-api/index.d.cts

@@ -1025,8 +1025,9 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
     createForAddress?(sharedClient?: unknown): TokenStorageProvider<TData>;
     /**
      * Subscribe to storage events
-     */
-    onEvent?(callback: StorageEventCallback): () => void;
+  
+    // --- History operations (optional — not supported by all providers, e.g. IPFS) ---
+  
     /** Store a history entry (upsert by dedupKey) */
     addHistoryEntry?(entry: HistoryRecord): Promise<void>;
     /** Get all history entries sorted by timestamp descending */
@@ -1038,14 +1039,6 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
     /** 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[];

package/dist/impl/shared/wallet-api/index.d.ts

@@ -1025,8 +1025,9 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
     createForAddress?(sharedClient?: unknown): TokenStorageProvider<TData>;
     /**
      * Subscribe to storage events
-     */
-    onEvent?(callback: StorageEventCallback): () => void;
+  
+    // --- History operations (optional — not supported by all providers, e.g. IPFS) ---
+  
     /** Store a history entry (upsert by dedupKey) */
     addHistoryEntry?(entry: HistoryRecord): Promise<void>;
     /** Get all history entries sorted by timestamp descending */
@@ -1038,14 +1039,6 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
     /** 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[];

package/dist/index.cjs

@@ -11783,8 +11783,7 @@ var PaymentsModule = class _PaymentsModule {
   incrementalHistoryPulls = 0;
   hydrationEpoch = 0;
   // Storage event subscriptions (push-based sync)
-  storageEventUnsubscribers = [];
-  syncDebounceTimer = null;
+  inventoryDebounceTimer = null;
   static SYNC_DEBOUNCE_MS = 500;
   /** Quiet-then-escalate logging for the background wallet-api pumps (#630). */
   pumpHealth = new PumpHealth();
@@ -11909,7 +11908,6 @@ var PaymentsModule = class _PaymentsModule {
     assertLegalCustodyComposition(deps);
     this.teardownDeliveryPump();
     this.teardownPaymentRequestPump();
-    this.unsubscribeStorageEvents();
     for (const [, resolver] of this.pendingResponseResolvers) {
       clearTimeout(resolver.timeout);
       resolver.reject(new Error("Address switched"));
@@ -11978,7 +11976,6 @@ var PaymentsModule = class _PaymentsModule {
         this.pumpHealth.run("payment-requests", () => this.pumpPaymentRequests());
       }, DELIVERY_POLL_INTERVAL_MS);
     }
-    this.subscribeToStorageEvents();
   }
   /**
    * Load all token data from storage providers and restore wallet state.
@@ -12151,7 +12148,6 @@ var PaymentsModule = class _PaymentsModule {
     this.reservationLedger.clear();
     this.parsedTokenCache.clear();
     this.tokens.clear();
-    this.unsubscribeStorageEvents();
   }
   // ===========================================================================
   // Public API - Send
@@ -14145,115 +14141,29 @@ var PaymentsModule = class _PaymentsModule {
   // Public API - Sync & Validate
   // ===========================================================================
   /**
-   * Sync local token state with all configured token storage providers (IPFS, file, etc.).
+   * Flush local token state to every configured token storage provider.
    *
-   * For each provider, the local data is packaged into TXF storage format, sent
-   * to the provider's `sync()` method, and the merged result is applied locally.
-   * Emits `sync:started`, `sync:completed`, and `sync:error` events.
-   *
-   * @returns Summary with counts of tokens added and removed during sync.
+   * Named `sync` for history: it once merged remote TXF state back in, which
+   * only IPFS ever supplied. The remaining providers all implement `sync()` as
+   * "save and return the input unchanged", so this is a write, and the returned
+   * counts are always zero.
    */
   async sync() {
     this.ensureInitialized();
-    if (this._syncInProgress) {
-      return this._syncInProgress;
-    }
-    this._syncInProgress = this._doSync();
+    if (this._syncInProgress) return this._syncInProgress;
+    this._syncInProgress = this._doFlush();
     try {
       return await this._syncInProgress;
     } finally {
       this._syncInProgress = null;
     }
   }
-  async _doSync() {
+  async _doFlush() {
     this.deps.emitEvent("sync:started", { source: "payments" });
     try {
-      const providers = this.getTokenStorageProviders();
-      if (providers.size === 0) {
-        await this.save();
-        this.deps.emitEvent("sync:completed", {
-          source: "payments",
-          count: this.tokens.size
-        });
-        return { added: 0, removed: 0 };
-      }
-      const localData = await this.createStorageData();
-      let totalAdded = 0;
-      let totalRemoved = 0;
-      const savedNametags = [...this.nametags];
-      for (const [providerId, provider] of providers) {
-        try {
-          const result = await provider.sync(localData);
-          if (result.success && result.merged) {
-            const mergedMeta = result.merged?._meta;
-            const currentChain = this.deps.identity.chainPubkey;
-            const isLegacyAlpha = mergedMeta?.address?.startsWith("alpha1") ?? false;
-            if (mergedMeta?.address && currentChain && !isLegacyAlpha && mergedMeta.address !== currentChain) {
-              logger.warn("Payments", `Sync: rejecting data from provider ${providerId} \u2014 address mismatch (got=${mergedMeta.address.slice(0, 20)}... expected=${currentChain.slice(0, 20)}...)`);
-              continue;
-            }
-            const savedTokens = new Map(this.tokens);
-            this.loadFromStorageData(result.merged);
-            const existingGenesisIds = /* @__PURE__ */ new Set();
-            for (const existing of this.tokens.values()) {
-              const gid = extractTokenIdFromSdkData(existing.sdkData);
-              if (gid) existingGenesisIds.add(gid);
-            }
-            let restoredCount = 0;
-            for (const [tokenId, token] of savedTokens) {
-              if (this.tokens.has(tokenId)) continue;
-              const sdkTokenId = extractTokenIdFromSdkData(token.sdkData);
-              const stateHash = extractStateHashFromSdkData(token.sdkData);
-              if (sdkTokenId && stateHash && this.isStateTombstoned(sdkTokenId, stateHash)) {
-                continue;
-              }
-              if (sdkTokenId && existingGenesisIds.has(sdkTokenId)) {
-                continue;
-              }
-              this.tokens.set(tokenId, token);
-              if (sdkTokenId) existingGenesisIds.add(sdkTokenId);
-              restoredCount++;
-            }
-            if (restoredCount > 0) {
-              logger.debug("Payments", `Sync: restored ${restoredCount} token(s) lost by loadFromStorageData`);
-            }
-            if (this.nametags.length === 0 && savedNametags.length > 0) {
-              this.nametags = savedNametags;
-            }
-            await this.rebuildParsedTokenCache();
-            const txfData = result.merged;
-            if (txfData._history && txfData._history.length > 0) {
-              const imported = await this.importRemoteHistoryEntries(txfData._history);
-              if (imported > 0) {
-                logger.debug("Payments", `Imported ${imported} history entries from IPFS sync`);
-              }
-            }
-            totalAdded += result.added;
-            totalRemoved += result.removed;
-          }
-          this.deps.emitEvent("sync:provider", {
-            providerId,
-            success: result.success,
-            added: result.added,
-            removed: result.removed
-          });
-        } catch (providerError) {
-          logger.warn("Payments", `Sync failed for provider ${providerId}:`, providerError);
-          this.deps.emitEvent("sync:provider", {
-            providerId,
-            success: false,
-            error: providerError instanceof Error ? providerError.message : String(providerError)
-          });
-        }
-      }
-      if (totalAdded > 0 || totalRemoved > 0) {
-        await this.save();
-      }
-      this.deps.emitEvent("sync:completed", {
-        source: "payments",
-        count: this.tokens.size
-      });
-      return { added: totalAdded, removed: totalRemoved };
+      await this.save();
+      this.deps.emitEvent("sync:completed", { source: "payments", count: this.tokens.size });
+      return { added: 0, removed: 0 };
     } catch (error) {
       this.deps.emitEvent("sync:error", {
         source: "payments",
@@ -14262,66 +14172,6 @@ var PaymentsModule = class _PaymentsModule {
       throw error;
     }
   }
-  // ===========================================================================
-  // Storage Event Subscription (Push-Based Sync)
-  // ===========================================================================
-  /**
-   * Subscribe to 'storage:remote-updated' events from all token storage providers.
-   * When a provider emits this event, a debounced sync is triggered.
-   */
-  subscribeToStorageEvents() {
-    this.unsubscribeStorageEvents();
-    const providers = this.getTokenStorageProviders();
-    for (const [providerId, provider] of providers) {
-      if (provider.onEvent) {
-        const unsub = provider.onEvent((event) => {
-          if (event.type === "storage:remote-updated") {
-            logger.debug("Payments", "Remote update detected from provider", providerId, event.data);
-            this.debouncedSyncFromRemoteUpdate(providerId, event.data);
-          }
-        });
-        this.storageEventUnsubscribers.push(unsub);
-      }
-    }
-  }
-  /**
-   * Unsubscribe from all storage provider events and clear debounce timer.
-   */
-  unsubscribeStorageEvents() {
-    for (const unsub of this.storageEventUnsubscribers) {
-      unsub();
-    }
-    this.storageEventUnsubscribers = [];
-    if (this.syncDebounceTimer) {
-      clearTimeout(this.syncDebounceTimer);
-      this.syncDebounceTimer = null;
-    }
-  }
-  /**
-   * Debounced sync triggered by a storage:remote-updated event.
-   * Waits 500ms to batch rapid updates, then performs sync.
-   */
-  debouncedSyncFromRemoteUpdate(providerId, eventData) {
-    if (this.syncDebounceTimer) {
-      clearTimeout(this.syncDebounceTimer);
-    }
-    this.syncDebounceTimer = setTimeout(() => {
-      this.syncDebounceTimer = null;
-      this.sync().then((result) => {
-        const data = eventData;
-        this.deps?.emitEvent("sync:remote-update", {
-          providerId,
-          name: data?.name ?? "",
-          sequence: data?.sequence ?? 0,
-          cid: data?.cid ?? "",
-          added: result.added,
-          removed: result.removed
-        });
-      }).catch((err) => {
-        logger.debug("Payments", "Auto-sync from remote update failed:", err);
-      });
-    }, _PaymentsModule.SYNC_DEBOUNCE_MS);
-  }
   /**
    * Get all active (non-disabled) token storage providers
    */
@@ -14366,7 +14216,6 @@ var PaymentsModule = class _PaymentsModule {
   updateTokenStorageProviders(providers) {
     if (this.deps) {
       this.deps.tokenStorageProviders = providers;
-      this.subscribeToStorageEvents();
     }
   }
   /**
@@ -14528,6 +14377,10 @@ var PaymentsModule = class _PaymentsModule {
   teardownDeliveryPump() {
     this.deliveryWakeUnsub?.();
     this.deliveryWakeUnsub = null;
+    if (this.inventoryDebounceTimer !== null) {
+      clearTimeout(this.inventoryDebounceTimer);
+      this.inventoryDebounceTimer = null;
+    }
     if (this.deliveryPollTimer !== null) {
       clearInterval(this.deliveryPollTimer);
       this.deliveryPollTimer = null;
@@ -14567,11 +14420,11 @@ var PaymentsModule = class _PaymentsModule {
    * without waiting for the next poll tick.
    */
   debouncedInventorySyncFromWake() {
-    if (this.syncDebounceTimer) {
-      clearTimeout(this.syncDebounceTimer);
+    if (this.inventoryDebounceTimer) {
+      clearTimeout(this.inventoryDebounceTimer);
     }
-    this.syncDebounceTimer = setTimeout(() => {
-      this.syncDebounceTimer = null;
+    this.inventoryDebounceTimer = setTimeout(() => {
+      this.inventoryDebounceTimer = null;
       this.pumpHealth.run("inventory", () => this.resyncInventory(true));
     }, _PaymentsModule.SYNC_DEBOUNCE_MS);
   }
@@ -30710,16 +30563,6 @@ var Sphere = class _Sphere {
       });
       if (unsub) this._providerEventCleanups.push(unsub);
     }
-    for (const [providerId, provider] of this._tokenStorageProviders) {
-      if (typeof provider.onEvent === "function") {
-        const unsub = provider.onEvent((event) => {
-          if (event.type === "storage:error" || event.type === "sync:error") {
-            this.emitConnectionChanged(providerId, provider.isConnected(), provider.getStatus(), event.error);
-          }
-        });
-        if (unsub) this._providerEventCleanups.push(unsub);
-      }
-    }
   }
   /**
    * Emit connection:changed with deduplication — only emits if status actually changed.