@hfunlabs/hypurr-connect 0.1.2 → 0.1.3

package/README.md

@@ -1,11 +1,13 @@
 # @hfunlabs/hypurr-connect
 
-React authentication and wallet connectivity library for the [Hyperliquid](https://hyperliquid.xyz) decentralized exchange via the [Hypurr](https://hypurr.fun) gRPC backend. Provides two authentication paths — **Telegram OAuth** and **EOA wallet** (MetaMask / browser wallet) — with a unified `ExchangeClient` API for placing orders, managing positions, and executing any L1 action.
+React authentication and wallet connectivity library for the [Hyperliquid](https://hyperliquid.xyz) decentralized exchange via the [Hypurr](https://hypurr.fun) gRPC backend. Provides two authentication paths — **Telegram OAuth** and **EOA wallet** (MetaMask / browser wallet) — with a unified `ExchangeClient` API for placing orders, managing positions, and executing both L1 and user-signed actions.
 
 ## Features
 
-- **Dual auth flows** — Telegram OAuth (server-side signing) and EOA wallet (client-side agent key signing)
-- **Unified exchange client** — Same `ExchangeClient` interface regardless of auth method
+- **Dual auth flows** — Telegram OAuth (server-side signing) and EOA wallet (client-side signing)
+- **Unified exchange client** — Same `ExchangeClient` interface regardless of auth method; handles both L1 actions (orders, cancels, leverage) and user-signed actions (transfers, withdrawals, staking)
+- **Dual wallet routing** — EOA exchange client automatically routes L1 actions through the agent key (silent) and user-signed actions through the master wallet (wallet popup)
+- **Auto agent provisioning** — Agent keys are created on-the-fly the first time an L1 action is executed; no manual `approveAgent` step required when a signer is provided
 - **Multi-wallet management** — Switch between wallets, create/delete wallets, manage wallet packs and labels (Telegram users)
 - **gRPC transport** — Custom transport that routes exchange actions through the Hypurr backend for Telegram users
 - **Agent key management** — Named agent keys (`"hypurr-connect"`) with on-chain approval, `extraAgents` validation, expiry-aware caching, and automatic dead-agent recovery
@@ -46,6 +48,7 @@ const config = {
   telegram: {
     botUsername: "YourBot",
     botId: "123456789",
+    useWidget: true,
   },
 };
 
@@ -111,14 +114,17 @@ function AppShell() {
 interface HypurrConnectConfig {
   grpcTimeout?: number; // Request timeout in ms (default: 15000)
   isTestnet?: boolean; // Use testnet endpoints (default: false)
-  telegram?: {
-    botUsername: string; // Telegram bot username for the login widget
-    botId: string; // Telegram bot ID for the OAuth URL
+  telegram: {
+    botUsername: string; // Telegram bot username (required for the widget)
+    botId?: string; // Telegram bot ID (required for the popup OAuth flow)
+    useWidget: boolean; // true = inline Telegram Login Widget, false = popup OAuth
   };
 }
 ```
 
-The `telegram` block is only required if you want to support Telegram login.
+When `useWidget` is `true`, the login modal renders Telegram's official [Login Widget](https://core.telegram.org/widgets/login) inline — no popup window is opened. This avoids popup-blocker issues and shows users the familiar Telegram button directly inside the modal. The widget requires `botUsername` and that your domain is linked to the bot via `/setdomain` in [@BotFather](https://t.me/botfather).
+
+When `useWidget` is `false` (or omitted), the popup OAuth flow is used, which requires `botId`.
 
 ### Dependencies
 
@@ -128,64 +134,115 @@ This package depends on [`hypurr-grpc`](https://gitlab.com/hypurr/hypurr-grpc) (
 
 ### Telegram Login
 
-1. User clicks "Telegram" in the `LoginModal`
-2. A popup opens to `oauth.telegram.org` with the configured bot
-3. User authorizes; Telegram posts auth data back via `postMessage`
+Two modes are available, controlled by `config.telegram.useWidget`:
+
+**Widget mode** (`useWidget: true`) — recommended:
+
+1. The `LoginModal` renders Telegram's official [Login Widget](https://core.telegram.org/widgets/login) inline
+2. User clicks the widget button and authorizes with Telegram
+3. The widget calls the `onAuth` callback with the user's auth data
 4. The provider calls the Hypurr gRPC backend (`telegramUser`) to fetch the user's wallet address and ID
 5. An `ExchangeClient` is created with `GrpcExchangeTransport` — all exchange actions are signed **server-side** by the Hypurr backend
 6. Session is persisted in localStorage (`hypurr-connect-tg-user`)
 
+**Popup mode** (`useWidget: false`):
+
+1. User clicks "Telegram" in the `LoginModal`
+2. A popup opens to `oauth.telegram.org` with the configured bot
+3. User authorizes; Telegram posts auth data back via `postMessage`
+4. Steps 4–6 are identical to widget mode
+
 ### EOA Wallet Login
 
-The EOA flow is split into two steps — **connect** and **approve** — so that the synchronous wallet connection never blocks on the signing prompt:
+When a signer is provided via `connectEoa`, the exchange client works immediately — no manual agent approval step is needed:
 
 1. User clicks "Wallet" in the `LoginModal`; the `onConnectWallet` callback fires
-2. Your app connects the wallet (e.g., via wagmi) and calls `connectEoa(address)` — this is **synchronous**, sets the user immediately, and restores a cached agent from localStorage if one is still valid
-3. When you need exchange functionality, call `approveAgent(signTypedDataAsync, chainId)`:
-   - If a valid cached agent exists, it is validated against Hyperliquid's `extraAgents` endpoint and its `validUntil` timestamp — reused only if still active
-   - If no valid agent exists, a fresh key pair is generated and approved on-chain as a **named agent** (`"hypurr-connect"`) via the SDK's `approveAgent`. Named agents are only replaced when another `ApproveAgent` is sent with the same name, so they won't be pruned by unrelated unnamed agent registrations
-   - The agent key and its `validUntil` are persisted in localStorage (`hypurr-connect-agent:{address}`)
-4. Check `agentReady` to know whether the exchange client can sign transactions. If `agentReady` is `false` and you call any method on `exchange`, the SDK throws an explicit error:
-   > `[HypurrConnect] No agent key approved. Call approveAgent(signTypedDataAsync) before using the exchange client.`
-5. Once the agent is approved, the `ExchangeClient` uses `HttpTransport` + `PrivateKeySigner` — all exchange actions are signed **client-side** with the agent key
-6. If an exchange action fails because the agent was pruned or expired, the SDK automatically clears the dead agent and surfaces the error via `error` so the consumer can prompt re-login
+2. Your app connects the wallet (e.g., via wagmi) and calls `connectEoa(address, signer)` with an `EoaSigner` — this sets the user immediately and restores a cached agent from localStorage if one is still valid
+3. The `exchange` client is ready to use right away:
+   - **User-signed actions** (transfers, withdrawals, staking) are routed directly to the master wallet — the wallet popup appears for the user to approve
+   - **L1 actions** (orders, cancels, leverage) use the agent key. If no agent exists yet, one is **auto-provisioned** on the first L1 call — this triggers a single wallet popup for the `approveAgent` signature, then the original action proceeds
+   - Named agent keys (`"hypurr-connect"`) are cached in localStorage with their `validUntil` timestamp and revalidated against Hyperliquid's `extraAgents` endpoint
+4. If an exchange action fails because the agent was pruned or expired, the SDK automatically clears the dead agent and surfaces the error via `error`
+
+Use the `createEoaSigner` helper to adapt wagmi's `signTypedDataAsync` to the `EoaSigner` interface. Pass a ref to avoid stale closure issues with React hooks:
 
 ```tsx
-// Step 1: Connect wallet (synchronous — safe to call from useEffect)
-const { connectEoa, approveAgent, agentReady, exchange } = useHypurrConnect();
+import { useHypurrConnect, createEoaSigner } from "@hfunlabs/hypurr-connect";
+import { useSignTypedData, useChainId, useAccountEffect } from "wagmi";
+
+function ConnectWallet() {
+  const { connectEoa, logout, exchange } = useHypurrConnect();
+  const { signTypedDataAsync } = useSignTypedData();
+  const chainId = useChainId();
+
+  // Keep a ref so the signer always calls the latest signTypedDataAsync
+  const signerRef = useRef(signTypedDataAsync);
+  signerRef.current = signTypedDataAsync;
+
+  useAccountEffect({
+    onConnect({ address }) {
+      connectEoa(address, createEoaSigner(signerRef, chainId));
+    },
+    onDisconnect() {
+      logout();
+    },
+  });
 
-// Call when wallet connects (e.g., wagmi onConnect callback)
-connectEoa(address);
+  // exchange is ready — L1 and user-signed actions both work
+  if (exchange) {
+    // L1 action — agent signs silently (auto-provisioned if needed)
+    await exchange.order({ orders: [/* ... */], grouping: "na" });
 
-// Step 2: Approve agent (async — triggers wallet signing prompt)
-// Pass the connected wallet's chain ID so the EIP-712 domain matches
-await approveAgent(signTypedDataAsync, chainId);
-
-// Now exchange is ready to use
-if (agentReady && exchange) {
-  await exchange.placeOrder(/* ... */);
+    // User-signed action — wallet popup appears
+    await exchange.usdSend({ destination: "0x...", amount: "100" });
+  }
 }
 ```
 
+If you prefer explicit control over agent approval (or don't need user-signed actions), you can omit the signer and call `approveAgent` manually:
+
+```tsx
+connectEoa(address); // no signer — only L1 actions after manual approval
+await approveAgent(signTypedDataAsync, chainId);
+```
+
 ### Using the Exchange Client
 
-Once authenticated, the `exchange` object from `useHypurrConnect()` is a fully functional `ExchangeClient` from `@hfunlabs/hyperliquid`. Use it for any L1 action:
+Once authenticated, the `exchange` object from `useHypurrConnect()` is a fully functional `ExchangeClient` from `@hfunlabs/hyperliquid`. For EOA users with a signer, it handles **both** L1 and user-signed actions transparently:
 
 ```tsx
 const { exchange } = useHypurrConnect();
 
-// Place an order (works identically for Telegram and EOA users)
 if (exchange) {
-  const result = await exchange.placeOrder({
-    asset: 0,
-    isBuy: true,
-    limitPx: "50000",
-    sz: "0.001",
-    orderType: { limit: { tif: "Gtc" } },
+  // L1 actions — signed by the agent key (no wallet popup)
+  await exchange.order({
+    orders: [
+      {
+        a: 0,
+        b: true,
+        p: "50000",
+        s: "0.001",
+        t: { limit: { tif: "Gtc" } },
+      },
+    ],
+    grouping: "na",
+  });
+
+  await exchange.cancelOrder({ asset: 0, oid: 12345 });
+
+  // User-signed actions — signed by the master wallet (wallet popup)
+  await exchange.usdSend({ destination: "0x...", amount: "100" });
+  await exchange.withdraw({ destination: "0x...", amount: "50" });
+  await exchange.spotSend({
+    destination: "0x...",
+    token: "PURR:0x...",
+    amount: "10",
   });
 }
 ```
 
+The routing is automatic — no need to call different methods or switch signers.
+
 ### Multi-Wallet Management (Telegram)
 
 Telegram users can have multiple wallets. The library exposes the full wallet list and lets you switch the active wallet — the `exchange` client and `user` automatically update.
@@ -294,7 +351,7 @@ Returns the full auth and exchange state. Throws if used outside `HypurrConnectP
 | `isLoading`        | `boolean`                                                                 | Whether auth is in progress                                      |
 | `error`            | `string \| null`                                                          | Last auth or dead-agent error message                            |
 | `authMethod`       | `AuthMethod`                                                              | `"telegram"`, `"eoa"`, or `null`                                 |
-| `exchange`         | `ExchangeClient \| null`                                                  | Hyperliquid exchange client for L1 actions                       |
+| `exchange`         | `ExchangeClient \| null`                                                  | Hyperliquid exchange client (L1 + user-signed actions for EOA)   |
 | `wallets`          | `HyperliquidWallet[]`                                                     | All wallets for the Telegram user (empty for EOA)                |
 | `selectedWalletId` | `number`                                                                  | ID of the currently active wallet                                |
 | `selectWallet`     | `(walletId: number) => void`                                              | Switch the active wallet                                         |
@@ -309,7 +366,7 @@ Returns the full auth and exchange state. Throws if used outside `HypurrConnectP
 | `loginModalOpen`   | `boolean`                                                                 | Whether the login modal is visible                               |
 | `openLoginModal`   | `() => void`                                                              | Show the login modal                                             |
 | `closeLoginModal`  | `() => void`                                                              | Hide the login modal                                             |
-| `connectEoa`       | `(address: \`0x\${string}\`) => void`                                     | Connect EOA wallet (sync, no signing)                            |
+| `connectEoa`       | `(address: \`0x\${string}\`, signer?: EoaSigner) => void`                 | Connect EOA wallet (sync); pass signer to enable user-signed actions and auto-provisioning |
 | `approveAgent`     | `(signTypedDataAsync: SignTypedDataFn, chainId: number) => Promise<void>` | Approve a named agent key (async, triggers wallet prompt)        |
 | `logout`           | `() => void`                                                              | Clear all auth state and localStorage                            |
 | `agent`            | `StoredAgent \| null`                                                     | Current agent key (EOA flow only)                                |
@@ -393,6 +450,31 @@ interface TelegramChatWalletPack {
 }
 ```
 
+#### `EoaSigner`
+
+Encapsulates the master wallet's EIP-712 signing function and chain ID. Pass to `connectEoa` to enable user-signed actions and auto agent provisioning.
+
+```typescript
+interface EoaSigner {
+  signTypedData: SignTypedDataFn;
+  chainId: number;
+}
+```
+
+#### `createEoaSigner(signTypedData, chainId): EoaSigner`
+
+Helper to create an `EoaSigner` from wagmi's `signTypedDataAsync` (or any compatible function). Accepts either a direct function or a `{ current: Function }` ref to avoid stale closures with React hooks:
+
+```typescript
+// With a ref (recommended for React — always calls the latest function)
+const signerRef = useRef(signTypedDataAsync);
+signerRef.current = signTypedDataAsync;
+const signer = createEoaSigner(signerRef, chainId);
+
+// With a direct function (fine for stable references)
+const signer = createEoaSigner(signTypedDataAsync, chainId);
+```
+
 #### `SignTypedDataFn`
 
 ```typescript
@@ -456,28 +538,39 @@ Both use `GrpcWebFetchTransport` with the configured `baseUrl`, `timeout`, and `
 ## Architecture
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│                  HypurrConnectProvider                   │
-│                                                         │
-│  ┌───────────────┐          ┌────────────────────────┐  │
-│  │ Telegram Auth │──gRPC──▶ │  GrpcExchangeTransport │  │
-│  │  (server-     │          │  ┌──────────────────┐   │  │
-│  │   signed)     │          │  │ telegramClient    │   │  │
-│  └───────────────┘          │  │ .hyperliquidCore  │   │  │
-│                              │  │  Action()         │   │  │
-│  ┌───────────────┐          │  └──────────────────┘   │  │
-│  │   EOA Auth    │──HTTP──▶ │  HttpTransport          │  │
-│  │  (agent key   │          │  + PrivateKeySigner     │  │
-│  │   signed)     │          └────────────────────────┘  │
-│  └───────────────┘                    │                  │
-│                                       ▼                  │
-│                              ┌──────────────┐           │
-│                              │ExchangeClient│           │
-│                              └──────────────┘           │
-│                                       │                  │
-│                                       ▼                  │
-│                              Hyperliquid L1              │
-└─────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────────┐
+│                      HypurrConnectProvider                        │
+│                                                                  │
+│  ┌──────────────────┐       ┌──────────────────────────────┐     │
+│  │  Telegram Auth    │─gRPC─▶│  GrpcExchangeTransport        │     │
+│  │  (server-signed)  │       │  telegramClient                │     │
+│  └──────────────────┘       │    .hyperliquidCoreAction()    │     │
+│                              └──────────────────────────────┘     │
+│                                                                  │
+│  ┌──────────────────┐       ┌──────────────────────────────┐     │
+│  │    EOA Auth       │─HTTP─▶│  HttpTransport + Dual Wallet   │     │
+│  │  (client-signed)  │       │                                │     │
+│  └──────────────────┘       │  signTypedData(params) ─┐      │     │
+│                              │                         │      │     │
+│                              │  domain = "Exchange"    │      │     │
+│                              │    └─▶ Agent Key        │      │     │
+│                              │        (auto-provision  │      │     │
+│                              │         if needed)      │      │     │
+│                              │                         │      │     │
+│                              │  domain = "Hyperliquid  │      │     │
+│                              │   SignTransaction"      │      │     │
+│                              │    └─▶ Master Wallet    │      │     │
+│                              │        (wallet popup)   │      │     │
+│                              └──────────────────────────────┘     │
+│                                          │                        │
+│                                          ▼                        │
+│                                 ┌──────────────┐                 │
+│                                 │ExchangeClient│                 │
+│                                 └──────────────┘                 │
+│                                          │                        │
+│                                          ▼                        │
+│                                  Hyperliquid L1                   │
+└──────────────────────────────────────────────────────────────────┘
 ```
 
 ## License

package/dist/index.d.ts

@@ -3,17 +3,18 @@ import { ReactNode } from 'react';
 import { ExchangeClient, IRequestTransport } from '@hfunlabs/hyperliquid';
 import { StaticClient } from 'hypurr-grpc/ts/hypurr/static/static_service.client';
 import { TelegramClient } from 'hypurr-grpc/ts/hypurr/telegram/telegram_service.client';
-import { HyperliquidWallet } from 'hypurr-grpc/ts/hypurr/wallet';
-export { HyperliquidWallet } from 'hypurr-grpc/ts/hypurr/wallet';
 import { TelegramChatWalletPack } from 'hypurr-grpc/ts/hypurr/user';
 export { TelegramChatWalletPack } from 'hypurr-grpc/ts/hypurr/user';
+import { HyperliquidWallet } from 'hypurr-grpc/ts/hypurr/wallet';
+export { HyperliquidWallet } from 'hypurr-grpc/ts/hypurr/wallet';
 
 interface HypurrConnectConfig {
     grpcTimeout?: number;
     isTestnet?: boolean;
-    telegram?: {
+    telegram: {
         botUsername: string;
-        botId: string;
+        botId?: string;
+        useWidget: boolean;
     };
 }
 interface TelegramLoginData {
@@ -52,6 +53,37 @@ type SignTypedDataFn = (params: {
     primaryType: string;
     message: Record<string, unknown>;
 }) => Promise<`0x${string}`>;
+/** Wallet signer provided at EOA connect time for user-signed actions. */
+interface EoaSigner {
+    signTypedData: SignTypedDataFn;
+    chainId: number;
+}
+/**
+ * Create an {@link EoaSigner} from any EIP-712 signing function.
+ *
+ * Accepts either a direct function or a `{ current }` ref object so the
+ * signer always calls through to the latest function (avoids stale closures
+ * with React hooks like wagmi's `useSignTypedData`).
+ *
+ * @example wagmi v2 — ref pattern (recommended)
+ * ```ts
+ * const { signTypedDataAsync } = useSignTypedData();
+ * const chainId = useChainId();
+ * const signerRef = useRef(signTypedDataAsync);
+ * signerRef.current = signTypedDataAsync; // stays fresh every render
+ *
+ * // call once — the ref keeps it up to date
+ * connectEoa(address, createEoaSigner(signerRef, chainId));
+ * ```
+ *
+ * @example direct function (e.g. from viem WalletClient)
+ * ```ts
+ * connectEoa(address, createEoaSigner(client.signTypedData, chainId));
+ * ```
+ */
+declare function createEoaSigner(signTypedDataAsync: ((args: Record<string, unknown>) => Promise<`0x${string}`>) | {
+    current: (args: Record<string, unknown>) => Promise<`0x${string}`>;
+}, chainId: number): EoaSigner;
 interface HypurrConnectState {
     user: HypurrUser | null;
     isLoggedIn: boolean;
@@ -84,7 +116,7 @@ interface HypurrConnectState {
     loginModalOpen: boolean;
     openLoginModal: () => void;
     closeLoginModal: () => void;
-    connectEoa: (address: `0x${string}`) => void;
+    connectEoa: (address: `0x${string}`, signer?: EoaSigner) => void;
     approveAgent: (signTypedDataAsync: SignTypedDataFn, chainId: number) => Promise<void>;
     logout: () => void;
     agent: StoredAgent | null;
@@ -108,6 +140,16 @@ interface LoginModalProps {
 }
 declare function LoginModal({ onConnectWallet, walletIcon }: LoginModalProps): react_jsx_runtime.JSX.Element;
 
+interface TelegramLoginWidgetProps {
+    botUsername: string;
+    onAuth: (data: TelegramLoginData) => void;
+    buttonSize?: "large" | "medium" | "small";
+    cornerRadius?: number;
+    showUserPhoto?: boolean;
+    requestAccess?: boolean;
+}
+declare function TelegramLoginWidget({ botUsername, onAuth, buttonSize, cornerRadius, showUserPhoto, requestAccess, }: TelegramLoginWidgetProps): react_jsx_runtime.JSX.Element;
+
 interface GrpcExchangeTransportConfig {
     isTestnet?: boolean;
     telegramClient: TelegramClient;
@@ -136,4 +178,4 @@ declare class GrpcExchangeTransport implements IRequestTransport {
 declare function createTelegramClient(config: HypurrConnectConfig): TelegramClient;
 declare function createStaticClient(config: HypurrConnectConfig): StaticClient;
 
-export { type AuthMethod, GrpcExchangeTransport, type GrpcExchangeTransportConfig, type HypurrConnectConfig, HypurrConnectProvider, type HypurrConnectState, type HypurrUser, LoginModal, type LoginModalProps, type SignTypedDataFn, type StoredAgent, type TelegramLoginData, createStaticClient, createTelegramClient, useHypurrConnect };
+export { type AuthMethod, type EoaSigner, GrpcExchangeTransport, type GrpcExchangeTransportConfig, type HypurrConnectConfig, HypurrConnectProvider, type HypurrConnectState, type HypurrUser, LoginModal, type LoginModalProps, type SignTypedDataFn, type StoredAgent, type TelegramLoginData, TelegramLoginWidget, type TelegramLoginWidgetProps, createEoaSigner, createStaticClient, createTelegramClient, useHypurrConnect };