@unicitylabs/sphere-sdk 0.6.4 → 0.6.6

package/dist/impl/browser/connect/index.cjs

@@ -24,10 +24,118 @@ __export(connect_exports, {
   EXT_MSG_TO_HOST: () => EXT_MSG_TO_HOST,
   ExtensionTransport: () => ExtensionTransport,
   PostMessageTransport: () => PostMessageTransport,
-  isExtensionConnectEnvelope: () => isExtensionConnectEnvelope
+  autoConnect: () => autoConnect,
+  detectTransport: () => detectTransport,
+  hasExtension: () => hasExtension,
+  isExtensionConnectEnvelope: () => isExtensionConnectEnvelope,
+  isInIframe: () => isInIframe
 });
 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 */
@@ -97,6 +205,8 @@ var STORAGE_KEYS = {
 };
 var DEFAULT_BASE_PATH = "m/44'/0'/0'";
 var DEFAULT_DERIVATION_PATH = `${DEFAULT_BASE_PATH}/0/0`;
+var HOST_READY_TYPE = "sphere-connect:host-ready";
+var HOST_READY_TIMEOUT = 3e4;
 
 // connect/protocol.ts
 var SPHERE_CONNECT_NAMESPACE = "sphere-connect";
@@ -132,6 +242,12 @@ function isSphereConnectMessage(msg) {
   const m = msg;
   return m.ns === SPHERE_CONNECT_NAMESPACE && m.v === SPHERE_CONNECT_VERSION;
 }
