@unicitylabs/sphere-sdk 0.5.4 → 0.5.5

package/dist/connect/index.cjs

@@ -42,6 +42,110 @@ __export(connect_exports, {
 });
 module.exports = __toCommonJS(connect_exports);
 
+// core/logger.ts
+var LOGGER_KEY = "__sphere_sdk_logger__";
+function getState() {
+  const g = globalThis;
+  if (!g[LOGGER_KEY]) {
+    g[LOGGER_KEY] = { debug: false, tags: {}, handler: null };
+  }
+  return g[LOGGER_KEY];
+}
+function isEnabled(tag) {
+  const state = getState();
+  if (tag in state.tags) return state.tags[tag];
+  return state.debug;
+}
+var logger = {
+  /**
+   * Configure the logger. Can be called multiple times (last write wins).
+   * Typically called by createBrowserProviders(), createNodeProviders(), or Sphere.init().
+   */
+  configure(config) {
+    const state = getState();
+    if (config.debug !== void 0) state.debug = config.debug;
+    if (config.handler !== void 0) state.handler = config.handler;
+  },
+  /**
+   * Enable/disable debug logging for a specific tag.
+   * Per-tag setting overrides the global debug flag.
+   *
+   * @example
+   * ```ts
+   * logger.setTagDebug('Nostr', true);  // enable only Nostr logs
+   * logger.setTagDebug('Nostr', false); // disable Nostr logs even if global debug=true
+   * ```
+   */
+  setTagDebug(tag, enabled) {
+    getState().tags[tag] = enabled;
+  },
+  /**
+   * Clear per-tag override, falling back to global debug flag.
+   */
+  clearTagDebug(tag) {
+    delete getState().tags[tag];
+  },
+  /** Returns true if debug mode is enabled for the given tag (or globally). */
+  isDebugEnabled(tag) {
+    if (tag) return isEnabled(tag);
+    return getState().debug;
+  },
+  /**
+   * Debug-level log. Only shown when debug is enabled (globally or for this tag).
+   * Use for detailed operational information.
+   */
+  debug(tag, message, ...args) {
+    if (!isEnabled(tag)) return;
+    const state = getState();
+    if (state.handler) {
+      state.handler("debug", tag, message, ...args);
+    } else {
+      console.log(`[${tag}]`, message, ...args);
+    }
+  },
+  /**
+   * Warning-level log. ALWAYS shown regardless of debug flag.
+   * Use for important but non-critical issues (timeouts, retries, degraded state).
+   */
+  warn(tag, message, ...args) {
+    const state = getState();
+    if (state.handler) {
+      state.handler("warn", tag, message, ...args);
+    } else {
+      console.warn(`[${tag}]`, message, ...args);
+    }
+  },
+  /**
+   * Error-level log. ALWAYS shown regardless of debug flag.
+   * Use for critical failures that should never be silenced.
+   */
+  error(tag, message, ...args) {
+    const state = getState();
+    if (state.handler) {
+      state.handler("error", tag, message, ...args);
+    } else {
+      console.error(`[${tag}]`, message, ...args);
+    }
+  },
+  /** Reset all logger state (debug flag, tags, handler). Primarily for tests. */
+  reset() {
+    const g = globalThis;
+    delete g[LOGGER_KEY];
+  }
+};
+
+// core/errors.ts
+var SphereError = class extends Error {
+  code;
+  cause;
+  constructor(message, code, cause) {
+    super(message);
+    this.name = "SphereError";
+    this.code = code;
+    this.cause = cause;
+  }
+};
+
 // constants.ts
 var STORAGE_KEYS_GLOBAL = {
   /** Encrypted BIP39 mnemonic */
@@ -306,7 +410,7 @@ var ConnectHost = class {
         return;
       }
     } catch (error) {
-      console.warn("[ConnectHost] Error handling message:", error);
+      logger.warn("ConnectHost", "Error handling message:", error);
     }
   }
   // ===========================================================================
@@ -381,7 +485,7 @@ var ConnectHost = class {
       this.revokeSession();
       this.sendResult(msg.id, { disconnected: true });
       if (disconnectedSession && this.config.onDisconnect) {
-        Promise.resolve(this.config.onDisconnect(disconnectedSession)).catch(console.warn);
+        Promise.resolve(this.config.onDisconnect(disconnectedSession)).catch((err) => logger.warn("Connect", "onDisconnect handler error", err));
       }
       return;
     }
