@dogeos/dogeos-sdk 2.0.4 → 3.0.0

package/README.md

@@ -1,163 +1,149 @@
-# DogeOS SDK
+# Wallet Connect SDK
 
-## Installation
-
-```bash
-npm install @dogeos/dogeos-sdk
-# or
-yarn add @dogeos/dogeos-sdk
-# or
-pnpm add @dogeos/dogeos-sdk
-```
+A lightweight React SDK to integrate crypto wallet connection into your app. It ships with a configurable wallet list modal and basic account actions. The current focus is EVM, built on top of `@tomo-inc/wallet-adaptor-base`, and supports custom wallets and chain configuration.
 
 ## Quick Start
 
-### 1. Import Styles
-
-Import the SDK styles in your app entry file:
-
-```tsx
-import "@dogeos/dogeos-sdk/styles.css";
-```
-
-### 2. Configure Wagmi
-
-Create a Wagmi configuration using `getDefaultConfig`:
-
 ```tsx
-import { getDefaultConfig } from "@dogeos/dogeos-sdk";
-import { mainnet, polygon, optimism, arbitrum, base } from "wagmi/chains";
-import { http } from "viem";
-
-const projectId = "YOUR_WALLETCONNECT_PROJECT_ID";
-const clientId = "YOUR_TOMO_CLIENT_ID";
-
-const chains = [mainnet, polygon, optimism, arbitrum, base] as const;
-
-export const config = getDefaultConfig({
-  appName: "My App",
-  projectId,
-  clientId,
-  chains,
-  transports: Object.fromEntries(chains.map((chain) => [chain.id, http()])),
-  ssr: true, // Enable server-side rendering support
-});
-```
+// App.tsx — wrap your app with provider (comments in English)
+import React from "react";
+import { WalletConnectProvider } from "@tomo-inc/wallet-connect-kit";
 
-### 3. Wrap Your App
-
-Wrap your application with the required providers:
-
-```tsx
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import { WagmiProvider } from "wagmi";
-import { DogeEVMKitProvider } from "@dogeos/dogeos-sdk";
-import { config } from "./wagmi";
-
-const queryClient = new QueryClient();
-
-function App() {
+export default function App() {
   return (
-    <WagmiProvider config={config}>
-      <QueryClientProvider client={queryClient}>
-        <DogeEVMKitProvider
-          appInfo={{
-            appName: "My App",
-          }}
-        >
-          {/* Your app content */}
-        </DogeEVMKitProvider>
-      </QueryClientProvider>
-    </WagmiProvider>
+    <WalletConnectProvider>
+      <YourApp />
+    </WalletConnectProvider>
   );
 }
 ```
 
-### 4. Add Connect Button
-
-Use the connect modal hooks in your components:
+### Open modal, connect and disconnect
 
 ```tsx
-import { useConnectModal } from "@dogeos/dogeos-sdk";
+import React from "react";
+import { useWalletConnect } from "@tomo-inc/wallet-connect-kit";
 
-function ConnectButton() {
-  const { openConnectModal } = useConnectModal();
+export function ConnectButton() {
+  const { openModal, isConnected, disconnect } = useWalletConnect();
 
-  return <button onClick={openConnectModal}>Connect Wallet</button>;
+  return (
+    <button onClick={() => (isConnected ? disconnect() : openModal())}>
+      {isConnected ? "Disconnect" : "Connect Wallet"}
+    </button>
+  );
 }
 ```
 
-## Configuration Options
-
-### DogeEVMKitProvider Props
+### Read account and sign
 
 ```tsx
-<DogeEVMKitProvider
-  appInfo={{
-    appName: "My App",
-    disclaimer: DisclaimerComponent, // Optional custom disclaimer
-  }}
-  avatar={CustomAvatarComponent} // Optional custom avatar
-  locale="en-US" // Optional locale
-  initialChain={1} // Optional initial chain ID
-  socialsFirst={true} // Show social logins first
-  theme={{
-    lightMode: lightTheme({
-      accentColor: "#7D5DFF",
-      accentColorForeground: "white",
-    }),
-    darkMode: darkTheme({
-      accentColor: "#7D5DFF",
-      accentColorForeground: "white",
-    }),
-  }}
->
-  {/* Your app */}
-</DogeEVMKitProvider>
-```
-
-## Available Hooks
+import React from "react";
+import { useAccount } from "@tomo-inc/wallet-connect-kit";
 
