@livo-build/kit 0.1.0 → 0.1.1

package/README.md

@@ -102,16 +102,56 @@ const { data } = useSubgraph({ url, query: GET_ITEMS });  // your indexer's grap
 <Card/>  <Skeleton width={120}/>  <Spinner/>  <EmptyState title="Nothing yet"/>  <CopyButton value={addr}/>
 ```
 
+## Theme it from one object
+
+```tsx
+<KitThemeProvider theme={{ accent: "#6d28d9", radius: 16 }}>
+  {/* every kit component beneath inherits the brand */}
+</KitThemeProvider>
+```
+
+## Accounts, tokens, approvals
+
+```tsx
+<RequireConnection>{/* shown only when connected; else a connect prompt */}</RequireConnection>
+<Connected><Identity address={addr} /></Connected>   <Avatar address={addr} />
+
+const { symbol, decimals } = useToken(token);
+const { enough } = useAllowance({ token, owner, spender });
+<ApproveButton token={token} spender={spender} amount={amt} />   // approve → toast → done
+```
+
+## Link a wallet to Telegram
+
+For apps that have both a Telegram bot and a web instance — verify the same person on both.
+
+```tsx
+<LinkTelegramButton />                    // Mini App: uses verified initData; web: bot deep-link
+const { status, telegram, link } = useTelegramLink();   // headless
+const mini = useTelegramMiniApp();        // { available, initData, user } when open inside Telegram
+```
+
+The hook talks to your `api/` (same-origin), which verifies both proofs with
+`@livo-build/runtime` (`verifyTelegramInitData` + a signed-nonce check) and writes
+the binding to D1 (`TelegramLinks`). Endpoints it expects under `endpoint` (default
+`/api/telegram`): `GET /nonce`, `GET /status`, `POST /link` (Mini App), `POST /start`
+(web deep-link), `POST /unlink`. (Livo's `telegram-app` blueprint scaffolds these.)
+
 ## Exports
 
 - **wallet** — `ConnectWallet`, `WalletModal`, `useWalletConnectors`
+- **telegram** — `LinkTelegramButton`, `useTelegramLink`, `useTelegramMiniApp`
 - **provider** — `LivoWeb3Provider`
-- **contracts** — `createLivoContracts`, `useContractValue`, `resolveAddress`
+- **contracts** — `createLivoContracts`, `useContractValue`, `useContractEvent`, `resolveAddress`
 - **tx** — `TxButton`, `useTx`, `decodeRevert`
 - **toast** — `ToastProvider`, `useToast`
-- **data** — `useApi`, `apiClient`, `useSubgraph`
-- **web3** — `Address`, `Balance`, `NetworkGuard`, `TokenAmountInput`
-- **ui** — `Dialog`, `Card`, `Skeleton`, `Spinner`, `EmptyState`, `CopyButton`
+- **data** — `useApi`, `apiClient`, `useSubgraph`, `Async`
+- **token** — `useToken`, `useAllowance`, `useApprove`, `ApproveButton`
+- **account** — `Connected`, `Disconnected`, `RequireConnection`, `useIsConnected`, `Avatar`, `Identity`
+- **web3** — `Address`, `Balance`, `NetworkGuard`, `TokenAmountInput`, `ChainSwitcher`, `AddressInput`
+- **ui** — `Dialog`, `Card`, `Skeleton`, `Spinner`, `EmptyState`, `CopyButton`, `Button`, `Badge`
+- **theme** — `KitThemeProvider`
+- **hooks** — `useCopyToClipboard`, `useLocalStorage`, `useDebounce`, `useInterval`
 - **format** — `shortAddress`, `shortHash`, `formatToken`, `parseToken`, `formatUsd`, `timeAgo`, `avatarGradient`
 
 Every component is neutral by default — **style it** (see [STYLING.md](./STYLING.md)).

package/dist/account/Avatar.d.ts

@@ -0,0 +1,9 @@
+import "./account.css";
+export interface AvatarProps {
+    address: `0x${string}`;
+    size?: number;
+    /** Resolve + use the ENS avatar when available. Default true. */
+    ens?: boolean;
+    className?: string;
+}
+export declare function Avatar({ address, size, ens, className }: AvatarProps): import("react").JSX.Element;

package/dist/account/Avatar.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import "./account.css";
+import { useEnsName, useEnsAvatar } from "wagmi";
+import { avatarGradient } from "../format";
+import { cx } from "../util";
+// An account avatar: the ENS avatar when set, otherwise a deterministic gradient
+// identicon derived from the address (no image dependency). Neutral.
+export function Avatar({ address, size = 32, ens = true, className }) {
+    const { data: name } = useEnsName({ address, query: { enabled: ens } });
+    const { data: url } = useEnsAvatar({ name: name ?? undefined, query: { enabled: ens && Boolean(name) } });
+    if (url) {
+        return _jsx("img", { className: cx("kit-avatar", className), src: url, width: size, height: size, alt: "", style: { borderRadius: "50%" } });
+    }
+    return (_jsx("span", { className: cx("kit-avatar", className), style: { width: size, height: size, borderRadius: "50%", background: avatarGradient(address), display: "inline-block" }, "aria-hidden": "true" }));
+}

package/dist/account/Identity.d.ts

@@ -0,0 +1,9 @@
+import "./account.css";
+export interface IdentityProps {
+    address: `0x${string}`;
+    size?: number;
+    /** Resolve ENS name/avatar. Default true. */
+    ens?: boolean;
+    className?: string;
+}
+export declare function Identity({ address, size, ens, className }: IdentityProps): import("react").JSX.Element;

package/dist/account/Identity.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import "./account.css";
+import { useEnsName } from "wagmi";
+import { Avatar } from "./Avatar";
+import { shortAddress } from "../format";
+import { cx } from "../util";
+// Avatar + name (ENS or shortened address) in a row. Neutral; style .kit-identity.
+export function Identity({ address, size = 28, ens = true, className }) {
+    const { data: name } = useEnsName({ address, query: { enabled: ens } });
+    return (_jsxs("span", { className: cx("kit-identity", className), children: [_jsx(Avatar, { address: address, size: size, ens: ens }), _jsx("span", { className: "kit-identity-name", children: name || shortAddress(address) })] }));
+}

package/dist/account/account.css

@@ -0,0 +1,3 @@
+.kit-avatar{flex:none;object-fit:cover}
+.kit-identity{display:inline-flex;align-items:center;gap:8px;font:inherit;font-weight:500}
+.kit-identity-name{font-variant-numeric:tabular-nums}

package/dist/account/gates.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from "react";
+/** Whether a wallet is currently connected. */
+export declare function useIsConnected(): boolean;
+/** Render children only when a wallet is connected (else `fallback`). */
+export declare function Connected({ children, fallback }: {
+    children: ReactNode;
+    fallback?: ReactNode;
+}): import("react").JSX.Element;
+/** Render children only when NO wallet is connected. */
+export declare function Disconnected({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element | null;
+/** Gate UI behind a connection: shows the children when connected, otherwise a
+ *  connect prompt (the kit's <ConnectWallet/> by default — pass `connect` to override). */
+export declare function RequireConnection({ children, connect }: {
+    children: ReactNode;
+    connect?: ReactNode;
+}): import("react").JSX.Element;

package/dist/account/gates.js

@@ -0,0 +1,21 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import {} from "react";
+import { useConnection } from "wagmi";
+import { ConnectWallet } from "../wallet";
+/** Whether a wallet is currently connected. */
+export function useIsConnected() {
+    return useConnection().isConnected;
+}
+/** Render children only when a wallet is connected (else `fallback`). */
+export function Connected({ children, fallback }) {
+    return useIsConnected() ? _jsx(_Fragment, { children: children }) : _jsx(_Fragment, { children: fallback ?? null });
+}
+/** Render children only when NO wallet is connected. */
+export function Disconnected({ children }) {
+    return useIsConnected() ? null : _jsx(_Fragment, { children: children });
+}
+/** Gate UI behind a connection: shows the children when connected, otherwise a
+ *  connect prompt (the kit's <ConnectWallet/> by default — pass `connect` to override). */
+export function RequireConnection({ children, connect }) {
+    return useIsConnected() ? _jsx(_Fragment, { children: children }) : _jsx(_Fragment, { children: connect ?? _jsx(ConnectWallet, {}) });
+}

package/dist/account/index.d.ts

@@ -0,0 +1,3 @@
+export { useIsConnected, Connected, Disconnected, RequireConnection } from "./gates";
+export { Avatar, type AvatarProps } from "./Avatar";
+export { Identity, type IdentityProps } from "./Identity";

package/dist/account/index.js

@@ -0,0 +1,3 @@
+export { useIsConnected, Connected, Disconnected, RequireConnection } from "./gates";
+export { Avatar } from "./Avatar";
+export { Identity } from "./Identity";

package/dist/contracts/index.d.ts

@@ -1,2 +1,3 @@
 export { useContractValue, type UseContractValueParams } from "./useContractValue";
+export { useContractEvent, type UseContractEventParams } from "./useContractEvent";
 export { createLivoContracts, resolveAddress, type LivoBindings, type LivoContracts, type ContractRef, } from "./createLivoContracts";

package/dist/contracts/index.js

@@ -1,2 +1,3 @@
 export { useContractValue } from "./useContractValue";
+export { useContractEvent } from "./useContractEvent";
 export { createLivoContracts, resolveAddress, } from "./createLivoContracts";

package/dist/contracts/useContractEvent.d.ts

@@ -0,0 +1,10 @@
+import type { Abi } from "viem";
+export interface UseContractEventParams {
+    address?: `0x${string}`;
+    abi: Abi;
+    eventName: string;
+    onLogs: (logs: readonly unknown[]) => void;
+    chainId?: number;
+    enabled?: boolean;
+}
+export declare function useContractEvent({ address, abi, eventName, onLogs, chainId, enabled }: UseContractEventParams): void;

package/dist/contracts/useContractEvent.js

@@ -0,0 +1,13 @@
+import { useWatchContractEvent } from "wagmi";
+// Subscribe to a contract event (live). A thin wrapper over useWatchContractEvent —
+// pair with createLivoContracts' useContract(name) to get { address, abi }.
+export function useContractEvent({ address, abi, eventName, onLogs, chainId, enabled }) {
+    useWatchContractEvent({
+        address,
+        abi,
+        eventName,
+        chainId,
+        enabled: (enabled ?? true) && Boolean(address),
+        onLogs: (logs) => onLogs(logs),
+    });
+}

package/dist/data/Async.d.ts

@@ -0,0 +1,17 @@
+import { type ReactNode } from "react";
+export interface AsyncQuery<T> {
+    data: T | undefined;
+    error: Error | null;
+    isLoading: boolean;
+}
+export interface AsyncProps<T> {
+    query: AsyncQuery<T>;
+    /** Render the loaded data. */
+    children: (data: T) => ReactNode;
+    loading?: ReactNode;
+    error?: (error: Error) => ReactNode;
+    /** Shown when data is "empty" (default: [] or null/undefined). */
+    empty?: ReactNode;
+    isEmpty?: (data: T) => boolean;
+}
+export declare function Async<T>({ query, children, loading, error, empty, isEmpty }: AsyncProps<T>): import("react").JSX.Element;

package/dist/data/Async.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import {} from "react";
+import { Spinner } from "../ui";
+// Render the loading / error / empty / data states of ANY kit data hook in one
+// place — `<Async query={useApi("/items")}>{(items) => …}</Async>`. Neutral
+// defaults (spinner, plain error); pass your own for each state.
+export function Async({ query, children, loading, error, empty, isEmpty }) {
+    if (query.error) {
+        return _jsx(_Fragment, { children: error ? error(query.error) : _jsx("span", { className: "kit-async-error", children: query.error.message }) });
+    }
+    if (query.isLoading || query.data === undefined) {
+        return _jsx(_Fragment, { children: loading ?? _jsx(Spinner, {}) });
+    }
+    const emptyVal = isEmpty
+        ? isEmpty(query.data)
+        : Array.isArray(query.data)
+            ? query.data.length === 0
+            : query.data === null;
+    if (emptyVal && empty !== undefined)
+        return _jsx(_Fragment, { children: empty });
+    return _jsx(_Fragment, { children: children(query.data) });
+}

package/dist/data/index.d.ts

@@ -1,2 +1,3 @@
 export { useApi, apiClient, type QueryResult, type UseApiOptions } from "./useApi";
 export { useSubgraph, type UseSubgraphArgs } from "./useSubgraph";
+export { Async, type AsyncProps, type AsyncQuery } from "./Async";

package/dist/data/index.js

@@ -1,2 +1,3 @@
 export { useApi, apiClient } from "./useApi";
 export { useSubgraph } from "./useSubgraph";
+export { Async } from "./Async";

package/dist/hooks/index.d.ts

@@ -0,0 +1,8 @@
+/** Copy text to the clipboard; returns [copied, copy]. `copied` flips true for ~1.2s. */
+export declare function useCopyToClipboard(): [boolean, (text: string) => void];
+/** State persisted to localStorage (SSR-safe; falls back to in-memory). */
+export declare function useLocalStorage<T>(key: string, initial: T): [T, (value: T) => void];
+/** Debounce a changing value by `ms` milliseconds. */
+export declare function useDebounce<T>(value: T, ms?: number): T;
+/** Run a callback every `ms` milliseconds. Pass `ms = null` to pause. */
+export declare function useInterval(callback: () => void, ms: number | null): void;

package/dist/hooks/index.js

@@ -0,0 +1,67 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+/** Copy text to the clipboard; returns [copied, copy]. `copied` flips true for ~1.2s. */
+export function useCopyToClipboard() {
+    const [copied, setCopied] = useState(false);
+    const timer = useRef(null);
+    const copy = useCallback((text) => {
+        try {
+            navigator.clipboard.writeText(text);
+            setCopied(true);
+            if (timer.current)
+                clearTimeout(timer.current);
+            timer.current = setTimeout(() => setCopied(false), 1200);
+        }
+        catch {
+            /* clipboard unavailable */
+        }
+    }, []);
+    useEffect(() => () => { if (timer.current)
+        clearTimeout(timer.current); }, []);
+    return [copied, copy];
+}
+/** State persisted to localStorage (SSR-safe; falls back to in-memory). */
+export function useLocalStorage(key, initial) {
+    const [value, setValue] = useState(() => {
+        if (typeof window === "undefined")
+            return initial;
+        try {
+            const raw = window.localStorage.getItem(key);
+            return raw ? JSON.parse(raw) : initial;
+        }
+        catch {
+            return initial;
+        }
+    });
+    const set = useCallback((next) => {
+        setValue(next);
+        try {
+            window.localStorage.setItem(key, JSON.stringify(next));
+        }
+        catch {
+            /* storage unavailable / quota */
+        }
+    }, [key]);
+    return [value, set];
+}
+/** Debounce a changing value by `ms` milliseconds. */
+export function useDebounce(value, ms = 300) {
+    const [debounced, setDebounced] = useState(value);
+    useEffect(() => {
+        const t = setTimeout(() => setDebounced(value), ms);
+        return () => clearTimeout(t);
+    }, [value, ms]);
+    return debounced;
+}
+/** Run a callback every `ms` milliseconds. Pass `ms = null` to pause. */
+export function useInterval(callback, ms) {
+    const saved = useRef(callback);
+    useEffect(() => {
+        saved.current = callback;
+    }, [callback]);
+    useEffect(() => {
+        if (ms == null)
+            return;
+        const id = setInterval(() => saved.current(), ms);
+        return () => clearInterval(id);
+    }, [ms]);
+}

package/dist/index.d.ts

@@ -5,5 +5,10 @@ export * from "./tx";
 export * from "./toast";
 export * from "./data";
 export * from "./web3";
+export * from "./token";
+export * from "./account";
 export * from "./ui";
+export * from "./telegram";
+export * from "./theme";
+export * from "./hooks";
 export * from "./format";

package/dist/index.js

@@ -9,7 +9,12 @@
 //   toast/     — ToastProvider, useToast
 //   data/      — useApi (same-origin /api/*), useSubgraph (indexer)
 //   web3/      — Address, Balance, NetworkGuard, TokenAmountInput
+//   token/     — useToken, useAllowance, useApprove, ApproveButton (ERC-20 + approvals)
+//   account/   — Connected, Disconnected, RequireConnection, useIsConnected, Avatar, Identity
 //   ui/        — Dialog, Card, Skeleton, Spinner, EmptyState, CopyButton
+//   telegram/  — useTelegramMiniApp, useTelegramLink, LinkTelegramButton (link a wallet ↔ Telegram)
+//   theme/     — KitThemeProvider (restyle the whole kit from one theme object)
+//   hooks/     — useCopyToClipboard, useLocalStorage, useDebounce, useInterval
 //   format     — shortAddress, formatToken, parseToken, formatUsd, timeAgo, …
 export * from "./wallet";
 export * from "./provider";
@@ -18,5 +23,10 @@ export * from "./tx";
 export * from "./toast";
 export * from "./data";
 export * from "./web3";
+export * from "./token";
+export * from "./account";
 export * from "./ui";
+export * from "./telegram";
+export * from "./theme";
+export * from "./hooks";
 export * from "./format";

package/dist/provider/LivoApp.d.ts

@@ -0,0 +1,13 @@
+import { type ReactNode } from "react";
+import { QueryClient } from "@tanstack/react-query";
+import { type Config } from "wagmi";
+import { type KitTheme } from "../theme";
+export interface LivoAppProps {
+    /** Your wagmi config (chains + connectors). */
+    config: Config;
+    /** Optional theme tokens applied to every kit component (accent, radius, …). */
+    theme?: KitTheme;
+    queryClient?: QueryClient;
+    children: ReactNode;
+}
+export declare function LivoApp({ config, theme, queryClient, children }: LivoAppProps): import("react").JSX.Element;

package/dist/provider/LivoApp.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import {} from "react";
+import { QueryClient } from "@tanstack/react-query";
+import {} from "wagmi";
+import { LivoWeb3Provider } from "./Web3Provider";
+import { ToastProvider } from "../toast";
+import { KitThemeProvider } from "../theme";
+// One wrapper for a Livo web3 app: wagmi + react-query (LivoWeb3Provider), toasts
+// (ToastProvider for TxButton et al.), and optional theming — so you wrap once
+// instead of nesting three providers. Pass your wagmi `config`; everything else is
+// optional.
+export function LivoApp({ config, theme, queryClient, children }) {
+    const withToasts = _jsx(ToastProvider, { children: children });
+    const themed = theme ? _jsx(KitThemeProvider, { theme: theme, children: withToasts }) : withToasts;
+    return (_jsx(LivoWeb3Provider, { config: config, queryClient: queryClient, children: themed }));
+}

package/dist/provider/index.d.ts

@@ -1 +1,2 @@
 export { LivoWeb3Provider, type LivoWeb3ProviderProps } from "./Web3Provider";
+export { LivoApp, type LivoAppProps } from "./LivoApp";

package/dist/provider/index.js

@@ -1 +1,2 @@
 export { LivoWeb3Provider } from "./Web3Provider";
+export { LivoApp } from "./LivoApp";

package/dist/telegram/LinkTelegramButton.d.ts

@@ -0,0 +1,12 @@
+import "./telegram.css";
+import { type UseTelegramLinkOptions } from "./useTelegramLink";
+export interface LinkTelegramButtonProps extends UseTelegramLinkOptions {
+    className?: string;
+    labels?: {
+        link?: string;
+        linking?: string;
+        open?: string;
+        linked?: (username?: string) => string;
+    };
+}
+export declare function LinkTelegramButton({ className, labels, ...opts }: LinkTelegramButtonProps): import("react").JSX.Element;

package/dist/telegram/LinkTelegramButton.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import "./telegram.css";
+import { useTelegramLink } from "./useTelegramLink";
+import { cx } from "../util";
+// One button for the whole Telegram-link lifecycle: "Link Telegram" → (Mini App)
+// done, or (open web) "Open Telegram to finish" deep link → linked chip. Neutral;
+// style .kit-tg / [data-state]. Build your own on useTelegramLink for full control.
+export function LinkTelegramButton({ className, labels, ...opts }) {
+    const { status, telegram, deepLink, link, unlink } = useTelegramLink(opts);
+    if (status === "linked") {
+        const who = telegram?.username ? `@${telegram.username}` : telegram?.id ? `#${telegram.id}` : "";
+        return (_jsx("button", { className: cx("kit-tg", className), "data-state": "linked", onClick: () => unlink(), children: labels?.linked ? labels.linked(telegram?.username) : `Telegram ${who} ✓` }));
+    }
+    if (status === "linking" && deepLink) {
+        return (_jsx("a", { className: cx("kit-tg", className), "data-state": "open", href: deepLink, target: "_blank", rel: "noreferrer", children: labels?.open ?? "Open Telegram to finish" }));
+    }
+    const busy = status === "linking" || status === "loading";
+    return (_jsx("button", { className: cx("kit-tg", className), "data-state": status, disabled: busy, onClick: () => link(), children: status === "linking" ? (labels?.linking ?? "Linking…") : (labels?.link ?? "Link Telegram") }));
+}

