@unicitylabs/sphere-sdk 0.3.0 → 0.3.2

package/dist/index.cjs

@@ -508,6 +508,7 @@ __export(index_exports, {
   base58Encode: () => base58Encode2,
   buildTxfStorageData: () => buildTxfStorageData,
   bytesToHex: () => bytesToHex2,
+  checkNetworkHealth: () => checkNetworkHealth,
   countCommittedTransactions: () => countCommittedTransactions,
   createAddress: () => createAddress,
   createCommunicationsModule: () => createCommunicationsModule,
@@ -1758,6 +1759,7 @@ async function sendAlpha(wallet, toAddress, amountAlpha, fromAddress) {
 // modules/payments/L1PaymentsModule.ts
 var L1PaymentsModule = class {
   _initialized = false;
+  _disabled = false;
   _config;
   _identity;
   _addresses = [];
@@ -1805,6 +1807,9 @@ var L1PaymentsModule = class {
    * (e.g. by the address scanner), this is a no-op.
    */
   async ensureConnected() {
+    if (this._disabled) {
+      throw new Error("L1 provider is disabled");
+    }
     if (!isWebSocketConnected() && this._config.electrumUrl) {
       await connect(this._config.electrumUrl);
     }
@@ -1818,6 +1823,24 @@ var L1PaymentsModule = class {
     this._addresses = [];
     this._wallet = void 0;
   }
+  /**
+   * Disable this module — disconnect WebSocket and block operations until re-enabled.
+   */
+  disable() {
+    this._disabled = true;
+    if (isWebSocketConnected()) {
+      disconnect();
+    }
+  }
+  /**
+   * Re-enable this module. Connection will be established lazily on next operation.
+   */
+  enable() {
+    this._disabled = false;
+  }
+  get disabled() {
+    return this._disabled;
+  }
   /**
    * Check if a string looks like an L1 address (alpha1... or alphat1...)
    */
@@ -5678,7 +5701,7 @@ var PaymentsModule = class _PaymentsModule {
    */
   async getFiatBalance() {
     const assets = await this.getAssets();
-    if (!this.priceProvider) {
+    if (!this.priceProvider || this.isPriceDisabled()) {
       return null;
     }
     let total = 0;
@@ -5713,7 +5736,7 @@ var PaymentsModule = class _PaymentsModule {
    */
   async getAssets(coinId) {
     const rawAssets = this.aggregateTokens(coinId);
-    if (!this.priceProvider || rawAssets.length === 0) {
+    if (!this.priceProvider || this.isPriceDisabled() || rawAssets.length === 0) {
       return rawAssets;
     }
     try {
@@ -6807,18 +6830,38 @@ var PaymentsModule = class _PaymentsModule {
     }, _PaymentsModule.SYNC_DEBOUNCE_MS);
   }
   /**
-   * Get all active token storage providers
+   * Get all active (non-disabled) token storage providers
    */
   getTokenStorageProviders() {
+    let providers;
     if (this.deps.tokenStorageProviders && this.deps.tokenStorageProviders.size > 0) {
-      return this.deps.tokenStorageProviders;
+      providers = this.deps.tokenStorageProviders;
+    } else if (this.deps.tokenStorage) {
+      providers = /* @__PURE__ */ new Map();
+      providers.set(this.deps.tokenStorage.id, this.deps.tokenStorage);
+    } else {
+      return /* @__PURE__ */ new Map();
     }
-    if (this.deps.tokenStorage) {
-      const map = /* @__PURE__ */ new Map();
-      map.set(this.deps.tokenStorage.id, this.deps.tokenStorage);
-      return map;
+    const disabled = this.deps.disabledProviderIds;
+    if (disabled && disabled.size > 0) {
+      const filtered = /* @__PURE__ */ new Map();
+      for (const [id, provider] of providers) {
+        if (!disabled.has(id)) {
+          filtered.set(id, provider);
+        }
+      }
+      return filtered;
     }
-    return /* @__PURE__ */ new Map();
+    return providers;
+  }
+  /**
+   * Check if the price provider is disabled via the disabled providers set.
+   */
+  isPriceDisabled() {
+    const disabled = this.deps?.disabledProviderIds;
+    if (!disabled || disabled.size === 0) return false;
+    const priceId = this.priceProvider?.id ?? "price";
+    return disabled.has(priceId);
   }
   /**
    * Replace the set of token storage providers at runtime.
@@ -9321,6 +9364,9 @@ async function scanAddressesImpl(deriveAddress, options = {}) {
   };
 }
 
+// core/Sphere.ts
+init_network();
+
 // serialization/wallet-text.ts
 var import_crypto_js7 = __toESM(require("crypto-js"), 1);
 
@@ -10049,6 +10095,10 @@ var Sphere = class _Sphere {
   _groupChat = null;
   // Events
   eventHandlers = /* @__PURE__ */ new Map();
+  // Provider management
+  _disabledProviders = /* @__PURE__ */ new Set();
+  _providerEventCleanups = [];
+  _lastProviderConnected = /* @__PURE__ */ new Map();
   // ===========================================================================
   // Constructor (private)
   // ===========================================================================
@@ -10255,9 +10305,14 @@ var Sphere = class _Sphere {
       throw new Error("Either mnemonic or masterKey is required");
     }
     console.log("[Sphere.import] Starting import...");
-    console.log("[Sphere.import] Clearing existing wallet data...");
-    await _Sphere.clear({ storage: options.storage, tokenStorage: options.tokenStorage });
-    console.log("[Sphere.import] Clear done");
+    const needsClear = _Sphere.instance !== null || await _Sphere.exists(options.storage);
+    if (needsClear) {
+      console.log("[Sphere.import] Clearing existing wallet data...");
+      await _Sphere.clear({ storage: options.storage, tokenStorage: options.tokenStorage });
+      console.log("[Sphere.import] Clear done");
+    } else {
+      console.log("[Sphere.import] No existing wallet \u2014 skipping clear");
+    }
     if (!options.storage.isConnected()) {
       console.log("[Sphere.import] Reconnecting storage...");
       await options.storage.connect();
@@ -11484,20 +11539,193 @@ var Sphere = class _Sphere {
   // ===========================================================================
   // Public Methods - Status
   // ===========================================================================
+  /**
+   * Get aggregated status of all providers, grouped by role.
+   *
+   * @example
+   * ```ts
+   * const status = sphere.getStatus();
+   * // status.transport[0].connected  // true/false
+   * // status.transport[0].metadata?.relays  // { total: 3, connected: 2 }
+   * // status.tokenStorage  // all registered token storage providers
+   * ```
+   */
   getStatus() {
+    const mkInfo = (provider, role, metadata) => ({
+      id: provider.id,
+      name: provider.name,
+      role,
+      status: provider.getStatus(),
+      connected: provider.isConnected(),
+      enabled: !this._disabledProviders.has(provider.id),
+      ...metadata ? { metadata } : {}
+    });
+    let transportMeta;
+    const transport = this._transport;
+    if (typeof transport.getRelays === "function") {
+      const total = transport.getRelays().length;
+      const connected = typeof transport.getConnectedRelays === "function" ? transport.getConnectedRelays().length : 0;
+      transportMeta = { relays: { total, connected } };
+    }
+    const l1Module = this._payments.l1;
+    const l1Providers = [];
+    if (l1Module) {
+      const wsConnected = isWebSocketConnected();
+      l1Providers.push({
+        id: "l1-alpha",
+        name: "ALPHA L1",
+        role: "l1",
+        status: wsConnected ? "connected" : "disconnected",
+        connected: wsConnected,
+        enabled: !this._disabledProviders.has("l1-alpha")
+      });
+    }
+    const priceProviders = [];
+    if (this._priceProvider) {
+      priceProviders.push({
+        id: this._priceProviderId,
+        name: this._priceProvider.platform ?? "Price",
+        role: "price",
+        status: "connected",
+        connected: true,
+        enabled: !this._disabledProviders.has(this._priceProviderId)
+      });
+    }
     return {
-      storage: { connected: this._storage.isConnected() },
-      transport: { connected: this._transport.isConnected() },
-      oracle: { connected: this._oracle.isConnected() }
+      storage: [mkInfo(this._storage, "storage")],
+      tokenStorage: Array.from(this._tokenStorageProviders.values()).map(
+        (p) => mkInfo(p, "token-storage")
+      ),
+      transport: [mkInfo(this._transport, "transport", transportMeta)],
+      oracle: [mkInfo(this._oracle, "oracle")],
+      l1: l1Providers,
+      price: priceProviders
     };
   }
   async reconnect() {
     await this._transport.disconnect();
     await this._transport.connect();
+  }
+  // ===========================================================================
+  // Public Methods - Provider Management
+  // ===========================================================================
+  /**
+   * Disable a provider at runtime. The provider stays registered but is disconnected
+   * and skipped during operations (e.g., sync).
+   *
+   * Main storage provider cannot be disabled.
+   *
+   * @returns true if successfully disabled, false if provider not found
+   */
+  async disableProvider(providerId) {
+    if (providerId === this._storage.id) {
+      throw new Error("Cannot disable the main storage provider");
+    }
+    const provider = this.findProviderById(providerId);
+    if (!provider) return false;
+    this._disabledProviders.add(providerId);
+    try {
+      if ("disable" in provider && typeof provider.disable === "function") {
+        provider.disable();
+      } else if ("shutdown" in provider && typeof provider.shutdown === "function") {
+        await provider.shutdown();
+      } else if ("disconnect" in provider && typeof provider.disconnect === "function") {
+        await provider.disconnect();
+      } else if ("clearCache" in provider && typeof provider.clearCache === "function") {
+        provider.clearCache();
+      }
+    } catch {
+    }
+    this.emitEvent("connection:changed", {
+      provider: providerId,
+      connected: false,
+      status: "disconnected",
+      enabled: false
+    });
+    return true;
+  }
+  /**
+   * Re-enable a previously disabled provider. Reconnects and resumes operations.
+   *
+   * @returns true if successfully enabled, false if provider not found
+   */
+  async enableProvider(providerId) {
+    const provider = this.findProviderById(providerId);
+    if (!provider) return false;
+    this._disabledProviders.delete(providerId);
+    if ("enable" in provider && typeof provider.enable === "function") {
+      provider.enable();
+      this.emitEvent("connection:changed", {
+        provider: providerId,
+        connected: false,
+        status: "disconnected",
+        enabled: true
+      });
+      return true;
+    }
+    const hasLifecycle = "connect" in provider && typeof provider.connect === "function" || "initialize" in provider && typeof provider.initialize === "function";
+    if (hasLifecycle) {
+      try {
+        if ("connect" in provider && typeof provider.connect === "function") {
+          await provider.connect();
+        } else if ("initialize" in provider && typeof provider.initialize === "function") {
+          await provider.initialize();
+        }
+      } catch (err) {
+        this.emitEvent("connection:changed", {
+          provider: providerId,
+          connected: false,
+          status: "error",
+          enabled: true,
+          error: err instanceof Error ? err.message : String(err)
+        });
+        return false;
+      }
+    }
     this.emitEvent("connection:changed", {
-      provider: "transport",
-      connected: true
+      provider: providerId,
+      connected: true,
+      status: "connected",
+      enabled: true
     });
+    return true;
+  }
+  /**
+   * Check if a provider is currently enabled
+   */
+  isProviderEnabled(providerId) {
+    return !this._disabledProviders.has(providerId);
+  }
+  /**
+   * Get the set of disabled provider IDs (for passing to modules)
+   */
+  getDisabledProviderIds() {
+    return this._disabledProviders;
+  }
+  /** Get the price provider's ID (implementation detail — not on PriceProvider interface) */
+  get _priceProviderId() {
+    if (!this._priceProvider) return "price";
+    const p = this._priceProvider;
+    return typeof p.id === "string" ? p.id : "price";
+  }
+  /**
+   * Find a provider by ID across all provider collections
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  findProviderById(providerId) {
+    if (this._storage.id === providerId) return this._storage;
+    if (this._transport.id === providerId) return this._transport;
+    if (this._oracle.id === providerId) return this._oracle;
+    if (this._tokenStorageProviders.has(providerId)) {
+      return this._tokenStorageProviders.get(providerId);
+    }
+    if (this._priceProvider && this._priceProviderId === providerId) {
+      return this._priceProvider;
+    }
+    if (providerId === "l1-alpha" && this._payments.l1) {
+      return this._payments.l1;
+    }
+    return null;
   }
   // ===========================================================================
   // Public Methods - Events
@@ -11840,6 +12068,33 @@ var Sphere = class _Sphere {
       return;
     }
     try {
+      if (this._identity?.directAddress && this._transport.resolve) {
+        try {
+          const existing = await this._transport.resolve(this._identity.directAddress);
+          if (existing) {
+            if (existing.nametag && !this._identity.nametag) {
+              this._identity.nametag = existing.nametag;
+              await this._updateCachedProxyAddress();
+              const entry = await this.ensureAddressTracked(this._currentAddressIndex);
+              let nametags = this._addressNametags.get(entry.addressId);
+              if (!nametags) {
+                nametags = /* @__PURE__ */ new Map();
+                this._addressNametags.set(entry.addressId, nametags);
+              }
+              if (!nametags.has(0)) {
+                nametags.set(0, existing.nametag);
+                await this.persistAddressNametags();
+              }
+              this.emitEvent("nametag:recovered", { nametag: existing.nametag });
+            }
+            console.log("[Sphere] Existing binding found, skipping re-publish");
+            return;
+          }
+        } catch (e) {
+          console.warn("[Sphere] resolve() failed, skipping publish to avoid overwrite", e);
+          return;
+        }
+      }
       const nametag = this._identity?.nametag;
       const success = await this._transport.publishIdentityBinding(
         this._identity.chainPubkey,
@@ -11913,17 +12168,26 @@ var Sphere = class _Sphere {
   // Public Methods - Lifecycle
   // ===========================================================================
   async destroy() {
+    this.cleanupProviderEventSubscriptions();
     this._payments.destroy();
     this._communications.destroy();
     this._groupChat?.destroy();
     await this._transport.disconnect();
     await this._storage.disconnect();
     await this._oracle.disconnect();
+    for (const provider of this._tokenStorageProviders.values()) {
+      try {
+        await provider.shutdown();
+      } catch {
+      }
+    }
+    this._tokenStorageProviders.clear();
     this._initialized = false;
     this._identity = null;
     this._trackedAddresses.clear();
     this._addressIdToIndex.clear();
     this._addressNametags.clear();
+    this._disabledProviders.clear();
     this.eventHandlers.clear();
     if (_Sphere.instance === this) {
       _Sphere.instance = null;
@@ -12116,6 +12380,79 @@ var Sphere = class _Sphere {
     for (const provider of this._tokenStorageProviders.values()) {
       await provider.initialize();
     }
+    this.subscribeToProviderEvents();
+  }
+  /**
+   * Subscribe to provider-level events and bridge them to Sphere connection:changed events.
+   * Uses deduplication to avoid emitting duplicate events.
+   */
+  subscribeToProviderEvents() {
+    this.cleanupProviderEventSubscriptions();
+    const transportAny = this._transport;
+    if (typeof transportAny.onEvent === "function") {
+      const unsub = transportAny.onEvent((event) => {
+        const type = event?.type;
+        if (type === "transport:connected") {
+          this.emitConnectionChanged(this._transport.id, true, "connected");
+        } else if (type === "transport:disconnected") {
+          this.emitConnectionChanged(this._transport.id, false, "disconnected");
+        } else if (type === "transport:reconnecting") {
+          this.emitConnectionChanged(this._transport.id, false, "connecting");
+        } else if (type === "transport:error") {
+          this.emitConnectionChanged(this._transport.id, false, "error", event?.error);
+        }
+      });
+      if (unsub) this._providerEventCleanups.push(unsub);
+    }
+    const oracleAny = this._oracle;
+    if (typeof oracleAny.onEvent === "function") {
+      const unsub = oracleAny.onEvent((event) => {
+        const type = event?.type;
+        if (type === "oracle:connected") {
+          this.emitConnectionChanged(this._oracle.id, true, "connected");
+        } else if (type === "oracle:disconnected") {
+          this.emitConnectionChanged(this._oracle.id, false, "disconnected");
+        } else if (type === "oracle:error") {
+          this.emitConnectionChanged(this._oracle.id, false, "error", event?.error);
+        }
+      });
+      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.
+   */
+  emitConnectionChanged(providerId, connected, status, error) {
+    const lastConnected = this._lastProviderConnected.get(providerId);
+    if (lastConnected === connected) return;
+    this._lastProviderConnected.set(providerId, connected);
+    this.emitEvent("connection:changed", {
+      provider: providerId,
+      connected,
+      status,
+      enabled: !this._disabledProviders.has(providerId),
+      ...error ? { error } : {}
+    });
+  }
+  cleanupProviderEventSubscriptions() {
+    for (const cleanup of this._providerEventCleanups) {
+      try {
+        cleanup();
+      } catch {
+      }
+    }
+    this._providerEventCleanups = [];
+    this._lastProviderConnected.clear();
   }
   async initializeModules() {
     const emitEvent = this.emitEvent.bind(this);
@@ -12128,7 +12465,8 @@ var Sphere = class _Sphere {
       emitEvent,
       // Pass chain code for L1 HD derivation
       chainCode: this._masterKey?.chainCode || void 0,
-      price: this._priceProvider ?? void 0
+      price: this._priceProvider ?? void 0,
+      disabledProviderIds: this._disabledProviders
     });
     this._communications.initialize({
       identity: this._identity,
@@ -12219,6 +12557,192 @@ function formatAmount(amount, options = {}) {
 // core/index.ts
 init_bech32();
 
+// core/network-health.ts
+var DEFAULT_TIMEOUT_MS = 5e3;
+async function checkNetworkHealth(network = "testnet", options) {
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const servicesToCheck = options?.services ?? ["relay", "oracle", "l1"];
+  const networkConfig = NETWORKS[network];
+  const customUrls = options?.urls;
+  const startTime = Date.now();
+  const allChecks = [];
+  if (servicesToCheck.includes("relay")) {
+    const relayUrl = customUrls?.relay ?? networkConfig.nostrRelays[0];
+    allChecks.push(checkWebSocket(relayUrl, timeoutMs).then((r) => ["relay", r]));
+  }
+  if (servicesToCheck.includes("oracle")) {
+    const oracleUrl = customUrls?.oracle ?? networkConfig.aggregatorUrl;
+    allChecks.push(checkOracle(oracleUrl, timeoutMs).then((r) => ["oracle", r]));
+  }
+  if (servicesToCheck.includes("l1")) {
+    const l1Url = customUrls?.l1 ?? networkConfig.electrumUrl;
+    allChecks.push(checkWebSocket(l1Url, timeoutMs).then((r) => ["l1", r]));
+  }
+  if (options?.checks) {
+    for (const [name, checkFn] of Object.entries(options.checks)) {
+      allChecks.push(
+        runCustomCheck(name, checkFn, timeoutMs).then((r) => [name, r])
+      );
+    }
+  }
+  const results = await Promise.allSettled(allChecks);
+  const services = {};
+  let allHealthy = true;
+  for (const result of results) {
+    if (result.status === "fulfilled") {
+      const [name, healthResult] = result.value;
+      services[name] = healthResult;
+      if (!healthResult.healthy) allHealthy = false;
+    } else {
+      allHealthy = false;
+    }
+  }
+  return {
+    healthy: allHealthy,
+    services,
+    totalTimeMs: Date.now() - startTime
+  };
+}
+async function checkWebSocket(url, timeoutMs) {
+  const startTime = Date.now();
+  const WS = typeof globalThis !== "undefined" && globalThis.WebSocket;
+  if (!WS) {
+    return {
+      healthy: false,
+      url,
+      responseTimeMs: null,
+      error: "WebSocket not available in this environment"
+    };
+  }
+  return new Promise((resolve) => {
+    let resolved = false;
+    const timer = setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        try {
+          ws2.close();
+        } catch {
+        }
+        resolve({
+          healthy: false,
+          url,
+          responseTimeMs: null,
+          error: `Connection timeout after ${timeoutMs}ms`
+        });
+      }
+    }, timeoutMs);
+    let ws2;
+    try {
+      ws2 = new WS(url);
+    } catch (err) {
+      clearTimeout(timer);
+      return resolve({
+        healthy: false,
+        url,
+        responseTimeMs: null,
+        error: `Failed to create WebSocket: ${err instanceof Error ? err.message : String(err)}`
+      });
+    }
+    ws2.onopen = () => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timer);
+        const responseTimeMs = Date.now() - startTime;
+        try {
+          ws2.close();
+        } catch {
+        }
+        resolve({ healthy: true, url, responseTimeMs });
+      }
+    };
+    ws2.onerror = (event) => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timer);
+        try {
+          ws2.close();
+        } catch {
+        }
+        resolve({
+          healthy: false,
+          url,
+          responseTimeMs: null,
+          error: "WebSocket connection error"
+        });
+      }
+    };
+    ws2.onclose = (event) => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timer);
+        resolve({
+          healthy: false,
+          url,
+          responseTimeMs: null,
+          error: `WebSocket closed: ${event.reason || `code ${event.code}`}`
+        });
+      }
+    };
+  });
+}
+async function checkOracle(url, timeoutMs) {
+  const startTime = Date.now();
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "get_round_number", params: {} }),
+      signal: controller.signal
+    });
+    clearTimeout(timer);
+    const responseTimeMs = Date.now() - startTime;
+    if (response.ok) {
+      return { healthy: true, url, responseTimeMs };
+    }
+    return {
+      healthy: false,
+      url,
+      responseTimeMs,
+      error: `HTTP ${response.status} ${response.statusText}`
+    };
+  } catch (err) {
+    return {
+      healthy: false,
+      url,
+      responseTimeMs: null,
+      error: err instanceof Error ? err.name === "AbortError" ? `Connection timeout after ${timeoutMs}ms` : err.message : String(err)
+    };
+  }
+}
+async function runCustomCheck(name, checkFn, timeoutMs) {
+  try {
+    const result = await Promise.race([
+      checkFn(timeoutMs),
+      new Promise(
+        (resolve) => setTimeout(
+          () => resolve({
+            healthy: false,
+            url: name,
+            responseTimeMs: null,
+            error: `Custom check '${name}' timeout after ${timeoutMs}ms`
+          }),
+          timeoutMs
+        )
+      )
+    ]);
+    return result;
+  } catch (err) {
+    return {
+      healthy: false,
+      url: name,
+      responseTimeMs: null,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+
 // types/payment-session.ts
 function createPaymentSession(params) {
   const now = Date.now();
@@ -12763,6 +13287,7 @@ function createPriceProvider(config) {
   base58Encode,
   buildTxfStorageData,
   bytesToHex,
+  checkNetworkHealth,
   countCommittedTransactions,
   createAddress,
   createCommunicationsModule,