+function createRequestId() {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
 
 // connect/permissions.ts
 var PERMISSION_SCOPES = {
@@ -179,6 +295,246 @@ var INTENT_PERMISSIONS = {
   [INTENT_ACTIONS.SIGN_MESSAGE]: PERMISSION_SCOPES.SIGN_REQUEST
 };
 
+// connect/client/ConnectClient.ts
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_INTENT_TIMEOUT = 12e4;
+var ConnectClient = class {
+  transport;
+  dapp;
+  requestedPermissions;
+  timeout;
+  intentTimeout;
+  resumeSessionId;
+  silent;
+  sessionId = null;
+  grantedPermissions = [];
+  identity = null;
+  connected = false;
+  pendingRequests = /* @__PURE__ */ new Map();
+  eventHandlers = /* @__PURE__ */ new Map();
+  unsubscribeTransport = null;
+  // Handshake resolver (one-shot)
+  handshakeResolver = null;
+  constructor(config) {
+    this.transport = config.transport;
+    this.dapp = config.dapp;
+    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
+  // ===========================================================================
+  /** Connect to the wallet. Returns session info and public identity. */
+  async connect() {
+    this.unsubscribeTransport = this.transport.onMessage(this.handleMessage.bind(this));
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.handshakeResolver = null;
+        reject(new Error("Connection timeout"));
+      }, this.timeout);
+      this.handshakeResolver = { resolve, reject, timer };
+      this.transport.send({
+        ns: SPHERE_CONNECT_NAMESPACE,
+        v: SPHERE_CONNECT_VERSION,
+        type: "handshake",
+        direction: "request",
+        permissions: this.requestedPermissions,
+        dapp: this.dapp,
+        ...this.resumeSessionId ? { sessionId: this.resumeSessionId } : {},
+        ...this.silent ? { silent: true } : {}
+      });
+    });
+  }
+  /** Disconnect from the wallet */
+  async disconnect() {
+    if (this.connected) {
+      try {
+        await this.query(RPC_METHODS.DISCONNECT);
+      } catch {
+      }
+    }
+    this.cleanup();
+  }
+  /** Whether currently connected */
+  get isConnected() {
+    return this.connected;
+  }
+  /** Granted permission scopes */
+  get permissions() {
+    return this.grantedPermissions;
+  }
+  /** Current session ID */
+  get session() {
+    return this.sessionId;
+  }
+  /** Public identity received during handshake */
+  get walletIdentity() {
+    return this.identity;
+  }
+  // ===========================================================================
+  // Query (read data)
+  // ===========================================================================
+  /** Send a query request and return the result */
+  async query(method, params) {
+    if (!this.connected) throw new SphereError("Not connected", "NOT_INITIALIZED");
+    const id = createRequestId();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(id);
+        reject(new Error(`Query timeout: ${method}`));
+      }, this.timeout);
+      this.pendingRequests.set(id, {
+        resolve,
+        reject,
+        timer
+      });
+      this.transport.send({
+        ns: SPHERE_CONNECT_NAMESPACE,
+        v: SPHERE_CONNECT_VERSION,
+        type: "request",
+        id,
+        method,
+        params
+      });
+    });
+  }
+  // ===========================================================================
+  // Intent (trigger wallet UI)
+  // ===========================================================================
+  /** Send an intent request. The wallet will open its UI for user confirmation. */
+  async intent(action, params) {
+    if (!this.connected) throw new SphereError("Not connected", "NOT_INITIALIZED");
+    const id = createRequestId();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(id);
+        reject(new Error(`Intent timeout: ${action}`));
+      }, this.intentTimeout);
+      this.pendingRequests.set(id, {
+        resolve,
+        reject,
+        timer
+      });
+      this.transport.send({
+        ns: SPHERE_CONNECT_NAMESPACE,
+        v: SPHERE_CONNECT_VERSION,
+        type: "intent",
+        id,
+        action,
+        params
+      });
+    });
+  }
+  // ===========================================================================
+  // Events
+  // ===========================================================================
+  /** Subscribe to a wallet event. Returns unsubscribe function. */
+  on(event, handler) {
+    if (!this.eventHandlers.has(event)) {
+      this.eventHandlers.set(event, /* @__PURE__ */ new Set());
+      if (this.connected) {
+        this.query(RPC_METHODS.SUBSCRIBE, { event }).catch((err) => logger.debug("Connect", "Event subscription failed", err));
+      }
+    }
+    this.eventHandlers.get(event).add(handler);
+    return () => {
+      const handlers = this.eventHandlers.get(event);
+      if (handlers) {
+        handlers.delete(handler);
+        if (handlers.size === 0) {
+          this.eventHandlers.delete(event);
+          if (this.connected) {
+            this.query(RPC_METHODS.UNSUBSCRIBE, { event }).catch((err) => logger.debug("Connect", "Event unsubscription failed", err));
+          }
+        }
+      }
+    };
+  }
+  // ===========================================================================
+  // Message Handling
+  // ===========================================================================
+  handleMessage(msg) {
+    if (msg.type === "handshake" && msg.direction === "response") {
+      this.handleHandshakeResponse(msg);
+      return;
+    }
+    if (msg.type === "response") {
+      this.handlePendingResponse(msg.id, msg.result, msg.error);
+      return;
+    }
+    if (msg.type === "intent_result") {
+      this.handlePendingResponse(msg.id, msg.result, msg.error);
+      return;
+    }
+    if (msg.type === "event") {
+      const handlers = this.eventHandlers.get(msg.event);
+      if (handlers) {
+        for (const handler of handlers) {
+          try {
+            handler(msg.data);
+          } catch (err) {
+            logger.debug("Connect", "Event handler error", err);
+          }
+        }
+      }
+    }
+  }
+  handleHandshakeResponse(msg) {
+    if (!this.handshakeResolver) return;
+    clearTimeout(this.handshakeResolver.timer);
+    if (msg.sessionId && msg.identity) {
+      this.sessionId = msg.sessionId;
+      this.grantedPermissions = msg.permissions;
+      this.identity = msg.identity;
+      this.connected = true;
+      this.handshakeResolver.resolve({
+        sessionId: msg.sessionId,
+        permissions: this.grantedPermissions,
+        identity: msg.identity
+      });
+    } else {
+      this.handshakeResolver.reject(new Error("Connection rejected by wallet"));
+    }
+    this.handshakeResolver = null;
+  }
+  handlePendingResponse(id, result, error) {
+    const pending = this.pendingRequests.get(id);
+    if (!pending) return;
+    clearTimeout(pending.timer);
+    this.pendingRequests.delete(id);
+    if (error) {
+      const err = new Error(error.message);
+      err.code = error.code;
+      err.data = error.data;
+      pending.reject(err);
+    } else {
+      pending.resolve(result);
+    }
+  }
+  // ===========================================================================
+  // Cleanup
+  // ===========================================================================
+  cleanup() {
+    if (this.unsubscribeTransport) {
+      this.unsubscribeTransport();
+      this.unsubscribeTransport = null;
+    }
+    for (const [, pending] of this.pendingRequests) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("Disconnected"));
+    }
+    this.pendingRequests.clear();
+    this.eventHandlers.clear();
+    this.connected = false;
+    this.sessionId = null;
+    this.grantedPermissions = [];
+    this.identity = null;
+  }
+};
+
 // impl/browser/connect/PostMessageTransport.ts
 var POPUP_CLOSE_CHECK_INTERVAL = 1e3;
 var PostMessageTransport = class _PostMessageTransport {
@@ -399,4 +755,149 @@ var ExtensionTransport = {
     return new ExtensionHostTransport(chromeApi);
   }
 };
+
+// impl/browser/connect/autoConnect.ts
+function isInIframe() {
+  try {
+    return window.parent !== window && window.self !== window.top;
+  } catch {
+    return true;
+  }
+}
+function hasExtension() {
+  try {
+    const sphere = window.sphere;
+    if (!sphere || typeof sphere !== "object") return false;
+    const isInstalled = sphere.isInstalled;
+    if (typeof isInstalled !== "function") return false;
+    return isInstalled() === true;
+  } catch {
+    return false;
+  }
+}
+function detectTransport() {
+  if (isInIframe()) return "iframe";
+  if (hasExtension()) return "extension";
+  return "popup";
+}
+var DEFAULT_POPUP_FEATURES = "width=420,height=720,scrollbars=yes,resizable=yes";
+async function autoConnect(config) {
+  const transportType = config.forceTransport ?? detectTransport();
+  switch (transportType) {
+    case "iframe":
+      return connectViaIframe(config);
+    case "extension":
+      return connectViaExtension(config);
+    case "popup":
+      return connectViaPopup(config);
+  }
+}
+async function connectViaIframe(config) {
+  const transport = PostMessageTransport.forClient();
+  const { client, connection, cleanup } = await createAndConnect(transport, config);
+  return {
+    client,
+    connection,
+    transport: "iframe",
+    disconnect: async () => {
+      await client.disconnect();
+      cleanup();
+    }
+  };
+}
+async function connectViaExtension(config) {
+  const transport = ExtensionTransport.forClient();
+  const { client, connection, cleanup } = await createAndConnect(transport, config);
+  return {
+    client,
+    connection,
+    transport: "extension",
+    disconnect: async () => {
+      await client.disconnect();
+      cleanup();
+    }
+  };
+}
+async function connectViaPopup(config) {
+  if (!config.walletUrl) {
+    throw new Error("autoConnect: walletUrl is required when no extension or iframe is available");
+  }
+  const origin = encodeURIComponent(window.location.origin);
+  const popupUrl = `${config.walletUrl}/connect?origin=${origin}`;
+  const features = config.popupFeatures ?? DEFAULT_POPUP_FEATURES;
+  const popup = window.open(popupUrl, "sphere-wallet", features);
+  if (!popup) {
+    throw new Error("autoConnect: Failed to open wallet popup \u2014 check popup blocker settings");
+  }
+  await waitForHostReady(popup, config.walletUrl);
+  const transport = PostMessageTransport.forClient({
+    target: popup,
+    targetOrigin: config.walletUrl
+  });
+  const { client, connection, cleanup } = await createAndConnect(transport, config);
+  const closeCheckInterval = setInterval(() => {
+    if (popup.closed) {
+      clearInterval(closeCheckInterval);
+      cleanup();
+    }
+  }, 1e3);
+  return {
+    client,
+    connection,
+    transport: "popup",
+    disconnect: async () => {
+      clearInterval(closeCheckInterval);
+      await client.disconnect();
+      cleanup();
+      if (!popup.closed) popup.close();
+    }
+  };
+}
+function waitForHostReady(popup, walletOrigin) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      window.removeEventListener("message", listener);
+      reject(new Error("autoConnect: Wallet popup did not respond in time"));
+    }, HOST_READY_TIMEOUT);
+    function listener(event) {
+      if (event.data?.type === HOST_READY_TYPE) {
+        clearTimeout(timer);
+        window.removeEventListener("message", listener);
+        resolve();
+      }
+    }
+    window.addEventListener("message", listener);
+    const closeCheck = setInterval(() => {
+      if (popup.closed) {
+        clearInterval(closeCheck);
+        clearTimeout(timer);
+        window.removeEventListener("message", listener);
+        reject(new Error("autoConnect: Wallet popup was closed before connecting"));
+      }
+    }, 500);
+  });
+}
+async function createAndConnect(transport, config) {
+  const clientConfig = {
+    transport,
+    dapp: config.dapp,
+    permissions: config.permissions,
+    timeout: config.timeout,
+    intentTimeout: config.intentTimeout,
+    resumeSessionId: config.resumeSessionId,
+    silent: config.silent
+  };
+  const client = new ConnectClient(clientConfig);
+  try {
+    const connection = await client.connect();
+    return {
+      client,
+      connection,
+      cleanup: () => transport.destroy()
+    };
+  } catch (err) {
+    transport.destroy();
+    throw err;
+  }
+}
 //# sourceMappingURL=index.cjs.map