-- `useConnectModal()` - Open the connect wallet modal
-- `useAccountModal()` - Open the account management modal
-- `useChainModal()` - Open the chain selection modal
+export function AccountInfo() {
+  const { address, chainId, signMessage, signInWithWallet } = useAccount();
 
-## Themes
+  const onSignMessage = async () => {
+    // Message signing for verification
+    const sig = await signMessage?.({ message: "Hello Tomo" });
+    console.log("signature:", sig);
+  };
 
-The SDK includes built-in themes:
+  const onSignin = async () => {
+    // SIW (sign-in with wallet) to get a token
+    const token = await signInWithWallet();
+    console.log("token:", token);
+  };
 
-```tsx
-import { lightTheme, darkTheme, midnightTheme } from "@dogeos/dogeos-sdk";
+  return (
+    <div>
+      <div>Address: {address}</div>
+      <div>ChainId: {chainId}</div>
+      <button onClick={onSignMessage}>Sign Message</button>
+      <button onClick={onSignin}>Sign In With Wallet</button>
+    </div>
+  );
+}
 ```
 
-## Wallets
-
-Import wallet connectors from the SDK:
+### Optional: custom wallets and chains
 
 ```tsx
+import React from "react";
 import {
-  metaMaskWallet,
-  coinbaseWallet,
-  walletConnectWallet,
-  rainbowWallet,
-  // ... and many more
-} from "@dogeos/dogeos-sdk/wallets";
-```
-
-Configure wallets in `getDefaultConfig`:
+  WalletConnectProvider,
+  type Chain,
+} from "@tomo-inc/wallet-connect-kit";
 
-```tsx
-const config = getDefaultConfig({
-  // ... other config
-  wallets: [
+const config = {
+  // Custom wallet connectors (merge with defaults)
+  connectors: [
     {
-      groupName: "Popular",
-      wallets: [metaMaskWallet, coinbaseWallet, walletConnectWallet],
+      id: "my-wallet",
+      name: "My Wallet",
+      namespace: "my.wallet",
+      icon: "https://example.com/icon.png",
+      iconBackground: "#000",
+      downloadUrls: { chrome: "https://example.com/install" },
     },
   ],
-});
+  // Supported chains by chain type (compatible with viem/Chain for EVM)
+  chains: {
+    evm: [
+      {
+        id: 1,
+        name: "Ethereum",
+        nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+        rpcUrls: { default: { http: ["https://eth.merkle.io"] } },
+        blockExplorers: {
+          default: { name: "Etherscan", url: "https://etherscan.io" },
+        },
+      } as Chain,
+    ],
+    // aptos: [...],
+    // solana: [...],
+  },
+  // Optional: WalletConnect protocol configuration
+  // walletConnectConfig: { ... },
+
+  // Optional: Embedded wallet configuration for social login
+  embeddedWalletConfig: {
+    apiKey: "your-api-key",
+    // ... other embedded wallet settings
+  },
+
+  // Optional: Product type for UI theme (default: "tomo")
+  prodType: "mydoge", // or "tomo"
+};
+
+export function AppWithConfig() {
+  return (
+    <WalletConnectProvider config={config}>
+      <YourApp />
+    </WalletConnectProvider>
+  );
+}
 ```
 
-## License
+## Exports
+
+- `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 }`
+- Types: `WalletConnectConfig`, `Chain`, `WalletProvider`, `UseAccount`, `UseWalletConnect`, `ChainType`, `ModalView`
+- Views: `MyDogeSocialLoginView` - Custom MyDoge-styled social login view with Twitter, Google login and email support
+
+### WalletConnectProvider Config
+
+The `config` prop accepts:
+
+- `connectors?: WalletConfig[]` - Custom wallet connectors to merge with defaults
+- `chains?: Partial<Record<ChainType, EvmChain[] | any[]>>` - Supported chains by chain type (e.g., `{ evm: [...], aptos: [...], solana: [...] }`)
+- `walletConnectConfig?: WalletConnectProtocolConfig` - WalletConnect protocol configuration
+- `embeddedWalletConfig?: InitConfig` - Embedded wallet configuration for social login features (API key, OAuth settings, etc.)
+- `prodType?: ProdTypeEnum` - Product type to determine UI theme (`"tomo"` or `"mydoge"`). Controls which social login view is displayed by default
+
+**Note:** When `prodType` is set to `"mydoge"`, the SDK will automatically use the MyDoge-styled UI theme for social login features. Set it to `"tomo"` or leave it unset for the default Tomo theme.
 
-MIT
+For more comprehensive examples, see `EXAMPLE.md` in the same directory.