@dogeos/dogeos-sdk 3.0.7 → 3.0.9-beta.0

package/README.md

@@ -1,59 +1,51 @@
-# dogeos-sdk
+# Wallet Connect Kit
 
-A lightweight React SDK for integrating crypto wallet connections into your app. It ships with a configurable wallet list modal and basic account actions. Currently focused on EVM chains, built on top of `@tomo-inc/wallet-adaptor-base`, and supports custom wallets and chain configuration.
+A lightweight React SDK for integrating crypto wallet connection functionality into your applications. It provides a configurable wallet list modal and basic account operations.
 
-## On This Page
+## Requirements
 
-- [Installation](#installation)
-- [Setup Provider](#setup-provider)
-- [Displaying the Modal](#displaying-the-modal)
-- [Account Actions](#account-actions)
-- [Additional Reference](#additional-reference)
-
----
+- React 18 or higher
+- TypeScript 5 or higher (recommended)
 
 ## Installation
 
+Install Wallet Connect Kit using your preferred package manager:
+
 ```bash
 npm install @dogeos/dogeos-sdk
-
 ```
 
-Or using yarn:
+```bash
+pnpm add @dogeos/dogeos-sdk
+```
 
 ```bash
 yarn add @dogeos/dogeos-sdk
-
 ```
 
-Or using pnpm:
+### Dependencies
 
-```bash
-pnpm add @dogeos/dogeos-sdk
+Wallet Connect Kit requires the following peer dependencies:
 
-```
+- `react >= 18`
+- `react-dom >= 18`
+- `wagmi >= 2.0.0` (optional, if using WagmiProvider)
 
----
+## Quick Start
 
-## Setup Provider
+### 0. Prerequisites
 
-### Use React
+This guide assumes you have already installed Wallet Connect Kit. If you haven't, please refer to the installation steps above.
 
-Wrap your app with `WalletConnectProvider` at the root component.
+### 1. Setup Provider
+
+First, wrap your app root component with `WalletConnectProvider`:
 
 ```tsx
 // App.tsx
+// App.tsx
 import React from "react";
 import { WalletConnectProvider } from "@dogeos/dogeos-sdk";
-import type { WalletConfig, WalletConnectKitConfig, WalletConnectProtocolConfig, clientId } from "@dogeos/dogeos-sdk"
-
-const config = {
-  connectors?: WalletConfig[];
-  // Supported chains (for EVM, compatible with viem/Chain)
-  chains?: Partial<Record<ChainType, EvmChain[] | any[]>>;
-  walletConnectConfig?: WalletConnectProtocolConfig;
-  clientId?: string;
-} as WalletConnectConfig;
 
 export default function App() {
   return (
@@ -64,157 +56,358 @@ export default function App() {
 }
 ```
 
-Embedded Wallet Evm Provider Method
+### 2. Connect Wallet
 
-support：
+Use the `useWalletConnect` hook to open the wallet connection modal and manage connection state:
 
-```
-// methods
-connect;
-disconnect;
-getChainId;
-switchChain;
-signMessage(siweSign);
-signTypedData;
-eth_signTransaction;
-sendTransaction;
-```
+```tsx
+// ConnectButton.tsx
+import React from "react";
+import { useWalletConnect } from "@dogeos/dogeos-sdk";
+import { useWalletConnect } from "@dogeos/dogeos-sdk";
 
--[MateMask Provider Doc](#https://docs.metamask.io/wallet/reference/provider-api/)
+export function ConnectButton() {
+  const { openModal, isConnected, disconnect, isConnecting } =
+    useWalletConnect();
 
----
+  if (isConnecting) {
+    return <button disabled>Connecting...</button>;
+  }
 
-## Displaying the Modal
+  return (
+    <button onClick={() => (isConnected ? disconnect() : openModal())}>
+      {isConnected ? "Disconnect" : "Connect Wallet"}
+    </button>
+  );
+}
+```
 
-To display the modal for wallet connection, you can use the hooks provided by **dogeos-sdk**.
+### 3. Read Account Information
 
-### Example Code
+Use the `useAccount` hook to get the currently connected account information:
 
 ```tsx
+// AccountInfo.tsx
 import React from "react";
-import { useWalletConnect } from "@dogeos/dogeos-sdk";
+import { useAccount } from "@dogeos/dogeos-sdk";
+import { useAccount } from "@dogeos/dogeos-sdk";
 
-const ConnectButton = () => {
-  const { openModal, isConnected, disconnect } = useWalletConnect();
+export function AccountInfo() {
+  const { address, chainId, chainType, currentWallet } = useAccount();
+
+  if (!address) {
+    return <div>No wallet connected</div>;
+  }
 
   return (
-    <button onClick={() => (isConnected ? disconnect() : openModal())}>
-      {isConnected ? "Disconnect" : "Connect Wallet"}
-    </button>
+    <div>
+      <div>Address: {address}</div>
+      <div>Chain ID: {chainId}</div>
+      <div>Chain Type: {chainType}</div>
+      <div>Wallet: {currentWallet?.info?.name}</div>
+    </div>
   );
-};
-
-export default ConnectButton;
+}
 ```
 
-### MyDoge Social Login Experience
+### 4. Sign Message
 
-When using the MyDoge theme, the modal will first display the social login interface, supporting:
+Use the `signMessage` method from the `useAccount` hook to sign messages:
 
-- **Twitter Login** - Quick login with Twitter/X account
-- **Google Login** - Quick login with Google account
-- **Email Login** - Login with email address
+```tsx
+// SignMessageButton.tsx
+import React from "react";
+import { useAccount } from "@dogeos/dogeos-sdk";
 
-Users can also select "Or connect a wallet" to directly connect traditional crypto wallets.
+export function SignMessageButton() {
+  const { signMessage, address } = useAccount();
+
+  const handleSignMessage = async () => {
+    if (!signMessage) {
+      console.error("Signing functionality not available");
+      return;
+    }
+
+    try {
+      const signature = await signMessage({
+        message: "Hello Tomo Wallet",
+      });
+      console.log("Signature result:", signature);
+    } catch (error) {
+      console.error("Signing failed:", error);
+    }
+  };
 
----
+  if (!address) {
+    return null;
+  }
 
-## Account Actions
+  return <button onClick={handleSignMessage}>Sign Message</button>;
+}
+```
 
-### Reading Account Info and Signing
+### 5. Sign In with Wallet (SIW)
 
-After connecting a wallet, you can use the `useAccount` hook to access account information and perform signing operations.
+Use the `signInWithWallet` method to sign in with wallet and obtain an authentication token:
 
 ```tsx
+// SignInButton.tsx
 import React from "react";
 import { useAccount } from "@dogeos/dogeos-sdk";
 
-export function AccountInfo() {
-  const { address, chainId, signMessage, signInWithWallet } = useAccount();
-
-  const onSignMessage = async () => {
-    // Message signing for verification
-    const sig = await signMessage?.({ message: "Hello MyDoge" });
-    console.log("signature:", sig);
+export function SignInButton() {
+  const { signInWithWallet, address } = useAccount();
+
+  const handleSignIn = async () => {
+    try {
+      const token = await signInWithWallet();
+      console.log("Authentication token:", token);
+      // Save token to localStorage or send to backend
+    } catch (error) {
+      console.error("Sign in failed:", error);
+    }
   };
 
-  const onSignin = async () => {
-    // Sign in with wallet to get a token
-    const token = await signInWithWallet();
-    console.log("token:", token);
-  };
+  if (!address) {
+    return null;
+  }
 
+  return <button onClick={handleSignIn}>Sign In with Wallet</button>;
+}
+```
+
+## Configuration
+
+`WalletConnectProvider` accepts an optional `config` prop to customize the SDK's behavior.
+
+### Basic Configuration
+
+```tsx
+import { WalletConnectProvider } from "@dogeos/dogeos-sdk";
+import type { WalletConnectKitConfig } from "@dogeos/dogeos-sdk";
+
+const config: WalletConnectKitConfig = {
+  // WalletConnect project ID (obtain from https://cloud.walletconnect.com)
+  walletConnectProjectId: "your-project-id",
+
+  // Application metadata
+  metadata: {
+    name: "My DApp",
+    description: "My decentralized application",
+    url: "https://myapp.com",
+    icons: ["https://myapp.com/icon.png"],
+  },
+};
+
+export function App() {
   return (
-    <div>
-      <div>Address: {address}</div>
-      <div>Chain ID: {chainId}</div>
-      <button onClick={onSignMessage}>Sign Message</button>
-      <button onClick={onSignin}>Sign In With Wallet</button>
-    </div>
+    <WalletConnectProvider config={config}>
+      <YourApp />
+    </WalletConnectProvider>
   );
 }
 ```
 
-### Available Account Actions
+### Configure Supported Chains
 
-- **address** - Current connected wallet address
-- **chainId** - Current connected chain ID
-- **balance** - Account balance
-- **chainType** - Chain type (e.g., "evm")
-- **currentWallet** - Current wallet information
-- **currentProvider** - Current wallet provider
-- **switchChain** - Switch network
-- **signMessage** - Sign message
-- **signInWithWallet** - Sign in with wallet
+Chains are automatically loaded by default. If you need to customize chains, use the `getChains()` method:
 
----
+```tsx
+import { WalletConnectProvider, getChains } from "@dogeos/dogeos-sdk";
+import { useEffect, useState } from "react";
 
-## Additional Reference
+export function App() {
+  const [chains, setChains] = useState<
+    Awaited<ReturnType<typeof getChains>> | undefined
+  >(undefined);
 
-### SDK Exports
+  useEffect(() => {
+    getChains().then(setChains);
+  }, []);
 
-The SDK provides the following main exports:
+  return (
+    <WalletConnectProvider config={{ chains }}>
+      <YourApp />
+    </WalletConnectProvider>
+  );
+}
+```
 
-- **WalletConnectProvider** - Main provider component with optional `config` prop
-- **useWalletConnect** - Hook for modal control and connection state
-  - `{ isOpenModal, openModal, closeModal, isConnected, isConnecting, error, connect, disconnect }`
-- **useAccount** - Hook for account info and actions
-  - `{ address, balance, chainType, chainId, currentWallet, currentProvider, switchChain, signMessage, signInWithWallet }`
-- **Type Definitions**: `WalletConnectConfig`, `Chain`, `WalletProvider`, `UseAccount`, `UseWalletConnect`, `ChainType`, `ModalView`
+### Configure Custom Wallets
 
-### Complete Example
+Connectors are automatically loaded by default. If you need to customize connectors, use the `getConnectors()` method:
 
 ```tsx
-import React from "react";
-import {
-  WalletConnectProvider,
-  useWalletConnect,
-  useAccount,
-} from "@dogeos/dogeos-sdk";
+import { WalletConnectProvider, getConnectors } from "@dogeos/dogeos-sdk";
+import { useEffect, useState } from "react";
 
-// Connect Button Component
-function ConnectButton() {
-  const { openModal, isConnected, disconnect } = useWalletConnect();
-  const { address } = useAccount();
+export function App() {
+  const [connectors, setConnectors] = useState<
+    Awaited<ReturnType<typeof getConnectors>> | undefined
+  >(undefined);
 
-  if (isConnected && address) {
-    return (
-      <div>
-        <p>
-          Connected: {address.slice(0, 6)}...{address.slice(-4)}
-        </p>
-        <button onClick={disconnect}>Disconnect</button>
-      </div>
-    );
-  }
+  useEffect(() => {
+    getConnectors().then(setConnectors);
+  }, []);
+
+  return (
+    <WalletConnectProvider config={{ connectors }}>
+      <YourApp />
+    </WalletConnectProvider>
+  );
+}
+```
+
+### Configure Login Options
+
+You can configure supported login methods, including basic logins (email, external wallets) and social logins (Google, X/Twitter):
+
+```tsx
+import { WalletConnectProvider } from "@dogeos/dogeos-sdk";
+
+const config = {
+  login: {
+    // Basic login methods
+    basicLogins: ["email", "externalWallets"], // or ["email"] or ["externalWallets"]
+
+    // Social login methods
+    socialLogins: [
+      {
+        type: "google",
+      },
+      {
+        type: "x",
+      },
+    ],
+  },
+};
+
+export function App() {
+  return (
+    <WalletConnectProvider config={config}>
+      <YourApp />
+    </WalletConnectProvider>
+  );
+}
+```
+
+### Configure Theme
+
+You can customize the UI theme:
+
+```tsx
+import { WalletConnectProvider } from "@dogeos/dogeos-sdk";
+import type { ThemeConfig } from "@dogeos/dogeos-sdk";
+
+const config = {
+  theme: {
+    themes: {
+      light: {
+        colors: {
+          primary: {
+            DEFAULT: "#FCD436",
+            foreground: "#FFF",
+          },
+          background: "#FFFFFF",
+          foreground: "#000000",
+        },
+      },
+      dark: {
+        colors: {
+          primary: {
+            DEFAULT: "#FF5CB8",
+            foreground: "#FFF",
+          },
+          background: "#000000",
+          foreground: "#FFFFFF",
+        },
+      },
+    },
+  } as ThemeConfig,
+};
 
-  return <button onClick={openModal}>Connect Wallet</button>;
+export function App() {
+  return (
+    <WalletConnectProvider config={config}>
+      <YourApp />
+    </WalletConnectProvider>
+  );
 }
+```
 
-// App Component
-function App() {
-  // Configuration
-  const config = {};
+### Complete Configuration Example
+
+```tsx
+import {
+  WalletConnectProvider,
+  getChains,
+  getConnectors,
+} from "@dogeos/dogeos-sdk";
+import type { WalletConnectKitConfig } from "@dogeos/dogeos-sdk";
+import { useEffect, useState } from "react";
+
+export function App() {
+  const [chains, setChains] = useState<
+    Awaited<ReturnType<typeof getChains>> | undefined
+  >(undefined);
+  const [connectors, setConnectors] = useState<
+    Awaited<ReturnType<typeof getConnectors>> | undefined
+  >(undefined);
+
+  useEffect(() => {
+    const loadConfig = async () => {
+      const [loadedChains, loadedConnectors] = await Promise.all([
+        getChains(),
+        getConnectors(),
+      ]);
+      setChains(loadedChains);
+      setConnectors(loadedConnectors);
+    };
+    loadConfig();
+  }, []);
+
+  const config: WalletConnectKitConfig = {
+    // WalletConnect configuration
+    walletConnectProjectId: "your-project-id",
+
+    // DApp application metadata
+    metadata: {
+      name: "My DApp",
+      description: "My decentralized application",
+      url: "https://myapp.com",
+      icons: ["https://myapp.com/icon.png"],
+    },
+
+    // Supported chains (must use getChains)
+    chains,
+
+    // Custom wallets (must use getConnectors)
+    connectors,
+
+    // Login configuration
+    login: {
+      basicLogins: ["email", "externalWallets"],
+      socialLogins: [{ type: "google" }, { type: "x" }],
+    },
+
+    // Theme configuration
+    theme: {
+      themes: {
+        light: {
+          colors: {
+            primary: {
+              DEFAULT: "#FCD436",
+              foreground: "#FFF",
+            },
+          },
+        },
+      },
+    },
+  };
+
+  if (!chains || !connectors) {
+    return <div>Loading configuration...</div>;
+  }
 
   return (
     <WalletConnectProvider config={config}>
@@ -225,36 +418,348 @@ function App() {
     </WalletConnectProvider>
   );
 }
+```
+
+## API Reference
+
+### WalletConnectProvider
+
+Main Provider component for wrapping your application.
 
-export default App;
+**Props:**
+
+```tsx
+interface WalletConnectProviderProps {
+  children: React.ReactNode;
+  config?: WalletConnectKitConfig;
+}
 ```
 
----
+### useWalletConnect
 
-## Support
+Hook for controlling the wallet connection modal and managing connection state.
 
-For more help or if you encounter issues, please visit:
+**Returns:**
 
-- [GitHub Issues](https://github.com/DogeOS69/mydoge-sdk)
-- [Support](support@dogeos.com)
-- [Documentation](https://docs.dogeos.com)
+```tsx
+interface UseWalletConnect {
+  // Modal control
+  isOpenModal: boolean;
+  openModal: () => void;
+  closeModal: () => void;
+
+  // Connection state
+  isConnected: boolean;
+  isConnecting: boolean;
+  error: Error | null;
+
+  // Connection operations
+  connect: (variables?: ConnectVariables) => Promise<ConnectData>;
+  disconnect: () => Promise<void>;
+}
+```
 
----
+**Example:**
 
-## FAQ
+```tsx
+const {
+  isOpenModal,
+  openModal,
+  closeModal,
+  isConnected,
+  isConnecting,
+  connect,
+  disconnect,
+} = useWalletConnect();
+```
+
+### useAccount
+
+Hook for getting the currently connected account information and performing account-related operations.
 
-1. How to use with Next.js?
+**Returns:**
 
-```js
-"use client"; // add "use client" at your index router page
+```tsx
+interface UseAccount {
+  // Account information
+  address: string;
+  balance?: string;
+  chainType?: ChainType;
+  chainId?: string;
+  currentWallet?: Connector | null;
+  currentProvider?: any;
+
+  // Operations
+  switchChain: (options: SwitchChainOptions) => Promise<boolean>;
+  signMessage?: (params: {
+    message: string;
+    nonce?: string;
+  }) => Promise<string | Uint8Array>;
+  signInWithWallet: (params?: SignInParams) => Promise<string | Uint8Array>;
+}
 ```
 
-2. Supported Next.js version
+**Example:**
+
+```tsx
+const {
+  address,
+  chainId,
+  chainType,
+  signMessage,
+  signInWithWallet,
+  switchChain,
+} = useAccount();
+```
+
+### getChains
+
+Utility function to get all available chains. Automatically fetches chains from the backend API and returns them in the config format.
+
+**Signature:**
+
+```tsx
+function getChains(): Promise<Partial<Record<ChainType, EvmChain[] | any[]>>>;
+```
+
+**Returns:**
+
+- A Promise that resolves to a chain configuration object containing all available chains
+- Automatically includes EVM, Solana, Aptos, and Dogecoin chains
+- Falls back to default chains if the API request fails
+
+**Example:**
+
+```tsx
+import { getChains } from "@dogeos/dogeos-sdk";
+import { useEffect, useState } from "react";
+
+export function MyComponent() {
+  const [chains, setChains] = useState<
+    Awaited<ReturnType<typeof getChains>> | undefined
+  >(undefined);
+
+  useEffect(() => {
+    const loadChains = async () => {
+      const allChains = await getChains();
+      setChains(allChains);
+    };
+    loadChains();
+  }, []);
+
+  // Use chains in your config
+  const config = { chains };
+}
+```
+
+## Advanced Usage
+
+### Switch Chain
+
+Use the `switchChain` method from the `useAccount` hook to switch chains:
+
+```tsx
+import { useAccount } from "@dogeos/dogeos-sdk";
+import type { Chain } from "@dogeos/dogeos-sdk";
+
+export function SwitchChainButton() {
+  const { switchChain, chainId } = useAccount();
+
+  const handleSwitchChain = async () => {
+    const targetChain: Chain = {
+      id: 137,
+      name: "Polygon",
+      nativeCurrency: {
+        name: "MATIC",
+        symbol: "MATIC",
+        decimals: 18,
+      },
+      rpcUrls: {
+        default: {
+          http: ["https://polygon-rpc.com"],
+        },
+      },
+      blockExplorers: {
+        default: {
+          name: "PolygonScan",
+          url: "https://polygonscan.com",
+        },
+      },
+    };
+
+    try {
+      const success = await switchChain({
+        chainType: "evm",
+        chainInfo: targetChain,
+      });
+
+      if (success) {
+        console.log("Chain switched successfully");
+      }
+    } catch (error) {
+      console.error("Chain switch failed:", error);
+    }
+  };
 
-- Next.js 14/15 version had supported
+  return <button onClick={handleSwitchChain}>Switch to Polygon</button>;
+}
+```
+
+### Integration with Wagmi
+
+Wallet Connect Kit can seamlessly integrate with Wagmi. If you're already using `WagmiProvider`, Wallet Connect Kit will automatically detect and use Wagmi's configuration:
+
+```tsx
+import { WagmiProvider } from "wagmi";
+import { WalletConnectProvider } from "@dogeos/dogeos-sdk";
+import { config } from "./wagmi-config";
+
+export function App() {
+  return (
+    <WagmiProvider config={config}>
+      <WalletConnectProvider>
+        <YourApp />
+      </WalletConnectProvider>
+    </WagmiProvider>
+  );
+}
+```
+
+### Error Handling
+
+Always handle errors in connections and operations:
+
+```tsx
+import { useWalletConnect, useAccount } from "@dogeos/dogeos-sdk";
+
+export function WalletComponent() {
+  const { error, isConnecting } = useWalletConnect();
+  const { signMessage } = useAccount();
+
+  const handleSign = async () => {
+    try {
+      if (!signMessage) {
+        throw new Error("Signing functionality not available");
+      }
+
+      const signature = await signMessage({ message: "Hello" });
+      console.log("Signing successful:", signature);
+    } catch (error) {
+      console.error("Signing failed:", error);
+      // Display error message to user
+    }
+  };
+
+  if (error) {
+    return <div>Error: {error.message}</div>;
+  }
+
+  if (isConnecting) {
+    return <div>Connecting...</div>;
+  }
+
+  return <button onClick={handleSign}>Sign</button>;
+}
+```
+
+## Type Definitions
+
+### WalletConnectKitConfig
+
+````tsx
+interface WalletConnectKitConfig {
+  connectors?: WalletConfig[];
+  chains?: Partial<Record<ChainType, EvmChain[] | any[]>>;
+  walletConnectProjectId?: string;
+  /**
+   * Default connect chain
+   * @default undefined
+   * @example
+   * ```tsx
+   * import { WalletConnectProvider } from "@tomo-inc/wallet-connect-kit";
+   * const config: WalletConnectKitConfig = {
+   *   defaultConnectChain: 'evm',
+   * };
+   */
+  defaultConnectChain?: ChainType;
+  metadata?: {
+    name: string;
+    description: string;
+    url: string;
+    icons: string[];
+  };
+  theme?: ThemeConfig;
+  login?: UserLoginConfig;
+}
+````
+
+### Chain
+
+```tsx
+interface Chain {
+  id: number;
+  name: string;
+  nativeCurrency: {
+    name: string;
+    symbol: string;
+    decimals: number;
+  };
+  rpcUrls: {
+    default: {
+      http: string[];
+    };
+  };
+  blockExplorers?: {
+    default: {
+      name: string;
+      url: string;
+    };
+  };
+  testnet?: boolean;
+}
+```
+
+### ChainType
+
+```tsx
+type ChainType = "evm" | "solana" | "aptos" | "dogecoin";
+```
+
+## Exports
+
+- `WalletConnectProvider` - Main Provider component
+- `useAccount` - Account information Hook
+- `useWalletConnect` - Connect Hook
+- `getChains` - Utility function to configure chains (can wrap backend API chains)
+- Types: `WalletConnectKitConfig`, `Chain`, `WalletConfig`, `UseAccount`, `ChainType`, `ModalView`, `ThemeConfig`, `UserLoginConfig`
+
+## FAQ
+
+### How to get WalletConnect Project ID?
+
+1. Visit [WalletConnect Cloud](https://cloud.walletconnect.com)
+2. Create a new project or select an existing project
+3. Copy the Project ID and use it in your configuration
+
+### How to customize chains and connectors?
+
+You can use `getChains()` and `getConnectors()` methods to customize chains and connectors:
+
+```tsx
+import { getChains, getConnectors } from "@dogeos/dogeos-sdk";
+
+// Get all available chains
+const chains = await getChains();
+
+// Get all available connectors
+const connectors = await getConnectors();
+
+// Use in config
+const config = { chains, connectors };
+```
 
----
+The `getChains()` method automatically fetches chains from the backend API and includes EVM, Solana, Aptos, and Dogecoin chains. The `getConnectors()` method loads all available connectors including EIP6963, Wallet Standard, and WalletConnect wallets.
 
-## License
+### What chain types are supported?
 
-Please check the project's LICENSE file for details.
+Currently, EVM chains are primarily supported, along with Solana, Aptos, and Dogecoin chains.