@satoshai/kit 0.1.1 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Satoshai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -6,6 +6,7 @@ Typesafe Stacks wallet & contract interaction library for React. Wagmi-inspired
 
 - **`StacksWalletProvider`** — React context provider for wallet state
 - **`useConnect` / `useDisconnect`** — Connect and disconnect wallets
+- **`useWallets`** — Configured wallets with availability status
 - **`useAddress`** — Access connected wallet address and status
 - **`useSignMessage`** — Sign arbitrary messages
 - **`useWriteContract`** — Call smart contracts with post-conditions
@@ -22,7 +23,7 @@ pnpm add @satoshai/kit @stacks/transactions react react-dom
 ## Quick Start
 
 ```tsx
-import { StacksWalletProvider, useConnect, useAddress, useDisconnect } from '@satoshai/kit';
+import { StacksWalletProvider, useConnect, useWallets, useAddress, useDisconnect } from '@satoshai/kit';
 
 function App() {
   return (
@@ -33,7 +34,8 @@ function App() {
 }
 
 function Wallet() {
-  const { connect, connectors } = useConnect();
+  const { connect, reset, isPending } = useConnect();
+  const { wallets } = useWallets();
   const { address, isConnected } = useAddress();
   const { disconnect } = useDisconnect();
 
@@ -48,9 +50,10 @@ function Wallet() {
 
   return (
     <div>
-      {connectors.map((wallet) => (
-        <button key={wallet} onClick={() => connect(wallet)}>
-          {wallet}
+      {isPending && <button onClick={reset}>Cancel</button>}
+      {wallets.map(({ id, available }) => (
+        <button key={id} onClick={() => connect(id)} disabled={!available || isPending}>
+          {id}
         </button>
       ))}
     </div>
@@ -66,28 +69,54 @@ Wrap your app to provide wallet context to all hooks.
 
 ```tsx
 <StacksWalletProvider
-  walletConnect={{ projectId: '...' }}  // optional — enables WalletConnect
-  onConnect={(provider, address) => {}}  // optional
-  onAddressChange={(newAddress) => {}}   // optional — Xverse account switching
-  onDisconnect={() => {}}                // optional
+  wallets={['xverse', 'leather', 'wallet-connect']}  // optional — defaults to all supported
+  walletConnect={{ projectId: '...' }}                 // optional — enables WalletConnect
+  onConnect={(provider, address) => {}}                // optional
+  onAddressChange={(newAddress) => {}}                 // optional — Xverse account switching
+  onDisconnect={() => {}}                              // optional
 >
   {children}
 </StacksWalletProvider>
 ```
 
+> If `wallets` includes `'wallet-connect'`, you must provide `walletConnect.projectId` or the provider will throw at mount.
+
+> **Important:** Define `wallets` and `walletConnect` outside of your component (or memoize them) so they remain referentially stable across renders. These values are treated as static configuration.
+
 ### `useConnect()`
 
 ```ts
-const { connect, connectors, isPending } = useConnect();
+const { connect, reset, isPending } = useConnect();
 
-// connectors = ['xverse', 'leather', 'okx', 'asigna', 'fordefi', 'wallet-connect']
 await connect('xverse');
 await connect('leather', {
   onSuccess: (address, provider) => {},
   onError: (error) => {},
 });
+
+// Reset stuck connecting state (e.g. when a wallet modal is dismissed)
+reset();
+```
+
+> **Note:** Some wallets (e.g. OKX) never reject the connection promise when the user closes the popup. Use `reset()` to clear the pending state in those cases.
+
+### `useWallets()`
+
+Returns all configured wallets with their availability status.
+
+```ts
+const { wallets } = useWallets();
+// [{ id: 'xverse', available: true }, { id: 'leather', available: false }, ...]
+
+{wallets.map(({ id, available }) => (
+  <button key={id} onClick={() => connect(id)} disabled={!available}>
+    {id}
+  </button>
+))}
 ```
 
+A wallet is `available` when its browser extension is installed. For `wallet-connect`, it's `available` when a `walletConnect.projectId` is provided to the provider.
+
 ### `useDisconnect()`
 
 ```ts

package/dist/index.cjs

