@horus-wallet/sdk-react 0.1.0-beta.2 → 0.3.0-beta.1

package/dist/connect.d.cts

@@ -0,0 +1,155 @@
+/**
+ * `useConnectWallet()` — connect a user's external wallet (MetaMask
+ * or any EIP-1193-compatible injected provider).
+ *
+ *   import { useConnectWallet } from '@horus-wallet/sdk-react/connect';
+ *
+ *   const { connect, disconnect, wallet, available } = useConnectWallet();
+ *
+ *   // In a click handler:
+ *   const w = await connect();
+ *   // → { address: '0xabc…', chainId: 1, provider: <EIP-1193> }
+ *
+ * Separate from the embedded-wallet hooks: this surface NEVER touches
+ * Horus's backend. The user's private key stays in their wallet
+ * extension; Horus never sees it. The hook just gives partners a
+ * unified way to surface "Connect" / "Switch" / "Sign with MetaMask"
+ * alongside their embedded-wallet flow.
+ *
+ * Lives in the `/connect` sub-entrypoint so partners who only use
+ * embedded wallets don't pay the bundle cost for EIP-1193 plumbing.
+ *
+ * v1 scope: injected providers only (`window.ethereum`). v2 will add
+ * WalletConnect via its own peer dep (large enough to warrant its own
+ * opt-in).
+ */
+/**
+ * EIP-1193 provider — the minimal surface we depend on. Defining it
+ * locally keeps the SDK free of an `ethers` / `viem` peer-dep just for
+ * type signatures. Partners can cast `provider` to ethers' or viem's
+ * provider type on the way out.
+ */
+interface Eip1193Provider {
+    request: (args: {
+        method: string;
+        params?: unknown[] | object;
+    }) => Promise<unknown>;
+    on?: (eventName: string, handler: (...args: any[]) => void) => void;
+    removeListener?: (eventName: string, handler: (...args: any[]) => void) => void;
+    isMetaMask?: boolean;
+    isCoinbaseWallet?: boolean;
+    isRabby?: boolean;
+    isBraveWallet?: boolean;
+}
+interface ConnectedExternalWallet {
+    /** EVM address (`0x…`, 40 hex chars). */
+    address: string;
+    /** Chain ID as a base-10 number (e.g., 1 for Ethereum mainnet). */
+    chainId: number;
+    /** Best-effort wallet brand name based on injected provider flags. */
+    walletName: string;
+    /** The raw EIP-1193 provider, passable to ethers / viem signers. */
+    provider: Eip1193Provider;
+}
+interface UseConnectWalletResult {
+    /**
+     * Currently-connected wallet, or `null` if the user hasn't connected
+     * (or has disconnected via their wallet UI).
+     */
+    wallet: ConnectedExternalWallet | null;
+    /** True while a `connect()` call is in flight. */
+    pending: boolean;
+    /** Last error from a connect/disconnect attempt. */
+    error: Error | undefined;
+    /** True if an EIP-1193 provider is detected on the page. */
+    available: boolean;
+    /** Prompt the user to connect their injected wallet. */
+    connect: () => Promise<ConnectedExternalWallet>;
+    /** Forget the current connection (does NOT log the user out of their wallet extension). */
+    disconnect: () => void;
+}
+declare function useConnectWallet(): UseConnectWalletResult;
+
+/**
+ * `useExternalSignMessage()` / `useExternalSignTypedData()` /
+ * `useExternalSendTransaction()` — signing helpers for external
+ * (EIP-1193) wallets connected via `useConnectWallet`.
+ *
+ * Separate from the embedded-wallet hooks because the dispatch model
+ * is fundamentally different: external wallets sign in the browser
+ * (no backend round-trip, no Bearer auth), while embedded wallets are
+ * signed by the Horus backend.
+ *
+ * Pattern:
+ *
+ *   import {
+ *     useConnectWallet,
+ *     useExternalSignMessage,
+ *   } from '@horus-wallet/sdk-react/connect';
+ *
+ *   const { wallet, connect } = useConnectWallet();
+ *   const { signMessage } = useExternalSignMessage();
+ *
+ *   const sig = await signMessage(wallet ?? await connect(), 'hello');
+ *
+ * Why a `wallet` parameter on every call instead of context state:
+ * partners often need to sign with a SPECIFIC wallet (the user might
+ * have multiple injected providers, e.g. MetaMask + Coinbase Wallet in
+ * the same browser). Forcing the wallet through the call site keeps
+ * intent explicit and avoids the "active wallet leaked into the
+ * wrong sign" footgun.
+ */
+
+interface UseExternalSignMessageResult {
+    signMessage: (wallet: ConnectedExternalWallet, message: string) => Promise<string>;
+    pending: boolean;
+    error: Error | undefined;
+}
+declare function useExternalSignMessage(): UseExternalSignMessageResult;
+/**
+ * EIP-712 typed-data signing via the external wallet. The wallet pops
+ * its own confirmation UI showing the typed-data fields; we don't
+ * render anything in the partner page.
+ */
+interface UseExternalSignTypedDataResult {
+    signTypedData: (wallet: ConnectedExternalWallet, typedData: {
+        domain: Record<string, unknown>;
+        types: Record<string, Array<{
+            name: string;
+            type: string;
+        }>>;
+        primaryType?: string;
+        message: Record<string, unknown>;
+    }) => Promise<string>;
+    pending: boolean;
+    error: Error | undefined;
+}
+declare function useExternalSignTypedData(): UseExternalSignTypedDataResult;
+/**
+ * Send a transaction from the external wallet. The wallet broadcasts
+ * via its own RPC and returns the tx hash. Confirmation polling is
+ * the partner's job — same as `useSendTransaction` for embedded.
+ */
+interface ExternalTx {
+    to: string;
+    value?: string;
+    data?: string;
+    gas?: string;
+    /**
+     * Optional — if the external wallet is on the wrong chain, the
+     * partner can pass the target chainId here and the hook will request
+     * a switchEthereumChain before sending. The hook does NOT auto-add
+     * unknown chains; if the wallet rejects the switch, the call throws.
+     */
+    chainId?: number;
+}
+interface UseExternalSendTransactionResult {
+    sendTransaction: (wallet: ConnectedExternalWallet, tx: ExternalTx) => Promise<{
+        hash: string;
+    }>;
+    pending: boolean;
+    error: Error | undefined;
+}
+declare function useExternalSendTransaction(): UseExternalSendTransactionResult;
+
+export { type ConnectedExternalWallet, type Eip1193Provider, useConnectWallet, useExternalSendTransaction, useExternalSignMessage, useExternalSignTypedData };

