@dogeos/dogeos-sdk 4.0.4-beta.0 → 4.0.4

package/README.md

@@ -1,909 +1,174 @@
-# DogeOS Connect Kit
+# DogeOS SDK
 
-A lightweight React SDK for integrating crypto wallet connection functionality into your applications. It provides a configurable wallet list modal and basic account operations.
+Connect your React app to DogeOS wallets. Let users sign in with email, Google or X, connect an external wallet, and use their MyDoge wallet inside the MyDoge dApp browser.
 
-## Requirements
+[Quickstart](https://docs.dogeos.com/en/sdk) · [API reference](https://docs.dogeos.com/en/sdk/api/hooks) · [Developer console](https://console.dogeos.com/)
 
-- React 18 or higher
-- TypeScript 5 or higher (recommended)
+## Install
 
-## SDK deployment configuration
-
-The npm package is built with deployment-owned public service destinations. The release job must provide:
-
-- `DOGEOS_SDK_WEB3_ASSETS_BASE_URL`
-- `DOGEOS_OIDC_AUTH_RELAY_BASE_URL`
-- `DOGEOS_EMBEDDED_WALLET_BASE_URL`
-- `DOGEOS_EMBEDDED_WALLET_STAGE`
-- `DOGEOS_SDK_AUTH_SERVICE_ORIGINS` (comma-separated gateway/service origins)
-
-The build fails when any required value is missing or invalid. These values are compiled into the published SDK and are not consumer provider options.
-
-The SDK directory is a library-only package. Consumers resolve it through its public `dist` export.
-
-## Installation
-
-Install Wallet Connect Kit using your preferred package manager:
-
-```bash
-npm install @dogeos/dogeos-sdk
-```
+Use React 18 or later and React DOM 18 or later. Install `wagmi`, a required peer dependency, even if you use only the SDK hooks. TypeScript is supported.
 
 ```bash
-pnpm add @dogeos/dogeos-sdk
+npm install @dogeos/dogeos-sdk wagmi
 ```
 
 ```bash
-yarn add @dogeos/dogeos-sdk
+pnpm add @dogeos/dogeos-sdk wagmi
 ```
 
-### Dependencies
-
-Wallet Connect Kit requires the following peer dependencies:
-
-- `react >= 18`
-- `react-dom >= 18`
-- `wagmi >= 2.0.0` (optional, if using WagmiProvider)
-
-## Quick Start
-
-### 0. Prerequisites
-
-This guide assumes you have already installed Wallet Connect Kit. If you haven't, please refer to the installation steps above.
+## Get a client ID
 
-### 1. Setup Provider
+Create a project in the [developer console](https://console.dogeos.com/) and copy its client ID into your app. A project has separate Sandbox and Live client IDs.
 
-First, wrap your app root component with `WalletConnectProvider`:
+Use a Sandbox client ID during development. Your project overview shows whether automatic access from `localhost` and `127.0.0.1` is ready. Add your hosted application origins to the matching environment before connecting from those domains. An origin includes the scheme, hostname and port, such as `https://app.example.com`.
 
-```tsx
-// App.tsx
-import React from "react";
-import { WalletConnectProvider } from "@dogeos/dogeos-sdk";
-
-const dogeConfig = {
-  clientId: "your-client-id",
-};
-
-export default function App() {
-  return (
-    <WalletConnectProvider config={dogeConfig}>
-      <YourApp />
-    </WalletConnectProvider>
-  );
-}
-```
+Your client ID is public and belongs in the browser bundle. Your app needs one client ID to configure the SDK.
 
-### 2. Connect Wallet
+## Connect a wallet
 
-Use the `useWalletConnect` hook to open the wallet connection modal and manage connection state:
+Wrap your app with `WalletConnectProvider` and import the stylesheet once. Components under the provider can use the SDK hooks.
 
 ```tsx
-// ConnectButton.tsx
-import React from "react";
-import { useWalletConnect } from "@dogeos/dogeos-sdk";
-
-export function ConnectButton() {
-  const { openModal, isConnected, disconnect, isConnecting } =
-    useWalletConnect();
-
-  if (isConnecting) {
-    return <button disabled>Connecting...</button>;
-  }
-
-  return (
-    <button onClick={() => (isConnected ? disconnect() : openModal())}>
-      {isConnected ? "Disconnect" : "Connect Wallet"}
-    </button>
-  );
-}
-```
-
-### 3. Read Account Information
+"use client";
 
-Use the `useAccount` hook to get the currently connected account information:
-
-```tsx
-// AccountInfo.tsx
-import React from "react";
-import { useAccount } from "@dogeos/dogeos-sdk";
+import {
+  WalletConnectProvider,
+  useAccount,
+  useWalletConnect,
+  type WalletConnectKitConfig,
+} from "@dogeos/dogeos-sdk";
+import "@dogeos/dogeos-sdk/style.css";
 
-export function AccountInfo() {
-  const { address, chainId, chainType, currentWallet } = useAccount();
+const config: WalletConnectKitConfig = {
+  clientId: "YOUR_DOGEOS_CLIENT_ID",
+};
 
-  if (!address) {
-    return <div>No wallet connected</div>;
-  }
+function WalletButton() {
+  const { openModal, isConnected, isConnecting, error } = useWalletConnect();
+  const { address } = useAccount();
 
   return (
     <div>
-      <div>Address: {address}</div>
-      <div>Chain ID: {chainId}</div>
-      <div>Chain Type: {chainType}</div>
-      <div>Wallet: {currentWallet?.info?.name}</div>
+      <button type="button" disabled={isConnecting} onClick={openModal}>
+        {isConnecting ? "Connecting..." : isConnected ? address : "Connect wallet"}
+      </button>
+      {error ? <p role="alert">{error}</p> : null}
     </div>
   );
 }
-```
-
-### 4. Sign Message
-
-Use the `signMessage` method from the `useAccount` hook to sign messages:
-
-```tsx
-// SignMessageButton.tsx
-import React from "react";
-import { useAccount } from "@dogeos/dogeos-sdk";
-
-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 Dogeos Wallet",
-      });
-      console.log("Signature result:", signature);
-    } catch (error) {
-      console.error("Signing failed:", error);
-    }
-  };
-
-  if (!address) {
-    return null;
-  }
-
-  return <button onClick={handleSignMessage}>Sign Message</button>;
-}
-```
-
-### 5. Sign In with Wallet (SIW)
-
-`signInWithWallet` constructs a message and returns its signature. It does not create a server session or return an authentication token. For EVM wallets it constructs an ERC-4361 (SIWE) message using the connected address and decimal chain ID. Supply your server-issued nonce and issuedAt, together with the expected domain and URI, so your server can reconstruct and verify the challenge. The helper preserves nonce and URI, normalizes issuedAt to ISO UTC, and signs the constructed bytes unchanged. A supplied address or chain ID must match the connected wallet. If your server already returns the complete message, use `signMessage({ message })` to sign those exact bytes instead.
-
-```tsx
-// SignInButton.tsx
-import React from "react";
-import { useAccount } from "@dogeos/dogeos-sdk";
-
-export function SignInButton() {
-  const { signInWithWallet, address } = useAccount();
-
-  const handleSignIn = async () => {
-    try {
-      // Your server creates and retains these SIWE fields, including nonce and issuedAt.
-      const challenge = await fetchSignInChallenge(address);
-      const proof = await signInWithWallet(challenge);
-      // Send the short-lived proof directly to your backend. Never log it or persist it in localStorage.
-      await sendProofToBackend(proof);
-    } catch (error) {
-      console.error("Sign in failed:", error);
-    }
-  };
-
-  if (!address) {
-    return null;
-  }
-
-  return <button onClick={handleSignIn}>Sign In with Wallet</button>;
-}
-```
-
-`fetchSignInChallenge` and `sendProofToBackend` above are application callbacks, not SDK endpoints. The server must verify the signature and expected challenge fields before creating a session. Version 4.0.1 corrects the EVM helper's previously nonstandard message format; custom verifiers that reconstructed the old text must adopt the SIWE format. No legacy-format fallback is performed.
-
-## Configuration
-
-`WalletConnectProvider` accepts a `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 dogeConfig: WalletConnectKitConfig = {
-  clientId: "your-client-id",
-};
-
-export function App() {
-  return (
-    <WalletConnectProvider config={dogeConfig}>
-      <YourApp />
-    </WalletConnectProvider>
-  );
-}
-```
-
-### Configure Supported Chains
-
-Chains are automatically loaded by default. If you need to customize chains, use the `getChains()` method:
-The examples below extend the `dogeConfig` object from the basic configuration example.
-
-```tsx
-import { WalletConnectProvider, getChains } from "@dogeos/dogeos-sdk";
-import { useEffect, useState } from "react";
-
-export function App() {
-  const [chains, setChains] = useState<
-    Awaited<ReturnType<typeof getChains>> | undefined
-  >(undefined);
-
-  useEffect(() => {
-    getChains().then(setChains);
-  }, []);
-
-  return (
-    <WalletConnectProvider config={{ ...dogeConfig, chains }}>
-      <YourApp />
-    </WalletConnectProvider>
-  );
-}
-```
-
-### Configure Custom Wallets
-
-Connectors are automatically loaded by default. If you need to customize connectors, use the `getConnectors()` method:
-
-```tsx
-import { WalletConnectProvider, getConnectors } from "@dogeos/dogeos-sdk";
-import { useEffect, useState } from "react";
-
-export function App() {
-  const [connectors, setConnectors] = useState<
-    Awaited<ReturnType<typeof getConnectors>> | undefined
-  >(undefined);
-
-  useEffect(() => {
-    getConnectors().then(setConnectors);
-  }, []);
-
-  return (
-    <WalletConnectProvider config={{ ...dogeConfig, 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 = {
-  ...dogeConfig,
-  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>
-  );
-}
-```
-
-Provider OAuth client IDs and credentials are owned by the DogeOS authentication
-authority for each environment. Consumer applications select the enabled login
-controls and provide only their registered DogeOS client ID. A successful SDK
-login continues to the associated embedded wallet automatically; returning
-wallet connections are restored by the provider without consumer session
-plumbing.
-
-### Configure Theme
-
-You can customize the UI theme:
-
-```tsx
-import { WalletConnectProvider } from "@dogeos/dogeos-sdk";
-import type { ThemeConfig } from "@dogeos/dogeos-sdk";
-
-const config = {
-  ...dogeConfig,
-  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,
-};
-
-export function App() {
-  return (
-    <WalletConnectProvider config={config}>
-      <YourApp />
-    </WalletConnectProvider>
-  );
-}
-```
-
-### 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",
-    clientId: "your-client-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>;
-  }
 
+export default function App() {
   return (
     <WalletConnectProvider config={config}>
-      <div>
-        <h1>MyDoge Wallet Connect Example</h1>
-        <ConnectButton />
-      </div>
+      <WalletButton />
     </WalletConnectProvider>
   );
 }
 ```
 
-## API Reference
-
-### WalletConnectProvider
-
-Main Provider component for wrapping your application.
-
-**Props:**
-
-```tsx
-interface WalletConnectProviderProps {
-  children: React.ReactNode;
-  config: WalletConnectKitConfig;
-}
-```
-
-### useWalletConnect
-
-Hook for controlling the wallet connection modal and managing connection state.
-
-**Returns:**
-
-```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:**
-
-```tsx
-const {
-  isOpenModal,
-  openModal,
-  closeModal,
-  isConnected,
-  isConnecting,
-  connect,
-  disconnect,
-} = useWalletConnect();
-```
-
-On mobile, selecting a wallet without an injected provider may open the dApp in
-that wallet's browser. The SDK picker closes and clears its connecting state;
-the source tab is not connected by this handoff. If you call `connect()` directly,
-its promise rejects with `code: "WALLET_BROWSER_REDIRECT"` for this outcome.
-Handle that code as a browser handoff, not a completed connection. An existing
-connection in the source tab is preserved. Injected providers and WalletConnect
-sessions continue to resolve normally after connection approval.
-
-### useAccount
-
-Hook for getting the currently connected account information and performing account-related operations.
-
-**Returns:**
-
-```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>;
-}
-```
-
-**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 = { ...dogeConfig, chains };
-}
-```
-
-## Advanced Usage
-
-### Switch Chain
+`openModal()` opens the connection flow. Once connected, it opens the account view. Use `disconnect()` from `useWalletConnect()` to disconnect the active wallet.
 
-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);
-    }
-  };
-
-  return <button onClick={handleSwitchChain}>Switch to Polygon</button>;
-}
-```
+In Next.js App Router, put the provider in a client component, as above. See the [Next.js setup guide](https://docs.dogeos.com/en/sdk#nextjs) for a layout example.
 
-### Get Wallet Providers and Connectors
+## Read the connected account
 
-Use the `useConnectors` hook to get all available providers from the currently connected wallet, grouped by chain type.  
-This is useful for multi-chain wallets (for example, OKX Wallet supports EVM, Solana, Aptos, Dogecoin, etc.).  
-Different chain providers are usually based on different underlying protocols, for example EVM providers commonly follow the EIP-1193 standard, while Dogecoin providers may come from Unisat-compatible implementations.
+`useAccount()` exposes the active address, chain, wallet and provider.
 
 ```tsx
-import { useConnectors } from "@dogeos/dogeos-sdk";
-
-export function SignMessageExamples() {
-  const { connectors } = useConnectors();
-
-  if (!connectors) {
-    return <div>No wallet connected</div>;
-  }
-
-  // connectors is an object with chain types as keys
-  // e.g., { evm: { provider, protocol, standard }, dogecoin: { provider, protocol, standard }, ... }
-  const evmConnector = connectors.evm ?? null;
-  const dogeConnector = connectors.dogecoin ?? null;
-
-  // EVM provider usually follows EIP-1193 standard
-  const evmProvider = evmConnector?.provider;
-  // Dogecoin provider usually comes from a Unisat-compatible provider
-  const dogeProvider = dogeConnector?.provider;
-
-  const handleEvmSignMessage = async () => {
-    if (!evmProvider) return;
-
-    const accounts = await evmProvider.request({
-      method: "eth_requestAccounts",
-    });
-    const from = accounts[0];
+"use client";
 
-    const message = "Hello from EVM";
+import { useAccount, useWalletConnect } from "@dogeos/dogeos-sdk";
 
-    // EIP-1193 personal_sign example
-    const signature = await evmProvider.request({
-      method: "personal_sign",
-      params: [message, from],
-    });
+export function AccountDetails() {
+  const { isConnected } = useWalletConnect();
+  const { address, chainType, chainId } = useAccount();
 
-    console.log("EVM signature:", signature);
-  };
-
-  const handleDogeSignMessage = async () => {
-    if (!dogeProvider) return;
-
-    const message = "Hello from Dogecoin";
-
-    // Unisat-like Dogecoin signMessage example
-    // Most Unisat-compatible providers expose a signMessage method
-    const signature = await dogeProvider.signMessage(message);
-
-    console.log("Dogecoin signature:", signature);
-  };
+  if (!isConnected) return <p>Connect a wallet to continue.</p>;
 
   return (
     <div>
-      <button disabled={!evmProvider} onClick={handleEvmSignMessage}>
-        Sign EVM Message
-      </button>
-      <button disabled={!dogeProvider} onClick={handleDogeSignMessage}>
-        Sign Dogecoin Message
-      </button>
+      <p>{address}</p>
+      <p>{chainType}: {chainId}</p>
     </div>
   );
 }
 ```
 
-**Returns:**
+The same hook provides `switchChain()`, `signMessage()` and `signInWithWallet()`. Use `currentProvider` for chain-specific requests, or `useConnectors()` to access the connected wallet's other chain providers. See [account actions and signing examples](https://docs.dogeos.com/en/sdk/guides).
 
-```tsx
-interface UseConnectors {
-  // All available providers from the current wallet, keyed by chain type
-  connectors: ConnectorProviders | null;
-  // The currently active provider for the selected chain
-  currentProvider: WalletProvider | null;
-}
-```
+A wallet connection or signature alone does not create an authenticated session for your backend. For wallet-based sign-in, have your server issue and verify a fresh challenge before creating a session. Follow the [sign-in guide](https://docs.dogeos.com/en/sdk/guides#sign-in-with-wallet).
 
-**Note:** `connectors` contains all connectors supported by the current wallet. For example, if you connect OKX Wallet, `connectors` may include `evm`, `dogecoin`, `solana`, and `aptos` connectors. Each entry provides a `provider` instance that you can use directly to call chain-specific RPC methods.
+## Connection and readiness
 
-### Integration with Wagmi
+Use the state that matches what your app needs.
 
-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:
+| Field | Meaning |
+| --- | --- |
+| `isConnected` | A wallet is connected. Use it with the current account and provider for wallet actions. |
+| `isConnecting` | A wallet connection attempt is in progress. |
+| `connectionStatus` | `disconnected`, `connecting` or `connected`. |
+| `walletStatus` | Embedded wallet state: `disabled`, `initializing`, `ready`, `unavailable` or `error`. |
+| `isWalletReady` | The embedded wallet is ready to accept login. |
 
-```tsx
-import { WagmiProvider } from "wagmi";
-import { WalletConnectProvider } from "@dogeos/dogeos-sdk";
-import { config } from "./wagmi-config";
+Inside MyDoge, the SDK selects the native wallet automatically. Keep your normal provider configuration and connection button. A native or external wallet can be connected while the embedded wallet is disabled, so do not require `isWalletReady` for all wallet actions. See [native wallet connections](https://docs.dogeos.com/en/sdk/embedded-wallets#native-first-connection-in-mydoge).
 
-export function App() {
-  return (
-    <WagmiProvider config={config}>
-      <WalletConnectProvider config={dogeConfig}>
-        <YourApp />
-      </WalletConnectProvider>
-    </WagmiProvider>
-  );
-}
-```
+## Configure your app
 
-### Error Handling
+Pass optional settings alongside `clientId` in `WalletConnectKitConfig`.
 
-Always handle errors in connections and operations:
+| Option | Use it to |
+| --- | --- |
+| `chains` | Choose supported networks, grouped by chain family. |
+| `defaultConnectChain` | Choose the initial chain family, such as `"evm"`. |
+| `login` | Choose which email, social and external wallet options appear. |
+| `metadata` | Set your app's name, description, URL and icon. |
+| `theme` | Set colors and light or dark mode. |
+| `walletConnectProjectId` | Enable WalletConnect with your own project ID. |
+| `connectors` | Customize the wallet list using `getConnectors()`. |
 
-```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>;
-}
-```
+See [configuration](https://docs.dogeos.com/en/sdk/configuration) for examples, including [DogeOS Chikyū Testnet](https://docs.dogeos.com/en/sdk/configuration#chains).
 
-## Type Definitions
-
-### WalletConnectKitConfig
-
-`walletConnectProjectId` is optional and has no SDK default. To enable WalletConnect,
-create a project in the [Reown Dashboard](https://dashboard.reown.com/) for your
-application, configure its allowed origins, and pass that project's ID. This public
-project ID is separate from your DogeOS `clientId`. Omitting it or passing a blank
-value hides WalletConnect and skips its discovery and initialization; injected
-wallets and the other configured login methods remain available. Rejected project
-IDs surface the provider error without a fallback project.
-
-````tsx
-interface WalletConnectKitConfig {
-  connectors?: WalletConfig[];
-  chains?: Partial<Record<ChainType, EvmChain[] | any[]>>;
-  walletConnectProjectId?: string;
-  /**
-   * Default connect chain
-   * @default undefined
-   * @example
-   * ```tsx
-   * import { WalletConnectProvider } from "@dogeos/dogeos-sdk";
-   * const config: WalletConnectKitConfig = {
-   *   defaultConnectChain: 'evm',
-   * };
-   */
-  defaultConnectChain?: ChainType;
-  metadata?: {
-    name: string;
-    description: string;
-    url: string;
-    icons: string[];
-  };
-  clientId: string;
-  theme?: ThemeConfig;
-  login?: UserLoginConfig;
-  embeddedWalletConfig?: {
-    /**
-     * @default "prod-dogeos"
-     */
-    stage?: "prod-dogeos" | "prod" | "pre" | "dev";
-  };
-}
-````
-
-### Chain
-
-```tsx
-interface Chain {
-  id: number;
-  name: string;
-  nativeCurrency: {
-    name: string;
-    symbol: string;
-    decimals: number;
-  };
-  rpcUrls: {
-    default: {
-      http: readonly string[];
-    };
-  };
-  blockExplorers?: {
-    default: {
-      name: string;
-      url: string;
-    };
-  };
-  testnet?: boolean;
-}
-```
+### WalletConnect
 
-### ChainType
+To enable WalletConnect, create a project in the [Reown dashboard](https://dashboard.reown.com/) and pass its project ID. It is separate from your DogeOS client ID.
 
 ```tsx
-type ChainType = "evm" | "solana" | "aptos" | "dogecoin";
-```
-
-## Exports
-
-- `WalletConnectProvider` - Main Provider component
-- `useAccount` - Account information Hook
-- `useWalletConnect` - Connect Hook
-- `useConnectors` - Providers information Hook (get all available providers from current wallet)
-- `getChains` - Utility function to configure chains (can wrap backend API chains)
-- Types: `WalletConnectKitConfig`, `Chain`, `WalletConfig`, `UseAccount`, `ChainType`, `ModalView`, `ThemeConfig`, `UserLoginConfig`
-
-## FAQ
-
-### How to use with Next.js?
+import type { WalletConnectKitConfig } from "@dogeos/dogeos-sdk";
 
-```js
-"use client"; // add "use client" at your index router page
+const config: WalletConnectKitConfig = {
+  clientId: "YOUR_DOGEOS_CLIENT_ID",
+  walletConnectProjectId: "YOUR_WALLETCONNECT_PROJECT_ID",
+  metadata: {
+    name: "My DogeOS app",
+    description: "My DogeOS application",
+    url: "https://app.example.com",
+    icons: ["https://app.example.com/icon.png"],
+  },
+};
 ```
 
-### Supported Next.js version
-
-- Next.js 14 and 15 are supported.
-
-### What Content Security Policy entries are required?
-
-If your app uses a restrictive CSP, allow the embedded-wallet, Social Relay, and Web3 Assets origins documented for the published SDK release you install. Those origins are compiled into the SDK by the release pipeline and cannot be overridden by the consumer app.
-
-Use the exact origins from that release in `frame-src` and `connect-src`; do not substitute consumer-controlled endpoints.
+Without `walletConnectProjectId`, WalletConnect is hidden. Email, social login and supported injected wallets remain available. Add your app's origins to your Reown project if you use its origin allowlist.
 
-### How to get WalletConnect Project ID?
+## Render the wallet UI inline
 
-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:
+Use `WalletConnectEmbed` inside your existing provider when the wallet flow belongs in a page instead of a modal.
 
 ```tsx
-import { getChains, getConnectors } from "@dogeos/dogeos-sdk";
-
-// Get all available chains
-const chains = await getChains();
+"use client";
 
-// Get all available connectors
-const connectors = await getConnectors();
+import { WalletConnectEmbed } from "@dogeos/dogeos-sdk";
 
-// Use in config
-const config = { ...dogeConfig, chains, connectors };
+export function WalletPanel() {
+  return <WalletConnectEmbed style={{ width: "100%", maxWidth: 448 }} />;
+}
 ```
 
-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.
-
-### What chain types are supported?
-
-Currently, EVM chains are primarily supported, along with Solana, Aptos, and Dogecoin chains.
+## Documentation
 
-> For internal release and publishing workflow, see `RELEASE.md` in the repository root (not published to npm).
+- [Quickstart](https://docs.dogeos.com/en/sdk) for installation and provider setup.
+- [Configuration](https://docs.dogeos.com/en/sdk/configuration) for chains, login options and themes.
+- [Core workflows](https://docs.dogeos.com/en/sdk/guides) for signing, network changes and provider requests.
+- [Embedded wallets](https://docs.dogeos.com/en/sdk/embedded-wallets) for inline UI and native MyDoge behavior.
+- [Wagmi integration](https://docs.dogeos.com/en/sdk/wagmi) for apps that already use Wagmi hooks.
+- [API reference](https://docs.dogeos.com/en/sdk/api/hooks) for components, hooks and helpers.
+- [Troubleshooting](https://docs.dogeos.com/en/sdk/troubleshooting) for connection errors and browser requirements.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dogeos/dogeos-sdk",
   "private": false,
-  "version": "4.0.4-beta.0",
+  "version": "4.0.4",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -87,11 +87,11 @@
     "vitest": "^4.0.18",
     "wagmi": "^2.0.0",
     "@dogeos/dogeos-ui": "0.0.14",
-    "@dogeos/inject-providers": "0.0.21",
     "@dogeos/embedded-wallet-providers": "0.0.28",
+    "@dogeos/inject-providers": "0.0.21",
     "@dogeos/oidc-auth": "0.0.20",
-    "@dogeos/wallet-utils": "0.0.23",
-    "@dogeos/wallet-adaptor-base": "0.0.25"
+    "@dogeos/wallet-adaptor-base": "0.0.25",
+    "@dogeos/wallet-utils": "0.0.23"
   },
   "sideEffects": [
     "**/*.css",