@@ -162,15 +162,18 @@ var useXverse = ({
   }, [provider]);
   react.useEffect(() => {
     if (provider !== "xverse" || !address || !isProviderReady) return;
+    let cancelled = false;
     let removeListener;
     const setupXverse = async () => {
       try {
         const productInfo = await getXverseProductInfo();
+        if (cancelled) return;
         if (!shouldSupportAccountChange(productInfo?.version)) return;
         const response = await connect.getSelectedProvider()?.request(
           "wallet_connect",
           null
         );
+        if (cancelled) return;
         extractAndValidateStacksAddress(
           response?.result?.addresses,
           address,
@@ -194,6 +197,7 @@ var useXverse = ({
     };
     void setupXverse();
     return () => {
+      cancelled = true;
       if (!removeListener) return;
       try {
         removeListener();
@@ -224,6 +228,7 @@ var StacksWalletContext = react.createContext(
 );
 var StacksWalletProvider = ({
   children,
+  wallets,
   walletConnect,
   onConnect,
   onAddressChange,
@@ -232,6 +237,16 @@ var StacksWalletProvider = ({
   const [address, setAddress] = react.useState();
   const [provider, setProvider] = react.useState();
   const [isConnecting, setIsConnecting] = react.useState(false);
+  const connectGenRef = react.useRef(0);
+  const wcInitRef = react.useRef(null);
+  const walletsKey = wallets?.join(",");
+  react.useEffect(() => {
+    if (wallets?.includes("wallet-connect") && !walletConnect?.projectId) {
+      throw new Error(
+        'StacksWalletProvider: "wallet-connect" is listed in wallets but no walletConnect.projectId was provided.'
+      );
+    }
+  }, [walletsKey, walletConnect?.projectId]);
   react.useEffect(() => {
     const loadPersistedWallet = async () => {
       const persisted = getLocalStorageWallet();
@@ -244,6 +259,18 @@ var StacksWalletProvider = ({
           setProvider(data.provider);
           return;
         }
+        if (persisted.provider === "wallet-connect" && walletConnect?.projectId) {
+          const initPromise = connect.WalletConnect.initializeProvider(
+            buildWalletConnectConfig(
+              walletConnect.projectId,
+              walletConnect.metadata,
+              walletConnect.chains
+            )
+          );
+          wcInitRef.current = initPromise;
+          await initPromise;
+          wcInitRef.current = null;
+        }
         setAddress(persisted.address);
         setProvider(persisted.provider);
         connect.setSelectedProviderId(
@@ -256,7 +283,7 @@ var StacksWalletProvider = ({
       }
     };
     void loadPersistedWallet();
-  }, []);
+  }, [walletConnect?.projectId]);
   const connect$1 = react.useCallback(
     async (providerId, options) => {
       const typedProvider = SUPPORTED_STACKS_WALLETS.find(
@@ -286,10 +313,12 @@ var StacksWalletProvider = ({
         options?.onError?.(error);
         return;
       }
+      const gen = ++connectGenRef.current;
       setIsConnecting(true);
       try {
         if (typedProvider === "okx") {
           const data2 = await getOKXStacksAddress();
+          if (connectGenRef.current !== gen) return;
           setAddress(data2.address);
           setProvider(data2.provider);
           options?.onSuccess?.(data2.address, data2.provider);
@@ -298,17 +327,25 @@ var StacksWalletProvider = ({
         connect.setSelectedProviderId(
           STACKS_TO_STACKS_CONNECT_PROVIDERS[typedProvider]
         );
-        const data = walletConnect ? await connect.request(
-          {
-            walletConnect: buildWalletConnectConfig(
-              walletConnect.projectId,
-              walletConnect.metadata,
-              walletConnect.chains
-            )
-          },
+        const wcConfig = typedProvider === "wallet-connect" && walletConnect ? buildWalletConnectConfig(
+          walletConnect.projectId,
+          walletConnect.metadata,
+          walletConnect.chains
+        ) : void 0;
+        if (wcConfig) {
+          if (wcInitRef.current) await wcInitRef.current;
+          const initPromise = connect.WalletConnect.initializeProvider(wcConfig);
+          wcInitRef.current = initPromise;
+          await initPromise;
+          wcInitRef.current = null;
+        }
+        if (connectGenRef.current !== gen) return;
+        const data = wcConfig ? await connect.request(
+          { walletConnect: wcConfig },
           "getAddresses",
           {}
         ) : await connect.request("getAddresses");
+        if (connectGenRef.current !== gen) return;
         const extractedAddress = extractStacksAddress(
           typedProvider,
           data.addresses
@@ -317,16 +354,26 @@ var StacksWalletProvider = ({
         setProvider(typedProvider);
         options?.onSuccess?.(extractedAddress, typedProvider);
       } catch (error) {
+        if (connectGenRef.current !== gen) return;
         console.error("Failed to connect wallet:", error);
-        connect.getSelectedProvider()?.disconnect?.();
-        connect.clearSelectedProviderId();
+        if (typedProvider !== "okx") {
+          connect.getSelectedProvider()?.disconnect?.();
+          connect.clearSelectedProviderId();
+        }
         options?.onError?.(error);
       } finally {
-        setIsConnecting(false);
+        if (connectGenRef.current === gen) {
+          setIsConnecting(false);
+        }
       }
     },
     [walletConnect]
   );
+  const reset = react.useCallback(() => {
+    connectGenRef.current++;
+    setIsConnecting(false);
+    connect.clearSelectedProviderId();
+  }, []);
   const disconnect = react.useCallback(
     (callback) => {
       localStorage.removeItem(LOCAL_STORAGE_STACKS);
@@ -359,6 +406,14 @@ var StacksWalletProvider = ({
     },
     connect: connect$1
   });
+  const walletInfos = react.useMemo(() => {
+    const { installed } = getStacksWallets();
+    const configured = wallets ?? [...SUPPORTED_STACKS_WALLETS];
+    return configured.map((w) => ({
+      id: w,
+      available: w === "wallet-connect" ? !!walletConnect?.projectId : installed.includes(w)
+    }));
+  }, [walletsKey, walletConnect?.projectId]);
   const value = react.useMemo(() => {
     const walletState = isConnecting ? { status: "connecting", address: void 0, provider: void 0 } : address && provider ? { status: "connected", address, provider } : {
       status: "disconnected",
@@ -368,9 +423,11 @@ var StacksWalletProvider = ({
     return {
       ...walletState,
       connect: connect$1,
-      disconnect
+      disconnect,
+      reset,
+      wallets: walletInfos
     };
-  }, [address, provider, isConnecting, connect$1, disconnect]);
+  }, [address, provider, isConnecting, connect$1, disconnect, reset, walletInfos]);
   return /* @__PURE__ */ jsxRuntime.jsx(StacksWalletContext.Provider, { value, children });
 };
 var useStacksWalletContext = () => {
@@ -404,37 +461,108 @@ var useAddress = () => {
   }, [address, status, provider]);
 };
 var useConnect = () => {
-  const { connect, status } = useStacksWalletContext();
+  const {
+    connect: contextConnect,
+    reset: contextReset,
+    status: walletStatus
+  } = useStacksWalletContext();
+  const [error, setError] = react.useState(null);
+  const [mutationStatus, setMutationStatus] = react.useState("idle");
+  const connect = react.useCallback(
+    async (providerId, options) => {
+      setError(null);
+      setMutationStatus("pending");
+      let settled = false;
+      try {
+        await contextConnect(providerId, {
+          onSuccess: (address, provider) => {
+            settled = true;
+            setMutationStatus("success");
+            options?.onSuccess?.(address, provider);
+          },
+          onError: (err) => {
+            settled = true;
+            setError(err);
+            setMutationStatus("error");
+            options?.onError?.(err);
+          }
+        });
+      } finally {
+        if (!settled) {
+          setMutationStatus("idle");
+        }
+      }
+    },
+    [contextConnect]
+  );
+  const reset = react.useCallback(() => {
+    setError(null);
+    setMutationStatus("idle");
+    contextReset();
+  }, [contextReset]);
   const value = react.useMemo(
     () => ({
       connect,
-      connectors: SUPPORTED_STACKS_WALLETS,
-      isPending: status === "connecting"
+      reset,
+      error,
+      isError: mutationStatus === "error",
+      isIdle: mutationStatus === "idle",
+      isPending: mutationStatus === "pending" || walletStatus === "connecting",
+      isSuccess: mutationStatus === "success",
+      status: mutationStatus
     }),
-    [connect, status]
+    [connect, reset, error, mutationStatus, walletStatus]
   );
   return value;
 };
 var useDisconnect = () => {
-  const { disconnect } = useStacksWalletContext();
-  return react.useMemo(
+  const { disconnect: contextDisconnect } = useStacksWalletContext();
+  const [error, setError] = react.useState(null);
+  const [mutationStatus, setMutationStatus] = react.useState("idle");
+  const disconnect = react.useCallback(
+    (callback) => {
+      setError(null);
+      try {
+        contextDisconnect(callback);
+        setMutationStatus("success");
+      } catch (err) {
+        const normalizedError = err instanceof Error ? err : new Error(String(err));
+        setError(normalizedError);
+        setMutationStatus("error");
+      }
+    },
+    [contextDisconnect]
+  );
+  const reset = react.useCallback(() => {
+    setError(null);
+    setMutationStatus("idle");
+  }, []);
+  const value = react.useMemo(
     () => ({
-      disconnect
+      disconnect,
+      reset,
+      error,
+      isError: mutationStatus === "error",
+      isIdle: mutationStatus === "idle",
+      isPending: mutationStatus === "pending",
+      isSuccess: mutationStatus === "success",
+      status: mutationStatus
     }),
-    [disconnect]
+    [disconnect, reset, error, mutationStatus]
   );
+  return value;
 };
 var useSignMessage = () => {
   const { isConnected, provider } = useAddress();
   const [data, setData] = react.useState(void 0);
   const [error, setError] = react.useState(null);
-  const [isPending, setIsPending] = react.useState(false);
+  const [status, setStatus] = react.useState("idle");
   const signMessageAsync = react.useCallback(
     async (variables) => {
       if (!isConnected) {
         throw new Error("Wallet is not connected");
       }
-      setIsPending(true);
+      setStatus("pending");
       setError(null);
       setData(void 0);
       try {
@@ -455,12 +583,12 @@ var useSignMessage = () => {
           });
         }
         setData(result);
-        setIsPending(false);
+        setStatus("success");
         return result;
       } catch (err) {
         const error2 = err instanceof Error ? err : new Error(String(err));
         setError(error2);
-        setIsPending(false);
+        setStatus("error");
         throw error2;
       }
     },
@@ -478,13 +606,26 @@ var useSignMessage = () => {
     },
     [signMessageAsync]
   );
-  return {
-    signMessage,
-    signMessageAsync,
-    data,
-    error,
-    isPending
-  };
+  const reset = react.useCallback(() => {
+    setData(void 0);
+    setError(null);
+    setStatus("idle");
+  }, []);
+  return react.useMemo(
+    () => ({
+      signMessage,
+      signMessageAsync,
+      reset,
+      data,
+      error,
+      isError: status === "error",
+      isIdle: status === "idle",
+      isPending: status === "pending",
+      isSuccess: status === "success",
+      status
+    }),
+    [signMessage, signMessageAsync, reset, data, error, status]
+  );
 };
 
 // src/utils/get-network-from-address.ts
@@ -505,13 +646,13 @@ var useWriteContract = () => {
   const { isConnected, address, provider } = useAddress();
   const [data, setData] = react.useState(void 0);
   const [error, setError] = react.useState(null);
-  const [isPending, setIsPending] = react.useState(false);
+  const [status, setStatus] = react.useState("idle");
   const writeContractAsync = react.useCallback(
     async (variables) => {
       if (!isConnected || !address) {
         throw new Error("Wallet is not connected");
       }
-      setIsPending(true);
+      setStatus("pending");
       setError(null);
       setData(void 0);
       try {
@@ -533,7 +674,7 @@ var useWriteContract = () => {
             anchorMode: 3
           });
           setData(response2.txHash);
-          setIsPending(false);
+          setStatus("success");
           return response2.txHash;
         }
         const response = await connect.request("stx_callContract", {
@@ -549,12 +690,12 @@ var useWriteContract = () => {
           throw new Error("No transaction ID returned");
         }
         setData(response.txid);
-        setIsPending(false);
+        setStatus("success");
         return response.txid;
       } catch (err) {
         const error2 = err instanceof Error ? err : new Error(String(err));
         setError(error2);
-        setIsPending(false);
+        setStatus("error");
         throw error2;
       }
     },
@@ -572,13 +713,26 @@ var useWriteContract = () => {
     },
     [writeContractAsync]
   );
-  return {
-    writeContract,
-    writeContractAsync,
-    data,
-    error,
-    isPending
-  };
+  const reset = react.useCallback(() => {
+    setData(void 0);
+    setError(null);
+    setStatus("idle");
+  }, []);
+  return react.useMemo(
+    () => ({
+      writeContract,
+      writeContractAsync,
+      reset,
+      data,
+      error,
+      isError: status === "error",
+      isIdle: status === "idle",
+      isPending: status === "pending",
+      isSuccess: status === "success",
+      status
+    }),
+    [writeContract, writeContractAsync, reset, data, error, status]
+  );
 };
 var useBnsName = (address) => {
   const [bnsName, setBnsName] = react.useState(null);
@@ -606,6 +760,10 @@ var useBnsName = (address) => {
   }, [address]);
   return { bnsName, isLoading };
 };
+var useWallets = () => {
+  const { wallets } = useStacksWalletContext();
+  return react.useMemo(() => ({ wallets }), [wallets]);
+};
 
 exports.SUPPORTED_STACKS_WALLETS = SUPPORTED_STACKS_WALLETS;
 exports.StacksWalletProvider = StacksWalletProvider;
@@ -617,6 +775,7 @@ exports.useBnsName = useBnsName;
 exports.useConnect = useConnect;
 exports.useDisconnect = useDisconnect;
 exports.useSignMessage = useSignMessage;
+exports.useWallets = useWallets;
 exports.useWriteContract = useWriteContract;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map