package/dist/telegram/index.d.ts

@@ -0,0 +1,3 @@
+export { useTelegramMiniApp, type TelegramMiniApp } from "./useTelegramMiniApp";
+export { useTelegramLink, type TelegramLinkState, type LinkStatus, type LinkedTelegram, type UseTelegramLinkOptions, } from "./useTelegramLink";
+export { LinkTelegramButton, type LinkTelegramButtonProps } from "./LinkTelegramButton";

package/dist/telegram/index.js

@@ -0,0 +1,3 @@
+export { useTelegramMiniApp } from "./useTelegramMiniApp";
+export { useTelegramLink, } from "./useTelegramLink";
+export { LinkTelegramButton } from "./LinkTelegramButton";

package/dist/telegram/telegram.css

@@ -0,0 +1,6 @@
+.kit-tg{display:inline-flex;align-items:center;justify-content:center;gap:8px;padding:10px 16px;border:0;border-radius:11px;font:inherit;font-weight:600;font-size:14px;cursor:pointer;text-decoration:none;transition:opacity .12s,transform .08s;background:var(--kit-accent,#229ED9);color:var(--kit-accent-fg,#fff)}
+.kit-tg:hover{opacity:.9}
+.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)}
+@media (prefers-color-scheme:dark){.kit-tg[data-state="linked"]{--kit-row:#27272c;--kit-fg:#f5f5f7}}

package/dist/telegram/useTelegramLink.d.ts

@@ -0,0 +1,20 @@
+export type LinkStatus = "loading" | "unlinked" | "linking" | "linked" | "error";
+export interface LinkedTelegram {
+    id: number;
+    username?: string;
+}
+export interface TelegramLinkState {
+    status: LinkStatus;
+    telegram?: LinkedTelegram;
+    /** Open-web flow: a t.me deep link to finish linking in the bot. */
+    deepLink?: string;
+    link: () => Promise<void>;
+    unlink: () => Promise<void>;
+    refresh: () => void;
+    error?: Error;
+}
+export interface UseTelegramLinkOptions {
+    /** Base path for the link API (default "/api/telegram"). */
+    endpoint?: string;
+}
+export declare function useTelegramLink(options?: UseTelegramLinkOptions): TelegramLinkState;

package/dist/telegram/useTelegramLink.js

@@ -0,0 +1,114 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useConnection, useSignMessage } from "wagmi";
+import { useTelegramMiniApp } from "./useTelegramMiniApp";
+// Link the connected wallet to the user's Telegram identity. Inside a Telegram Mini
+// App it uses the verified initData; on a normal website it falls back to a bot
+// deep-link handshake (poll until the bot completes it). The server (your api/)
+// verifies both the Telegram identity and the wallet signature before binding.
+export function useTelegramLink(options = {}) {
+    const base = options.endpoint ?? "/api/telegram";
+    const { address } = useConnection();
+    const { signMessageAsync } = useSignMessage();
+    const mini = useTelegramMiniApp();
+    const [status, setStatus] = useState("loading");
+    const [telegram, setTelegram] = useState();
+    const [deepLink, setDeepLink] = useState();
+    const [error, setError] = useState();
+    const pollRef = useRef(null);
+    const stopPoll = () => {
+        if (pollRef.current) {
+            clearInterval(pollRef.current);
+            pollRef.current = null;
+        }
+    };
+    const refresh = useCallback(async () => {
+        if (!address) {
+            setStatus("unlinked");
+            return;
+        }
+        try {
+            const r = await fetch(`${base}/status?address=${address}`);
+            const j = (await r.json());
+            if (j.linked) {
+                setStatus("linked");
+                setTelegram(j.telegram);
+                stopPoll();
+            }
+            else {
+                setStatus((s) => (s === "linking" ? s : "unlinked"));
+            }
+        }
+        catch (e) {
+            setError(e);
+            setStatus("error");
+        }
+    }, [address, base]);
+    useEffect(() => {
+        void refresh();
+        return stopPoll;
+    }, [refresh]);
+    const sign = useCallback(async () => {
+        const nonceRes = await fetch(`${base}/nonce?address=${address}`);
+        const { nonce, message } = (await nonceRes.json());
+        const msg = message ?? `Link my Telegram to ${address}\nnonce: ${nonce}`;
+        const signature = await signMessageAsync({ message: msg });
+        return { nonce, signature };
+    }, [address, base, signMessageAsync]);
+    const link = useCallback(async () => {
+        if (!address)
+            return;
+        setStatus("linking");
+        setError(undefined);
+        try {
+            const { nonce, signature } = await sign();
+            if (mini.available) {
+                const res = await fetch(`${base}/link`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ initData: mini.initData, address, signature, nonce }),
+                });
+                const j = (await res.json());
+                if (!res.ok || !j.linked)
+                    throw new Error(j.error ?? "Link failed");
+                setStatus("linked");
+                setTelegram(j.telegram);
+            }
+            else {
+                const res = await fetch(`${base}/start`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ address, signature, nonce }),
+                });
+                const j = (await res.json());
+                if (!res.ok || !j.deepLink)
+                    throw new Error(j.error ?? "Link failed");
+                setDeepLink(j.deepLink);
+                stopPoll();
+                pollRef.current = setInterval(() => void refresh(), 3000);
+            }
+        }
+        catch (e) {
+            setError(e);
+            setStatus("error");
+        }
+    }, [address, base, mini, sign, refresh]);
+    const unlink = useCallback(async () => {
+        if (!address)
+            return;
+        try {
+            const { nonce, signature } = await sign();
+            await fetch(`${base}/unlink`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ address, signature, nonce }),
+            });
+        }
+        catch {
+            /* ignore */
+        }
+        setStatus("unlinked");
+        setTelegram(undefined);
+        setDeepLink(undefined);
+    }, [address, base, sign]);
+    return { status, telegram, deepLink, link, unlink, refresh: () => void refresh(), error };
+}

