@livo-build/kit 0.1.0 → 0.1.6

package/dist/index.js

@@ -5,18 +5,39 @@
 //   wallet/    — ConnectWallet, WalletModal, useWalletConnectors
 //   provider/  — LivoWeb3Provider (wagmi + react-query)
 //   contracts/ — useContractValue, createLivoContracts (bound to Livo's generated bindings)
-//   tx/        — useTx, TxButton, decodeRevert
+//   tx/        — useTx, TxButton, TxProgress, decodeRevert
+//   auth/      — useSiwe, SignInWithEthereum (Sign-In With Ethereum vs a same-origin /api/auth)
 //   toast/     — ToastProvider, useToast
-//   data/      — useApi (same-origin /api/*), useSubgraph (indexer)
-//   web3/      — Address, Balance, NetworkGuard, TokenAmountInput
-//   ui/        — Dialog, Card, Skeleton, Spinner, EmptyState, CopyButton
-//   format     — shortAddress, formatToken, parseToken, formatUsd, timeAgo, …
+//   data/      — useApi, useSubgraph, useCollection + DataTable (search/sort/paginate), useEventSource/useWebSocket (realtime)
+//   web3/      — Address, Balance, NetworkGuard, TokenAmount(Input)
+//   token/     — useToken, useAllowance, useApprove, ApproveButton (ERC-20 + approvals)
+//   nft/       — useNFT, NFTCard, NFTMedia, MintButton (metadata + mint, ipfs-resolved)
+//   dataviz/   — Sparkline (inline SVG trend), Stat + StatGroup (dashboard metrics)
+//   user/      — useUser, UserMenu (wallet + SIWE session + Telegram link, unified)
+//   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)
+//   theme/     — KitThemeProvider (restyle the whole kit from one theme object)
+//   hooks/     — useCopyToClipboard, useLocalStorage, useDebounce, useInterval, useCountdown
+//   format     — shortAddress, formatToken, parseToken, formatUsd, formatPrice, timeAgo, …
 export * from "./wallet";
 export * from "./provider";
 export * from "./contracts";
 export * from "./tx";
+export * from "./auth";
 export * from "./toast";
 export * from "./data";
 export * from "./web3";
+export * from "./token";
+export * from "./nft";
+export * from "./dataviz";
+export * from "./user";
+export * from "./hyperliquid";
+export * from "./account";
 export * from "./ui";
+export * from "./telegram";
+export * from "./theme";
+export * from "./hooks";
 export * from "./format";

package/dist/nft/MintButton.d.ts

@@ -0,0 +1,20 @@
+import { type ReactNode } from "react";
+import type { Abi } from "viem";
+export interface MintButtonProps {
+    address: `0x${string}`;
+    abi: Abi;
+    /** Mint function name. Default "mint". */
+    functionName?: string;
+    /** Number to mint. Default 1. Passed as the first arg unless `args` is given. */
+    quantity?: number;
+    /** Price per unit in wei — total value sent = pricePerUnit * quantity. */
+    pricePerUnit?: bigint;
+    /** Explicit args (overrides the default `[quantity]`). */
+    args?: readonly unknown[];
+    className?: string;
+    children?: ReactNode;
+    toast?: boolean;
+    onSuccess?: (hash: `0x${string}`) => void;
+    onError?: (error: Error) => void;
+}
+export declare function MintButton({ address, abi, functionName, quantity, pricePerUnit, args, className, children, toast, onSuccess, onError, }: MintButtonProps): import("react").JSX.Element;

package/dist/nft/MintButton.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import {} from "react";
+import { TxButton } from "../tx/TxButton";
+// A mint button: wraps TxButton with the common shape — value = pricePerUnit ×
+// quantity, args default to [quantity]. Neutral styling (inherits .kit-btn).
+export function MintButton({ address, abi, functionName = "mint", quantity = 1, pricePerUnit, args, className, children, toast, onSuccess, onError, }) {
+    const value = pricePerUnit !== undefined ? pricePerUnit * BigInt(quantity) : undefined;
+    return (_jsx(TxButton, { address: address, abi: abi, functionName: functionName, args: args ?? [BigInt(quantity)], value: value, className: className, toast: toast, onSuccess: onSuccess, onError: onError, children: children ?? `Mint${quantity > 1 ? ` ${quantity}` : ""}` }));
+}

