@unicitylabs/sphere-sdk 0.5.3 → 0.5.5

package/README.md

@@ -16,6 +16,7 @@ A modular TypeScript SDK for Unicity wallet operations supporting both Layer 1 (
 - **TXF Serialization** - Token eXchange Format for storage and transfer
 - **Token Validation** - Aggregator-based token verification
 - **Core Utilities** - Crypto, currency, bech32, base58 functions
+- **Connect Protocol** - dApp ↔ wallet communication via `ConnectClient` / `ConnectHost` (browser extension + popup)
 
 ## Installation
 
@@ -32,6 +33,7 @@ Choose your platform:
 | **Browser** | [QUICKSTART-BROWSER.md](docs/QUICKSTART-BROWSER.md) | SDK only | IPFS sync (built-in) |
 | **Node.js** | [QUICKSTART-NODEJS.md](docs/QUICKSTART-NODEJS.md) | SDK + `ws` | IPFS sync (built-in) |
 | **CLI** | See below | SDK + `tsx` | - |
+| **dApp integration** | [CONNECT.md](docs/CONNECT.md) | SDK only | Sphere extension |
 
 ## CLI (Command Line Interface)
 

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);
     }
   }
   // ===========================================================================
@@ -318,10 +422,16 @@ var ConnectHost = class {
       this.sendHandshakeResponse([], void 0, void 0);
       return;
     }
+    if (msg.sessionId && this.session?.active && this.session.id === msg.sessionId) {
+      const identity2 = this.getPublicIdentity();
+      this.sendHandshakeResponse([...this.grantedPermissions], this.session.id, identity2);
+      return;
+    }
     const requestedPermissions = msg.permissions;
     const { approved, grantedPermissions } = await this.config.onConnectionRequest(
       dapp,
-      requestedPermissions
+      requestedPermissions,
+      msg.silent
     );
     if (!approved) {
       this.sendHandshakeResponse([], void 0, void 0);
@@ -371,8 +481,12 @@ var ConnectHost = class {
       return;
     }
     if (msg.method === RPC_METHODS.DISCONNECT) {
+      const disconnectedSession = this.session;
       this.revokeSession();
       this.sendResult(msg.id, { disconnected: true });
+      if (disconnectedSession && this.config.onDisconnect) {
+        Promise.resolve(this.config.onDisconnect(disconnectedSession)).catch((err) => logger.warn("Connect", "onDisconnect handler error", err));
+      }
       return;
     }
     if (!hasMethodPermission(this.grantedPermissions, msg.method)) {
@@ -443,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:
@@ -461,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 = [];
@@ -484,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++) {
@@ -497,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,
           {
@@ -508,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
@@ -516,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 };
     }
@@ -548,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();
@@ -639,6 +756,8 @@ var ConnectClient = class {
   requestedPermissions;
   timeout;
   intentTimeout;
+  resumeSessionId;
+  silent;
   sessionId = null;
   grantedPermissions = [];
   identity = null;
@@ -654,6 +773,8 @@ var ConnectClient = class {
     this.requestedPermissions = config.permissions ?? [...ALL_PERMISSIONS];
     this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
     this.intentTimeout = config.intentTimeout ?? DEFAULT_INTENT_TIMEOUT;
+    this.resumeSessionId = config.resumeSessionId ?? null;
+    this.silent = config.silent ?? false;
   }
   // ===========================================================================
   // Connection
@@ -673,7 +794,9 @@ var ConnectClient = class {
         type: "handshake",
         direction: "request",
         permissions: this.requestedPermissions,
-        dapp: this.dapp
+        dapp: this.dapp,
+        ...this.resumeSessionId ? { sessionId: this.resumeSessionId } : {},
+        ...this.silent ? { silent: true } : {}
       });
     });
   }
@@ -708,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(() => {
@@ -735,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(() => {
@@ -765,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);
@@ -777,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));
           }
         }
       }
@@ -806,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);
           }
         }
       }