package/dist/telegram/useTelegramMiniApp.d.ts

@@ -0,0 +1,17 @@
+export interface TelegramMiniApp {
+    /** True when the page is running inside Telegram (initData present). */
+    available: boolean;
+    /** Raw signed initData — send to the server to verify the user. */
+    initData: string;
+    /** Client-side (UNVERIFIED) user, for display only — verify server-side. */
+    user?: {
+        id: number;
+        username?: string;
+        firstName?: string;
+        photoUrl?: string;
+    };
+    colorScheme?: "light" | "dark";
+    ready: () => void;
+    expand: () => void;
+}
+export declare function useTelegramMiniApp(): TelegramMiniApp;

package/dist/telegram/useTelegramMiniApp.js

@@ -0,0 +1,24 @@
+import { useEffect } from "react";
+function getWebApp() {
+    if (typeof window === "undefined")
+        return undefined;
+    return window.Telegram?.WebApp;
+}
+// Read the Telegram Mini App context (window.Telegram.WebApp), if the page is open
+// inside Telegram. Requires the Telegram WebApp SDK script
+// (https://telegram.org/js/telegram-web-app.js) in your <head>.
+export function useTelegramMiniApp() {
+    const wa = getWebApp();
+    useEffect(() => {
+        wa?.ready();
+    }, [wa]);
+    const u = wa?.initDataUnsafe?.user;
+    return {
+        available: Boolean(wa?.initData),
+        initData: wa?.initData ?? "",
+        user: u ? { id: u.id, username: u.username, firstName: u.first_name, photoUrl: u.photo_url } : undefined,
+        colorScheme: wa?.colorScheme,
+        ready: () => wa?.ready(),
+        expand: () => wa?.expand(),
+    };
+}

