@b3dotfun/sdk 0.1.69-alpha.23 → 0.1.69-alpha.25

package/dist/types/global-account/react/components/index.d.ts

@@ -8,6 +8,7 @@ export { useB3Config } from "./B3Provider/useB3Config";
 export { StyleRoot } from "./StyleRoot";
 export { BetterAuthResetPassword, type BetterAuthResetPasswordProps } from "./SignInWithB3/BetterAuthResetPassword";
 export { BetterAuthSignIn, type BetterAuthSignInProps } from "./SignInWithB3/BetterAuthSignIn";
+export { BetterAuthVerifyEmail, type BetterAuthVerifyEmailProps, type BetterAuthVerifyEmailState, } from "./SignInWithB3/BetterAuthVerifyEmail";
 export { AuthButton } from "./SignInWithB3/components/AuthButton";
 export { PermissionItem } from "./SignInWithB3/components/PermissionItem";
 export { WalletRow } from "./SignInWithB3/components/WalletRow";

package/dist/types/global-account/react/hooks/useBetterAuth.d.ts

@@ -13,7 +13,7 @@ export declare class EmailVerificationRequiredError extends Error {
  */
 export declare function useBetterAuth(): {
     signInWithEmail: (email: string, password: string) => Promise<import("@feathersjs/authentication").AuthenticationResult>;
-    signUpWithEmail: (email: string, password: string, name: string) => Promise<import("@feathersjs/authentication").AuthenticationResult>;
+    signUpWithEmail: (email: string, password: string, name: string, verifyCallbackURL?: string) => Promise<import("@feathersjs/authentication").AuthenticationResult>;
     signInWithSocial: (provider: BetterAuthSocialProvider) => Promise<void>;
     requestPasswordReset: (email: string, redirectTo?: string) => Promise<{
         data: {

package/dist/types/global-account/react/stores/useModalStore.d.ts

@@ -41,6 +41,8 @@ export interface SignInWithB3ModalProps extends BaseModalProps {
     source?: "signInWithB3Button" | "requestPermissions";
     /** Whether to show the signers enabled modal */
     signersEnabled?: boolean;
+    /** URL Better Auth redirects to after server-side email verification. */
+    verifyEmailRedirectTo?: string;
 }
 /**
  * Props for the Request Permissions modal

package/dist/types/shared/constants/index.d.ts

@@ -16,3 +16,4 @@ export declare const CLIENT_APP_BUNDLE_ID: string;
 export declare const B3_AUTH_COOKIE_NAME = "b3-auth";
 export declare const ENS_GATEWAY_URL = "https://ens-gateway.b3.fun/";
 export declare const PUBLIC_BASE_RPC_URL = "https://base-rpc.publicnode.com";
+export declare const AVATAR_COLORS: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b3dotfun/sdk",
-  "version": "0.1.69-alpha.23",
+  "version": "0.1.69-alpha.25",
   "source": "src/index.ts",
   "main": "./dist/cjs/index.js",
   "react-native": "./dist/cjs/index.native.js",

package/src/global-account/react/components/AvatarEditor/AvatarEditor.tsx

@@ -62,6 +62,8 @@ export function AvatarEditor({ onSetAvatar, className }: AvatarEditorProps) {
   const setB3ModalContentType = useModalStore(state => state.setB3ModalContentType);
   const contentType = useModalStore(state => state.contentType);
 
+  const { authStrategy } = useB3Config();
+  const isBetterAuth = authStrategy === "better-auth";
   const account = useActiveAccount();
   const { data: profile, refetch: refreshProfile } = useProfile({
     address: account?.address,
@@ -162,7 +164,7 @@ export function AvatarEditor({ onSetAvatar, className }: AvatarEditorProps) {
   };
 
   const handleSaveChanges = async () => {
-    if (!account?.address) {
+    if (!isBetterAuth && !account?.address) {
       toast.error("No account connected");
       return;
     }

package/src/global-account/react/components/ManageAccount/BottomNavigation.tsx

@@ -1,4 +1,4 @@
-import { TabsListPrimitive, TabTriggerPrimitive, useModalStore } from "@b3dotfun/sdk/global-account/react";
+import { TabsListPrimitive, TabTriggerPrimitive, useB3Config, useModalStore } from "@b3dotfun/sdk/global-account/react";
 
 const HomeIcon = () => {
   return (
@@ -42,6 +42,8 @@ const SettingsIcon = () => {
 
 const BottomNavigation = () => {
   const setB3ModalContentType = useModalStore(state => state.setB3ModalContentType);
+  const { authStrategy } = useB3Config();
+  const isBetterAuth = authStrategy === "better-auth";
 
   return (
     <div className="b3-modal-bottom-navigation sticky bottom-0 left-0 w-full rounded-b-xl border-t border-gray-200 bg-[#FAFAFA]">
@@ -54,19 +56,21 @@ const BottomNavigation = () => {
           <span className="text-b3-grey font-neue-montreal-semibold text-xs">Home</span>
         </TabTriggerPrimitive>
 
-        <TabTriggerPrimitive
-          value="swap"
-          className="data-[state=active]:border-b3-primary-blue group flex flex-initial flex-col items-center gap-1 border-r-0 border-t-0 px-6 pb-2 pt-2.5 text-[#a0a0ab] data-[state=active]:border-t-4 data-[state=active]:text-[#18181B] dark:data-[state=active]:text-white"
-          onClick={() => {
-            setB3ModalContentType({
-              type: "anySpend",
-              showBackButton: true,
-            });
-          }}
-        >
-          <SwapIcon />
-          <span className="text-b3-grey font-neue-montreal-semibold text-xs">Swap</span>
-        </TabTriggerPrimitive>
+        {!isBetterAuth && (
+          <TabTriggerPrimitive
+            value="swap"
+            className="data-[state=active]:border-b3-primary-blue group flex flex-initial flex-col items-center gap-1 border-r-0 border-t-0 px-6 pb-2 pt-2.5 text-[#a0a0ab] data-[state=active]:border-t-4 data-[state=active]:text-[#18181B] dark:data-[state=active]:text-white"
+            onClick={() => {
+              setB3ModalContentType({
+                type: "anySpend",
+                showBackButton: true,
+              });
+            }}
+          >
+            <SwapIcon />
+            <span className="text-b3-grey font-neue-montreal-semibold text-xs">Swap</span>
+          </TabTriggerPrimitive>
+        )}
 
         <TabTriggerPrimitive
           value="settings"

package/src/global-account/react/components/ManageAccount/Header.tsx

@@ -2,10 +2,13 @@ import {
   CopyToClipboard,
   ManageAccountModalProps,
   useAuthentication,
+  useB3Config,
   useModalStore,
 } from "@b3dotfun/sdk/global-account/react";
+import { AVATAR_COLORS } from "@b3dotfun/sdk/shared/constants";
 import * as AccordionPrimitive from "@radix-ui/react-accordion";
 import { AnimatePresence, motion } from "framer-motion";
+import Avatar from "boring-avatars";
 import { Loader2 } from "lucide-react";
 import { useState } from "react";
 import { useActiveWallet, useConnectedWallets, useSetActiveWallet, useWalletImage } from "thirdweb/react";
@@ -89,7 +92,71 @@ function WalletItem({ wallet, isActive, onClick }: { wallet: Wallet; isActive: b
   );
 }
 
+function BetterAuthHeader({ onLogout }: { onLogout?: () => void }) {
+  const contentType = useModalStore(state => state.contentType) as ManageAccountModalProps;
+  const setB3ModalOpen = useModalStore(state => state.setB3ModalOpen);
+  const partnerId = contentType?.partnerId;
+  const { logout, user } = useAuthentication(partnerId);
+  const [logoutLoading, setLogoutLoading] = useState(false);
+
+  const displayName = user?.username || user?.email || "Account";
+
+  const onLogoutEnhanced = async () => {
+    setLogoutLoading(true);
+    try {
+      await logout();
+      onLogout?.();
+    } finally {
+      setB3ModalOpen(false);
+      setLogoutLoading(false);
+    }
+  };
+
+  return (
+    <div className="bg-b3-background border-b3-line flex items-center justify-between border-b px-5 py-3">
+      <div className="flex items-center gap-2">
+        <div className="size-10 shrink-0 overflow-hidden rounded-full">
+          <Avatar name={displayName} variant="beam" size={40} colors={AVATAR_COLORS} />
+        </div>
+        <div className="flex flex-col gap-0.5">
+          {user?.username && (
+            <p className="text-b3-grey font-neue-montreal-semibold text-left text-sm">{user.username}</p>
+          )}
+          {user?.email && (
+            <div className="flex items-center gap-1">
+              <p className="text-b3-foreground-muted font-neue-montreal-medium text-sm">{user.email}</p>
+              <CopyToClipboard text={user.email} />
+            </div>
+          )}
+        </div>
+      </div>
+      <button
+        className="border-b3-line hover:bg-b3-line flex items-center justify-center gap-1.5 rounded-xl border border-solid px-3 py-2 transition-colors"
+        onClick={onLogoutEnhanced}
+        disabled={logoutLoading}
+      >
+        {logoutLoading ? (
+          <Loader2 className="animate-spin" size={16} />
+        ) : (
+          <SignOutIcon size={16} className="text-b3-grey" />
+        )}
+        <p className="text-b3-grey font-neue-montreal-semibold text-sm">Sign out</p>
+      </button>
+    </div>
+  );
+}
+
 export function Header({ onLogout }: { onLogout?: () => void }) {
+  const { authStrategy } = useB3Config();
+
+  if (authStrategy === "better-auth") {
+    return <BetterAuthHeader onLogout={onLogout} />;
+  }
+
+  return <WalletHeader onLogout={onLogout} />;
+}
+
+function WalletHeader({ onLogout }: { onLogout?: () => void }) {
   const activeWallet = useActiveWallet();
 
   const connectedWallets = useConnectedWallets();
@@ -110,10 +177,13 @@ export function Header({ onLogout }: { onLogout?: () => void }) {
 
   const onLogoutEnhanced = async () => {
     setLogoutLoading(true);
-    await logout();
-    onLogout?.();
-    setB3ModalOpen(false);
-    setLogoutLoading(false);
+    try {
+      await logout();
+      onLogout?.();
+    } finally {
+      setB3ModalOpen(false);
+      setLogoutLoading(false);
+    }
   };
 
   const handleWalletSwitch = (wallet: Wallet) => {

package/src/global-account/react/components/ManageAccount/HomeContent.tsx

@@ -1,3 +1,4 @@
+import { useB3Config } from "@b3dotfun/sdk/global-account/react";
 import { Tabs, TabsContent, TabsList, TabTrigger } from "../ui/Tabs";
 import { Header } from "./Header";
 import HomeActions from "./HomeActions";
@@ -11,31 +12,36 @@ interface HomeContentProps {
 }
 
 export function HomeContent({ showDeposit = false, showSwap = true }: HomeContentProps) {
+  const { authStrategy } = useB3Config();
+  const isBetterAuth = authStrategy === "better-auth";
+
   return (
     <div className="flex flex-col">
       <Header />
       <div className="flex flex-col">
         <ProfileSection />
 
-        <HomeActions showDeposit={showDeposit} showSwap={showSwap} />
-        <div className="b3-modal-balance-content space-y-2 p-5">
-          <Tabs defaultValue={"balance"}>
-            <TabsList className="b3-modal-balance-tabs-list">
-              <TabTrigger value="balance" className="font-neue-montreal-semibold p-0 pr-3">
-                Balance
-              </TabTrigger>
-              <TabTrigger value="nfts" className="font-neue-montreal-semibold p-0 pr-3">
-                NFTs
-              </TabTrigger>
-            </TabsList>
-            <TabsContent value="balance" className="px-0 pb-4 pt-2">
-              <TokenContent />
-            </TabsContent>
-            <TabsContent value="nfts" className="px-0 pb-4 pt-2">
-              <NFTContent />
-            </TabsContent>
-          </Tabs>
-        </div>
+        {!isBetterAuth && <HomeActions showDeposit={showDeposit} showSwap={showSwap} />}
+        {!isBetterAuth && (
+          <div className="b3-modal-balance-content space-y-2 p-5">
+            <Tabs defaultValue={"balance"}>
+              <TabsList className="b3-modal-balance-tabs-list">
+                <TabTrigger value="balance" className="font-neue-montreal-semibold p-0 pr-3">
+                  Balance
+                </TabTrigger>
+                <TabTrigger value="nfts" className="font-neue-montreal-semibold p-0 pr-3">
+                  NFTs
+                </TabTrigger>
+              </TabsList>
+              <TabsContent value="balance" className="px-0 pb-4 pt-2">
+                <TokenContent />
+              </TabsContent>
+              <TabsContent value="nfts" className="px-0 pb-4 pt-2">
+                <NFTContent />
+              </TabsContent>
+            </Tabs>
+          </div>
+        )}
       </div>
     </div>
   );

package/src/global-account/react/components/ManageAccount/ProfileSection.tsx

@@ -1,11 +1,13 @@
 import {
   useAccountWallet,
+  useB3Config,
   useModalStore,
   useProfile,
   useSimBalance,
   useUser,
 } from "@b3dotfun/sdk/global-account/react";
 import { validateImageUrl } from "@b3dotfun/sdk/global-account/react/utils/profileDisplay";
+import { AVATAR_COLORS } from "@b3dotfun/sdk/shared/constants";
 import { formatUsername } from "@b3dotfun/sdk/shared/utils";
 import { formatDisplayNumber } from "@b3dotfun/sdk/shared/utils/number";
 import Avatar from "boring-avatars";
@@ -15,9 +17,9 @@ import { useActiveAccount } from "thirdweb/react";
 import { useFirstEOA } from "../../hooks/useFirstEOA";
 import { IPFSMediaRenderer } from "../IPFSMediaRenderer/IPFSMediaRenderer";
 
-const AVATAR_COLORS = ["#3368ef", "#272727", "#6366f1", "#06b6d4", "#eeb0d9", "#ba3fbf", "#ff777b", "#dfbb53"];
-
 const ProfileSection = () => {
+  const { authStrategy } = useB3Config();
+  const isBetterAuth = authStrategy === "better-auth";
   const account = useActiveAccount();
   const { address: eoaAddress } = useFirstEOA();
   const { address: smartWalletAddress } = useAccountWallet();
@@ -60,7 +62,7 @@ const ProfileSection = () => {
   }, [avatarSrc]);
 
   const currentUsername = user?.username || profile?.displayName || formatUsername(profile?.name || "");
-  const avatarSeed = eoaAddress || account?.address || smartWalletAddress || currentUsername || "user";
+  const avatarSeed = eoaAddress || account?.address || smartWalletAddress || currentUsername || user?.email || "user";
 
   return (
     <div className="flex items-center justify-between px-5 py-6">
@@ -87,13 +89,18 @@ const ProfileSection = () => {
           </button>
         </div>
         <div className="global-account-profile-info flex flex-col gap-1">
-          <h2 className="text-b3-grey font-neue-montreal-semibold flex h-[38px] items-center gap-1 text-xl">
-            <div className="text-b3-foreground-muted"> $</div>
-            <div className="text-[30px]">{formatDisplayNumber(totalBalanceUsd, { fractionDigits: 2 })}</div>
-          </h2>
+          {!isBetterAuth && (
+            <h2 className="text-b3-grey font-neue-montreal-semibold flex h-[38px] items-center gap-1 text-xl">
+              <div className="text-b3-foreground-muted"> $</div>
+              <div className="text-[30px]">{formatDisplayNumber(totalBalanceUsd, { fractionDigits: 2 })}</div>
+            </h2>
+          )}
           <div className="b3-modal-username font-neue-montreal-semibold text-base leading-none text-[#0B57C2]">
             {currentUsername}
           </div>
+          {isBetterAuth && user?.email && (
+            <div className="text-b3-foreground-muted font-neue-montreal-medium text-sm">{user.email}</div>
+          )}
         </div>
       </div>
     </div>

package/src/global-account/react/components/ManageAccount/SettingsContent.tsx

@@ -1,4 +1,4 @@
-import { useAuthentication, useModalStore } from "@b3dotfun/sdk/global-account/react";
+import { useAuthentication, useB3Config, useModalStore } from "@b3dotfun/sdk/global-account/react";
 import { client } from "@b3dotfun/sdk/shared/utils/thirdweb";
 import { getSessionDurationDays, SESSION_DURATION_LABELS } from "@b3dotfun/sdk/shared/utils/session-duration";
 import { Loader2 } from "lucide-react";
@@ -19,6 +19,8 @@ const SettingsContent = ({
   onLogout?: () => void;
   chain: Chain;
 }) => {
+  const { authStrategy } = useB3Config();
+  const isBetterAuth = authStrategy === "better-auth";
   const setB3ModalContentType = useModalStore(state => state.setB3ModalContentType);
   const setB3ModalOpen = useModalStore(state => state.setB3ModalOpen);
   const { logout, user } = useAuthentication(partnerId);
@@ -69,19 +71,21 @@ const SettingsContent = ({
 
       {/* Menu Items */}
       <div className="space-y-3 px-5">
-        <SettingsMenuItem
-          icon={
-            <svg width="40" height="40" viewBox="0 0 40 40" fill="none" xmlns="http://www.w3.org/2000/svg">
-              <path
-                d="M0 12C0 5.37258 5.37258 0 12 0H28C34.6274 0 40 5.37258 40 12V28C40 34.6274 34.6274 40 28 40H12C5.37258 40 0 34.6274 0 28V12Z"
-                fill="#F4F4F5"
-              />
-            </svg>
-          }
-          title="Linked Accounts"
-          subtitle={`${profiles.length} connected account${profiles.length > 1 ? "s" : ""}`}
-          onClick={() => handleNavigate("linkAccount")}
-        />
+        {!isBetterAuth && (
+          <SettingsMenuItem
+            icon={
+              <svg width="40" height="40" viewBox="0 0 40 40" fill="none" xmlns="http://www.w3.org/2000/svg">
+                <path
+                  d="M0 12C0 5.37258 5.37258 0 12 0H28C34.6274 0 40 5.37258 40 12V28C40 34.6274 34.6274 40 28 40H12C5.37258 40 0 34.6274 0 28V12Z"
+                  fill="#F4F4F5"
+                />
+              </svg>
+            }
+            title="Linked Accounts"
+            subtitle={`${profiles.length} connected account${profiles.length > 1 ? "s" : ""}`}
+            onClick={() => handleNavigate("linkAccount")}
+          />
+        )}
         <SettingsMenuItem
           icon={
             <svg width="40" height="40" viewBox="0 0 40 40" fill="none" xmlns="http://www.w3.org/2000/svg">

package/src/global-account/react/components/ManageAccount/SettingsProfileCard.tsx

@@ -18,7 +18,8 @@ const SettingsProfileCard = () => {
     address: eoaAddress || account?.address,
     fresh: true,
   });
-  const { partnerId } = useB3Config();
+  const { partnerId, authStrategy } = useB3Config();
+  const isBetterAuth = authStrategy === "better-auth";
   const { user, setUser } = useAuthentication(partnerId);
   const setB3ModalOpen = useModalStore(state => state.setB3ModalOpen);
   const setB3ModalContentType = useModalStore(state => state.setB3ModalContentType);
@@ -78,25 +79,33 @@ const SettingsProfileCard = () => {
 
     setIsSaving(true);
     try {
-      const sanitizedUsername = ens_normalize(editedUsername.trim());
-      const b3Username = `${sanitizedUsername}.b3.fun`;
-      const usernameSignMessage = `Register "${b3Username}"`;
-      const usernameSignature = await account?.signMessage({ message: usernameSignMessage });
-
-      if (!usernameSignature) {
-        throw new Error("Failed to sign username registration message");
+      let updatedUser: Users;
+      if (isBetterAuth) {
+        // Better Auth: register username without wallet signing (DB-only, no ENS)
+        // Skip ens_normalize — it rejects underscores/mixed-case that are valid non-ENS usernames
+        const sanitizedUsername = editedUsername.trim().toLowerCase();
+        // Type assertion needed: b3-mono now accepts message/hash as optional for Better Auth users
+        updatedUser = (await app
+          .service("users")
+          .registerUsername({ username: sanitizedUsername } as any, {} as any)) as unknown as Users;
+      } else {
+        // Thirdweb: register username with wallet signature + on-chain ENS
+        const sanitizedUsername = ens_normalize(editedUsername.trim());
+        const b3Username = `${sanitizedUsername}.b3.fun`;
+        const usernameSignMessage = `Register "${b3Username}"`;
+        const usernameSignature = await account?.signMessage({ message: usernameSignMessage });
+
+        if (!usernameSignature) {
+          throw new Error("Failed to sign username registration message");
+        }
+
+        updatedUser = (await app
+          .service("users")
+          .registerUsername(
+            { username: sanitizedUsername, message: usernameSignMessage, hash: usernameSignature },
+            {} as any,
+          )) as unknown as Users;
       }
-
-      console.log("@@usernameSignature", usernameSignature);
-
-      // Register username with ENS
-      // Note: Type assertion needed until @b3dotfun/b3-api package is updated with RegisterUsername type
-      const updatedUser = (await app
-        .service("users")
-        .registerUsername(
-          { username: sanitizedUsername, message: usernameSignMessage, hash: usernameSignature },
-          {} as any,
-        )) as unknown as Users;
       // Update user state - registerUsername returns an array with single user
       setUser(Array.isArray(updatedUser) ? updatedUser[0] : updatedUser);
 
@@ -179,7 +188,7 @@ const SettingsProfileCard = () => {
           <>
             <div className="flex items-center gap-1">
               <p className="b3-modal-username font-neue-montreal-semibold text-lg leading-none text-[#0B57C2]">
-                {currentUsername}
+                {currentUsername || user?.email}
               </p>
             </div>
             <button

package/src/global-account/react/components/SignInWithB3/BetterAuthSignIn.tsx

@@ -33,6 +33,11 @@ export interface BetterAuthSignInProps {
   showEmail?: boolean;
   /** URL to redirect to after password reset link is clicked. Token is appended as ?token=... */
   passwordResetRedirectTo?: string;
+  /**
+   * URL Better Auth redirects to after server-side email verification. Render
+   * `BetterAuthVerifyEmail` at this route so the user gets a confirmation page.
+   */
+  verifyEmailRedirectTo?: string;
   /** Called after successful authentication */
   onSuccess?: () => void;
   /** Called on authentication error */
@@ -61,6 +66,7 @@ export function BetterAuthSignIn({
   socialProviders = DEFAULT_SOCIAL_PROVIDERS.map(p => p.id),
   showEmail = true,
   passwordResetRedirectTo,
+  verifyEmailRedirectTo,
   onSuccess,
   onError,
   className,
@@ -153,7 +159,7 @@ export function BetterAuthSignIn({
       setError(null);
 
       if (mode === "sign-up") {
-        await signUpWithEmail(normalizedEmail, password, name.trim());
+        await signUpWithEmail(normalizedEmail, password, name.trim(), verifyEmailRedirectTo);
       } else {
         await signInWithEmail(normalizedEmail, password);
       }

package/src/global-account/react/components/SignInWithB3/BetterAuthVerifyEmail.tsx

@@ -0,0 +1,155 @@
+import { Button } from "@b3dotfun/sdk/global-account/react";
+import { debugB3React } from "@b3dotfun/sdk/shared/utils/debug";
+
+const debug = debugB3React("BetterAuthVerifyEmail");
+
+export type BetterAuthVerifyEmailState = "success" | "expired" | "invalid" | "already-verified" | "error";
+
+export interface BetterAuthVerifyEmailProps {
+  /**
+   * Error code from the callback URL's `?error=` query param. Pass `null` /
+   * `undefined` when the user landed here cleanly (successful verification).
+   * Better Auth appends this param when server-side verification fails.
+   */
+  errorCode?: string | null;
+  /** Called when the user clicks the "Go to sign in" button. */
+  onGoToSignIn?: () => void;
+  /** Fallback href used when `onGoToSignIn` is not provided. Defaults to "/login". */
+  signInHref?: string;
+  /** Optional override for the success headline. */
+  successTitle?: string;
+  /** Optional override for the success body text. */
+  successMessage?: string;
+  /** Optional class name for the root container. */
+  className?: string;
+}
+
+function classifyError(code: string | null | undefined): BetterAuthVerifyEmailState {
+  if (!code) return "success";
+  const normalized = code.toLowerCase();
+
+  // Exact matches for Better Auth's documented verification error codes.
+  if (normalized === "expired_token") return "expired";
+  if (normalized === "invalid_token") return "invalid";
+  if (normalized === "already_verified" || normalized === "email_already_verified") return "already-verified";
+
+  // Loose fallbacks for close variants. Order matters — check "already" before
+  // "verified" so `email_already_verified` maps to already-verified, not invalid.
+  if (normalized.includes("expired")) return "expired";
+  if (normalized.includes("already")) return "already-verified";
+  if (normalized.includes("invalid")) return "invalid";
+  return "error";
+}
+
+const COPY: Record<BetterAuthVerifyEmailState, { title: string; message: string }> = {
+  success: {
+    title: "Email verified",
+    message: "Your email is confirmed. You can now sign in to your account.",
+  },
+  expired: {
+    title: "Link expired",
+    message: "This verification link has expired. Request a new one from the sign-in page.",
+  },
+  invalid: {
+    title: "Invalid link",
+    message: "This verification link is invalid or has already been used. Try signing in or request a new link.",
+  },
+  "already-verified": {
+    title: "Already verified",
+    message: "Your email was already confirmed. You can sign in now.",
+  },
+  error: {
+    title: "Verification failed",
+    message: "We couldn't verify your email. Request a new link from the sign-in page.",
+  },
+};
+
+/**
+ * Standalone email-verification confirmation page. Render on the route you
+ * set as `callbackURL` when calling `betterAuthClient.sendVerificationEmail`
+ * (or the `verifyCallbackURL` arg on `useBetterAuth().signUpWithEmail`).
+ *
+ * Better Auth verifies the token server-side before redirecting here. This
+ * component only displays the outcome based on the `?error=` query param.
+ *
+ * Usage:
+ * ```tsx
+ * const error = new URLSearchParams(window.location.search).get("error");
+ * <BetterAuthVerifyEmail
+ *   errorCode={error}
+ *   onGoToSignIn={() => router.push("/login")}
+ * />
+ * ```
+ */
+export function BetterAuthVerifyEmail({
+  errorCode,
+  onGoToSignIn,
+  signInHref = "/login",
+  successTitle,
+  successMessage,
+  className,
+}: BetterAuthVerifyEmailProps) {
+  const state = classifyError(errorCode);
+  const isSuccess = state === "success" || state === "already-verified";
+  const copy = COPY[state];
+  const title = isSuccess && successTitle ? successTitle : copy.title;
+  const message = isSuccess && successMessage ? successMessage : copy.message;
+
+  debug("Rendering verify-email state", { state, errorCode });
+
+  const handleClick = () => {
+    if (onGoToSignIn) {
+      onGoToSignIn();
+      return;
+    }
+    if (typeof window !== "undefined") {
+      window.location.href = signInHref;
+    }
+  };
+
+  return (
+    <div className={`w-full max-w-[400px] px-6 ${className || ""}`}>
+      <div className="space-y-6 text-center">
+        <div
+          className={`mx-auto flex h-12 w-12 items-center justify-center rounded-full ${
+            isSuccess ? "bg-green-100" : "bg-red-100"
+          }`}
+        >
+          {isSuccess ? (
+            <svg
+              className="h-6 w-6 text-green-600"
+              fill="none"
+              viewBox="0 0 24 24"
+              stroke="currentColor"
+              aria-hidden="true"
+            >
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
+            </svg>
+          ) : (
+            <svg
+              className="h-6 w-6 text-red-600"
+              fill="none"
+              viewBox="0 0 24 24"
+              stroke="currentColor"
+              aria-hidden="true"
+            >
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
+            </svg>
+          )}
+        </div>
+
+        <div>
+          <h1 className="text-[28px] font-semibold tracking-tight text-gray-900 dark:text-gray-100">{title}</h1>
+          <p className="mt-3 text-[15px] text-gray-500 dark:text-gray-400">{message}</p>
+        </div>
+
+        <Button
+          onClick={handleClick}
+          className="h-11 w-full bg-gray-900 text-[15px] font-medium text-white hover:bg-gray-800 dark:bg-white dark:text-gray-900 dark:hover:bg-gray-100"
+        >
+          {isSuccess ? "Go to sign in" : "Back to sign in"}
+        </Button>
+      </div>
+    </div>
+  );
+}