@@ -453,17 +557,17 @@ var ConnectHost = class {
         return this.sphere.payments.getHistory();
       case RPC_METHODS.L1_GET_BALANCE:
         if (!this.sphere.payments.l1) {
-          throw new Error("L1 module not available");
+          throw new SphereError("L1 module not available", "MODULE_NOT_AVAILABLE");
         }
         return this.sphere.payments.l1.getBalance();
       case RPC_METHODS.L1_GET_HISTORY:
         if (!this.sphere.payments.l1) {
-          throw new Error("L1 module not available");
+          throw new SphereError("L1 module not available", "MODULE_NOT_AVAILABLE");
         }
         return this.sphere.payments.l1.getHistory(params.limit);
       case RPC_METHODS.RESOLVE:
         if (!params.identifier) {
-          throw new Error("Missing required parameter: identifier");
+          throw new SphereError("Missing required parameter: identifier", "VALIDATION_ERROR");
         }
         return this.sphere.resolve(params.identifier);
       case RPC_METHODS.SUBSCRIBE:
@@ -471,7 +575,7 @@ var ConnectHost = class {
       case RPC_METHODS.UNSUBSCRIBE:
         return this.handleUnsubscribe(params.event);
       case RPC_METHODS.GET_CONVERSATIONS: {
-        if (!this.sphere.communications) throw new Error("Communications module not available");
+        if (!this.sphere.communications) throw new SphereError("Communications module not available", "MODULE_NOT_AVAILABLE");
         const convos = this.sphere.communications.getConversations();
         const result = [];
         const needsResolve = [];
@@ -494,7 +598,10 @@ var ConnectHost = class {
         if (needsResolve.length > 0) {
           const resolved = await Promise.all(
             needsResolve.map(
-              ({ peerPubkey }) => this.sphere.communications.resolvePeerNametag(peerPubkey).catch(() => void 0)
+              ({ peerPubkey }) => this.sphere.communications.resolvePeerNametag(peerPubkey).catch((err) => {
+                logger.debug("Connect", "Peer nametag resolution failed", err);
+                return void 0;
+              })
             )
           );
           for (let i = 0; i < needsResolve.length; i++) {
@@ -507,8 +614,8 @@ var ConnectHost = class {
         return result;
       }
       case RPC_METHODS.GET_MESSAGES: {
-        if (!this.sphere.communications) throw new Error("Communications module not available");
-        if (!params.peerPubkey) throw new Error("Missing required parameter: peerPubkey");
+        if (!this.sphere.communications) throw new SphereError("Communications module not available", "MODULE_NOT_AVAILABLE");
+        if (!params.peerPubkey) throw new SphereError("Missing required parameter: peerPubkey", "VALIDATION_ERROR");
         return this.sphere.communications.getConversationPage(
           params.peerPubkey,
           {
@@ -518,7 +625,7 @@ var ConnectHost = class {
         );
       }
       case RPC_METHODS.GET_DM_UNREAD_COUNT: {
-        if (!this.sphere.communications) throw new Error("Communications module not available");
+        if (!this.sphere.communications) throw new SphereError("Communications module not available", "MODULE_NOT_AVAILABLE");
         return {
           unreadCount: this.sphere.communications.getUnreadCount(
             params.peerPubkey
@@ -526,22 +633,22 @@ var ConnectHost = class {
         };
       }
       case RPC_METHODS.MARK_AS_READ: {
-        if (!this.sphere.communications) throw new Error("Communications module not available");
+        if (!this.sphere.communications) throw new SphereError("Communications module not available", "MODULE_NOT_AVAILABLE");
         if (!params.messageIds || !Array.isArray(params.messageIds)) {
-          throw new Error("Missing required parameter: messageIds (string[])");
+          throw new SphereError("Missing required parameter: messageIds (string[])", "VALIDATION_ERROR");
         }
         await this.sphere.communications.markAsRead(params.messageIds);
         return { marked: true, count: params.messageIds.length };
       }
       default:
-        throw new Error(`Unknown method: ${method}`);
+        throw new SphereError(`Unknown method: ${method}`, "VALIDATION_ERROR");
     }
   }
   // ===========================================================================
   // Event Subscriptions
   // ===========================================================================
   handleSubscribe(eventName) {
-    if (!eventName) throw new Error("Missing required parameter: event");
+    if (!eventName) throw new SphereError("Missing required parameter: event", "VALIDATION_ERROR");
     if (this.eventSubscriptions.has(eventName)) {
       return { subscribed: true, event: eventName };
     }
@@ -558,7 +665,7 @@ var ConnectHost = class {
     return { subscribed: true, event: eventName };
   }
   handleUnsubscribe(eventName) {
-    if (!eventName) throw new Error("Missing required parameter: event");
+    if (!eventName) throw new SphereError("Missing required parameter: event", "VALIDATION_ERROR");
     const unsub = this.eventSubscriptions.get(eventName);
     if (unsub) {
       unsub();
@@ -724,7 +831,7 @@ var ConnectClient = class {
   // ===========================================================================
   /** Send a query request and return the result */
   async query(method, params) {
-    if (!this.connected) throw new Error("Not connected");
+    if (!this.connected) throw new SphereError("Not connected", "NOT_INITIALIZED");
     const id = createRequestId();
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -751,7 +858,7 @@ var ConnectClient = class {
   // ===========================================================================
   /** Send an intent request. The wallet will open its UI for user confirmation. */
   async intent(action, params) {
-    if (!this.connected) throw new Error("Not connected");
+    if (!this.connected) throw new SphereError("Not connected", "NOT_INITIALIZED");
     const id = createRequestId();
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -781,8 +888,7 @@ var ConnectClient = class {
     if (!this.eventHandlers.has(event)) {
       this.eventHandlers.set(event, /* @__PURE__ */ new Set());
       if (this.connected) {
-        this.query(RPC_METHODS.SUBSCRIBE, { event }).catch(() => {
-        });
+        this.query(RPC_METHODS.SUBSCRIBE, { event }).catch((err) => logger.debug("Connect", "Event subscription failed", err));
       }
     }
     this.eventHandlers.get(event).add(handler);
@@ -793,8 +899,7 @@ var ConnectClient = class {
         if (handlers.size === 0) {
           this.eventHandlers.delete(event);
           if (this.connected) {
-            this.query(RPC_METHODS.UNSUBSCRIBE, { event }).catch(() => {
-            });
+            this.query(RPC_METHODS.UNSUBSCRIBE, { event }).catch((err) => logger.debug("Connect", "Event unsubscription failed", err));
           }
         }
       }
@@ -822,7 +927,8 @@ var ConnectClient = class {
         for (const handler of handlers) {
           try {
             handler(msg.data);
-          } catch {
+          } catch (err) {
+            logger.debug("Connect", "Event handler error", err);
           }
         }
       }