package/dist/connect.d.ts

@@ -0,0 +1,155 @@
+/**
+ * `useConnectWallet()` — connect a user's external wallet (MetaMask
+ * or any EIP-1193-compatible injected provider).
+ *
+ *   import { useConnectWallet } from '@horus-wallet/sdk-react/connect';
+ *
+ *   const { connect, disconnect, wallet, available } = useConnectWallet();
+ *
+ *   // In a click handler:
+ *   const w = await connect();
+ *   // → { address: '0xabc…', chainId: 1, provider: <EIP-1193> }
+ *
+ * Separate from the embedded-wallet hooks: this surface NEVER touches
+ * Horus's backend. The user's private key stays in their wallet
+ * extension; Horus never sees it. The hook just gives partners a
+ * unified way to surface "Connect" / "Switch" / "Sign with MetaMask"
+ * alongside their embedded-wallet flow.
+ *
+ * Lives in the `/connect` sub-entrypoint so partners who only use
+ * embedded wallets don't pay the bundle cost for EIP-1193 plumbing.
+ *
+ * v1 scope: injected providers only (`window.ethereum`). v2 will add
+ * WalletConnect via its own peer dep (large enough to warrant its own
+ * opt-in).
+ */
+/**
+ * EIP-1193 provider — the minimal surface we depend on. Defining it
+ * locally keeps the SDK free of an `ethers` / `viem` peer-dep just for
+ * type signatures. Partners can cast `provider` to ethers' or viem's
+ * provider type on the way out.
+ */
+interface Eip1193Provider {
+    request: (args: {
+        method: string;
+        params?: unknown[] | object;
+    }) => Promise<unknown>;
+    on?: (eventName: string, handler: (...args: any[]) => void) => void;
+    removeListener?: (eventName: string, handler: (...args: any[]) => void) => void;
+    isMetaMask?: boolean;
+    isCoinbaseWallet?: boolean;
+    isRabby?: boolean;
+    isBraveWallet?: boolean;
+}
+interface ConnectedExternalWallet {
+    /** EVM address (`0x…`, 40 hex chars). */
+    address: string;
+    /** Chain ID as a base-10 number (e.g., 1 for Ethereum mainnet). */
+    chainId: number;
+    /** Best-effort wallet brand name based on injected provider flags. */
+    walletName: string;
+    /** The raw EIP-1193 provider, passable to ethers / viem signers. */
+    provider: Eip1193Provider;
+}
+interface UseConnectWalletResult {
+    /**
+     * Currently-connected wallet, or `null` if the user hasn't connected
+     * (or has disconnected via their wallet UI).
+     */
+    wallet: ConnectedExternalWallet | null;
+    /** True while a `connect()` call is in flight. */
+    pending: boolean;
+    /** Last error from a connect/disconnect attempt. */
+    error: Error | undefined;
+    /** True if an EIP-1193 provider is detected on the page. */
+    available: boolean;
+    /** Prompt the user to connect their injected wallet. */
+    connect: () => Promise<ConnectedExternalWallet>;
+    /** Forget the current connection (does NOT log the user out of their wallet extension). */
+    disconnect: () => void;
+}
+declare function useConnectWallet(): UseConnectWalletResult;
+
+/**
+ * `useExternalSignMessage()` / `useExternalSignTypedData()` /
+ * `useExternalSendTransaction()` — signing helpers for external
+ * (EIP-1193) wallets connected via `useConnectWallet`.
+ *
+ * Separate from the embedded-wallet hooks because the dispatch model
+ * is fundamentally different: external wallets sign in the browser
+ * (no backend round-trip, no Bearer auth), while embedded wallets are
+ * signed by the Horus backend.
+ *
+ * Pattern:
+ *
+ *   import {
+ *     useConnectWallet,
+ *     useExternalSignMessage,
+ *   } from '@horus-wallet/sdk-react/connect';
+ *
+ *   const { wallet, connect } = useConnectWallet();
+ *   const { signMessage } = useExternalSignMessage();
+ *
+ *   const sig = await signMessage(wallet ?? await connect(), 'hello');
+ *
+ * Why a `wallet` parameter on every call instead of context state:
+ * partners often need to sign with a SPECIFIC wallet (the user might
+ * have multiple injected providers, e.g. MetaMask + Coinbase Wallet in
+ * the same browser). Forcing the wallet through the call site keeps
+ * intent explicit and avoids the "active wallet leaked into the
+ * wrong sign" footgun.
+ */
+
+interface UseExternalSignMessageResult {
+    signMessage: (wallet: ConnectedExternalWallet, message: string) => Promise<string>;
+    pending: boolean;
+    error: Error | undefined;
+}
+declare function useExternalSignMessage(): UseExternalSignMessageResult;
+/**
+ * EIP-712 typed-data signing via the external wallet. The wallet pops
+ * its own confirmation UI showing the typed-data fields; we don't
+ * render anything in the partner page.
+ */
+interface UseExternalSignTypedDataResult {
+    signTypedData: (wallet: ConnectedExternalWallet, typedData: {
+        domain: Record<string, unknown>;
+        types: Record<string, Array<{
+            name: string;
+            type: string;
+        }>>;
+        primaryType?: string;
+        message: Record<string, unknown>;
+    }) => Promise<string>;
+    pending: boolean;
+    error: Error | undefined;
+}
+declare function useExternalSignTypedData(): UseExternalSignTypedDataResult;
+/**
+ * Send a transaction from the external wallet. The wallet broadcasts
+ * via its own RPC and returns the tx hash. Confirmation polling is
+ * the partner's job — same as `useSendTransaction` for embedded.
+ */
+interface ExternalTx {
+    to: string;
+    value?: string;
+    data?: string;
+    gas?: string;
+    /**
+     * Optional — if the external wallet is on the wrong chain, the
+     * partner can pass the target chainId here and the hook will request
+     * a switchEthereumChain before sending. The hook does NOT auto-add
+     * unknown chains; if the wallet rejects the switch, the call throws.
+     */
+    chainId?: number;
+}
+interface UseExternalSendTransactionResult {
+    sendTransaction: (wallet: ConnectedExternalWallet, tx: ExternalTx) => Promise<{
+        hash: string;
+    }>;
+    pending: boolean;
+    error: Error | undefined;
+}
+declare function useExternalSendTransaction(): UseExternalSendTransactionResult;
+
+export { type ConnectedExternalWallet, type Eip1193Provider, useConnectWallet, useExternalSendTransaction, useExternalSignMessage, useExternalSignTypedData };

