keyring-chatbot-agent-sdk-test 1.0.25 → 1.0.27

package/README.md

@@ -1,679 +1,439 @@
-# Keyring Chatbot Agent SDK
+# keyring-chatbot-agent
 
-An AI-powered Web3 chatbot SDK. Provides a floating chat widget with on-chain capabilities: token swaps, sending tokens/NFTs, viewing balances, and natural-language AI conversation.
+React chat widget — drops a floating chat button + modal into any React dApp.
+The widget answers questions and handles wallet / token / NFT lookups in the
+browser. When it proposes an on-chain action (send / approve / wrap / unwrap /
+send NFT / swap), it renders a confirmation form and hands the host an unsigned
+transaction to sign and broadcast.
 
----
-
-## Features
-
-- **Natural language AI chat** — Understands user intent, distinguishes general questions from on-chain tasks
-- **Token swaps** — Best-price routing via deBridge, automatic ERC-20 approval when needed
-- **Send tokens** — ERC-20 and native tokens, supports "max", "50%", "$5" amount expressions
-- **Send NFTs** — ERC-721 and ERC-1155, resolves NFT by name or token ID from the user's wallet
-- **View balances** — Token list with USD values
-- **Trending tokens** — Per-chain trending data with quick-buy buttons
-- **Wrap / Unwrap** — ETH ↔ WETH and equivalents on each chain
-- **Approve token** — ERC-20 spending allowance
-- **Custom chat UI** — Custom title, welcome message, floating button icon, header icon, suggestion buttons, and fully custom chat button
-- **Multi-language** — English, Japanese, Chinese UI
-- **Multi-chain** — Ethereum, Optimism, BNB Chain, Polygon, Base, Arbitrum, Avalanche, Linea
-- **Full TypeScript** — Complete type declarations included
-
----
-
-## Installation
-
-```bash
-npm install keyring-chatbot-agent-sdk-test
-# or
-yarn add keyring-chatbot-agent-sdk-test
-```
-
-**Peer dependencies** (React 17, 18, or 19):
+## Install
 
 ```bash
-npm install react react-dom
+yarn add keyring-chatbot-agent
+# peer deps
+yarn add react react-dom
 ```
 
----
-
-## React Usage
+Peer deps: `react` / `react-dom` (17, 18 or 19).
 
-### Basic example
+## Quick start
 
 ```tsx
-import { ChatWidget } from 'keyring-chatbot-agent-sdk-test';
-import type {
-  Transaction,
-  TransactionResult,
-} from 'keyring-chatbot-agent-sdk-test';
+import { ChatWidget } from 'keyring-chatbot-agent';
+import type { Transaction, TransactionResult } from 'keyring-chatbot-agent';
 
-function App() {
+export function App() {
+  // Sign + broadcast with your own wallet/provider, then report the result.
   const handleTransaction = async (
     tx: Transaction
   ): Promise<TransactionResult> => {
     try {
-      const hash = await walletClient.sendTransaction(tx);
+      const hash = await wallet.sendTransaction({
+        from: tx.from,
+        to: tx.to,
+        data: tx.data,
+        value: tx.value, // wei, decimal string
+        chainId: tx.chainId,
+      });
       return { status: 'success', transactionHash: hash };
-    } catch (err: unknown) {
+    } catch (err) {
       return { status: 'fail', error: (err as Error).message };
     }
   };
 
   return (
     <ChatWidget
-      account={{ address: '0x...', chainId: 10 }}
+      account={{ address: '0x…', chainId: 8453 }}
+      language="en"
+      position="bottom-right"
+      theme={{ buttonSize: 56 }}
       onTransaction={handleTransaction}
     />
   );
 }
 ```
 
-### Full example
+The widget creates **one chat session per mount**, persists history in
+`localStorage`, and forwards the connected wallet address + chain so wallet /
+token / NFT lookups have the context they need.
 