package/dist/nft/NFTCard.d.ts

@@ -0,0 +1,15 @@
+import "./nft.css";
+import { type ReactNode } from "react";
+import { type NftMetadata } from "./useNFT";
+export interface NFTCardProps {
+    address?: `0x${string}`;
+    tokenId?: bigint | number;
+    standard?: "erc721" | "erc1155";
+    gateway?: string;
+    /** Show the trait/attribute chips. Default true. */
+    attributes?: boolean;
+    className?: string;
+    /** Custom render given the loaded metadata (overrides the default body). */
+    children?: (meta: NftMetadata | undefined) => ReactNode;
+}
+export declare function NFTCard({ address, tokenId, standard, gateway, attributes, className, children }: NFTCardProps): import("react").JSX.Element;

package/dist/nft/NFTCard.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import "./nft.css";
+import {} from "react";
+import { useNFT } from "./useNFT";
+import { NFTMedia } from "./NFTMedia";
+import { cx } from "../util";
+// A neutral NFT card: media + name + (optional) attribute chips, loaded from the
+// contract's token metadata. Style via the .kit-nft* classes — see STYLING.md.
+export function NFTCard({ address, tokenId, standard, gateway, attributes = true, className, children }) {
+    const { metadata, image, isLoading, error } = useNFT({ address, tokenId, standard, gateway });
+    if (children)
+        return _jsx("div", { className: cx("kit-nft-card", className), children: children(metadata) });
+    return (_jsxs("div", { className: cx("kit-nft-card", className), "data-state": error ? "error" : isLoading ? "loading" : "ready", children: [_jsx(NFTMedia, { src: image, alt: metadata?.name, gateway: gateway }), _jsxs("div", { className: "kit-nft-body", children: [_jsx("div", { className: "kit-nft-name", children: metadata?.name ?? (isLoading ? "Loading…" : error ? "Unavailable" : "Untitled") }), attributes && metadata?.attributes?.length ? (_jsx("div", { className: "kit-nft-traits", children: metadata.attributes.map((a, i) => (_jsxs("span", { className: "kit-nft-trait", children: [a.trait_type ? _jsx("span", { className: "kit-nft-trait-k", children: a.trait_type }) : null, _jsx("span", { className: "kit-nft-trait-v", children: String(a.value) })] }, i))) })) : null] })] }));
+}

package/dist/nft/NFTMedia.d.ts

@@ -0,0 +1,11 @@
+import "./nft.css";
+export interface NFTMediaProps {
+    /** Media URL — ipfs://, ar://, http(s) or data: (resolved automatically). */
+    src?: string;
+    /** Treat as a <video> (autoplay/loop/muted). Default: infer from extension. */
+    video?: boolean;
+    alt?: string;
+    gateway?: string;
+    className?: string;
+}
+export declare function NFTMedia({ src, video, alt, gateway, className }: NFTMediaProps): import("react").JSX.Element;

package/dist/nft/NFTMedia.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import "./nft.css";
+import { useState } from "react";
+import { resolveUri } from "./resolveUri";
+import { cx } from "../util";
+const VIDEO_RE = /\.(mp4|webm|ogg|mov)(\?|$)/i;
+// Render NFT media from a (possibly ipfs://) URL: <img> or <video>, with a neutral
+// skeleton until it loads and a fallback box on error. Style via .kit-nft-media*.
+export function NFTMedia({ src, video, alt = "", gateway, className }) {
+    const [state, setState] = useState("loading");
+    if (!src)
+        return _jsx("div", { className: cx("kit-nft-media", "kit-nft-media-empty", className) });
+    const url = resolveUri(src, gateway);
+    const isVideo = video ?? VIDEO_RE.test(src);
+    return (_jsx("div", { className: cx("kit-nft-media", className), "data-state": state, children: isVideo ? (_jsx("video", { src: url, autoPlay: true, loop: true, muted: true, playsInline: true, onCanPlay: () => setState("ready"), onError: () => setState("error") })) : (_jsx("img", { src: url, alt: alt, loading: "lazy", onLoad: () => setState("ready"), onError: () => setState("error") })) }));
+}