package/dist/connect.js

@@ -0,0 +1,188 @@
+// src/connect/useConnectWallet.ts
+import { useCallback, useEffect, useState } from "react";
+function detectProvider() {
+  if (typeof window === "undefined") return null;
+  const provider = window.ethereum;
+  return provider ?? null;
+}
+function nameFor(provider) {
+  if (provider.isMetaMask) return "MetaMask";
+  if (provider.isCoinbaseWallet) return "Coinbase Wallet";
+  if (provider.isRabby) return "Rabby";
+  if (provider.isBraveWallet) return "Brave Wallet";
+  return "Injected Wallet";
+}
+function useConnectWallet() {
+  const [wallet, setWallet] = useState(null);
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState(void 0);
+  const [available, setAvailable] = useState(false);
+  useEffect(() => {
+    setAvailable(detectProvider() !== null);
+  }, []);
+  useEffect(() => {
+    const provider = detectProvider();
+    if (!provider || !provider.on) return;
+    const onAccountsChanged = (accounts) => {
+      if (!accounts || accounts.length === 0) {
+        setWallet(null);
+        return;
+      }
+      setWallet((prev) => prev ? { ...prev, address: accounts[0] } : prev);
+    };
+    const onChainChanged = (chainIdHex) => {
+      const chainId = Number(chainIdHex);
+      if (!Number.isFinite(chainId)) return;
+      setWallet((prev) => prev ? { ...prev, chainId } : prev);
+    };
+    provider.on("accountsChanged", onAccountsChanged);
+    provider.on("chainChanged", onChainChanged);
+    return () => {
+      provider.removeListener?.("accountsChanged", onAccountsChanged);
+      provider.removeListener?.("chainChanged", onChainChanged);
+    };
+  }, []);
+  const connect = useCallback(async () => {
+    const provider = detectProvider();
+    if (!provider) {
+      const err = new Error(
+        "No injected wallet provider detected. Install MetaMask (or similar) and reload."
+      );
+      setError(err);
+      throw err;
+    }
+    setPending(true);
+    setError(void 0);
+    try {
+      const accounts = await provider.request({
+        method: "eth_requestAccounts"
+      });
+      if (!accounts || accounts.length === 0) {
+        throw new Error("No accounts returned from wallet.");
+      }
+      const chainIdHex = await provider.request({
+        method: "eth_chainId"
+      });
+      const chainId = Number(chainIdHex);
+      const next = {
+        address: accounts[0],
+        chainId: Number.isFinite(chainId) ? chainId : 0,
+        walletName: nameFor(provider),
+        provider
+      };
+      setWallet(next);
+      return next;
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      setError(e);
+      throw e;
+    } finally {
+      setPending(false);
+    }
+  }, []);
+  const disconnect = useCallback(() => {
+    setWallet(null);
+  }, []);
+  return { wallet, pending, error, available, connect, disconnect };
+}
+
+// src/connect/useExternalSign.ts
+import { useCallback as useCallback2, useState as useState2 } from "react";
+function useExternalSignMessage() {
+  const [pending, setPending] = useState2(false);
+  const [error, setError] = useState2(void 0);
+  const signMessage = useCallback2(
+    async (wallet, message) => {
+      setPending(true);
+      setError(void 0);
+      try {
+        const sig = await wallet.provider.request({
+          method: "personal_sign",
+          params: [message, wallet.address]
+        });
+        return sig;
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setPending(false);
+      }
+    },
+    []
+  );
+  return { signMessage, pending, error };
+}
+function useExternalSignTypedData() {
+  const [pending, setPending] = useState2(false);
+  const [error, setError] = useState2(void 0);
+  const signTypedData = useCallback2(
+    async (wallet, typedData) => {
+      setPending(true);
+      setError(void 0);
+      try {
+        const sig = await wallet.provider.request({
+          method: "eth_signTypedData_v4",
+          params: [wallet.address, JSON.stringify(typedData)]
+        });
+        return sig;
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setPending(false);
+      }
+    },
+    []
+  );
+  return { signTypedData, pending, error };
+}
+function useExternalSendTransaction() {
+  const [pending, setPending] = useState2(false);
+  const [error, setError] = useState2(void 0);
+  const sendTransaction = useCallback2(
+    async (wallet, tx) => {
+      setPending(true);
+      setError(void 0);
+      try {
+        if (tx.chainId && tx.chainId !== wallet.chainId) {
+          await wallet.provider.request({
+            method: "wallet_switchEthereumChain",
+            params: [{ chainId: `0x${tx.chainId.toString(16)}` }]
+          });
+        }
+        const params = {
+          from: wallet.address,
+          to: tx.to
+        };
+        if (tx.value !== void 0) params.value = toHex(tx.value);
+        if (tx.data !== void 0) params.data = tx.data;
+        if (tx.gas !== void 0) params.gas = toHex(tx.gas);
+        const hash = await wallet.provider.request({
+          method: "eth_sendTransaction",
+          params: [params]
+        });
+        return { hash };
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setPending(false);
+      }
+    },
+    []
+  );
+  return { sendTransaction, pending, error };
+}
+function toHex(v) {
+  if (v.startsWith("0x")) return v;
+  return `0x${BigInt(v).toString(16)}`;
+}
+export {
+  useConnectWallet,
+  useExternalSendTransaction,
+  useExternalSignMessage,
+  useExternalSignTypedData
+};