-```tsx
-import { ChatWidget } from 'keyring-chatbot-agent-sdk-test';
-import type {
-  Transaction,
-  TransactionResult,
-} from 'keyring-chatbot-agent-sdk-test';
+> The session is built once on mount. Changing `account`'s address/chain after
+> mount does not rebuild it — remount the widget with a new React `key` (e.g.
+> ``key={`${address}-${chainId}`}``) when you want a fresh session on account
+> switch.
 
-function App() {
-  const handleTransaction = async (
-    tx: Transaction
-  ): Promise<TransactionResult> => {
-    try {
-      const hash = await walletClient.sendTransaction(tx);
-      return { status: 'success', transactionHash: hash };
-    } catch (err: unknown) {
-      return { status: 'fail', error: (err as Error).message };
-    }
-  };
+## When the widget renders
 
-  return (
-    <ChatWidget
-      account={{ address: userAddress, chainId: 10 }}
-      onTransaction={handleTransaction}
-      position="bottom-right"
-      language="en"
-      defaultOpen={false}
-      theme={{
-        primaryColor: '#5B7FFF',
-        buttonSize: 60,
-        zIndex: 9999,
-      }}
-      chatTitle="Keyring Assistant"
-      welcomeMessage="How can I help you today?"
-      buttonIcon="https://your-cdn.com/chat-button.svg"
-      chatIcon="https://your-cdn.com/chat-header-logo.svg"
-      customChatButton={<MyCustomButton />}
-      styleButtonChat={{ bottom: 100, right: 30 }}
-      customSuggestions={[
-        { text: 'Show my balance', icon: '💼' },
-        { text: 'Swap ETH to USDC', icon: '🔄' },
-        { text: 'What tokens are trending?' },
-      ]}
-      rpcUrls={{
-        1: 'https://mainnet.infura.io/v3/YOUR_KEY',
-        10: 'https://optimism-mainnet.infura.io/v3/YOUR_KEY',
-        56: 'https://bsc-dataseed.binance.org',
-        137: 'https://polygon-rpc.com',
-        8453: 'https://mainnet.base.org',
-        42161: 'https://arb1.arbitrum.io/rpc',
-        43114: 'https://api.avax.network/ext/bc/C/rpc',
-        59144: 'https://rpc.linea.build',
-      }}
-      onOpen={() => console.log('Chat opened')}
-      onClose={() => console.log('Chat closed')}
-    />
-  );
-}
+`<ChatWidget>` returns `null` (renders nothing) unless **both**:
+
+1. `account.address` is a valid address and `account.chainId` is set, and
+2. the current `window.location.origin` is allowed.
+
+Origins are gated by `WHITELIST_ORIGIN` in `src/shared/app.ts`. `localhost`
+always passes for local dev; an empty whitelist disables the gate.
+
+## `onTransaction`
+
+Invoked when the user confirms an action form (`send` / `approve` / `wrap` /
+`unwrap` / `send_nft`) or a buy/swap confirmation. The widget passes an unsigned
+transaction; the host signs, broadcasts, and returns the result. **Required**
+for any on-chain action — without it the widget can only answer questions.
+
+```ts
+type Transaction = {
+  from: string;
+  to: string;
+  data: string;
+  value: string; // wei, decimal string
+  chainId?: number | string;
+  gasLimit?: string;
+  gasPrice?: string;
+  maxFeePerGas?: string;
+  maxPriorityFeePerGas?: string;
+  nonce?: number;
+};
+
+type TransactionResult = {
+  status: 'success' | 'fail';
+  transactionHash?: string;
+  error?: string;
+};
 ```
 
-### With wagmi v2
+Before signing, the widget pre-flights the tx against the wallet's native
+balance (gas + value). If it can't cover it, the widget posts an
+"insufficient gas" message in the user's language and never calls
+`onTransaction`. A flaky RPC fails open — the wallet stays the final gatekeeper.
+
+## Props
+
+| Prop                    | Type                                            | Default          | Notes                                                                 |
+| ----------------------- | ----------------------------------------------- | ---------------- | --------------------------------------------------------------------- |
+| `account`               | `{ address: string; chainId: number \| string }`| —                | Connected wallet. Required for the widget to render.                  |
+| `onTransaction`         | `(tx) => Promise<TransactionResult>`            | —                | Sign + broadcast handler. Required for on-chain actions.              |
+| `language`              | `'en' \| 'ja' \| 'cn'`                          | `'en'`           | UI language. Per-message language from the agent is honored too.      |
+| `rpcUrls`               | `Record<number, string>`                        | built-in         | RPC per **numeric** chainId. Merged over the built-in defaults.       |
+| `position`              | `'bottom-right' \| 'bottom-left'`               | `'bottom-right'` | Anchor of the floating button + modal.                                |
+| `theme`                 | `ChatWidgetTheme`                               | `{}`             | `primaryColor`, `buttonSize`, `zIndex`, `modalChatStyle`, `offset`.   |
+| `defaultOpen`           | `boolean`                                       | `false`          | Open the modal on mount.                                              |
+| `onOpen` / `onClose`    | `() => void`                                    | —                | Fired when the modal opens / closes.                                  |
+| `chatTitle`             | `string`                                        | built-in         | Header title.                                                         |
+| `welcomeMessage`        | `string`                                        | localized        | First bot bubble.                                                     |
+| `customSuggestions`     | `SuggestionButtonConfig[]`                      | built-in chips   | Replace the default suggestion chips.                                 |
+| `additionalSuggestions` | `SuggestionButtonConfig[]`                      | —                | Append extra chips after the base set.                                |
+| `buttonIcon`            | `string`                                        | —                | Custom floating-button icon.                                          |
+| `chatIcon`              | `string`                                        | built-in         | Header / avatar icon.                                                 |
+| `customChatButton`      | `ReactNode`                                     | —                | Replace the floating button entirely.                                 |
+| `styleButtonChat`       | `CSSProperties`                                 | —                | Extra styles on the floating container.                               |
+| `modalConfig`           | `{ isShowIcon?: boolean }`                      | `{}`             | Modal-level toggles.                                                  |
+
+`SuggestionButtonConfig` is `{ icon?: string; text: string }`.
+
+> Agent behavior (model, subagents, storage key, data sources, …) is **not** a
+> prop — it's fixed by the package descriptor in `src/shared/app.ts`. The only
+> agent-related prop is `rpcUrls`.
+
+### Prop details & examples
+
+#### `account` (required to render)
+
+The connected wallet. Pass `undefined` while disconnected — the widget then
+renders nothing. `chainId` may be a number (`8453`) or hex string (`"0x2105"`).
 
 ```tsx
