@livo-build/kit 0.2.1 → 0.2.3

package/dist/data/index.d.ts

@@ -1,4 +1,4 @@
-export { useApi, apiClient, type QueryResult, type UseApiOptions } from "./useApi";
+export { useApi, apiClient, setApiAuthToken, type QueryResult, type UseApiOptions } from "./useApi";
 export { useSubgraph, type UseSubgraphArgs } from "./useSubgraph";
 export { Async, type AsyncProps, type AsyncQuery } from "./Async";
 export { useCollection, processCollection, type Collection, type CollectionConfig, type SortState, type SortDir, } from "./useCollection";

package/dist/data/index.js

@@ -1,4 +1,4 @@
-export { useApi, apiClient } from "./useApi";
+export { useApi, apiClient, setApiAuthToken } from "./useApi";
 export { useSubgraph } from "./useSubgraph";
 export { Async } from "./Async";
 export { useCollection, processCollection, } from "./useCollection";

package/dist/data/useApi.d.ts

@@ -5,6 +5,8 @@ export interface QueryResult<T> {
     isError: boolean;
     refetch: () => void;
 }
+/** Set (or clear, with null) the bearer token sent on every same-origin api call. */
+export declare function setApiAuthToken(token: string | null): void;
 export interface UseApiOptions {
     enabled?: boolean;
     init?: RequestInit;

package/dist/data/useApi.js

@@ -1,10 +1,25 @@
 import { useQuery } from "@tanstack/react-query";
+// A bearer token applied to every same-origin api call (set by useTelegramLogin /
+// any session hook). Sent as `Authorization: Bearer <token>` unless the call already
+// supplies that header. `setApiAuthToken(null)` clears it (on logout).
+let apiAuthToken = null;
+/** Set (or clear, with null) the bearer token sent on every same-origin api call. */
+export function setApiAuthToken(token) {
+    apiAuthToken = token;
+}
 // Call a Livo same-origin api/ backend ({slug}.livo.build/api/*). Paths are
 // resolved under /api, so `useApi("/health")` hits /api/health — zero CORS, keys
 // stay server-side. JSON in/out; a non-2xx throws with the body's `error` if present.
 async function apiFetch(path, init) {
     const p = path.startsWith("/api") ? path : "/api" + (path.startsWith("/") ? path : "/" + path);
-    const res = await fetch(p, init);
+    let finalInit = init;
+    if (apiAuthToken) {
+        const headers = new Headers(init?.headers);
+        if (!headers.has("authorization"))
+            headers.set("authorization", `Bearer ${apiAuthToken}`);
+        finalInit = { ...init, headers };
+    }
+    const res = await fetch(p, finalInit);
     const text = await res.text();
     let body = null;
     try {

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from "./provider";
 export * from "./contracts";
 export * from "./tx";
 export * from "./auth";
+export * from "./verify";
 export * from "./toast";
 export * from "./data";
 export * from "./web3";

package/dist/index.js

@@ -7,6 +7,8 @@
 //   contracts/ — useContractValue, createLivoContracts (bound to Livo's generated bindings)
 //   tx/        — useTx, TxButton, TxProgress, decodeRevert
 //   auth/      — useSiwe, SignInWithEthereum (Sign-In With Ethereum vs a same-origin /api/auth)
+//   verify/    — useWalletVerify, WalletVerifyButton (prove wallet ownership by signing an
+//                app-specific message → POST to a backend; the frontend half of runtime Gatekeeper)
 //   toast/     — ToastProvider, useToast
 //   data/      — useApi, useSubgraph, useCollection + DataTable (search/sort/paginate), useEventSource/useWebSocket (realtime)
 //   web3/      — Address, Balance, NetworkGuard, TokenAmount(Input)
@@ -17,8 +19,9 @@
 //   hyperliquid/ — useHlPrice/Mids/Candles/OrderBook/Positions, PriceTicker (public market data, no key)
 //   account/   — Connected, Disconnected, RequireConnection, useIsConnected, Avatar, Identity
 //   ui/        — Dialog, Card, Skeleton, Spinner, EmptyState, CopyButton, Countdown
-//   telegram/  — useTelegramMiniApp, useTelegramLink, LinkTelegramButton, useTelegramTheme,
-//                useTelegramMainButton/BackButton/Haptics (Mini App + wallet ↔ Telegram linking)
+//   telegram/  — useTelegramLogin/TelegramLoginButton (bot-driven web login, no wallet),
+//                useTelegramMiniApp, useTelegramLink, LinkTelegramButton, useTelegramTheme,
+//                useTelegramMainButton/BackButton/Haptics (login + Mini App + wallet ↔ Telegram linking)
 //   theme/     — KitThemeProvider (restyle the whole kit from one theme object)
 //   polymarket/ — useMarkets/useMarket/useMarketTrades/useOrderbook/usePriceHistory/usePlaceOrder,
 //                 MarketsList/MarketCard/OddsBar/OrderTicket (prediction markets via Livo's indexer)
@@ -29,6 +32,7 @@ export * from "./provider";
 export * from "./contracts";
 export * from "./tx";
 export * from "./auth";
+export * from "./verify";
 export * from "./toast";
 export * from "./data";
 export * from "./web3";

package/dist/telegram/TelegramGate.d.ts

@@ -0,0 +1,10 @@
+import type { ReactNode } from "react";
+import { type UseTelegramLoginOptions, type TelegramLoginUser } from "./useTelegramLogin";
+export interface TelegramGateProps extends UseTelegramLoginOptions {
+    /** Shown once the visitor is signed in. A function receives the verified user. */
+    children: ReactNode | ((user: TelegramLoginUser | undefined) => ReactNode);
+    /** Optional override for the signed-out view (defaults to a <TelegramLoginButton />). */
+    fallback?: ReactNode;
+    className?: string;
+}
+export declare function TelegramGate({ children, fallback, className, ...opts }: TelegramGateProps): import("react").JSX.Element;

package/dist/telegram/TelegramGate.js

@@ -0,0 +1,14 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useTelegramLogin } from "./useTelegramLogin";
+import { TelegramLoginButton } from "./TelegramLoginButton";
+// Drop-in "you must log in with Telegram to see this" wrapper — the whole flow in one
+// component. Renders `children` when the visitor is authenticated, otherwise a
+// "Continue with Telegram" button (or your `fallback`). For more control, build on
+// useTelegramLogin directly. Secure by default (HttpOnly cookie session).
+export function TelegramGate({ children, fallback, className, ...opts }) {
+    const { status, user } = useTelegramLogin(opts);
+    if (status === "authenticated") {
+        return _jsx(_Fragment, { children: typeof children === "function" ? children(user) : children });
+    }
+    return (_jsx("div", { className: className, "data-state": status, children: fallback ?? _jsx(TelegramLoginButton, { ...opts }) }));
+}

package/dist/telegram/TelegramLoginButton.d.ts

@@ -0,0 +1,15 @@
+import "./telegram.css";
+import { type UseTelegramLoginOptions } from "./useTelegramLogin";
+export interface TelegramLoginButtonProps extends UseTelegramLoginOptions {
+    className?: string;
+    labels?: {
+        login?: string;
+        starting?: string;
+        open?: string;
+        authenticated?: (user?: {
+            username?: string;
+            id: number;
+        }) => string;
+    };
+}
+export declare function TelegramLoginButton({ className, labels, ...opts }: TelegramLoginButtonProps): import("react").JSX.Element;

package/dist/telegram/TelegramLoginButton.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import "./telegram.css";
+import { useTelegramLogin } from "./useTelegramLogin";
+import { cx } from "../util";
+// One button for the whole "Login with Telegram" lifecycle: "Continue with Telegram"
+// → (open web) an "Open Telegram" deep link plus the match code to confirm in the bot
+// → an authenticated chip (tap to sign out). Inside a Mini App it logs in instantly.
+// Neutral; style via .kit-tg / [data-state]. Build your own on useTelegramLogin for
+// full control.
+export function TelegramLoginButton({ className, labels, ...opts }) {
+    const { status, user, deepLink, matchCode, login, logout, error } = useTelegramLogin(opts);
+    if (status === "authenticated") {
+        const who = user?.username ? `@${user.username}` : user?.id ? `#${user.id}` : "";
+        return (_jsx("button", { className: cx("kit-tg", className), "data-state": "linked", onClick: () => logout(), children: labels?.authenticated ? labels.authenticated(user) : `Telegram ${who} ✓` }));
+    }
+    if (status === "awaiting" && deepLink) {
+        return (_jsxs("span", { className: cx("kit-tg-await", className), children: [_jsx("a", { className: "kit-tg", "data-state": "open", href: deepLink, target: "_blank", rel: "noreferrer", children: labels?.open ?? "Open Telegram to confirm" }), matchCode ? (_jsxs("small", { className: "kit-tg-code", children: ["Confirm code ", _jsx("code", { children: matchCode }), " in the bot"] })) : null] }));
+    }
+    const busy = status === "starting";
+    return (_jsx("button", { className: cx("kit-tg", className), "data-state": status === "error" ? "error" : status, disabled: busy, onClick: () => login(), title: error?.message, children: busy ? (labels?.starting ?? "Starting…") : (labels?.login ?? "Continue with Telegram") }));
+}

package/dist/telegram/index.d.ts

@@ -1,5 +1,8 @@
 export { useTelegramMiniApp, type TelegramMiniApp } from "./useTelegramMiniApp";
 export { useTelegramLink, type TelegramLinkState, type LinkStatus, type LinkedTelegram, type UseTelegramLinkOptions, } from "./useTelegramLink";
 export { LinkTelegramButton, type LinkTelegramButtonProps } from "./LinkTelegramButton";
+export { useTelegramLogin, type TelegramLoginState, type TelegramLoginStatus, type TelegramLoginUser, type TelegramSessionTransport, type UseTelegramLoginOptions, } from "./useTelegramLogin";
+export { TelegramLoginButton, type TelegramLoginButtonProps } from "./TelegramLoginButton";
+export { TelegramGate, type TelegramGateProps } from "./TelegramGate";
 export { useTelegramTheme } from "./useTelegramTheme";
 export { useTelegramMainButton, useTelegramBackButton, useTelegramHaptics, type MainButtonOptions, type Haptics, } from "./miniapp";

package/dist/telegram/index.js

@@ -1,5 +1,8 @@
 export { useTelegramMiniApp } from "./useTelegramMiniApp";
 export { useTelegramLink, } from "./useTelegramLink";
 export { LinkTelegramButton } from "./LinkTelegramButton";
+export { useTelegramLogin, } from "./useTelegramLogin";
+export { TelegramLoginButton } from "./TelegramLoginButton";
+export { TelegramGate } from "./TelegramGate";
 export { useTelegramTheme } from "./useTelegramTheme";
 export { useTelegramMainButton, useTelegramBackButton, useTelegramHaptics, } from "./miniapp";

package/dist/telegram/telegram.css

@@ -3,4 +3,8 @@
 .kit-tg:active{transform:translateY(1px)}
 .kit-tg:disabled{opacity:.6;cursor:default}
 .kit-tg[data-state="linked"]{background:var(--kit-row,#f3f4f6);color:var(--kit-fg,#111827)}
+.kit-tg[data-state="error"]{background:var(--kit-danger,#dc2626);color:#fff}
 @media (prefers-color-scheme:dark){.kit-tg[data-state="linked"]{--kit-row:#27272c;--kit-fg:#f5f5f7}}
+.kit-tg-await{display:inline-flex;flex-direction:column;align-items:center;gap:6px}
+.kit-tg-code{color:var(--kit-muted,#6b7280);font-size:12px}
+.kit-tg-code code{background:var(--kit-row,#f3f4f6);padding:1px 6px;border-radius:6px;font-weight:700;letter-spacing:1px}

package/dist/telegram/useTelegramLogin.d.ts

@@ -0,0 +1,43 @@
+export type TelegramLoginStatus = "anon" | "starting" | "awaiting" | "authenticated" | "error";
+export type TelegramSessionTransport = "cookie" | "bearer";
+export interface TelegramLoginUser {
+    id: number;
+    username?: string;
+    firstName?: string;
+}
+export interface TelegramLoginState {
+    status: TelegramLoginStatus;
+    /** The verified Telegram identity, once authenticated. */
+    user?: TelegramLoginUser;
+    /** The signed session token — bearer transport only (cookie mode never exposes it to JS). */
+    token?: string;
+    /** Open-web flow: the t.me deep link to open the bot. */
+    deepLink?: string;
+    /** Short code shown on this page — the user confirms it matches the one the bot shows. */
+    matchCode?: string;
+    /** Begin a login. On a normal website this opens the bot; inside Telegram it's instant. */
+    login: () => Promise<void>;
+    /** Sign out — clears the session (cookie or stored token). */
+    logout: () => void;
+    error?: Error;
+}
+export interface UseTelegramLoginOptions {
+    /** Base path for the login API (default "/api/telegram/login"). */
+    endpoint?: string;
+    /**
+     * How the session is delivered. "cookie" (default) keeps the token out of JS — the
+     * server sets an HttpOnly cookie and the hook hydrates via the `/me` route; immune to
+     * XSS token theft (needs the api same-origin with the page, true on Livo). "bearer"
+     * stores the token in localStorage and attaches it to useApi calls (works cross-origin).
+     */
+    transport?: TelegramSessionTransport;
+    /** "who am I" route for cookie-mode hydration (default `${endpoint}/me`). */
+    meEndpoint?: string;
+    /** localStorage key for the session (bearer transport only; default "livo.tg.session"). */
+    storageKey?: string;
+    /** Poll interval while waiting for the bot confirmation (default 2500ms). */
+    pollIntervalMs?: number;
+    /** Open the deep link automatically when login() starts (default true). */
+    autoOpen?: boolean;
+}
+export declare function useTelegramLogin(options?: UseTelegramLoginOptions): TelegramLoginState;

package/dist/telegram/useTelegramLogin.js

@@ -0,0 +1,184 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useTelegramMiniApp } from "./useTelegramMiniApp";
+import { setApiAuthToken } from "../data/useApi";
+function loadSession(key) {
+    if (typeof window === "undefined")
+        return null;
+    try {
+        const raw = window.localStorage.getItem(key);
+        return raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
+// "Login with Telegram" for any web frontend — the user authenticates just by tapping
+// your bot; no wallet, no password. On a normal website it opens a t.me deep link and
+// polls until the user confirms in the bot (a match code defeats link-forwarding
+// hijacks); inside a Telegram Mini App it verifies the signed initData instantly. The
+// server (your api/) runs @livo-build/runtime's TelegramLogin and issues the session.
+//
+// Cookie transport (default) is the secure path: the session lives in an HttpOnly
+// cookie the page JS never sees, so it can't be stolen via XSS — the hook learns who
+// you are from the `/me` route. Switch to "bearer" only when the api is on a different
+// origin; then the token is stored in localStorage and auto-attached to useApi calls.
+export function useTelegramLogin(options = {}) {
+    const base = options.endpoint ?? "/api/telegram/login";
+    const transport = options.transport ?? "cookie";
+    const meEndpoint = options.meEndpoint ?? `${base}/me`;
+    const storageKey = options.storageKey ?? "livo.tg.session";
+    const pollMs = options.pollIntervalMs ?? 2500;
+    const autoOpen = options.autoOpen ?? true;
+    const mini = useTelegramMiniApp();
+    const [status, setStatus] = useState("anon");
+    const [user, setUser] = useState();
+    const [token, setToken] = useState();
+    const [deepLink, setDeepLink] = useState();
+    const [matchCode, setMatchCode] = useState();
+    const [error, setError] = useState();
+    const pollRef = useRef(null);
+    const stopPoll = () => {
+        if (pollRef.current) {
+            clearInterval(pollRef.current);
+            pollRef.current = null;
+        }
+    };
+    const authenticated = useCallback((who, tok) => {
+        stopPoll();
+        setUser(who);
+        setStatus("authenticated");
+        setDeepLink(undefined);
+        setMatchCode(undefined);
+        if (transport === "bearer" && tok) {
+            // Bearer: persist the token and attach it to every same-origin api call.
+            setApiAuthToken(tok);
+            setToken(tok);
+            if (typeof window !== "undefined") {
+                try {
+                    window.localStorage.setItem(storageKey, JSON.stringify({ token: tok, user: who }));
+                }
+                catch {
+                    /* storage may be unavailable (private mode) — session still lives in memory */
+                }
+            }
+        }
+        // Cookie: nothing to store — the HttpOnly cookie is already set by the server.
+    }, [transport, storageKey]);
+    // Restore a session on mount: cookie mode asks the server (/me); bearer reads storage.
+    useEffect(() => {
+        let cancelled = false;
+        if (transport === "cookie") {
+            (async () => {
+                try {
+                    const r = await fetch(meEndpoint, { credentials: "same-origin" });
+                    if (!r.ok)
+                        return;
+                    const j = (await r.json());
+                    if (!cancelled && j.user) {
+                        setUser(j.user);
+                        setStatus("authenticated");
+                    }
+                }
+                catch {
+                    /* not signed in / offline — stay anon */
+                }
+            })();
+        }
+        else {
+            const saved = loadSession(storageKey);
+            if (saved?.token) {
+                setApiAuthToken(saved.token);
+                setToken(saved.token);
+                setUser(saved.user);
+                setStatus("authenticated");
+            }
+        }
+        return () => {
+            cancelled = true;
+            stopPoll();
+        };
+    }, [transport, meEndpoint, storageKey]);
+    const logout = useCallback(() => {
+        stopPoll();
+        setUser(undefined);
+        setStatus("anon");
+        setDeepLink(undefined);
+        setMatchCode(undefined);
+        if (transport === "bearer") {
+            setApiAuthToken(null);
+            setToken(undefined);
+            if (typeof window !== "undefined") {
+                try {
+                    window.localStorage.removeItem(storageKey);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+        else {
+            // Cookie: ask the server to clear the HttpOnly cookie.
+            void fetch(`${base}/logout`, { method: "POST", credentials: "same-origin" }).catch(() => { });
+        }
+    }, [transport, base, storageKey]);
+    const login = useCallback(async () => {
+        setError(undefined);
+        setStatus("starting");
+        try {
+            // Inside Telegram (Mini App): we already have signed initData — verify it directly.
+            if (mini.available && mini.initData) {
+                const r = await fetch(`${base}/miniapp`, {
+                    method: "POST",
+                    credentials: "same-origin",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ initData: mini.initData }),
+                });
+                const j = (await r.json());
+                if (!r.ok || j.status !== "authenticated")
+                    throw new Error(j.error ?? "Telegram login failed");
+                authenticated(j.user, j.token);
+                return;
+            }
+            // Normal website: create a challenge, open the bot, poll until confirmed.
+            const startRes = await fetch(`${base}/start`, {
+                method: "POST",
+                credentials: "same-origin",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ origin: typeof window !== "undefined" ? window.location.origin : undefined }),
+            });
+            const start = (await startRes.json());
+            if (!startRes.ok || !start.code || !start.deepLink)
+                throw new Error(start.error ?? "Could not start login");
+            setDeepLink(start.deepLink);
+            setMatchCode(start.matchCode);
+            setStatus("awaiting");
+            if (autoOpen && typeof window !== "undefined")
+                window.open(start.deepLink, "_blank", "noopener");
+            const code = start.code;
+            stopPoll();
+            pollRef.current = setInterval(async () => {
+                try {
+                    const r = await fetch(`${base}/poll?code=${encodeURIComponent(code)}`, { credentials: "same-origin" });
+                    const j = (await r.json());
+                    if (j.status === "authenticated") {
+                        authenticated(j.user, j.token);
+                    }
+                    else if (j.status === "expired" || j.status === "unknown" || j.status === "used") {
+                        stopPoll();
+                        setStatus("error");
+                        setError(new Error("Login expired — tap to try again."));
+                    }
+                }
+                catch {
+                    /* transient network error — keep polling */
+                }
+            }, pollMs);
+        }
+        catch (e) {
+            stopPoll();
+            setError(e);
+            setStatus("error");
+        }
+    }, [base, mini.available, mini.initData, autoOpen, pollMs, authenticated]);
+    return { status, user, token, deepLink, matchCode, login, logout, error };
+}

package/dist/verify/WalletVerifyButton.d.ts

@@ -0,0 +1,17 @@
+import "../wallet/wallet.css";
+import { type ReactNode } from "react";
+import { type UseWalletVerifyOptions, type WalletVerifyState } from "./useWalletVerify";
+export interface WalletVerifyButtonProps extends UseWalletVerifyOptions {
+    className?: string;
+    /** Override the button copy per state. */
+    labels?: {
+        idle?: string;
+        signing?: string;
+        verifying?: string;
+        verified?: string;
+        error?: string;
+    };
+    /** Custom render — receives the full hook state. */
+    children?: (api: WalletVerifyState) => ReactNode;
+}
+export declare function WalletVerifyButton({ className, labels, children, ...opts }: WalletVerifyButtonProps): import("react").JSX.Element;

package/dist/verify/WalletVerifyButton.js

@@ -0,0 +1,31 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import "../wallet/wallet.css";
+import {} from "react";
+import { useWalletVerify } from "./useWalletVerify";
+import { ConnectWallet } from "../wallet";
+import { useIsConnected } from "../account";
+import { cx } from "../util";
+// Drop-in: prompts a wallet connect if needed, then runs connect → sign → verify and
+// reflects the result. Reuses the wallet-connect button styling (wm-cta / wm-account).
+// Pair with the runtime `Gatekeeper` (set `endpoint` to your verifyAndLink route).
+export function WalletVerifyButton({ className, labels, children, ...opts }) {
+    const v = useWalletVerify(opts);
+    const connected = useIsConnected();
+    if (children)
+        return _jsx(_Fragment, { children: children(v) });
+    // Not connected yet — let the user connect first (the proof needs a wallet).
+    if (!connected)
+        return _jsx(ConnectWallet, {});
+    if (v.status === "verified") {
+        return (_jsx("button", { className: cx("wm-account", className), disabled: true, children: labels?.verified ?? "Verified ✓" }));
+    }
+    const busy = v.status === "signing" || v.status === "verifying";
+    const label = v.status === "signing"
+        ? labels?.signing ?? "Check your wallet…"
+        : v.status === "verifying"
+            ? labels?.verifying ?? "Verifying…"
+            : v.status === "error"
+                ? labels?.error ?? "Try again"
+                : labels?.idle ?? "Verify wallet";
+    return (_jsx("button", { className: cx("wm-cta", className), disabled: busy, onClick: () => (v.status === "error" ? v.reset() : void v.verify()), children: label }));
+}

package/dist/verify/index.d.ts

@@ -0,0 +1,2 @@
+export { useWalletVerify, buildVerifyMessage, isVerifySuccess, DEFAULT_VERIFY_MESSAGE_PREFIX, type UseWalletVerifyOptions, type WalletVerifyState, type WalletVerifyStatus, type WalletVerifyResult, } from "./useWalletVerify";
+export { WalletVerifyButton, type WalletVerifyButtonProps } from "./WalletVerifyButton";

package/dist/verify/index.js

@@ -0,0 +1,2 @@
+export { useWalletVerify, buildVerifyMessage, isVerifySuccess, DEFAULT_VERIFY_MESSAGE_PREFIX, } from "./useWalletVerify";
+export { WalletVerifyButton } from "./WalletVerifyButton";

package/dist/verify/useWalletVerify.d.ts

@@ -0,0 +1,68 @@
+export type WalletVerifyStatus = "idle" | "signing" | "verifying" | "verified" | "error";
+/** Whatever the backend returns from the verify route (ok + any extra fields). */
+export interface WalletVerifyResult {
+    ok: boolean;
+    address?: string;
+    [key: string]: unknown;
+}
+export interface UseWalletVerifyOptions {
+    /**
+     * POST endpoint that verifies the signature + records the proof (default
+     * "/api/verify"). Mirrors the backend `Gatekeeper.verifyAndLink` route — it
+     * receives `{ nonce, address, signature }` and returns `{ ok, ... }`. When
+     * pairing with the `wallet-link-bot` template (which serves it at `/link`), set
+     * `endpoint: "/link"`.
+     */
+    endpoint?: string;
+    /**
+     * The challenge nonce. Defaults to the `?n=` query param — the backend
+     * `Gatekeeper.challenge()` embeds it in the link URL it DMs the user. Pass it
+     * explicitly, or use `nonceEndpoint` to have the frontend mint one.
+     */
+    nonce?: string;
+    /** GET endpoint that mints a nonce (and optionally the exact message) → `{ nonce, message? }`. */
+    nonceEndpoint?: string;
+    /**
+     * Prefix prepended to the nonce to form the signed message. MUST match the
+     * backend `Gatekeeper`'s `messagePrefix` byte-for-byte. Default matches the
+     * Gatekeeper default — override on BOTH sides to make the text app-specific.
+     */
+    messagePrefix?: string;
+    /** Full control of the signed text (overrides messagePrefix). A server-supplied message wins. */
+    message?: string | ((address: string, nonce: string) => string);
+    /** Send cookies with the verify POST (for a session-issuing backend). */
+    credentials?: boolean;
+    onVerified?: (result: WalletVerifyResult) => void;
+    onError?: (error: Error) => void;
+}
+export interface WalletVerifyState {
+    status: WalletVerifyStatus;
+    /** The connected wallet address (the one being proven). */
+    address?: string;
+    /** The nonce used for the current/last attempt. */
+    nonce?: string;
+    /** The backend's response on success. */
+    result?: WalletVerifyResult;
+    /** Connect-aware: false until a wallet is connected. */
+    ready: boolean;
+    verify: () => Promise<void>;
+    reset: () => void;
+    error?: Error;
+}
+/** The default signed-message prefix — matches the runtime `Gatekeeper` default. */
+export declare const DEFAULT_VERIFY_MESSAGE_PREFIX = "Link my wallet to this community \u00B7 nonce: ";
+/**
+ * Build the exact text to sign. A server-supplied message wins (guaranteed match);
+ * otherwise `message` (string or fn), otherwise `messagePrefix + nonce`. Pure —
+ * exported for testing and so callers can preview the message.
+ */
+export declare function buildVerifyMessage(opts: Pick<UseWalletVerifyOptions, "message" | "messagePrefix">, address: string, nonce: string, serverMessage?: string): string;
+/** Read success out of a verify response, accepting ok/verified/linked. Pure — tested. */
+export declare function isVerifySuccess(httpOk: boolean, json: Record<string, unknown>): boolean;
+/**
+ * Prove the connected wallet owns an address by signing an app-specific message and
+ * POSTing the proof to your backend (the frontend half of the runtime `Gatekeeper`:
+ * connect → sign(messagePrefix + nonce) → verifyAndLink). No gas, no transaction.
+ * Use `<WalletVerifyButton>` for a drop-in button, or this hook for custom UI.
+ */
+export declare function useWalletVerify(options?: UseWalletVerifyOptions): WalletVerifyState;

package/dist/verify/useWalletVerify.js

@@ -0,0 +1,104 @@
+import { useCallback, useState } from "react";
+import { useConnection, useSignMessage } from "wagmi";
+/** The default signed-message prefix — matches the runtime `Gatekeeper` default. */
+export const DEFAULT_VERIFY_MESSAGE_PREFIX = "Link my wallet to this community · nonce: ";
+/** Read the `?n=` nonce from the page URL (browser only). */
+function nonceFromUrl() {
+    if (typeof window === "undefined")
+        return undefined;
+    return new URLSearchParams(window.location.search).get("n") ?? undefined;
+}
+/**
+ * Build the exact text to sign. A server-supplied message wins (guaranteed match);
+ * otherwise `message` (string or fn), otherwise `messagePrefix + nonce`. Pure —
+ * exported for testing and so callers can preview the message.
+ */
+export function buildVerifyMessage(opts, address, nonce, serverMessage) {
+    if (serverMessage)
+        return serverMessage;
+    if (typeof opts.message === "function")
+        return opts.message(address, nonce);
+    if (typeof opts.message === "string")
+        return opts.message;
+    return (opts.messagePrefix ?? DEFAULT_VERIFY_MESSAGE_PREFIX) + nonce;
+}
+/** Read success out of a verify response, accepting ok/verified/linked. Pure — tested. */
+export function isVerifySuccess(httpOk, json) {
+    return httpOk && (json.ok === true || json.verified === true || json.linked === true);
+}
+/**
+ * Prove the connected wallet owns an address by signing an app-specific message and
+ * POSTing the proof to your backend (the frontend half of the runtime `Gatekeeper`:
+ * connect → sign(messagePrefix + nonce) → verifyAndLink). No gas, no transaction.
+ * Use `<WalletVerifyButton>` for a drop-in button, or this hook for custom UI.
+ */
+export function useWalletVerify(options = {}) {
+    const base = options.endpoint ?? "/api/verify";
+    const { address } = useConnection();
+    const { signMessageAsync } = useSignMessage();
+    const [status, setStatus] = useState("idle");
+    const [nonce, setNonce] = useState();
+    const [result, setResult] = useState();
+    const [error, setError] = useState();
+    const verify = useCallback(async () => {
+        if (!address) {
+            const e = new Error("Connect a wallet first.");
+            setError(e);
+            setStatus("error");
+            options.onError?.(e);
+            return;
+        }
+        setStatus("signing");
+        setError(undefined);
+        try {
+            // 1) Resolve the nonce: explicit option → ?n= link → mint from nonceEndpoint.
+            let n = options.nonce ?? nonceFromUrl();
+            let serverMessage;
+            if (!n && options.nonceEndpoint) {
+                const nr = await fetch(`${options.nonceEndpoint}?address=${address}`, {
+                    credentials: options.credentials ? "include" : "same-origin",
+                });
+                const nj = (await nr.json());
+                n = nj.nonce;
+                serverMessage = nj.message;
+            }
+            if (!n) {
+                throw new Error("No challenge nonce — pass `nonce`, open via a `?n=` link, or set `nonceEndpoint`.");
+            }
+            setNonce(n);
+            // 2) Sign the app-specific message (must match the backend's reconstruction).
+            const msg = buildVerifyMessage(options, address, n, serverMessage);
+            const signature = await signMessageAsync({ message: msg });
+            // 3) POST the proof to the backend (Gatekeeper.verifyAndLink).
+            setStatus("verifying");
+            const res = await fetch(base, {
+                method: "POST",
+                credentials: options.credentials ? "include" : "same-origin",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ nonce: n, address, signature }),
+            });
+            const j = (await res.json().catch(() => ({})));
+            if (!isVerifySuccess(res.ok, j)) {
+                throw new Error(j.error ?? "Verification failed");
+            }
+            const out = { ok: true, address, ...j };
+            setResult(out);
+            setStatus("verified");
+            options.onVerified?.(out);
+        }
+        catch (e) {
+            setError(e);
+            setStatus("error");
+            options.onError?.(e);
+        }
+        // options is intentionally read fresh each call (callbacks/config may change).
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [address, base, signMessageAsync]);
+    const reset = useCallback(() => {
+        setStatus("idle");
+        setNonce(undefined);
+        setResult(undefined);
+        setError(undefined);
+    }, []);
+    return { status, address, nonce, result, ready: Boolean(address), verify, reset, error };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livo-build/kit",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Livo frontend kit — reusable React + wagmi v3 building blocks (wallet connect modal, providers, hooks) for web3 apps built on Livo.",
   "type": "module",
   "license": "UNLICENSED",