package/dist/nft/index.d.ts

@@ -0,0 +1,5 @@
+export { useNFT, type UseNFTParams, type NftResult, type NftMetadata, type NftAttribute } from "./useNFT";
+export { NFTMedia, type NFTMediaProps } from "./NFTMedia";
+export { NFTCard, type NFTCardProps } from "./NFTCard";
+export { MintButton, type MintButtonProps } from "./MintButton";
+export { resolveUri } from "./resolveUri";

package/dist/nft/index.js

@@ -0,0 +1,5 @@
+export { useNFT } from "./useNFT";
+export { NFTMedia } from "./NFTMedia";
+export { NFTCard } from "./NFTCard";
+export { MintButton } from "./MintButton";
+export { resolveUri } from "./resolveUri";

package/dist/nft/nft.css

@@ -0,0 +1,16 @@
+/* NFT card + media. Neutral; restyle via these classes or --kit-* vars. */
+.kit-nft-card{display:flex;flex-direction:column;gap:0;border:1px solid var(--kit-border,#e5e7eb);border-radius:var(--kit-radius,14px);overflow:hidden;background:var(--kit-bg,#fff);font:inherit}
+.kit-nft-media{position:relative;aspect-ratio:1/1;background:var(--kit-skeleton,#f1f3f5);overflow:hidden}
+.kit-nft-media img,.kit-nft-media video{width:100%;height:100%;object-fit:cover;display:block}
+.kit-nft-media[data-state="loading"]{animation:kit-nft-pulse 1.2s ease-in-out infinite}
+.kit-nft-media-empty{aspect-ratio:1/1;background:var(--kit-skeleton,#f1f3f5)}
+@keyframes kit-nft-pulse{0%,100%{opacity:1}50%{opacity:.6}}
+.kit-nft-body{display:flex;flex-direction:column;gap:8px;padding:12px}
+.kit-nft-name{font-weight:600;font-size:15px;color:var(--kit-fg,#111827)}
+.kit-nft-traits{display:flex;flex-wrap:wrap;gap:6px}
+.kit-nft-trait{display:inline-flex;gap:4px;align-items:baseline;padding:3px 8px;border-radius:999px;background:var(--kit-skeleton,#f1f3f5);font-size:12px}
+.kit-nft-trait-k{color:var(--kit-muted,#6b7280)}
+.kit-nft-trait-v{font-weight:600;color:var(--kit-fg,#111827)}
+@media (prefers-color-scheme:dark){
+  .kit-nft-card{--kit-border:#2c2e36;--kit-bg:#15171c;--kit-fg:#f5f5f7;--kit-skeleton:#23262e}
+}

package/dist/nft/resolveUri.d.ts

@@ -0,0 +1 @@
+export declare function resolveUri(uri: string, gateway?: string): string;

package/dist/nft/resolveUri.js

@@ -0,0 +1,15 @@
+// Resolve an ipfs:// / ar:// URI to an HTTP(S) URL. http(s)/data URIs pass through.
+// (Mirrors @livo-build/runtime's resolveUri so the kit needs no runtime dependency.)
+export function resolveUri(uri, gateway = "https://ipfs.io/ipfs/") {
+    if (!uri)
+        return uri;
+    if (uri.startsWith("ipfs://")) {
+        let rest = uri.slice("ipfs://".length);
+        if (rest.startsWith("ipfs/"))
+            rest = rest.slice("ipfs/".length);
+        return gateway + rest;
+    }
+    if (uri.startsWith("ar://"))
+        return "https://arweave.net/" + uri.slice("ar://".length);
+    return uri;
+}

package/dist/nft/resolveUri.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/nft/resolveUri.test.js

@@ -0,0 +1,13 @@
+import { describe, it, expect } from "vitest";
+import { resolveUri } from "./resolveUri";
+describe("resolveUri (kit)", () => {
+    it("resolves ipfs:// (and ipfs://ipfs/), ar://, and passes http/data through", () => {
+        expect(resolveUri("ipfs://bafyCID/1.png")).toBe("https://ipfs.io/ipfs/bafyCID/1.png");
+        expect(resolveUri("ipfs://ipfs/bafyCID")).toBe("https://ipfs.io/ipfs/bafyCID");
+        expect(resolveUri("ipfs://CID", "https://x.mypinata.cloud/ipfs/")).toBe("https://x.mypinata.cloud/ipfs/CID");
+        expect(resolveUri("ar://TXID")).toBe("https://arweave.net/TXID");
+        expect(resolveUri("https://cdn/x.png")).toBe("https://cdn/x.png");
+        expect(resolveUri("data:image/svg+xml,<svg/>")).toBe("data:image/svg+xml,<svg/>");
+        expect(resolveUri("")).toBe("");
+    });
+});

package/dist/nft/useNFT.d.ts

@@ -0,0 +1,34 @@
+export interface NftAttribute {
+    trait_type?: string;
+    value?: unknown;
+    [k: string]: unknown;
+}
+export interface NftMetadata {
+    name?: string;
+    description?: string;
+    /** Image URL resolved through the gateway (ipfs:// → https). */
+    image?: string;
+    /** animation_url resolved through the gateway. */
+    animationUrl?: string;
+    attributes?: NftAttribute[];
+    raw: Record<string, unknown>;
+}
+export interface UseNFTParams {
+    /** Collection contract address. */
+    address?: `0x${string}`;
+    tokenId?: bigint | number;
+    /** ERC-1155 reads uri(id); default ERC-721 tokenURI(id). */
+    standard?: "erc721" | "erc1155";
+    /** IPFS gateway base (trailing slash). Default "https://ipfs.io/ipfs/". */
+    gateway?: string;
+}
+export interface NftResult {
+    metadata: NftMetadata | undefined;
+    /** Convenience: the resolved image URL from metadata. */
+    image: string | undefined;
+    /** The on-chain token URI (pre-fetch). */
+    uri: string | undefined;
+    isLoading: boolean;
+    error: Error | null;
+}
+export declare function useNFT(params: UseNFTParams): NftResult;

package/dist/nft/useNFT.js

@@ -0,0 +1,65 @@
+import { useReadContract } from "wagmi";
+import { useQuery } from "@tanstack/react-query";
+import { resolveUri } from "./resolveUri";
+const TOKEN_URI_ABI = [
+    { type: "function", name: "tokenURI", stateMutability: "view", inputs: [{ name: "id", type: "uint256" }], outputs: [{ type: "string" }] },
+    { type: "function", name: "uri", stateMutability: "view", inputs: [{ name: "id", type: "uint256" }], outputs: [{ type: "string" }] },
+];
+function idHex(id) {
+    return id.toString(16).padStart(64, "0");
+}
+async function loadMetadata(uri, gateway, id, standard) {
+    const sub = standard === "erc1155" ? uri.replace(/\{id\}/g, idHex(id)) : uri;
+    const resolved = resolveUri(sub, gateway);
+    let doc;
+    if (resolved.startsWith("data:")) {
+        const comma = resolved.indexOf(",");
+        const header = resolved.slice(5, comma);
+        const body = resolved.slice(comma + 1);
+        doc = JSON.parse(header.includes("base64") ? atob(body) : decodeURIComponent(body));
+    }
+    else {
+        const res = await fetch(resolved);
+        if (!res.ok)
+            throw new Error(`metadata fetch ${res.status}`);
+        doc = (await res.json());
+    }
+    const imageRaw = (doc.image ?? doc.image_url ?? doc.imageUrl);
+    const animRaw = (doc.animation_url ?? doc.animationUrl);
+    return {
+        name: doc.name,
+        description: doc.description,
+        image: imageRaw ? resolveUri(imageRaw, gateway) : undefined,
+        animationUrl: animRaw ? resolveUri(animRaw, gateway) : undefined,
+        attributes: doc.attributes,
+        raw: doc,
+    };
+}
+// Read an NFT's on-chain metadata URI, then fetch + parse it (resolving ipfs:// →
+// gateway for the doc and its image). Works for ERC-721 (tokenURI) and ERC-1155
+// (uri(id) with {id} substitution). Caches via react-query.
+export function useNFT(params) {
+    const { address, tokenId, standard = "erc721", gateway = "https://ipfs.io/ipfs/" } = params;
+    const id = tokenId === undefined ? undefined : BigInt(tokenId);
+    const fn = standard === "erc1155" ? "uri" : "tokenURI";
+    const uriRead = useReadContract({
+        address,
+        abi: TOKEN_URI_ABI,
+        functionName: fn,
+        args: id === undefined ? undefined : [id],
+        query: { enabled: Boolean(address && id !== undefined) },
+    });
+    const uri = uriRead.data;
+    const meta = useQuery({
+        queryKey: ["livo-nft", address, id?.toString(), uri, gateway],
+        queryFn: () => loadMetadata(uri, gateway, id, standard),
+        enabled: Boolean(uri),
+    });
+    return {
+        metadata: meta.data,
+        image: meta.data?.image,
+        uri,
+        isLoading: uriRead.isLoading || meta.isLoading,
+        error: uriRead.error ?? meta.error ?? null,
+    };
+}

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,5 @@
+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 { useTelegramTheme } from "./useTelegramTheme";
+export { useTelegramMainButton, useTelegramBackButton, useTelegramHaptics, type MainButtonOptions, type Haptics, } from "./miniapp";

package/dist/telegram/index.js

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

package/dist/telegram/miniapp.d.ts

@@ -0,0 +1,15 @@
+export interface MainButtonOptions {
+    text: string;
+    onClick: () => void;
+    show?: boolean;
+    enabled?: boolean;
+    progress?: boolean;
+}
+export declare function useTelegramMainButton(opts: MainButtonOptions): void;
+export declare function useTelegramBackButton(onClick: () => void, show?: boolean): void;
+export interface Haptics {
+    impact: (style?: "light" | "medium" | "heavy" | "rigid" | "soft") => void;
+    notification: (type?: "error" | "success" | "warning") => void;
+    selection: () => void;
+}
+export declare function useTelegramHaptics(): Haptics;

package/dist/telegram/miniapp.js

@@ -0,0 +1,63 @@
+import { useEffect, useRef } from "react";
+function webApp() {
+    if (typeof window === "undefined")
+        return undefined;
+    return window.Telegram?.WebApp;
+}
+// Drive the Telegram Mini App MainButton from React. No-op outside Telegram.
+export function useTelegramMainButton(opts) {
+    const cbRef = useRef(opts.onClick);
+    cbRef.current = opts.onClick;
+    useEffect(() => {
+        const mb = webApp()?.MainButton;
+        if (!mb)
+            return;
+        const handler = () => cbRef.current();
+        mb.setText(opts.text);
+        if (opts.enabled === false)
+            mb.disable();
+        else
+            mb.enable();
+        if (opts.progress)
+            mb.showProgress?.();
+        else
+            mb.hideProgress?.();
+        if (opts.show === false)
+            mb.hide();
+        else
+            mb.show();
+        mb.onClick(handler);
+        return () => {
+            mb.offClick(handler);
+            mb.hide();
+        };
+    }, [opts.text, opts.show, opts.enabled, opts.progress]);
+}
+// Drive the Telegram Mini App BackButton. No-op outside Telegram.
+export function useTelegramBackButton(onClick, show = true) {
+    const cbRef = useRef(onClick);
+    cbRef.current = onClick;
+    useEffect(() => {
+        const bb = webApp()?.BackButton;
+        if (!bb)
+            return;
+        const handler = () => cbRef.current();
+        bb.onClick(handler);
+        if (show)
+            bb.show();
+        else
+            bb.hide();
+        return () => {
+            bb.offClick(handler);
+            bb.hide();
+        };
+    }, [show]);
+}
+// Telegram haptic feedback helpers. Safely no-op outside Telegram.
+export function useTelegramHaptics() {
+    return {
+        impact: (style = "medium") => webApp()?.HapticFeedback?.impactOccurred(style),
+        notification: (type = "success") => webApp()?.HapticFeedback?.notificationOccurred(type),
+        selection: () => webApp()?.HapticFeedback?.selectionChanged(),
+    };
+}

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;