-import { useSendTransaction, useAccount } from 'wagmi';
-import { ChatWidget } from 'keyring-chatbot-agent-sdk-test';
-import type {
-  Transaction,
-  TransactionResult,
-} from 'keyring-chatbot-agent-sdk-test';
+<ChatWidget account={{ address: '0xAbc…123', chainId: 8453 }} />
 
-function App() {
-  const { address, chainId } = useAccount();
-  const { sendTransactionAsync } = useSendTransaction();
+// Disconnected → widget renders null:
+<ChatWidget account={connected ? { address, chainId } : undefined} />
+```
 
-  const handleTransaction = async (
-    tx: Transaction
-  ): Promise<TransactionResult> => {
-    try {
-      const hash = await sendTransactionAsync({
-        to: tx.to as `0x${string}`,
-        data: tx.data as `0x${string}`,
-        value: BigInt(tx.value || '0'),
-      });
-      return { status: 'success', transactionHash: hash };
-    } catch (err: unknown) {
-      return { status: 'fail', error: (err as Error).message };
-    }
-  };
+Remount on identity change to start a fresh session:
 
-  return (
-    <ChatWidget
-      account={address ? { address, chainId: chainId ?? 1 } : undefined}
-      onTransaction={handleTransaction}
-    />
-  );
-}
+```tsx
+<ChatWidget key={`${address}-${chainId}`} account={{ address, chainId }} />
 ```
 
-### `<ChatWidget />` Props
-
-| Prop                | Type                                              | Default          | Required | Description                                                                                                      |
-| ------------------- | ------------------------------------------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
-| `account`           | `Account`                                         | `undefined`      | No       | Connected wallet. Omit when no wallet is connected.                                                              |
-| `onTransaction`     | `(tx: Transaction) => Promise<TransactionResult>` | `undefined`      | \*       | Called when the chatbot needs to sign/send a transaction.                                                        |
-| `position`          | `'bottom-right'` \| `'bottom-left'`               | `'bottom-right'` | No       | Corner where the floating button appears.                                                                        |
-| `language`          | `'en'` \| `'ja'` \| `'cn'`                        | `'en'`           | No       | UI language.                                                                                                     |
-| `theme`             | `ChatWidgetTheme`                                 | `{}`             | No       | Visual customization (color, size, z-index).                                                                     |
-| `defaultOpen`       | `boolean`                                         | `false`          | No       | Open the chat modal on first render.                                                                             |
-| `rpcUrls`           | `Record<number, string>`                          | —                | No       | Per-chain RPC URL overrides. Takes priority over built-in defaults for balance queries and gas estimation.       |
-| `onOpen`            | `() => void`                                      | —                | No       | Callback fired when the modal opens.                                                                             |
-| `onClose`           | `() => void`                                      | —                | No       | Callback fired when the modal closes.                                                                            |
-| `chatTitle`         | `string`                                          | built-in title   | No       | Override the title shown in the modal header.                                                                    |
-| `welcomeMessage`    | `string`                                          | built-in message | No       | Override the first assistant message shown in the conversation.                                                  |
-| `customSuggestions` | `SuggestionButtonConfig[]`                        | built-in list    | No       | Replace the default quick suggestion buttons. Each item needs `text`; `icon` is optional.                        |
-| `buttonIcon`        | `string`                                          | built-in icon    | No       | Custom image URL for the floating chat button icon.                                                              |
-| `chatIcon`          | `string`                                          | built-in logo    | No       | Custom image URL for the modal header logo.                                                                      |
-| `customChatButton`  | `React.ReactNode`                                 | `undefined`      | No       | Fully custom React element to replace the default floating chat button. Click handling is applied automatically. |
-| `styleButtonChat`   | `React.CSSProperties`                             | `undefined`      | No       | Custom CSS styles applied to the floating chat button container.                                                 |
-
-> \* `onTransaction` is required to execute on-chain actions (swap, send, approve, etc.). Without it, the AI can still answer questions and display information.
-
-### Chat UI customization
+#### `onTransaction` (required for on-chain actions)
+
+Called when the user confirms a wallet action. Sign + broadcast, then return the
+result. See [`onTransaction`](#ontransaction) for the full `Transaction` /
+`TransactionResult` shapes.
 
 ```tsx
 <ChatWidget
-  account={{ address: userAddress, chainId: 10 }}
-  onTransaction={handleTransaction}
-  chatTitle="Keyring Pro"
-  welcomeMessage="Ask me about swaps, balances, or NFTs."
-  buttonIcon="https://your-cdn.com/button-icon.svg"
-  chatIcon="https://your-cdn.com/header-logo.svg"
-  customChatButton={
-    <div
-      style={{
-        padding: 12,
-        background: '#5B7FFF',
-        borderRadius: 16,
-        color: '#fff',
-      }}
-    >
-      💬 Chat with AI
-    </div>
-  }
-  customSuggestions={[
-    { text: 'Check my portfolio', icon: '📊' },
-    { text: 'Swap ETH to USDC', icon: '🔄' },
-    { text: 'Show trending tokens' },
-  ]}
-  styleButtonChat={{ bottom: 100, right: 30 }}
+  account={{ address, chainId }}
+  onTransaction={async (tx) => {
+    try {
+      const hash = await wallet.sendTransaction(tx);
+      return { status: 'success', transactionHash: hash };
+    } catch (e) {
+      return { status: 'fail', error: (e as Error).message };
+    }
+  }}
 />
 ```
 
-`customSuggestions` shape:
+#### `language`
 
-```ts
-type SuggestionButtonConfig = {
-  text: string;
-  icon?: string;
-};
+UI language for the widget's own strings: `'en'` | `'ja'` | `'cn'`. The agent
+also tags each reply with a language, which is honored per-message.
+
+```tsx
+<ChatWidget account={acct} language="ja" />
 ```
 
-### Clear chat history
+#### `rpcUrls`
 
-You can clear the current chat history programmatically:
+Override RPC endpoints, keyed by **numeric** chainId. Merged over the built-in
+defaults, so you only list the chains you want to change.
 
 ```tsx
-import { ChatWidget, clearChat } from 'keyring-chatbot-agent-sdk-test';
-
-function App() {
-  return (
-    <>
-      <button onClick={() => clearChat()}>Clear chat</button>
-      <ChatWidget
-        account={{ address: userAddress, chainId: 10 }}
-        onTransaction={handleTransaction}
-      />
-    </>
-  );
-}
+<ChatWidget
+  account={acct}
+  rpcUrls={{
+    1: 'https://my-eth-rpc.example',
+    8453: 'https://my-base-rpc.example',
+  }}
+/>
 ```
 
-### Origin whitelist behavior
+#### `position`
 
-For packaged deployments, the widget is rendered only when the current `window.location.origin` is included in the SDK's internal whitelist. Localhost is allowed for development. If the whitelist is empty, the widget renders normally.
+Which corner the floating button + modal anchor to: `'bottom-right'` (default)
+or `'bottom-left'`.
 
----
+```tsx
+<ChatWidget account={acct} position="bottom-left" />
+```
 
-## HTML / Web Component Usage
+#### `theme`
 
-The SDK ships a **Web Component** build (`chat-widget-wc`) that can be embedded in any HTML page without a React build pipeline. The Web Component supports **the same full feature set as the React component**: wallet connection, transaction signing, RPC URL overrides, language selection, and all callbacks.
+```ts
+type ChatWidgetTheme = {
+  primaryColor?: string;
+  buttonSize?: number; // px
+  zIndex?: number;
+  modalChatStyle?: React.CSSProperties; // styles on the modal surface
+  offset?: { x: number; y: number }; // px from the anchored corner
+};
+```
 
-### Configuration via HTML attributes
+```tsx
+<ChatWidget
+  account={acct}
+  theme={{
+    primaryColor: '#0b3988',
+    buttonSize: 56,
+    zIndex: 9999,
+    offset: { x: 24, y: 24 },
+    modalChatStyle: { width: 420, maxHeight: '70vh' },
+  }}
+/>
+```
 
-Simple scalar values (strings, numbers, booleans) can be set directly on the HTML tag:
+#### `defaultOpen`, `onOpen`, `onClose`
 
-| Attribute       | Type      | Default          | Description                                      |
-| --------------- | --------- | ---------------- | ------------------------------------------------ |
-| `position`      | `string`  | `'bottom-right'` | `'bottom-right'` or `'bottom-left'`              |
-| `primary-color` | `string`  | `'#007bff'`      | Widget accent color (hex or any CSS color value) |
-| `button-size`   | `number`  | `60`             | Floating button diameter in pixels               |
-| `z-index`       | `number`  | `9999`           | CSS `z-index` of the widget                      |
-| `default-open`  | `boolean` | `false`          | Set to `"true"` to open the chat on page load    |
-| `language`      | `string`  | `'en'`           | UI language: `'en'`, `'ja'`, or `'cn'`           |
+Open on mount and observe open/close.
 
-### Configuration via JavaScript properties
+```tsx
+<ChatWidget
+  account={acct}
+  defaultOpen
+  onOpen={() => analytics.track('chat_open')}
+  onClose={() => analytics.track('chat_close')}
+/>
+```
 
-Complex objects (`account`, `rpcUrls`, callbacks) are assigned as JavaScript properties on the element. Setting any property triggers an immediate re-render.
+#### `chatTitle`, `welcomeMessage`
 
-| Property            | Type                                              | Description                                                |
-| ------------------- | ------------------------------------------------- | ---------------------------------------------------------- |
-| `account`           | `{ address: string; chainId: number }`            | Connected wallet info                                      |
-| `onTransaction`     | `(tx: Transaction) => Promise<TransactionResult>` | Transaction signing / sending handler                      |
-| `rpcUrls`           | `Record<number, string>`                          | Per-chain RPC URL overrides                                |
-| `onOpen`            | `() => void`                                      | Callback fired when the modal opens                        |
-| `onClose`           | `() => void`                                      | Callback fired when the modal closes                       |
-| `chatTitle`         | `string`                                          | Custom modal header title                                  |
-| `welcomeMessage`    | `string`                                          | Custom first assistant message                             |
-| `customSuggestions` | `{ text: string; icon?: string }[]`               | Custom quick suggestion buttons                            |
-| `buttonIcon`        | `string`                                          | Custom floating button icon URL                            |
-| `chatIcon`          | `string`                                          | Custom modal header logo URL                               |
-| `customChatButton`  | `React.ReactNode`                                 | Fully custom element replacing the default floating button |
-| `styleButtonChat`   | `React.CSSProperties`                             | Custom CSS styles for the floating button container        |
+Header title and the first bot bubble.
 
-Web Component method:
+```tsx
+<ChatWidget
+  account={acct}
+  chatTitle="Ask Keyring"
+  welcomeMessage="Hi! Ask me about your wallet, tokens, or NFTs."
+/>
+```
 
-| Method        | Description                |
-| ------------- | -------------------------- |
-| `clearChat()` | Clear current chat history |
+#### `customSuggestions` vs `additionalSuggestions`
 
-### Via CDN — UMD script tag
+Suggestion chips above the input. `customSuggestions` **replaces** the built-in
+set; `additionalSuggestions` **appends** after the base set. Each chip is
+`{ icon?: string; text: string }` — `text` is sent as the prompt when tapped.
 
-```html
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <title>My dApp</title>
-  </head>
-  <body>
-    <!-- 1. Load the bundle -->
-    <script src="https://unpkg.com/keyring-chatbot-agent-sdk-test/dist/chat-widget-wc.umd.js"></script>
+```tsx
+// Replace the defaults entirely:
+<ChatWidget
+  account={acct}
+  customSuggestions={[
+    { icon: '💸', text: 'Send 0.01 ETH' },
+    { icon: '📈', text: 'Show my token balances' },
+  ]}
+/>
 
-    <!-- 2. Place the custom element with basic attributes -->
-    <chat-widget
-      id="my-chat"
-      position="bottom-right"
-      primary-color="#5B7FFF"
-      button-size="60"
-      z-index="9999"
-      language="en"
-    ></chat-widget>
-
-    <!-- 3. Assign account and onTransaction via JavaScript -->
-    <script>
-      const widget = document.getElementById('my-chat');
-
-      // Set wallet info (reassign whenever the wallet changes)
-      widget.account = { address: '0xYourWalletAddress', chainId: 10 };
-
-      // Set the transaction handler
-      widget.onTransaction = async function (tx) {
-        try {
-          // Works with any provider: ethers.js, viem, MetaMask, etc.
-          const provider = new ethers.BrowserProvider(window.ethereum);
-          const signer = await provider.getSigner();
-          const txResponse = await signer.sendTransaction({
-            to: tx.to,
-            data: tx.data,
-            value: BigInt(tx.value || '0'),
-          });
-          const receipt = await txResponse.wait();
-          return { status: 'success', transactionHash: receipt.hash };
-        } catch (err) {
-          return { status: 'fail', error: err.message };
-        }
-      };
-
-      // Optional: override RPC URLs
-      widget.rpcUrls = {
-        10: 'https://optimism-mainnet.infura.io/v3/YOUR_KEY',
-        8453: 'https://mainnet.base.org',
-      };
-
-      widget.chatTitle = 'Keyring Assistant';
-      widget.welcomeMessage = 'How can I help you today?';
-      widget.buttonIcon = 'https://your-cdn.com/chat-button.svg';
-      widget.chatIcon = 'https://your-cdn.com/chat-header-logo.svg';
-      widget.customSuggestions = [
-        { text: 'Show my balance', icon: '💼' },
-        { text: 'Swap ETH to USDC', icon: '🔄' },
-        { text: 'Show trending tokens' },
-      ];
-
-      // Optional: use a fully custom chat button (React.ReactNode)
-      // widget.customChatButton = yourCustomElement;
-
-      // Optional: custom style for the chat button container
-      // widget.styleButtonChat = { bottom: '100px', right: '30px' };
-
-      // Clear chat history when needed
-      widget.clearChat();
-    </script>
-  </body>
-</html>
+// Keep the defaults, add two more:
+<ChatWidget
+  account={acct}
+  additionalSuggestions={[{ icon: '🖼️', text: 'List my NFTs' }]}
+/>
 ```
 
-### Via CDN — ES module
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <title>My dApp</title>
-  </head>
-  <body>
-    <chat-widget
-      id="my-chat"
-      position="bottom-right"
-      language="en"
-    ></chat-widget>
+#### `buttonIcon`, `chatIcon`
 
-    <script type="module">
-      import 'https://unpkg.com/keyring-chatbot-agent-sdk-test/dist/chat-widget-wc.es.js';
+Image URLs. `buttonIcon` is the floating button; `chatIcon` is the header /
+avatar icon.
 
-      const widget = document.getElementById('my-chat');
+```tsx
+<ChatWidget
+  account={acct}
+  buttonIcon="https://cdn.example/chat.png"
+  chatIcon="https://cdn.example/avatar.png"
+/>
+```
 
-      widget.account = { address: '0xYourWalletAddress', chainId: 10 };
+#### `customChatButton`
 
-      widget.onTransaction = async (tx) => {
-        // handle transaction signing here
-      };
-    </script>
-  </body>
-</html>
-```
+Replace the floating button with your own node. The widget still owns the
+open/close behavior, so render a presentational element (no `onClick` needed).
 
-### Full MetaMask integration (plain HTML)
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <title>My dApp</title>
-    <script src="https://cdnjs.cloudflare.com/ajax/libs/ethers/6.13.0/ethers.umd.min.js"></script>
-    <script src="https://unpkg.com/keyring-chatbot-agent-sdk-test/dist/chat-widget-wc.umd.js"></script>
-  </head>
-  <body>
-    <button id="connect-btn">Connect Wallet</button>
-    <chat-widget
-      id="my-chat"
-      position="bottom-right"
-      language="en"
-    ></chat-widget>
-
-    <script>
-      const widget = document.getElementById('my-chat');
-
-      widget.onTransaction = async function (tx) {
-        try {
-          const provider = new ethers.BrowserProvider(window.ethereum);
-          const signer = await provider.getSigner();
-          const txResponse = await signer.sendTransaction({
-            to: tx.to,
-            data: tx.data,
-            value: BigInt(tx.value || '0'),
-          });
-          const receipt = await txResponse.wait();
-          return { status: 'success', transactionHash: receipt.hash };
-        } catch (err) {
-          return { status: 'fail', error: err.message };
-        }
-      };
-
-      document.getElementById('connect-btn').onclick = async function () {
-        if (!window.ethereum) return alert('Please install MetaMask!');
-        const provider = new ethers.BrowserProvider(window.ethereum);
-        const accounts = await provider.send('eth_requestAccounts', []);
-        const network = await provider.getNetwork();
-        widget.account = {
-          address: accounts[0],
-          chainId: Number(network.chainId),
-        };
-      };
-
-      // React to wallet / chain changes
-      if (window.ethereum) {
-        window.ethereum.on('accountsChanged', async (accounts) => {
-          if (accounts.length === 0) {
-            widget.account = undefined;
-          } else {
-            const provider = new ethers.BrowserProvider(window.ethereum);
-            const network = await provider.getNetwork();
-            widget.account = {
-              address: accounts[0],
-              chainId: Number(network.chainId),
-            };
-          }
-        });
-        window.ethereum.on('chainChanged', async () => {
-          const provider = new ethers.BrowserProvider(window.ethereum);
-          const network = await provider.getNetwork();
-          const accounts = await provider.listAccounts();
-          if (accounts.length > 0) {
-            widget.account = {
-              address: accounts[0].address,
-              chainId: Number(network.chainId),
-            };
-          }
-        });
-      }
-    </script>
-  </body>
-</html>
+```tsx
+<ChatWidget
+  account={acct}
+  customChatButton={
+    <div className="my-fab">
+      <img src="/chat.svg" alt="" /> Chat
+    </div>
+  }
+/>
 ```
 
----
+#### `styleButtonChat`
 
-## Type Definitions
+Extra inline styles applied to the floating container (merged over the
+position/offset styles).
 
-```typescript
-interface Account {
-  address: string; // Wallet address (0x...)
-  chainId: number | string; // EIP-155 chain ID
-}
+```tsx
+<ChatWidget account={acct} styleButtonChat={{ bottom: 96, right: 32 }} />
+```
 
-interface Transaction {
-  from: string;
-  to: string;
-  data: string; // ABI-encoded calldata (hex)
-  value: string; // Native token amount in wei
-  gasLimit?: string;
-  gasPrice?: string;
-  maxFeePerGas?: string;
-  maxPriorityFeePerGas?: string;
-  nonce?: number;
-  chainId?: number | string;
-}
+#### `modalConfig`
 
-interface TransactionResult {
-  status: 'success' | 'fail';
-  transactionHash?: string; // Present on success
-  error?: string; // Present on failure
-}
+Modal-level toggles. Currently `{ isShowIcon?: boolean }` (default `true`) —
+set `false` to hide the header icon.
 
-interface ChatWidgetTheme {
-  primaryColor?: string; // Hex / CSS color
-  buttonSize?: number; // Floating button size in px
-  zIndex?: number; // CSS z-index
-}
+```tsx
+<ChatWidget account={acct} modalConfig={{ isShowIcon: false }} />
+```
 
-interface SuggestionButtonConfig {
-  text: string;
-  icon?: string;
-}
+### A fuller example
 
-interface ChatUICustomization {
-  chatTitle?: string;
-  welcomeMessage?: string;
-  suggestions?: SuggestionButtonConfig[];
-  buttonIcon?: string;
-  chatIcon?: string;
-}
+```tsx
+import { ChatWidget } from 'keyring-chatbot-agent';
+import type { Transaction, TransactionResult } from 'keyring-chatbot-agent';
 
-type Language = 'en' | 'ja' | 'cn';
-```
+export function Chat({ address, chainId, connected }) {
+  const onTransaction = async (tx: Transaction): Promise<TransactionResult> => {
+    try {
+      const hash = await wallet.sendTransaction(tx);
+      return { status: 'success', transactionHash: hash };
+    } catch (e) {
+      return { status: 'fail', error: (e as Error).message };
+    }
+  };
 
----
-
-## Supported Chains
-
-| Chain     | Chain ID |
-| --------- | -------- |
-| Ethereum  | 1        |
-| Optimism  | 10       |
-| BNB Chain | 56       |
-| Polygon   | 137      |
-| Base      | 8453     |
-| Arbitrum  | 42161    |
-| Avalanche | 43114    |
-| Linea     | 59144    |
-
----
-
-## AI Capabilities
-
-The embedded AI (GPT-4.1-mini via Moralis Cortex) understands natural language and automatically routes to on-chain actions:
-
-| What the user says                 | Action performed                     |
-| ---------------------------------- | ------------------------------------ |
-| "Swap 1 ETH to USDC"               | Token swap via deBridge              |
-| "Swap max USDT to ETH"             | Swap with full-balance resolution    |
-| "Buy WBTC"                         | Trending token list for selection    |
-| "Send 10 USDC to 0x..."            | ERC-20 transfer                      |
-| "Send 0.05 ETH to 0x..."           | Native token transfer                |
-| "Wrap 1 ETH" / "Unwrap 0.5 WETH"   | Wrap / unwrap native token           |
-| "Show my NFTs"                     | Link to NFT gallery                  |
-| "Send my Bored Ape #1234 to 0x..." | ERC-721 / ERC-1155 transfer          |
-| "What is the current gas fee?"     | General blockchain Q&A               |
-| "What tokens are trending?"        | Trending list with quick-buy buttons |
-| "What is my balance?"              | Token list with USD values           |
-
-### Smart swap flow
-
-The AI handles missing parameters gracefully:
-
-| Available information            | Behaviour                                     |
-| -------------------------------- | --------------------------------------------- |
-| token_in + token_out + amount    | Full auto-swap: estimate → confirm → execute  |
-| token_in + token_out (no amount) | Shows 25 / 50 / 75 / 100 % amount selector    |
-| token_out only                   | Shows wallet balances to choose source token  |
-| token_in only                    | Shows trending tokens to choose destination   |
-| Neither token specified          | Asks the user to specify both tokens          |
-| ERC-20 needs approval            | Prompts Approve step before swap              |
-| Insufficient balance or fee      | Warning message, no confirmation button shown |
-
----
-
-## Build Outputs
-
-| File                         | Format | Use case                                   |
-| ---------------------------- | ------ | ------------------------------------------ |
-| `dist/chat-widget.es.js`     | ESM    | React / Vite / bundler                     |
-| `dist/chat-widget.umd.js`    | UMD    | CommonJS / `require`                       |
-| `dist/chat-widget-wc.es.js`  | ESM    | Web Component via `<script type="module">` |
-| `dist/chat-widget-wc.umd.js` | UMD    | Web Component via `<script src>` / CDN     |
-| `dist/lib.d.ts`              | Types  | TypeScript declarations                    |
-
-### Package exports map
-
-```json
-{
-  ".": {
-    "import": "dist/chat-widget.es.js",
-    "require": "dist/chat-widget.umd.js",
-    "types": "dist/lib.d.ts"
-  },
-  "./web-component": {
-    "import": "dist/chat-widget-wc.es.js",
-    "require": "dist/chat-widget-wc.umd.js"
-  }
+  return (
+    <ChatWidget
+      key={`${address}-${chainId}`}
+      account={connected ? { address, chainId } : undefined}
+      onTransaction={onTransaction}
+      language="en"
+      position="bottom-right"
+      theme={{ primaryColor: '#0b3988', buttonSize: 56, offset: { x: 24, y: 24 } }}
+      chatTitle="Ask Keyring"
+      welcomeMessage="Hi! Ask me about your wallet, tokens, or NFTs."
+      additionalSuggestions={[{ icon: '🖼️', text: 'List my NFTs' }]}
+      rpcUrls={{ 8453: 'https://my-base-rpc.example' }}
+      onOpen={() => console.log('opened')}
+    />
+  );
 }
 ```
 
-## Project Structure
+## Clearing history
 
-```
-src/
-├── components/
-│   ├── ActionForm.tsx           # Inline transaction forms (send, approve, ...)
-│   ├── ChatButton.tsx           # Floating action button
-│   ├── ChatModal.tsx            # Chat UI + all AI and on-chain logic
-│   ├── ChatWidget.tsx           # Root component — public API entry point
-│   ├── MessageContent.tsx       # Markdown message renderer
-│   ├── ScrollToBottomButton.tsx
-│   └── WalletUserInfo.tsx
-├── constants/
-│   ├── agentActions.ts          # AgentActionType definitions + form schemas
-│   ├── chains.ts                # Supported chain configs
-│   ├── storage.ts               # localStorage key constants
-│   └── systemPrompt.ts          # AI system prompt builder
-├── contexts/
-│   ├── ConfigContext.tsx        # RPC URLs + theme config context
-│   ├── ConnectContext.tsx       # Wallet account context
-│   └── LanguageContext.tsx      # i18n language context
-├── hooks/
-│   └── useChatMessages.ts       # Chat message state management
-├── services/
-│   ├── BaseApi.ts               # Base HTTP client
-│   ├── deBridge.ts              # deBridge swap quote + transaction API
-│   ├── gemini.ts                # Gemini AI: question classification, general chat
-│   ├── moralis.ts               # Moralis AI chat, wallet balances, NFTs, metadata
-│   ├── token.ts                 # Token info + trending data
-│   └── web3.ts                  # Transaction builder, fee estimation, allowance check
-├── types/
-│   └── index.ts                 # All public TypeScript interfaces
-├── lib.tsx                      # React library entry point
-└── web-component.tsx            # Web Component entry point
-```
+Reset the active widget's chat history imperatively — e.g. on logout — without
+holding a ref:
 
----
+```ts
+import { clearChat } from 'keyring-chatbot-agent';
 
-## Publishing
+function onLogout() {
+  clearChat(); // clears in-memory + localStorage history and re-shows suggestions
+}
+```
 
-```bash
-# Build a specific package name and update README/.env/package.json accordingly
-yarn build:package keyring-chatbot-agent-sdk-test
+## Compose your own UI
 
-# Publish current package, then auto commit + tag
-yarn publish:package
+For a custom layout that reuses the same wiring, skip `<ChatWidget>` and compose
+the providers + hooks yourself:
 
-# Build + publish all packages from SDK_PACKAGE_DATA, then push commits and tags
-yarn publish:all
+```tsx
+import {
+  ConfigProvider,
+  ConnectProvider,
+  LanguageProvider,
+  useAgent,
+  useAgentChat,
+  ActionForm,
+} from 'keyring-chatbot-agent';
 ```
 
-Build/publish automation behavior:
-
-- `build:package <package-name>` updates `README.md`, `package.json`, and `.env`, then runs the build.
-- `publish:package` publishes the current package, creates a git commit, and creates a git tag in the form `<package>@<version>`.
-- `publish:all` loops through all package names from `SDK_PACKAGE_DATA`, builds and publishes them one by one, then pushes commits and tags.
-
----
+- `useAgent()` — builds the per-session chat agent (config-driven; takes no args).
+- `useAgentChat({ agent, addMessage })` — `send(text)` → reply + wallet actions.
+- `ActionForm` — the confirmation form primitive for a wallet action.
 
-## License
+## Exports
 
-ISC
+```ts
+// Widget
+import { ChatWidget, type ChatWidgetProps } from 'keyring-chatbot-agent';
+
+// Imperative
+import { clearChat } from 'keyring-chatbot-agent';
+
+// Compose-your-own
+import {
+  ConfigProvider,
+  useConfig,
+  ConnectProvider,
+  useConnect,
+  LanguageProvider,
+  useLanguage,
+  useAgent,
+  useAgentChat,
+  ActionForm,
+} from 'keyring-chatbot-agent';
+
+// Types
+import type {
+  Account,
+  ChatWidgetTheme,
+  Config,
+  Language,
+  ChatWidgetLanguage,
+  Message,
+  MessageButton,
+  MessageActionButton,
+  MessageWalletAction,
+  MessageTokenInfo,
+  MessageNftInfo,
+  WalletActionStatus,
+  SuggestionButtonConfig,
+  ChatUICustomization,
+  AgentActionType,
+  Transaction,
+  TransactionStatus,
+  TransactionResult,
+} from 'keyring-chatbot-agent';
+```