package/dist/theme/ThemeProvider.d.ts

@@ -0,0 +1,17 @@
+import { type ReactNode, type CSSProperties } from "react";
+export interface KitTheme {
+    accent?: string;
+    accentFg?: string;
+    radius?: number | string;
+    bg?: string;
+    fg?: string;
+    muted?: string;
+    border?: string;
+}
+export interface KitThemeProviderProps {
+    theme: KitTheme;
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+export declare function KitThemeProvider({ theme, children, className, style }: KitThemeProviderProps): import("react").JSX.Element;

package/dist/theme/ThemeProvider.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import {} from "react";
+const VARS = {
+    accent: ["--wm-accent", "--kit-accent", "--kit-t-accent"],
+    accentFg: ["--wm-accent-fg", "--kit-accent-fg"],
+    radius: ["--wm-radius", "--kit-radius"],
+    bg: ["--wm-bg", "--kit-bg", "--kit-t-bg"],
+    fg: ["--wm-fg", "--kit-fg", "--kit-t-fg"],
+    muted: ["--wm-muted", "--kit-muted", "--kit-t-muted"],
+    border: ["--wm-border", "--kit-border", "--kit-t-border"],
+};
+export function KitThemeProvider({ theme, children, className, style }) {
+    const vars = {};
+    Object.keys(theme).forEach((k) => {
+        const v = theme[k];
+        if (v == null)
+            return;
+        const value = typeof v === "number" ? `${v}px` : String(v);
+        for (const cssVar of VARS[k])
+            vars[cssVar] = value;
+    });
+    return (_jsx("div", { className: className, style: { ...vars, ...style }, children: children }));
+}

package/dist/theme/index.d.ts

@@ -0,0 +1 @@
+export { KitThemeProvider, type KitTheme, type KitThemeProviderProps } from "./ThemeProvider";

package/dist/theme/index.js

@@ -0,0 +1 @@
+export { KitThemeProvider } from "./ThemeProvider";

package/dist/token/ApproveButton.d.ts

@@ -0,0 +1,12 @@
+import { type ReactNode } from "react";
+export interface ApproveButtonProps {
+    token: `0x${string}`;
+    spender: `0x${string}`;
+    /** Amount to approve (base units). Omit for unlimited. */
+    amount?: bigint;
+    children?: ReactNode;
+    className?: string;
+    toast?: boolean;
+    onSuccess?: (hash: `0x${string}`) => void;
+}
+export declare function ApproveButton({ token, spender, amount, children, className, toast, onSuccess }: ApproveButtonProps): import("react").JSX.Element;

package/dist/token/ApproveButton.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import {} from "react";
+import { erc20Abi, maxUint256 } from "viem";
+import { TxButton } from "../tx";
+// A TxButton wired for ERC-20 approve — pending/confirming states + toast + explorer
+// link, same as any other write.
+export function ApproveButton({ token, spender, amount, children, className, toast, onSuccess }) {
+    return (_jsx(TxButton, { address: token, abi: erc20Abi, functionName: "approve", args: [spender, amount ?? maxUint256], className: className, toast: toast, onSuccess: onSuccess, children: children ?? "Approve" }));
+}

package/dist/token/index.d.ts

@@ -0,0 +1,5 @@
+export { useToken, type TokenInfo } from "./useToken";
+export { useAllowance, type AllowanceResult, type UseAllowanceParams } from "./useAllowance";
+export { useApprove, type UseApproveParams } from "./useApprove";
+export { ApproveButton, type ApproveButtonProps } from "./ApproveButton";
+export { useTokenGate, type UseTokenGateParams, type TokenGateResult } from "./useTokenGate";

package/dist/token/index.js

@@ -0,0 +1,5 @@
+export { useToken } from "./useToken";
+export { useAllowance } from "./useAllowance";
+export { useApprove } from "./useApprove";
+export { ApproveButton } from "./ApproveButton";
+export { useTokenGate } from "./useTokenGate";

package/dist/token/useAllowance.d.ts

@@ -0,0 +1,13 @@
+export interface AllowanceResult {
+    data: bigint | undefined;
+    /** Whether the allowance covers `amount` (false until loaded, or if `amount` omitted). */
+    enough: (amount: bigint) => boolean;
+    isLoading: boolean;
+    refetch: () => void;
+}
+export interface UseAllowanceParams {
+    token?: `0x${string}`;
+    owner?: `0x${string}`;
+    spender?: `0x${string}`;
+}
+export declare function useAllowance({ token, owner, spender }: UseAllowanceParams): AllowanceResult;

package/dist/token/useAllowance.js

@@ -0,0 +1,22 @@
+import { useReadContract } from "wagmi";
+import { erc20Abi } from "viem";
+// The ERC-20 allowance owner has granted spender. Pair with useApprove — the
+// classic approve→spend gate.
+export function useAllowance({ token, owner, spender }) {
+    const r = useReadContract({
+        address: token,
+        abi: erc20Abi,
+        functionName: "allowance",
+        args: owner && spender ? [owner, spender] : undefined,
+        query: { enabled: Boolean(token && owner && spender) },
+    });
+    const data = r.data;
+    return {
+        data,
+        enough: (amount) => data !== undefined && data >= amount,
+        isLoading: r.isLoading,
+        refetch: () => {
+            void r.refetch();
+        },
+    };
+}

package/dist/token/useApprove.d.ts

@@ -0,0 +1,10 @@
+import { type UseTxResult } from "../tx/useTx";
+export interface UseApproveParams {
+    token: `0x${string}`;
+    spender: `0x${string}`;
+    /** Amount to approve (base units). Omit for an unlimited (maxUint256) approval. */
+    amount?: bigint;
+    onSuccess?: () => void;
+    onError?: (error: Error) => void;
+}
+export declare function useApprove({ token, spender, amount, onSuccess, onError }: UseApproveParams): UseTxResult;

package/dist/token/useApprove.js

@@ -0,0 +1,14 @@
+import { erc20Abi, maxUint256 } from "viem";
+import { useTx } from "../tx/useTx";
+// Approve an ERC-20 spender — the whole approve tx lifecycle via useTx. Read the
+// current allowance with useAllowance to decide whether you even need this.
+export function useApprove({ token, spender, amount, onSuccess, onError }) {
+    return useTx({
+        address: token,
+        abi: erc20Abi,
+        functionName: "approve",
+        args: [spender, amount ?? maxUint256],
+        onSuccess: onSuccess ? () => onSuccess() : undefined,
+        onError,
+    });
+}

package/dist/token/useToken.d.ts

@@ -0,0 +1,7 @@
+export interface TokenInfo {
+    name?: string;
+    symbol?: string;
+    decimals?: number;
+    isLoading: boolean;
+}
+export declare function useToken(token?: `0x${string}`): TokenInfo;

package/dist/token/useToken.js

@@ -0,0 +1,15 @@
+import { useReadContract } from "wagmi";
+import { erc20Abi } from "viem";
+// ERC-20 metadata (name / symbol / decimals) for a token address.
+export function useToken(token) {
+    const enabled = Boolean(token);
+    const name = useReadContract({ address: token, abi: erc20Abi, functionName: "name", query: { enabled } });
+    const symbol = useReadContract({ address: token, abi: erc20Abi, functionName: "symbol", query: { enabled } });
+    const decimals = useReadContract({ address: token, abi: erc20Abi, functionName: "decimals", query: { enabled } });
+    return {
+        name: name.data,
+        symbol: symbol.data,
+        decimals: decimals.data,
+        isLoading: name.isLoading || symbol.isLoading || decimals.isLoading,
+    };
+}

package/dist/token/useTokenGate.d.ts

@@ -0,0 +1,17 @@
+export interface UseTokenGateParams {
+    /** ERC-20 / ERC-721 token address that gates access. */
+    token: `0x${string}`;
+    /** Minimum balance required (base units for ERC-20; count for ERC-721). */
+    threshold: bigint;
+    /** Account to check (defaults to the connected wallet). */
+    address?: `0x${string}`;
+}
+export interface TokenGateResult {
+    /** Whether the wallet currently meets the gate. */
+    eligible: boolean;
+    balance: bigint | undefined;
+    /** How much more is needed to qualify (0n when eligible). */
+    shortBy: bigint;
+    isLoading: boolean;
+}
+export declare function useTokenGate({ token, threshold, address }: UseTokenGateParams): TokenGateResult;

package/dist/token/useTokenGate.js

@@ -0,0 +1,24 @@
+import { useReadContract, useConnection } from "wagmi";
+import { erc20Abi } from "viem";
+// Does a wallet hold enough of a token to pass a gate? For showing eligibility on
+// the link/join page (the bot/keeper enforces it server-side with meetsGate). Works
+// for ERC-20 (balance) and ERC-721 (count) via balanceOf.
+export function useTokenGate({ token, threshold, address }) {
+    const { address: connected } = useConnection();
+    const owner = address ?? connected;
+    const r = useReadContract({
+        address: token,
+        abi: erc20Abi,
+        functionName: "balanceOf",
+        args: owner ? [owner] : undefined,
+        query: { enabled: Boolean(token && owner) },
+    });
+    const balance = r.data;
+    const eligible = balance !== undefined && balance >= threshold;
+    return {
+        eligible,
+        balance,
+        shortBy: balance !== undefined && balance < threshold ? threshold - balance : 0n,
+        isLoading: r.isLoading,
+    };
+}

package/dist/ui/index.d.ts

@@ -1 +1 @@
-export { Dialog, Card, Skeleton, Spinner, EmptyState, CopyButton, type DialogProps, type SkeletonProps, type EmptyStateProps, type CopyButtonProps, } from "./ui";
+export { Dialog, Card, Skeleton, Spinner, EmptyState, CopyButton, Button, Badge, type DialogProps, type SkeletonProps, type EmptyStateProps, type CopyButtonProps, type ButtonProps, } from "./ui";

package/dist/ui/index.js

@@ -1 +1 @@
-export { Dialog, Card, Skeleton, Spinner, EmptyState, CopyButton, } from "./ui";
+export { Dialog, Card, Skeleton, Spinner, EmptyState, CopyButton, Button, Badge, } from "./ui";

package/dist/ui/ui.css

@@ -13,6 +13,17 @@
 .kit-empty-desc{font-size:14px;margin:0;max-width:34ch}
 .kit-spinner{display:inline-block;box-sizing:border-box;border:2px solid var(--kit-border,#e5e7eb);border-top-color:currentColor;border-radius:50%;animation:kit-spin .7s linear infinite}
 .kit-copy{display:inline-flex;align-items:center;gap:6px;border:0;background:transparent;color:inherit;font:inherit;cursor:pointer;padding:0}
+.kit-button{display:inline-flex;align-items:center;justify-content:center;gap:8px;padding:9px 15px;border-radius:10px;font:inherit;font-weight:600;font-size:14px;cursor:pointer;transition:opacity .12s,transform .08s,background .12s;border:1px solid transparent}
+.kit-button:disabled{opacity:.6;cursor:default}
+.kit-button:active:not(:disabled){transform:translateY(1px)}
+.kit-button-primary{background:var(--kit-accent,#111827);color:var(--kit-accent-fg,#fff)}
+.kit-button-primary:hover:not(:disabled){opacity:.9}
+.kit-button-secondary{background:var(--kit-row,#f3f4f6);color:var(--kit-fg,#111827)}
+.kit-button-secondary:hover:not(:disabled){background:var(--kit-row-hover,#e9eaee)}
+.kit-button-ghost{background:transparent;color:inherit;border-color:var(--kit-border,#e5e7eb)}
+.kit-button-ghost:hover:not(:disabled){background:var(--kit-row,#f3f4f6)}
+.kit-badge{display:inline-flex;align-items:center;gap:4px;padding:2px 9px;border-radius:999px;font:inherit;font-size:12px;font-weight:600;background:var(--kit-row,#f3f4f6);color:var(--kit-muted,#6b7280)}
+@media (prefers-color-scheme:dark){.kit-button-secondary,.kit-badge{--kit-row:#27272c;--kit-row-hover:#313137;--kit-fg:#f5f5f7}}
 @keyframes kit-fade{from{opacity:0}to{opacity:1}}
 @keyframes kit-pop{from{opacity:0;transform:translateY(6px) scale(.98)}to{opacity:1;transform:none}}
 @keyframes kit-spin{to{transform:rotate(360deg)}}

package/dist/ui/ui.d.ts

@@ -1,5 +1,10 @@
 import "./ui.css";
-import { type ReactNode, type CSSProperties, type HTMLAttributes } from "react";
+import { type ReactNode, type CSSProperties, type HTMLAttributes, type ButtonHTMLAttributes } from "react";
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: "primary" | "secondary" | "ghost";
+}
+export declare function Button({ variant, className, ...rest }: ButtonProps): import("react").JSX.Element;
+export declare function Badge({ className, ...rest }: HTMLAttributes<HTMLSpanElement>): import("react").JSX.Element;
 export interface DialogProps {
     open: boolean;
     onClose: () => void;

package/dist/ui/ui.js

@@ -2,6 +2,13 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import "./ui.css";
 import { useEffect, useRef, useState, } from "react";
 import { cx } from "../util";
+export function Button({ variant = "secondary", className, ...rest }) {
+    return _jsx("button", { className: cx("kit-button", "kit-button-" + variant, className), ...rest });
+}
+// ---- Badge ---------------------------------------------------------------------
+export function Badge({ className, ...rest }) {
+    return _jsx("span", { className: cx("kit-badge", className), ...rest });
+}
 export function Dialog({ open, onClose, title, children, className }) {
     const ref = useRef(null);
     useEffect(() => {

package/dist/web3/AddressInput.d.ts

@@ -0,0 +1,10 @@
+import "./web3.css";
+export interface AddressInputProps {
+    value: string;
+    onChange: (value: string) => void;
+    /** Fires with the resolved checksummed address (or null when invalid/unresolved). */
+    onResolved?: (address: `0x${string}` | null) => void;
+    placeholder?: string;
+    className?: string;
+}
+export declare function AddressInput({ value, onChange, onResolved, placeholder, className }: AddressInputProps): import("react").JSX.Element;

package/dist/web3/AddressInput.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import "./web3.css";
+import { useEffect } from "react";
+import { useEnsAddress } from "wagmi";
+import { isAddress } from "viem";
+import { shortAddress } from "../format";
+import { cx } from "../util";
+// An address input that accepts a hex address OR an ENS name (`name.eth`), resolves
+// it, and reports validity via [data-valid] + onResolved. Neutral; style .kit-addr-input.
+export function AddressInput({ value, onChange, onResolved, placeholder = "0x… or name.eth", className }) {
+    const isEns = /\.eth$/i.test(value.trim());
+    const { data: resolved } = useEnsAddress({ name: isEns ? value.trim() : undefined, query: { enabled: isEns } });
+    const address = isAddress(value.trim())
+        ? value.trim()
+        : (resolved ?? null);
+    useEffect(() => {
+        onResolved?.(address);
+    }, [address, onResolved]);
+    return (_jsxs("div", { className: cx("kit-addr-input", className), "data-valid": address ? "" : undefined, children: [_jsx("input", { value: value, onChange: (e) => onChange(e.target.value), placeholder: placeholder, spellCheck: false, autoComplete: "off" }), isEns && resolved ? _jsx("span", { className: "kit-addr-input-resolved", children: shortAddress(resolved) }) : null] }));
+}

package/dist/web3/ChainSwitcher.d.ts

@@ -0,0 +1,5 @@
+import "./web3.css";
+export interface ChainSwitcherProps {
+    className?: string;
+}
+export declare function ChainSwitcher({ className }: ChainSwitcherProps): import("react").JSX.Element;

package/dist/web3/ChainSwitcher.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import "./web3.css";
+import { useChainId, useSwitchChain } from "wagmi";
+import { cx } from "../util";
+// A network picker — lists the chains in your wagmi config and switches on select.
+// Neutral; style .kit-chain.
+export function ChainSwitcher({ className }) {
+    const chainId = useChainId();
+    const { chains, switchChain, isPending } = useSwitchChain();
+    return (_jsx("select", { className: cx("kit-chain", className), value: chainId, disabled: isPending, onChange: (e) => switchChain({ chainId: Number(e.target.value) }), "aria-label": "Network", children: chains.map((c) => (_jsx("option", { value: c.id, children: c.name }, c.id))) }));
+}

package/dist/web3/index.d.ts

@@ -2,3 +2,5 @@ export { Address, type AddressProps } from "./Address";
 export { Balance, type BalanceProps } from "./Balance";
 export { NetworkGuard, type NetworkGuardProps } from "./NetworkGuard";
 export { TokenAmountInput, type TokenAmountInputProps } from "./TokenAmountInput";
+export { ChainSwitcher, type ChainSwitcherProps } from "./ChainSwitcher";
+export { AddressInput, type AddressInputProps } from "./AddressInput";

package/dist/web3/index.js

@@ -2,3 +2,5 @@ export { Address } from "./Address";
 export { Balance } from "./Balance";
 export { NetworkGuard } from "./NetworkGuard";
 export { TokenAmountInput } from "./TokenAmountInput";
+export { ChainSwitcher } from "./ChainSwitcher";
+export { AddressInput } from "./AddressInput";

package/dist/web3/web3.css

@@ -12,4 +12,11 @@
 .kit-amount-sym{color:var(--kit-muted,#6b7280);font-size:14px}
 .kit-amount-max{border:0;background:transparent;color:var(--kit-muted,#6b7280);font:inherit;font-weight:600;font-size:12px;letter-spacing:.02em;text-transform:uppercase;cursor:pointer}
 .kit-amount-max:hover{color:inherit}
-@media (prefers-color-scheme:dark){.kit-net,.kit-amount{--kit-border:#2c2e36}}
+.kit-chain{font:inherit;font-size:14px;padding:8px 10px;border:1px solid var(--kit-border,#e5e7eb);border-radius:10px;background:transparent;color:inherit;cursor:pointer}
+.kit-addr-input{display:flex;align-items:center;gap:8px;border:1px solid var(--kit-border,#e5e7eb);border-radius:10px;padding:8px 10px;font:inherit}
+.kit-addr-input:focus-within{border-color:var(--kit-muted,#6b7280)}
+.kit-addr-input[data-valid]{border-color:var(--kit-success,#16a34a)}
+.kit-addr-input input{flex:1;border:0;outline:0;background:transparent;color:inherit;font:inherit;font-size:15px;min-width:0;font-variant-numeric:tabular-nums}
+.kit-addr-input-resolved{color:var(--kit-muted,#6b7280);font-size:13px;font-variant-numeric:tabular-nums}
+.kit-async-error{color:var(--kit-error,#dc2626);font:inherit;font-size:14px}
+@media (prefers-color-scheme:dark){.kit-net,.kit-amount,.kit-chain,.kit-addr-input{--kit-border:#2c2e36}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livo-build/kit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",