keyring-chatbot-agent 1.0.8 → 1.0.17
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +163 -28
- package/dist/chat-widget-wc.es.js +46 -56
- package/dist/chat-widget-wc.umd.js +2 -2
- package/dist/chat-widget.es.js +45 -55
- package/dist/chat-widget.umd.js +2 -2
- package/dist/lib.d.ts +24 -1
- package/package.json +5 -2
package/README.md
CHANGED
|
@@ -14,6 +14,7 @@ An AI-powered Web3 chatbot SDK. Provides a floating chat widget with on-chain ca
|
|
|
14
14
|
- **Trending tokens** — Per-chain trending data with quick-buy buttons
|
|
15
15
|
- **Wrap / Unwrap** — ETH ↔ WETH and equivalents on each chain
|
|
16
16
|
- **Approve token** — ERC-20 spending allowance
|
|
17
|
+
- **Custom chat UI** — Custom title, welcome message, floating button icon, header icon, suggestion buttons, and fully custom chat button
|
|
17
18
|
- **Multi-language** — English, Japanese, Chinese UI
|
|
18
19
|
- **Multi-chain** — Ethereum, Optimism, BNB Chain, Polygon, Base, Arbitrum, Avalanche, Linea
|
|
19
20
|
- **Full TypeScript** — Complete type declarations included
|
|
@@ -42,7 +43,10 @@ npm install react react-dom
|
|
|
42
43
|
|
|
43
44
|
```tsx
|
|
44
45
|
import { ChatWidget } from 'keyring-chatbot-agent';
|
|
45
|
-
import type {
|
|
46
|
+
import type {
|
|
47
|
+
Transaction,
|
|
48
|
+
TransactionResult,
|
|
49
|
+
} from 'keyring-chatbot-agent';
|
|
46
50
|
|
|
47
51
|
function App() {
|
|
48
52
|
const handleTransaction = async (
|
|
@@ -69,7 +73,10 @@ function App() {
|
|
|
69
73
|
|
|
70
74
|
```tsx
|
|
71
75
|
import { ChatWidget } from 'keyring-chatbot-agent';
|
|
72
|
-
import type {
|
|
76
|
+
import type {
|
|
77
|
+
Transaction,
|
|
78
|
+
TransactionResult,
|
|
79
|
+
} from 'keyring-chatbot-agent';
|
|
73
80
|
|
|
74
81
|
function App() {
|
|
75
82
|
const handleTransaction = async (
|
|
@@ -95,6 +102,16 @@ function App() {
|
|
|
95
102
|
buttonSize: 60,
|
|
96
103
|
zIndex: 9999,
|
|
97
104
|
}}
|
|
105
|
+
chatTitle="Keyring Assistant"
|
|
106
|
+
welcomeMessage="How can I help you today?"
|
|
107
|
+
buttonIcon="https://your-cdn.com/chat-button.svg"
|
|
108
|
+
chatIcon="https://your-cdn.com/chat-header-logo.svg"
|
|
109
|
+
customChatButton={<MyCustomButton />}
|
|
110
|
+
customSuggestions={[
|
|
111
|
+
{ text: 'Show my balance', icon: '💼' },
|
|
112
|
+
{ text: 'Swap ETH to USDC', icon: '🔄' },
|
|
113
|
+
{ text: 'What tokens are trending?' },
|
|
114
|
+
]}
|
|
98
115
|
rpcUrls={{
|
|
99
116
|
1: 'https://mainnet.infura.io/v3/YOUR_KEY',
|
|
100
117
|
10: 'https://optimism-mainnet.infura.io/v3/YOUR_KEY',
|
|
@@ -117,7 +134,10 @@ function App() {
|
|
|
117
134
|
```tsx
|
|
118
135
|
import { useSendTransaction, useAccount } from 'wagmi';
|
|
119
136
|
import { ChatWidget } from 'keyring-chatbot-agent';
|
|
120
|
-
import type {
|
|
137
|
+
import type {
|
|
138
|
+
Transaction,
|
|
139
|
+
TransactionResult,
|
|
140
|
+
} from 'keyring-chatbot-agent';
|
|
121
141
|
|
|
122
142
|
function App() {
|
|
123
143
|
const { address, chainId } = useAccount();
|
|
@@ -149,20 +169,89 @@ function App() {
|
|
|
149
169
|
|
|
150
170
|
### `<ChatWidget />` Props
|
|
151
171
|
|
|
152
|
-
| Prop
|
|
153
|
-
|
|
|
154
|
-
| `account`
|
|
155
|
-
| `onTransaction`
|
|
156
|
-
| `position`
|
|
157
|
-
| `language`
|
|
158
|
-
| `theme`
|
|
159
|
-
| `defaultOpen`
|
|
160
|
-
| `rpcUrls`
|
|
161
|
-
| `onOpen`
|
|
162
|
-
| `onClose`
|
|
172
|
+
| Prop | Type | Default | Required | Description |
|
|
173
|
+
| ------------------- | ------------------------------------------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
174
|
+
| `account` | `Account` | `undefined` | No | Connected wallet. Omit when no wallet is connected. |
|
|
175
|
+
| `onTransaction` | `(tx: Transaction) => Promise<TransactionResult>` | `undefined` | \* | Called when the chatbot needs to sign/send a transaction. |
|
|
176
|
+
| `position` | `'bottom-right'` \| `'bottom-left'` | `'bottom-right'` | No | Corner where the floating button appears. |
|
|
177
|
+
| `language` | `'en'` \| `'ja'` \| `'cn'` | `'en'` | No | UI language. |
|
|
178
|
+
| `theme` | `ChatWidgetTheme` | `{}` | No | Visual customization (color, size, z-index). |
|
|
179
|
+
| `defaultOpen` | `boolean` | `false` | No | Open the chat modal on first render. |
|
|
180
|
+
| `rpcUrls` | `Record<number, string>` | — | No | Per-chain RPC URL overrides. Takes priority over built-in defaults for balance queries and gas estimation. |
|
|
181
|
+
| `onOpen` | `() => void` | — | No | Callback fired when the modal opens. |
|
|
182
|
+
| `onClose` | `() => void` | — | No | Callback fired when the modal closes. |
|
|
183
|
+
| `chatTitle` | `string` | built-in title | No | Override the title shown in the modal header. |
|
|
184
|
+
| `welcomeMessage` | `string` | built-in message | No | Override the first assistant message shown in the conversation. |
|
|
185
|
+
| `customSuggestions` | `SuggestionButtonConfig[]` | built-in list | No | Replace the default quick suggestion buttons. Each item needs `text`; `icon` is optional. |
|
|
186
|
+
| `buttonIcon` | `string` | built-in icon | No | Custom image URL for the floating chat button icon. |
|
|
187
|
+
| `chatIcon` | `string` | built-in logo | No | Custom image URL for the modal header logo. |
|
|
188
|
+
| `customChatButton` | `React.ReactNode` | `undefined` | No | Fully custom React element to replace the default floating chat button. Click handling is applied automatically. |
|
|
163
189
|
|
|
164
190
|
> \* `onTransaction` is required to execute on-chain actions (swap, send, approve, etc.). Without it, the AI can still answer questions and display information.
|
|
165
191
|
|
|
192
|
+
### Chat UI customization
|
|
193
|
+
|
|
194
|
+
```tsx
|
|
195
|
+
<ChatWidget
|
|
196
|
+
account={{ address: userAddress, chainId: 10 }}
|
|
197
|
+
onTransaction={handleTransaction}
|
|
198
|
+
chatTitle="Keyring Pro"
|
|
199
|
+
welcomeMessage="Ask me about swaps, balances, or NFTs."
|
|
200
|
+
buttonIcon="https://your-cdn.com/button-icon.svg"
|
|
201
|
+
chatIcon="https://your-cdn.com/header-logo.svg"
|
|
202
|
+
customChatButton={
|
|
203
|
+
<div
|
|
204
|
+
style={{
|
|
205
|
+
padding: 12,
|
|
206
|
+
background: '#5B7FFF',
|
|
207
|
+
borderRadius: 16,
|
|
208
|
+
color: '#fff',
|
|
209
|
+
}}
|
|
210
|
+
>
|
|
211
|
+
💬 Chat with AI
|
|
212
|
+
</div>
|
|
213
|
+
}
|
|
214
|
+
customSuggestions={[
|
|
215
|
+
{ text: 'Check my portfolio', icon: '📊' },
|
|
216
|
+
{ text: 'Swap ETH to USDC', icon: '🔄' },
|
|
217
|
+
{ text: 'Show trending tokens' },
|
|
218
|
+
]}
|
|
219
|
+
/>
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
`customSuggestions` shape:
|
|
223
|
+
|
|
224
|
+
```ts
|
|
225
|
+
type SuggestionButtonConfig = {
|
|
226
|
+
text: string;
|
|
227
|
+
icon?: string;
|
|
228
|
+
};
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
### Clear chat history
|
|
232
|
+
|
|
233
|
+
You can clear the current chat history programmatically:
|
|
234
|
+
|
|
235
|
+
```tsx
|
|
236
|
+
import { ChatWidget, clearChat } from 'keyring-chatbot-agent';
|
|
237
|
+
|
|
238
|
+
function App() {
|
|
239
|
+
return (
|
|
240
|
+
<>
|
|
241
|
+
<button onClick={() => clearChat()}>Clear chat</button>
|
|
242
|
+
<ChatWidget
|
|
243
|
+
account={{ address: userAddress, chainId: 10 }}
|
|
244
|
+
onTransaction={handleTransaction}
|
|
245
|
+
/>
|
|
246
|
+
</>
|
|
247
|
+
);
|
|
248
|
+
}
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
### Origin whitelist behavior
|
|
252
|
+
|
|
253
|
+
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.
|
|
254
|
+
|
|
166
255
|
---
|
|
167
256
|
|
|
168
257
|
## HTML / Web Component Usage
|
|
@@ -186,13 +275,25 @@ Simple scalar values (strings, numbers, booleans) can be set directly on the HTM
|
|
|
186
275
|
|
|
187
276
|
Complex objects (`account`, `rpcUrls`, callbacks) are assigned as JavaScript properties on the element. Setting any property triggers an immediate re-render.
|
|
188
277
|
|
|
189
|
-
| Property
|
|
190
|
-
|
|
|
191
|
-
| `account`
|
|
192
|
-
| `onTransaction`
|
|
193
|
-
| `rpcUrls`
|
|
194
|
-
| `onOpen`
|
|
195
|
-
| `onClose`
|
|
278
|
+
| Property | Type | Description |
|
|
279
|
+
| ------------------- | ------------------------------------------------- | ---------------------------------------------------------- |
|
|
280
|
+
| `account` | `{ address: string; chainId: number }` | Connected wallet info |
|
|
281
|
+
| `onTransaction` | `(tx: Transaction) => Promise<TransactionResult>` | Transaction signing / sending handler |
|
|
282
|
+
| `rpcUrls` | `Record<number, string>` | Per-chain RPC URL overrides |
|
|
283
|
+
| `onOpen` | `() => void` | Callback fired when the modal opens |
|
|
284
|
+
| `onClose` | `() => void` | Callback fired when the modal closes |
|
|
285
|
+
| `chatTitle` | `string` | Custom modal header title |
|
|
286
|
+
| `welcomeMessage` | `string` | Custom first assistant message |
|
|
287
|
+
| `customSuggestions` | `{ text: string; icon?: string }[]` | Custom quick suggestion buttons |
|
|
288
|
+
| `buttonIcon` | `string` | Custom floating button icon URL |
|
|
289
|
+
| `chatIcon` | `string` | Custom modal header logo URL |
|
|
290
|
+
| `customChatButton` | `React.ReactNode` | Fully custom element replacing the default floating button |
|
|
291
|
+
|
|
292
|
+
Web Component method:
|
|
293
|
+
|
|
294
|
+
| Method | Description |
|
|
295
|
+
| ------------- | -------------------------- |
|
|
296
|
+
| `clearChat()` | Clear current chat history |
|
|
196
297
|
|
|
197
298
|
### Via CDN — UMD script tag
|
|
198
299
|
|
|
@@ -247,6 +348,22 @@ Complex objects (`account`, `rpcUrls`, callbacks) are assigned as JavaScript pro
|
|
|
247
348
|
10: 'https://optimism-mainnet.infura.io/v3/YOUR_KEY',
|
|
248
349
|
8453: 'https://mainnet.base.org',
|
|
249
350
|
};
|
|
351
|
+
|
|
352
|
+
widget.chatTitle = 'Keyring Assistant';
|
|
353
|
+
widget.welcomeMessage = 'How can I help you today?';
|
|
354
|
+
widget.buttonIcon = 'https://your-cdn.com/chat-button.svg';
|
|
355
|
+
widget.chatIcon = 'https://your-cdn.com/chat-header-logo.svg';
|
|
356
|
+
widget.customSuggestions = [
|
|
357
|
+
{ text: 'Show my balance', icon: '💼' },
|
|
358
|
+
{ text: 'Swap ETH to USDC', icon: '🔄' },
|
|
359
|
+
{ text: 'Show trending tokens' },
|
|
360
|
+
];
|
|
361
|
+
|
|
362
|
+
// Optional: use a fully custom chat button (React.ReactNode)
|
|
363
|
+
// widget.customChatButton = yourCustomElement;
|
|
364
|
+
|
|
365
|
+
// Clear chat history when needed
|
|
366
|
+
widget.clearChat();
|
|
250
367
|
</script>
|
|
251
368
|
</body>
|
|
252
369
|
</html>
|
|
@@ -398,6 +515,19 @@ interface ChatWidgetTheme {
|
|
|
398
515
|
zIndex?: number; // CSS z-index
|
|
399
516
|
}
|
|
400
517
|
|
|
518
|
+
interface SuggestionButtonConfig {
|
|
519
|
+
text: string;
|
|
520
|
+
icon?: string;
|
|
521
|
+
}
|
|
522
|
+
|
|
523
|
+
interface ChatUICustomization {
|
|
524
|
+
chatTitle?: string;
|
|
525
|
+
welcomeMessage?: string;
|
|
526
|
+
suggestions?: SuggestionButtonConfig[];
|
|
527
|
+
buttonIcon?: string;
|
|
528
|
+
chatIcon?: string;
|
|
529
|
+
}
|
|
530
|
+
|
|
401
531
|
type Language = 'en' | 'ja' | 'cn';
|
|
402
532
|
```
|
|
403
533
|
|
|
@@ -519,17 +649,22 @@ src/
|
|
|
519
649
|
## Publishing
|
|
520
650
|
|
|
521
651
|
```bash
|
|
522
|
-
#
|
|
523
|
-
|
|
524
|
-
yarn build
|
|
652
|
+
# Build a specific package name and update README/.env/package.json accordingly
|
|
653
|
+
yarn build:package keyring-chatbot-agent
|
|
525
654
|
|
|
526
|
-
#
|
|
527
|
-
|
|
655
|
+
# Publish current package, then auto commit + tag
|
|
656
|
+
yarn publish:package
|
|
528
657
|
|
|
529
|
-
#
|
|
530
|
-
|
|
658
|
+
# Build + publish all packages from SDK_PACKAGE_DATA, then push commits and tags
|
|
659
|
+
yarn publish:all
|
|
531
660
|
```
|
|
532
661
|
|
|
662
|
+
Build/publish automation behavior:
|
|
663
|
+
|
|
664
|
+
- `build:package <package-name>` updates `README.md`, `package.json`, and `.env`, then runs the build.
|
|
665
|
+
- `publish:package` publishes the current package, creates a git commit, and creates a git tag in the form `<package>@<version>`.
|
|
666
|
+
- `publish:all` loops through all package names from `SDK_PACKAGE_DATA`, builds and publishes them one by one, then pushes commits and tags.
|
|
667
|
+
|
|
533
668
|
---
|
|
534
669
|
|
|
535
670
|
## License
|