@dogeos/dogeos-sdk 4.0.7-beta.0 → 4.1.0-beta.0

package/README.md

@@ -66,6 +66,8 @@ export default function App() {
 }
 ```
 
+The stylesheet only styles SDK UI: the modal, toasts and `WalletConnectEmbed`. Your page keeps its own reset, fonts and colors. If you leave out the import, the provider adds the same stylesheet when it mounts. It adds its stylesheets as constructed stylesheets, which a Content Security Policy without `'unsafe-inline'` in `style-src` allows. Browsers without constructed stylesheets (before Safari 16.4) get `<style>` elements instead, which such a policy blocks; importing `style.css` covers the stylesheet there, but not `config.theme` colors. To restyle SDK UI, target elements inside `.dogeos-sdk`.
+
 `openModal()` opens the connection flow. Once connected, it opens the account view. Use `disconnect()` from `useWalletConnect()` to disconnect the active wallet.
 
 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.
@@ -110,15 +112,17 @@ Use the state that matches what your app needs.
 | `walletStatus` | Embedded wallet state: `disabled`, `initializing`, `ready`, `unavailable` or `error`. |
 | `isWalletReady` | The embedded wallet is ready to accept login. |
 
+`WalletConnectProvider` renders your app straight away outside MyDoge. In an Android in-app browser (a WebView), the embedded wallet, and with email or social sign-in configured also restoring a saved connection, wait until the page finishes loading, for up to 5 seconds, before they start: MyDoge's in-app browser can still identify itself until then. `walletStatus` reports `initializing` meanwhile. Inside MyDoge the provider shows a short "Preparing wallet connection…" status in place of your app while the native wallet gets ready, with a Retry button if it takes longer than 5 seconds. On some older Android devices MyDoge identifies itself late, so your app can render once in browser mode and then mount again in native mode.
+
 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).
 
 ## Inside the MyDoge app
 
 In MyDoge's dApp browser the native app answers every wallet request, and the SDK shows none of its own wallet UI and opens no popups. The same code works in a browser and in MyDoge:
 
-- `openModal()` asks MyDoge to connect, or opens MyDoge's account sheet when a wallet is already connected.
-- `WalletConnectEmbed` shows a small MyDoge card with Connect, Account and Disconnect buttons instead of the wallet list.
-- A first visit does not prompt on page load. MyDoge reconnects a dApp the user already approved; otherwise the SDK waits for the user to tap connect.
+- `openModal()` asks MyDoge to connect. When a wallet is already connected, it opens MyDoge's account sheet on MyDoge builds that support it; on builds without it, including 3.1.1 (build 652) and earlier, it does nothing and logs a warning, so give users a Disconnect button and, if you support several networks, a `switchChain()` control.
+- `WalletConnectEmbed` shows a small MyDoge card with Connect, Account and Disconnect buttons instead of the wallet list. Its Account button needs the same account-sheet support.
+- A first visit does not prompt on page load. A saved connection is restored, and MyDoge builds that support it also reconnect a dApp the user already approved; otherwise the SDK waits for the user to tap connect.
 - `disconnect()` also revokes the dApp's approval in MyDoge.
 - DogeOS email and social sign-in (`useDogeOSAuth().login()`) reject with `DogeOSHostError`. Use `signInWithWallet()` and verify the signature on your server.
 
@@ -195,6 +199,48 @@ export function WalletPanel() {
 }
 ```
 
+`WalletConnectEmbed` also takes these props:
+
+- `initialView`: the picker it starts on and returns to, `"walletList"` or `"walletSearch"`. By default it follows `config.login`.
+- `hideHeader`: leaves out the starting view's title, for a page that gives the embed its own heading. Controls in that row, such as a link to the wallet list, stay. Later views keep their titles.
+- `keepPickerAfterConnect`: keeps the picker on screen after a wallet connects, instead of showing the account view. Connecting another wallet, its errors and the install guide still show.
+
+Inside MyDoge the embed is always the MyDoge card, whatever these props say.
+
+## Link a second wallet
+
+To let a signed-in user prove they own another wallet, for example to link it to their account, render a second `WalletConnectProvider` around an embed. Configure it so it doesn't take over the page's main connection:
+
+```tsx
+"use client";
+
+import { WalletConnectEmbed, WalletConnectProvider, type WalletConnectKitConfig } from "@dogeos/dogeos-sdk";
+
+const linkConfig: WalletConnectKitConfig = {
+  clientId: process.env.NEXT_PUBLIC_DOGEOS_CLIENT_ID!,
+  login: { basicLogins: ["externalWallets"], socialLogins: [] },
+  // Connect only when the user picks a wallet, and save nothing.
+  autoRestore: false,
+  persistConnection: false,
+  // Ask an EVM wallet to show its account picker even for a site it already approved.
+  forceAccountSelection: { blockedAddresses: alreadyLinkedAddresses },
+};
+
+export function LinkWallet() {
+  return (
+    <WalletConnectProvider config={linkConfig}>
+      <WalletConnectEmbed initialView="walletSearch" hideHeader keepPickerAfterConnect />
+    </WalletConnectProvider>
+  );
+}
+```
+
+- `autoRestore: false` skips restoring a saved connection on load, and inside MyDoge the silent reconnect too. It does not cover the DogeOS sign-in: on a page where the user is signed in, a provider that offers social logins connects their Social Wallet on load. The `login` line above keeps the link provider to external wallets, so that doesn't happen.
+- `persistConnection: false` saves no reconnect hint, and leaves the main provider's alone.
+- `forceAccountSelection` applies to EVM browser wallets; MyDoge and the embedded wallet ignore it. Before connecting it asks the wallet for the site's account permission again (EIP-2255), which makes most wallets show their picker. If the wallet supports no such request and returns one of `blockedAddresses`, the connection fails with a message asking the user to disconnect the site in their wallet. `revokePermissions: true` revokes the permission first, for wallets that skip their picker otherwise. The permission is per site, so that also disconnects a main connection to the same wallet on the page.
+
+Ask for a signature from the connected wallet to prove ownership, and check it on your server.
+
 ## Link to another dApp from inside MyDoge
 
 In MyDoge's in-app browser, a plain `https` link to another dApp loads in your dApp's browser session. The wallet stays bound to your dApp's origin, so the other dApp can't connect. Link to it with a `mydoge://dapp` URL instead: MyDoge then opens the target as its own dApp with its own wallet session. The user sees the target's details screen and taps **Open**; your dApp closes only then.