@dogeos/dogeos-sdk 4.0.6-beta.2 → 4.0.7-beta.0

package/README.md

@@ -112,6 +112,38 @@ Use the state that matches what your app needs.
 
 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.
+- `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.
+
+`useWalletHost()` tells you where the dApp is running and gives you a connect call that returns the account in both places:
+
+```tsx
+import { isWalletError, useWalletHost, WalletErrorCode } from "@dogeos/dogeos-sdk";
+
+function ConnectButton() {
+  const { isNativeHost, connect } = useWalletHost();
+
+  const onClick = async () => {
+    try {
+      const { address } = await connect();
+      console.log("Connected", address);
+    } catch (error) {
+      if (isWalletError(error, WalletErrorCode.UserRejected)) return;
+      throw error;
+    }
+  };
+
+  return <button type="button" onClick={onClick}>{isNativeHost ? "Connect MyDoge" : "Connect wallet"}</button>;
+}
+```
+
 ## Configure your app
 
 Pass optional settings alongside `clientId` in `WalletConnectKitConfig`.
@@ -163,6 +195,45 @@ export function WalletPanel() {
 }
 ```
 
+## 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.
+
+`isInMyDogeBrowser()` detects MyDoge's in-app browser through its EIP-6963 announcement (rdns `com.mydoge.wallet`). It resolves `false` after a timeout (500 ms by default) and during server rendering. `getDappHref()` returns the `mydoge://dapp` link inside MyDoge and the plain URL everywhere else.
+
+```tsx
+"use client";
+
+import { useEffect, useState } from "react";
+import { getDappHref, isInMyDogeBrowser } from "@dogeos/dogeos-sdk";
+
+const BUY_MOON_URL = "https://muchfi.example/buy?token=MOON";
+
+export function BuyMoonLink() {
+  // null until detection finishes, so no plain link can be tapped inside MyDoge first.
+  const [inMyDoge, setInMyDoge] = useState<boolean | null>(null);
+
+  useEffect(() => {
+    void isInMyDogeBrowser().then(setInMyDoge);
+  }, []);
+
+  const href = inMyDoge === null ? undefined : getDappHref(BUY_MOON_URL, { inMyDoge });
+  return <a href={href}>Buy MOON</a>;
+}
+```
+
+Leave the link without an `href` until detection finishes. A server-rendered plain link can be tapped inside MyDoge before your page hydrates, which loads the target in your dApp's session. Outside MyDoge, detection takes up to 500 ms after hydration.
+
+`getMyDogeDappLink(targetUrl)` builds the link directly: `mydoge://dapp?url=` followed by the complete target URL, encoded once with `encodeURIComponent`. Pass the raw `https` URL, not an already encoded one. It normalizes the URL first, as a browser would (for example, a space becomes `%20`), because MyDoge rejects raw spaces and similar characters. It throws a `TypeError` for anything other than an absolute `https` URL, for a URL with a username or password, and for a URL over MyDoge's 8 KiB limit. `getDappHref()` applies the same checks in every browser, so a bad URL shows up in ordinary testing.
+
+These rules come from MyDoge's dApp deep-link partner guide:
+
+- **Set the href before the tap.** Detect MyDoge first, then put the link in the element the user taps. A plain link, a `target="_blank"` link, or `window.open` called synchronously in the tap handler all work. Setting `location.href` doesn't work on iOS, and navigation after an `await` or a timer may be blocked.
+- **Only top-level pages work.** Links inside an iframe are ignored on iOS and may be ignored on Android.
+- **The target must be listed in MyDoge.** Its origin must exactly match the destination dApp's published CMS `projectLink` origin. Subdomains such as `www` and non-default ports count as different origins. Path, query and fragment are passed through unchanged.
+- **MyDoge 3.1.1 (build 652) or later is required.** Earlier builds ignore a tapped `mydoge://` link, so nothing happens. They announce the same `com.mydoge.wallet` provider, so a page can't tell them apart from 652.
+- MyDoge ignores a second link within two seconds.
+
 ## Documentation
 
 - [Quickstart](https://docs.dogeos.com/en/sdk) for installation and provider setup.