@unicitylabs/sphere-sdk 0.3.1 → 0.3.3

package/dist/core/index.d.cts

@@ -718,6 +718,9 @@ interface SphereEventMap {
     'connection:changed': {
         provider: string;
         connected: boolean;
+        status?: ProviderStatus;
+        enabled?: boolean;
+        error?: string;
     };
     'nametag:registered': {
         nametag: string;
@@ -832,6 +835,74 @@ interface WalletJSONExportOptions {
     addressCount?: number;
 }
 
+/**
+ * Result of a single service health check
+ */
+interface ServiceHealthResult {
+    /** Whether the service is reachable */
+    healthy: boolean;
+    /** URL that was checked */
+    url: string;
+    /** Response time in ms (null if unreachable) */
+    responseTimeMs: number | null;
+    /** Error message if unhealthy */
+    error?: string;
+}
+/**
+ * User-provided health check function for custom services.
+ * Receives the configured timeout and should return a ServiceHealthResult.
+ */
+type HealthCheckFn = (timeoutMs: number) => Promise<ServiceHealthResult>;
+/**
+ * Result of checking all network services (pre-init)
+ */
+interface NetworkHealthResult {
+    /** Overall health: true if all checked services are reachable */
+    healthy: boolean;
+    /** Per-service results (built-in + custom) */
+    services: {
+        relay?: ServiceHealthResult;
+        oracle?: ServiceHealthResult;
+        l1?: ServiceHealthResult;
+        /** Custom service results keyed by user-provided name */
+        [key: string]: ServiceHealthResult | undefined;
+    };
+    /** Total time to complete all checks (ms) */
+    totalTimeMs: number;
+}
+/** Role of a provider in the system */
+type ProviderRole = 'storage' | 'token-storage' | 'transport' | 'oracle' | 'l1' | 'price';
+/**
+ * Rich status information for a single provider (used in getStatus())
+ */
+interface ProviderStatusInfo {
+    /** Provider unique ID */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Role in the system */
+    role: ProviderRole;
+    /** Detailed status */
+    status: ProviderStatus;
+    /** Shorthand for status === 'connected' */
+    connected: boolean;
+    /** Whether the provider is enabled (can be toggled at runtime) */
+    enabled: boolean;
+    /** Provider-specific metadata (e.g., relay count for transport) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Aggregated status of all providers, grouped by role
+ */
+interface SphereStatus {
+    storage: ProviderStatusInfo[];
+    tokenStorage: ProviderStatusInfo[];
+    transport: ProviderStatusInfo[];
+    oracle: ProviderStatusInfo[];
+    l1: ProviderStatusInfo[];
+    price: ProviderStatusInfo[];
+}
+
 /**
  * Transport Provider Interface
  * Platform-independent P2P messaging abstraction
@@ -1235,6 +1306,7 @@ interface L1PaymentsModuleDependencies {
  */
 declare class L1PaymentsModule {
     private _initialized;
+    private _disabled;
     private _config;
     private _identity?;
     private _addresses;
@@ -1249,6 +1321,15 @@ declare class L1PaymentsModule {
      */
     private ensureConnected;
     destroy(): void;
+    /**
+     * Disable this module — disconnect WebSocket and block operations until re-enabled.
+     */
+    disable(): void;
+    /**
+     * Re-enable this module. Connection will be established lazily on next operation.
+     */
+    enable(): void;
+    get disabled(): boolean;
     /**
      * Check if a string looks like an L1 address (alpha1... or alphat1...)
      */
@@ -1725,6 +1806,8 @@ interface PaymentsModuleDependencies {
     l1Addresses?: string[];
     /** Price provider (optional — enables fiat value display) */
     price?: PriceProvider;
+    /** Set of disabled provider IDs — disabled providers are skipped during sync/save */
+    disabledProviderIds?: ReadonlySet<string>;
 }
 declare class PaymentsModule {
     private readonly moduleConfig;
@@ -2307,9 +2390,13 @@ declare class PaymentsModule {
      */
     private debouncedSyncFromRemoteUpdate;
     /**
-     * Get all active token storage providers
+     * Get all active (non-disabled) token storage providers
      */
     private getTokenStorageProviders;
+    /**
+     * Check if the price provider is disabled via the disabled providers set.
+     */
+    private isPriceDisabled;
     /**
      * Replace the set of token storage providers at runtime.
      *
@@ -2623,7 +2710,7 @@ declare const NETWORKS: {
         readonly name: "Mainnet";
         readonly aggregatorUrl: "https://aggregator.unicity.network/rpc";
         readonly nostrRelays: readonly ["wss://relay.unicity.network", "wss://relay.damus.io", "wss://nos.lol", "wss://relay.nostr.band"];
-        readonly ipfsGateways: readonly ["https://ipfs.unicity.network", "https://dweb.link", "https://ipfs.io"];
+        readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
         readonly electrumUrl: "wss://fulcrum.alpha.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
     };
@@ -2631,7 +2718,7 @@ declare const NETWORKS: {
         readonly name: "Testnet";
         readonly aggregatorUrl: "https://goggregator-test.unicity.network";
         readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
-        readonly ipfsGateways: readonly ["https://ipfs.unicity.network", "https://dweb.link", "https://ipfs.io"];
+        readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
         readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
     };
@@ -2639,7 +2726,7 @@ declare const NETWORKS: {
         readonly name: "Development";
         readonly aggregatorUrl: "https://dev-aggregator.dyndns.org/rpc";
         readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
-        readonly ipfsGateways: readonly ["https://ipfs.unicity.network", "https://dweb.link", "https://ipfs.io"];
+        readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
         readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
     };
@@ -2893,6 +2980,9 @@ declare class Sphere {
     private _communications;
     private _groupChat;
     private eventHandlers;
+    private _disabledProviders;
+    private _providerEventCleanups;
+    private _lastProviderConnected;
     private constructor();
     /**
      * Check if wallet exists in storage
@@ -3356,18 +3446,48 @@ declare class Sphere {
         hidden: boolean;
         nametag?: string;
     }>): Promise<void>;
-    getStatus(): {
-        storage: {
-            connected: boolean;
-        };
-        transport: {
-            connected: boolean;
-        };
-        oracle: {
-            connected: boolean;
-        };
-    };
+    /**
+     * 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(): SphereStatus;
     reconnect(): Promise<void>;
+    /**
+     * 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
+     */
+    disableProvider(providerId: string): Promise<boolean>;
+    /**
+     * Re-enable a previously disabled provider. Reconnects and resumes operations.
+     *
+     * @returns true if successfully enabled, false if provider not found
+     */
+    enableProvider(providerId: string): Promise<boolean>;
+    /**
+     * Check if a provider is currently enabled
+     */
+    isProviderEnabled(providerId: string): boolean;
+    /**
+     * Get the set of disabled provider IDs (for passing to modules)
+     */
+    getDisabledProviderIds(): ReadonlySet<string>;
+    /** Get the price provider's ID (implementation detail — not on PriceProvider interface) */
+    private get _priceProviderId();
+    /**
+     * Find a provider by ID across all provider collections
+     */
+    private findProviderById;
     on<T extends SphereEventType>(type: T, handler: SphereEventHandler<T>): () => void;
     off<T extends SphereEventType>(type: T, handler: SphereEventHandler<T>): void;
     sync(): Promise<void>;
@@ -3503,6 +3623,16 @@ declare class Sphere {
     private initializeIdentityFromMnemonic;
     private initializeIdentityFromMasterKey;
     private initializeProviders;
+    /**
+     * Subscribe to provider-level events and bridge them to Sphere connection:changed events.
+     * Uses deduplication to avoid emitting duplicate events.
+     */
+    private subscribeToProviderEvents;
+    /**
+     * Emit connection:changed with deduplication — only emits if status actually changed.
+     */
+    private emitConnectionChanged;
+    private cleanupProviderEventSubscriptions;
     private initializeModules;
     private ensureReady;
     private emitEvent;
@@ -3770,4 +3900,101 @@ declare function randomHex(byteLength: number): string;
  */
 declare function randomUUID(): string;
 
-export { type AddressInfo, CHARSET, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type EncryptedData, type EncryptionOptions, type KeyPair, type L1Config, type MasterKey, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };
+/**
+ * Network Health Check
+ *
+ * Standalone utility for checking network service availability before Sphere.init().
+ * Uses NETWORKS config for URLs — no providers or Sphere instance needed.
+ */
+
+type ServiceName = 'relay' | 'oracle' | 'l1';
+interface CheckNetworkHealthOptions {
+    /** Timeout per service check in ms (default: 5000) */
+    timeoutMs?: number;
+    /** Which services to check (default: all) */
+    services?: ServiceName[];
+    /** Custom URLs — override defaults from NETWORKS[network] */
+    urls?: {
+        /** Custom Nostr relay WebSocket URL (e.g. 'wss://my-relay.example.com') */
+        relay?: string;
+        /** Custom aggregator HTTP URL (e.g. 'https://my-aggregator.example.com') */
+        oracle?: string;
+        /** Custom Electrum WebSocket URL (e.g. 'wss://my-fulcrum.example.com:50004') */
+        l1?: string;
+    };
+    /**
+     * Custom health checks — run in parallel alongside built-in checks.
+     * Key = service name (e.g. 'mongodb', 'ipfs', 'redis'), value = check function.
+     *
+     * @example
+     * ```typescript
+     * const health = await checkNetworkHealth('testnet', {
+     *   checks: {
+     *     mongodb: async (timeoutMs) => {
+     *       const start = Date.now();
+     *       try {
+     *         await mongoClient.db().command({ ping: 1 });
+     *         return { healthy: true, url: 'mongodb://localhost:27017', responseTimeMs: Date.now() - start };
+     *       } catch (err) {
+     *         return { healthy: false, url: 'mongodb://localhost:27017', responseTimeMs: null, error: err.message };
+     *       }
+     *     },
+     *   },
+     * });
+     * // health.services.mongodb?.healthy
+     * ```
+     */
+    checks?: Record<string, HealthCheckFn>;
+}
+/**
+ * Check network service availability before Sphere.init().
+ *
+ * Runs all checks in parallel. Each service is tested independently with its own timeout.
+ *
+ * @example
+ * ```typescript
+ * import { checkNetworkHealth } from '@unicitylabs/sphere-sdk';
+ *
+ * const health = await checkNetworkHealth('testnet');
+ * if (health.healthy) {
+ *   // Safe to init
+ *   const { sphere } = await Sphere.init({ ... });
+ * } else {
+ *   // Show which services are down
+ *   for (const [name, result] of Object.entries(health.services)) {
+ *     if (!result.healthy) console.warn(`${name}: ${result.error}`);
+ *   }
+ * }
+ *
+ * // Check only specific services
+ * const relayHealth = await checkNetworkHealth('testnet', { services: ['relay'] });
+ *
+ * // Use custom URLs instead of defaults
+ * const custom = await checkNetworkHealth('testnet', {
+ *   urls: {
+ *     relay: 'wss://my-relay.example.com',
+ *     oracle: 'https://my-aggregator.example.com',
+ *     l1: 'wss://my-fulcrum.example.com:50004',
+ *   },
+ * });
+ *
+ * // Add custom health checks for your own providers
+ * const health = await checkNetworkHealth('testnet', {
+ *   checks: {
+ *     mongodb: async (timeoutMs) => {
+ *       const start = Date.now();
+ *       try {
+ *         await mongoClient.db().command({ ping: 1 });
+ *         return { healthy: true, url: 'mongodb://localhost:27017', responseTimeMs: Date.now() - start };
+ *       } catch (err) {
+ *         return { healthy: false, url: 'mongodb://localhost:27017', responseTimeMs: null, error: String(err) };
+ *       }
+ *     },
+ *   },
+ * });
+ * // health.services.mongodb?.healthy === true
+ * ```
+ */
+declare function checkNetworkHealth(network?: NetworkType, options?: CheckNetworkHealthOptions): Promise<NetworkHealthResult>;
+
+export { type AddressInfo, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type EncryptedData, type EncryptionOptions, type KeyPair, type L1Config, type MasterKey, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };