@satoshai/kit 0.6.0 → 0.8.0

package/dist/index.cjs

@@ -6,6 +6,79 @@ var jsxRuntime = require('react/jsx-runtime');
 var transactions = require('@stacks/transactions');
 var bnsV2Sdk = require('bns-v2-sdk');
 
+// src/errors.ts
+var BaseError = class extends Error {
+  name = "StacksKitError";
+  /** Short, human-readable error summary without details or cause chain. */
+  shortMessage;
+  constructor(shortMessage, options) {
+    const message = [
+      shortMessage,
+      options?.details && `Details: ${options.details}`
+    ].filter(Boolean).join("\n\n");
+    super(message, options?.cause ? { cause: options.cause } : void 0);
+    this.shortMessage = shortMessage;
+  }
+  /**
+   * Walk the error cause chain. If `fn` is provided, returns the first error
+   * where `fn` returns `true`; otherwise returns the root cause.
+   */
+  walk(fn) {
+    return walk(this, fn);
+  }
+};
+function walk(err, fn) {
+  if (fn?.(err)) return err;
+  if (err && typeof err === "object" && "cause" in err) {
+    return walk(err.cause, fn);
+  }
+  return err;
+}
+var WalletNotConnectedError = class extends BaseError {
+  name = "WalletNotConnectedError";
+  constructor() {
+    super("Wallet is not connected");
+  }
+};
+var WalletNotFoundError = class extends BaseError {
+  name = "WalletNotFoundError";
+  /** The wallet ID that was not found. */
+  wallet;
+  constructor({ wallet }) {
+    super(`${wallet} wallet not found`, {
+      details: "The wallet extension may not be installed."
+    });
+    this.wallet = wallet;
+  }
+};
+var UnsupportedMethodError = class extends BaseError {
+  name = "UnsupportedMethodError";
+  /** The SIP-030 method name that is not supported. */
+  method;
+  /** The wallet that does not support the method. */
+  wallet;
+  constructor({ method, wallet }) {
+    super(`${method} is not supported by ${wallet} wallet`);
+    this.method = method;
+    this.wallet = wallet;
+  }
+};
+var WalletRequestError = class extends BaseError {
+  name = "WalletRequestError";
+  /** The SIP-030 method name that failed. */
+  method;
+  /** The wallet that returned the error. */
+  wallet;
+  constructor({ method, wallet, cause }) {
+    super(`${wallet} wallet request failed`, {
+      cause,
+      details: cause.message
+    });
+    this.method = method;
+    this.wallet = wallet;
+  }
+};
+
 // src/constants/stacks-provider-mapping.ts
 var STACKS_TO_STACKS_CONNECT_PROVIDERS = {
   xverse: "XverseProviders.BitcoinProvider",
@@ -151,6 +224,102 @@ var extractStacksAddress = (typedProvider, addresses) => {
     `No valid Stacks address found for ${typedProvider} wallet`
   );
 };
+
+// src/hooks/use-wallet-connect/use-wallet-connect.helpers.ts
+var getWcUniversalProvider = () => window.WalletConnectProvider?.connector?.provider ?? null;
+var extractStacksAddress2 = (accounts) => {
+  for (const entry of accounts) {
+    if (typeof entry === "object" && entry !== null && "address" in entry) {
+      return entry.address;
+    }
+    if (typeof entry === "string") {
+      if (entry.startsWith("S")) return entry;
+      if (entry.startsWith("stacks:")) return entry.split(":")[2] ?? null;
+    }
+  }
+  return null;
+};
+var PING_TIMEOUT_MS = 1e4;
+var pingSession = async () => {
+  const wcProvider = getWcUniversalProvider();
+  const client = wcProvider?.client;
+  const session = wcProvider?.session;
+  if (!client || !session) return false;
+  try {
+    await Promise.race([
+      client.ping({ topic: session.topic }),
+      new Promise(
+        (_, reject) => setTimeout(() => reject(new Error("Ping timeout")), PING_TIMEOUT_MS)
+      )
+    ]);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// src/hooks/use-wallet-connect/use-wallet-connect.ts
+var useWalletConnect = ({
+  address,
+  provider,
+  onAddressChange,
+  onDisconnect
+}) => {
+  react.useEffect(() => {
+    if (provider !== "wallet-connect" || !address) return;
+    let cancelled = false;
+    const validateSession = async () => {
+      const alive = await pingSession();
+      if (cancelled) return;
+      if (!alive) {
+        const wcProvider = getWcUniversalProvider();
+        try {
+          await wcProvider?.disconnect();
+        } catch {
+        }
+        connect.clearSelectedProviderId();
+        onDisconnect();
+      }
+    };
+    void validateSession();
+    return () => {
+      cancelled = true;
+    };
+  }, [provider, address, onDisconnect]);
+  react.useEffect(() => {
+    if (provider !== "wallet-connect" || !address) return;
+    const wcProvider = getWcUniversalProvider();
+    if (!wcProvider) return;
+    const handleDisconnect = () => {
+      connect.clearSelectedProviderId();
+      onDisconnect();
+    };
+    const handleAccountsChanged = (...args) => {
+      const accounts = args[0];
+      const newAddress = extractStacksAddress2(accounts);
+      if (newAddress && newAddress !== address) {
+        onAddressChange(newAddress);
+      }
+    };
+    wcProvider.on("disconnect", handleDisconnect);
+    wcProvider.on("accountsChanged", handleAccountsChanged);
+    wcProvider.on("stx_accountChange", handleAccountsChanged);
+    wcProvider.on("stx_accountsChanged", handleAccountsChanged);
+    return () => {
+      try {
+        wcProvider.off("disconnect", handleDisconnect);
+        wcProvider.off("accountsChanged", handleAccountsChanged);
+        wcProvider.off("stx_accountChange", handleAccountsChanged);
+        wcProvider.off("stx_accountsChanged", handleAccountsChanged);
+      } catch (error) {
+        console.error(
+          "Failed to remove WalletConnect listeners:",
+          error
+        );
+      }
+    };
+  }, [address, provider, onAddressChange, onDisconnect]);
+};
 var getXverseProductInfo = async () => await window.XverseProviders?.StacksProvider?.getProductInfo?.() ?? null;
 var shouldSupportAccountChange = (version) => version !== void 0 && version !== "1.0.0";
 var waitForXverseProvider = async (maxAttempts = 10, initialDelay = 200) => {
@@ -529,6 +698,18 @@ var StacksWalletProvider = ({
     onAddressChange: handleAddressChange,
     connect: connect$1
   });
+  const handleWcDisconnect = react.useCallback(() => {
+    localStorage.removeItem(LOCAL_STORAGE_STACKS);
+    setAddress(void 0);
+    setProvider(void 0);
+    onDisconnect?.();
+  }, [onDisconnect]);
+  useWalletConnect({
+    address,
+    provider,
+    onAddressChange: handleAddressChange,
+    onDisconnect: handleWcDisconnect
+  });
   const { installed } = getStacksWallets();
   const configured = wallets ?? [...SUPPORTED_STACKS_WALLETS];
   const walletInfos = configured.map((w) => ({
@@ -685,7 +866,7 @@ var useSignMessage = () => {
   const signMessageAsync = react.useCallback(
     async (variables) => {
       if (!isConnected) {
-        throw new Error("Wallet is not connected");
+        throw new WalletNotConnectedError();
       }
       setStatus("pending");
       setError(null);
@@ -694,7 +875,7 @@ var useSignMessage = () => {
         let result;
         if (provider === "okx") {
           if (!window.okxwallet) {
-            throw new Error("OKX wallet not found");
+            throw new WalletNotFoundError({ wallet: "OKX" });
           }
           result = await window.okxwallet.stacks.signMessage({
             message: variables.message
@@ -711,7 +892,11 @@ var useSignMessage = () => {
         setStatus("success");
         return result;
       } catch (err) {
-        const error2 = err instanceof Error ? err : new Error(String(err));
+        const error2 = err instanceof BaseError ? err : new WalletRequestError({
+          method: "stx_signMessage",
+          wallet: provider ?? "unknown",
+          cause: err instanceof Error ? err : new Error(String(err))
+        });
         setError(error2);
         setStatus("error");
         throw error2;
@@ -762,12 +947,13 @@ var useSignStructuredMessage = () => {
   const signStructuredMessageAsync = react.useCallback(
     async (variables) => {
       if (!isConnected) {
-        throw new Error("Wallet is not connected");
+        throw new WalletNotConnectedError();
       }
       if (provider === "okx") {
-        throw new Error(
-          "Structured message signing is not supported by OKX wallet"
-        );
+        throw new UnsupportedMethodError({
+          method: "stx_signStructuredMessage",
+          wallet: "OKX"
+        });
       }
       setStatus("pending");
       setError(null);
@@ -781,7 +967,11 @@ var useSignStructuredMessage = () => {
         setStatus("success");
         return result;
       } catch (err) {
-        const error2 = err instanceof Error ? err : new Error(String(err));
+        const error2 = err instanceof BaseError ? err : new WalletRequestError({
+          method: "stx_signStructuredMessage",
+          wallet: provider ?? "unknown",
+          cause: err instanceof Error ? err : new Error(String(err))
+        });
         setError(error2);
         setStatus("error");
         throw error2;
@@ -837,12 +1027,13 @@ var useSignTransaction = () => {
   const signTransactionAsync = react.useCallback(
     async (variables) => {
       if (!isConnected) {
-        throw new Error("Wallet is not connected");
+        throw new WalletNotConnectedError();
       }
       if (provider === "okx") {
-        throw new Error(
-          "Transaction signing is not supported by OKX wallet"
-        );
+        throw new UnsupportedMethodError({
+          method: "stx_signTransaction",
+          wallet: "OKX"
+        });
       }
       setStatus("pending");
       setError(null);
@@ -858,7 +1049,11 @@ var useSignTransaction = () => {
         setStatus("success");
         return result;
       } catch (err) {
-        const error2 = err instanceof Error ? err : new Error(String(err));
+        const error2 = err instanceof BaseError ? err : new WalletRequestError({
+          method: "stx_signTransaction",
+          wallet: provider ?? "unknown",
+          cause: err instanceof Error ? err : new Error(String(err))
+        });
         setError(error2);
         setStatus("error");
         throw error2;
@@ -920,7 +1115,7 @@ var useTransferSTX = () => {
   const transferSTXAsync = react.useCallback(
     async (variables) => {
       if (!isConnected || !address) {
-        throw new Error("Wallet is not connected");
+        throw new WalletNotConnectedError();
       }
       setStatus("pending");
       setError(null);
@@ -928,7 +1123,7 @@ var useTransferSTX = () => {
       try {
         if (provider === "okx") {
           if (!window.okxwallet) {
-            throw new Error("OKX wallet not found");
+            throw new WalletNotFoundError({ wallet: "OKX" });
           }
           const response2 = await window.okxwallet.stacks.signTransaction({
             txType: "token_transfer",
@@ -963,7 +1158,11 @@ var useTransferSTX = () => {
         setStatus("success");
         return response.txid;
       } catch (err) {
-        const error2 = err instanceof Error ? err : new Error(String(err));
+        const error2 = err instanceof BaseError ? err : new WalletRequestError({
+          method: "stx_transferStx",
+          wallet: provider ?? "unknown",
+          cause: err instanceof Error ? err : new Error(String(err))
+        });
         setError(error2);
         setStatus("error");
         throw error2;
@@ -1151,7 +1350,7 @@ var useWriteContract = () => {
   const writeContractAsync = react.useCallback(
     async (variables) => {
       if (!isConnected || !address) {
-        throw new Error("Wallet is not connected");
+        throw new WalletNotConnectedError();
       }
       setStatus("pending");
       setError(null);
@@ -1160,7 +1359,7 @@ var useWriteContract = () => {
       try {
         if (provider === "okx") {
           if (!window.okxwallet) {
-            throw new Error("OKX wallet not found");
+            throw new WalletNotFoundError({ wallet: "OKX" });
           }
           const response2 = await window.okxwallet.stacks.signTransaction({
             contractAddress: variables.address,
@@ -1195,7 +1394,11 @@ var useWriteContract = () => {
         setStatus("success");
         return response.txid;
       } catch (err) {
-        const error2 = err instanceof Error ? err : new Error(String(err));
+        const error2 = err instanceof BaseError ? err : new WalletRequestError({
+          method: "stx_callContract",
+          wallet: provider ?? "unknown",
+          cause: err instanceof Error ? err : new Error(String(err))
+        });
         setError(error2);
         setStatus("error");
         throw error2;
@@ -1280,8 +1483,13 @@ function createContractConfig(config) {
   return config;
 }
 
+exports.BaseError = BaseError;
 exports.SUPPORTED_STACKS_WALLETS = SUPPORTED_STACKS_WALLETS;
 exports.StacksWalletProvider = StacksWalletProvider;
+exports.UnsupportedMethodError = UnsupportedMethodError;
+exports.WalletNotConnectedError = WalletNotConnectedError;
+exports.WalletNotFoundError = WalletNotFoundError;
+exports.WalletRequestError = WalletRequestError;
 exports.createContractConfig = createContractConfig;
 exports.getLocalStorageWallet = getLocalStorageWallet;
 exports.getNetworkFromAddress = getNetworkFromAddress;