keyring-chatbot-agent 1.0.8 → 1.0.19
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 +170 -28
- package/dist/chat-widget-wc.es.js +63 -73
- package/dist/chat-widget-wc.umd.js +2 -2
- package/dist/chat-widget.es.js +47 -57
- package/dist/chat-widget.umd.js +2 -2
- package/dist/lib.d.ts +25 -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,17 @@ 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
|
+
styleButtonChat={{ bottom: 100, right: 30 }}
|
|
111
|
+
customSuggestions={[
|
|
112
|
+
{ text: 'Show my balance', icon: '💼' },
|
|
113
|
+
{ text: 'Swap ETH to USDC', icon: '🔄' },
|
|
114
|
+
{ text: 'What tokens are trending?' },
|
|
115
|
+
]}
|
|
98
116
|
rpcUrls={{
|
|
99
117
|
1: 'https://mainnet.infura.io/v3/YOUR_KEY',
|
|
100
118
|
10: 'https://optimism-mainnet.infura.io/v3/YOUR_KEY',
|
|
@@ -117,7 +135,10 @@ function App() {
|
|
|
117
135
|
```tsx
|
|
118
136
|
import { useSendTransaction, useAccount } from 'wagmi';
|
|
119
137
|
import { ChatWidget } from 'keyring-chatbot-agent';
|
|
120
|
-
import type {
|
|
138
|
+
import type {
|
|
139
|
+
Transaction,
|
|
140
|
+
TransactionResult,
|
|
141
|
+
} from 'keyring-chatbot-agent';
|
|
121
142
|
|
|
122
143
|
function App() {
|
|
123
144
|
const { address, chainId } = useAccount();
|
|
@@ -149,20 +170,91 @@ function App() {
|
|
|
149
170
|
|
|
150
171
|
### `<ChatWidget />` Props
|
|
151
172
|
|
|
152
|
-
| Prop
|
|
153
|
-
|
|
|
154
|
-
| `account`
|
|
155
|
-
| `onTransaction`
|
|
156
|
-
| `position`
|
|
157
|
-
| `language`
|
|
158
|
-
| `theme`
|
|
159
|
-
| `defaultOpen`
|
|
160
|
-
| `rpcUrls`
|
|
161
|
-
| `onOpen`
|
|
162
|
-
| `onClose`
|
|
173
|
+
| Prop | Type | Default | Required | Description |
|
|
174
|
+
| ------------------- | ------------------------------------------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
175
|
+
| `account` | `Account` | `undefined` | No | Connected wallet. Omit when no wallet is connected. |
|
|
176
|
+
| `onTransaction` | `(tx: Transaction) => Promise<TransactionResult>` | `undefined` | \* | Called when the chatbot needs to sign/send a transaction. |
|
|
177
|
+
| `position` | `'bottom-right'` \| `'bottom-left'` | `'bottom-right'` | No | Corner where the floating button appears. |
|
|
178
|
+
| `language` | `'en'` \| `'ja'` \| `'cn'` | `'en'` | No | UI language. |
|
|
179
|
+
| `theme` | `ChatWidgetTheme` | `{}` | No | Visual customization (color, size, z-index). |
|
|
180
|
+
| `defaultOpen` | `boolean` | `false` | No | Open the chat modal on first render. |
|
|
181
|
+
| `rpcUrls` | `Record<number, string>` | — | No | Per-chain RPC URL overrides. Takes priority over built-in defaults for balance queries and gas estimation. |
|
|
182
|
+
| `onOpen` | `() => void` | — | No | Callback fired when the modal opens. |
|
|
183
|
+
| `onClose` | `() => void` | — | No | Callback fired when the modal closes. |
|
|
184
|
+
| `chatTitle` | `string` | built-in title | No | Override the title shown in the modal header. |
|
|
185
|
+
| `welcomeMessage` | `string` | built-in message | No | Override the first assistant message shown in the conversation. |
|
|
186
|
+
| `customSuggestions` | `SuggestionButtonConfig[]` | built-in list | No | Replace the default quick suggestion buttons. Each item needs `text`; `icon` is optional. |
|
|
187
|
+
| `buttonIcon` | `string` | built-in icon | No | Custom image URL for the floating chat button icon. |
|
|
188
|
+
| `chatIcon` | `string` | built-in logo | No | Custom image URL for the modal header logo. |
|
|
189
|
+
| `customChatButton` | `React.ReactNode` | `undefined` | No | Fully custom React element to replace the default floating chat button. Click handling is applied automatically. |
|
|
190
|
+
| `styleButtonChat` | `React.CSSProperties` | `undefined` | No | Custom CSS styles applied to the floating chat button container. |
|
|
163
191
|
|
|
164
192
|
> \* `onTransaction` is required to execute on-chain actions (swap, send, approve, etc.). Without it, the AI can still answer questions and display information.
|
|
165
193
|
|
|
194
|
+
### Chat UI customization
|
|
195
|
+
|
|
196
|
+
```tsx
|
|
197
|
+
<ChatWidget
|
|
198
|
+
account={{ address: userAddress, chainId: 10 }}
|
|
199
|
+
onTransaction={handleTransaction}
|
|
200
|
+
chatTitle="Keyring Pro"
|
|
201
|
+
welcomeMessage="Ask me about swaps, balances, or NFTs."
|
|
202
|
+
buttonIcon="https://your-cdn.com/button-icon.svg"
|
|
203
|
+
chatIcon="https://your-cdn.com/header-logo.svg"
|
|
204
|
+
customChatButton={
|
|
205
|
+
<div
|
|
206
|
+
style={{
|
|
207
|
+
padding: 12,
|
|
208
|
+
background: '#5B7FFF',
|
|
209
|
+
borderRadius: 16,
|
|
210
|
+
color: '#fff',
|
|
211
|
+
}}
|
|
212
|
+
>
|
|
213
|
+
💬 Chat with AI
|
|
214
|
+
</div>
|
|
215
|
+
}
|
|
216
|
+
customSuggestions={[
|
|
217
|
+
{ text: 'Check my portfolio', icon: '📊' },
|
|
218
|
+
{ text: 'Swap ETH to USDC', icon: '🔄' },
|
|
219
|
+
{ text: 'Show trending tokens' },
|
|
220
|
+
]}
|
|
221
|
+
styleButtonChat={{ bottom: 100, right: 30 }}
|
|
222
|
+
/>
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
`customSuggestions` shape:
|
|
226
|
+
|
|
227
|
+
```ts
|
|
228
|
+
type SuggestionButtonConfig = {
|
|
229
|
+
text: string;
|
|
230
|
+
icon?: string;
|
|
231
|
+
};
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
### Clear chat history
|
|
235
|
+
|
|
236
|
+
You can clear the current chat history programmatically:
|
|
237
|
+
|
|
238
|
+
```tsx
|
|
239
|
+
import { ChatWidget, clearChat } from 'keyring-chatbot-agent';
|
|
240
|
+
|
|
241
|
+
function App() {
|
|
242
|
+
return (
|
|
243
|
+
<>
|
|
244
|
+
<button onClick={() => clearChat()}>Clear chat</button>
|
|
245
|
+
<ChatWidget
|
|
246
|
+
account={{ address: userAddress, chainId: 10 }}
|
|
247
|
+
onTransaction={handleTransaction}
|
|
248
|
+
/>
|
|
249
|
+
</>
|
|
250
|
+
);
|
|
251
|
+
}
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
### Origin whitelist behavior
|
|
255
|
+
|
|
256
|
+
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.
|
|
257
|
+
|
|
166
258
|
---
|
|
167
259
|
|
|
168
260
|
## HTML / Web Component Usage
|
|
@@ -186,13 +278,26 @@ Simple scalar values (strings, numbers, booleans) can be set directly on the HTM
|
|
|
186
278
|
|
|
187
279
|
Complex objects (`account`, `rpcUrls`, callbacks) are assigned as JavaScript properties on the element. Setting any property triggers an immediate re-render.
|
|
188
280
|
|
|
189
|
-
| Property
|
|
190
|
-
|
|
|
191
|
-
| `account`
|
|
192
|
-
| `onTransaction`
|
|
193
|
-
| `rpcUrls`
|
|
194
|
-
| `onOpen`
|
|
195
|
-
| `onClose`
|
|
281
|
+
| Property | Type | Description |
|
|
282
|
+
| ------------------- | ------------------------------------------------- | ---------------------------------------------------------- |
|
|
283
|
+
| `account` | `{ address: string; chainId: number }` | Connected wallet info |
|
|
284
|
+
| `onTransaction` | `(tx: Transaction) => Promise<TransactionResult>` | Transaction signing / sending handler |
|
|
285
|
+
| `rpcUrls` | `Record<number, string>` | Per-chain RPC URL overrides |
|
|
286
|
+
| `onOpen` | `() => void` | Callback fired when the modal opens |
|
|
287
|
+
| `onClose` | `() => void` | Callback fired when the modal closes |
|
|
288
|
+
| `chatTitle` | `string` | Custom modal header title |
|
|
289
|
+
| `welcomeMessage` | `string` | Custom first assistant message |
|
|
290
|
+
| `customSuggestions` | `{ text: string; icon?: string }[]` | Custom quick suggestion buttons |
|
|
291
|
+
| `buttonIcon` | `string` | Custom floating button icon URL |
|
|
292
|
+
| `chatIcon` | `string` | Custom modal header logo URL |
|
|
293
|
+
| `customChatButton` | `React.ReactNode` | Fully custom element replacing the default floating button |
|
|
294
|
+
| `styleButtonChat` | `React.CSSProperties` | Custom CSS styles for the floating button container |
|
|
295
|
+
|
|
296
|
+
Web Component method:
|
|
297
|
+
|
|
298
|
+
| Method | Description |
|
|
299
|
+
| ------------- | -------------------------- |
|
|
300
|
+
| `clearChat()` | Clear current chat history |
|
|
196
301
|
|
|
197
302
|
### Via CDN — UMD script tag
|
|
198
303
|
|
|
@@ -247,6 +352,25 @@ Complex objects (`account`, `rpcUrls`, callbacks) are assigned as JavaScript pro
|
|
|
247
352
|
10: 'https://optimism-mainnet.infura.io/v3/YOUR_KEY',
|
|
248
353
|
8453: 'https://mainnet.base.org',
|
|
249
354
|
};
|
|
355
|
+
|
|
356
|
+
widget.chatTitle = 'Keyring Assistant';
|
|
357
|
+
widget.welcomeMessage = 'How can I help you today?';
|
|
358
|
+
widget.buttonIcon = 'https://your-cdn.com/chat-button.svg';
|
|
359
|
+
widget.chatIcon = 'https://your-cdn.com/chat-header-logo.svg';
|
|
360
|
+
widget.customSuggestions = [
|
|
361
|
+
{ text: 'Show my balance', icon: '💼' },
|
|
362
|
+
{ text: 'Swap ETH to USDC', icon: '🔄' },
|
|
363
|
+
{ text: 'Show trending tokens' },
|
|
364
|
+
];
|
|
365
|
+
|
|
366
|
+
// Optional: use a fully custom chat button (React.ReactNode)
|
|
367
|
+
// widget.customChatButton = yourCustomElement;
|
|
368
|
+
|
|
369
|
+
// Optional: custom style for the chat button container
|
|
370
|
+
// widget.styleButtonChat = { bottom: '100px', right: '30px' };
|
|
371
|
+
|
|
372
|
+
// Clear chat history when needed
|
|
373
|
+
widget.clearChat();
|
|
250
374
|
</script>
|
|
251
375
|
</body>
|
|
252
376
|
</html>
|
|
@@ -398,6 +522,19 @@ interface ChatWidgetTheme {
|
|
|
398
522
|
zIndex?: number; // CSS z-index
|
|
399
523
|
}
|
|
400
524
|
|
|
525
|
+
interface SuggestionButtonConfig {
|
|
526
|
+
text: string;
|
|
527
|
+
icon?: string;
|
|
528
|
+
}
|
|
529
|
+
|
|
530
|
+
interface ChatUICustomization {
|
|
531
|
+
chatTitle?: string;
|
|
532
|
+
welcomeMessage?: string;
|
|
533
|
+
suggestions?: SuggestionButtonConfig[];
|
|
534
|
+
buttonIcon?: string;
|
|
535
|
+
chatIcon?: string;
|
|
536
|
+
}
|
|
537
|
+
|
|
401
538
|
type Language = 'en' | 'ja' | 'cn';
|
|
402
539
|
```
|
|
403
540
|
|
|
@@ -519,17 +656,22 @@ src/
|
|
|
519
656
|
## Publishing
|
|
520
657
|
|
|
521
658
|
```bash
|
|
522
|
-
#
|
|
523
|
-
|
|
524
|
-
yarn build
|
|
659
|
+
# Build a specific package name and update README/.env/package.json accordingly
|
|
660
|
+
yarn build:package keyring-chatbot-agent
|
|
525
661
|
|
|
526
|
-
#
|
|
527
|
-
|
|
662
|
+
# Publish current package, then auto commit + tag
|
|
663
|
+
yarn publish:package
|
|
528
664
|
|
|
529
|
-
#
|
|
530
|
-
|
|
665
|
+
# Build + publish all packages from SDK_PACKAGE_DATA, then push commits and tags
|
|
666
|
+
yarn publish:all
|
|
531
667
|
```
|
|
532
668
|
|
|
669
|
+
Build/publish automation behavior:
|
|
670
|
+
|
|
671
|
+
- `build:package <package-name>` updates `README.md`, `package.json`, and `.env`, then runs the build.
|
|
672
|
+
- `publish:package` publishes the current package, creates a git commit, and creates a git tag in the form `<package>@<version>`.
|
|
673
|
+
- `publish:all` loops through all package names from `SDK_PACKAGE_DATA`, builds and publishes them one by one, then pushes commits and tags.
|
|
674
|
+
|
|
533
675
|
---
|
|
534
676
|
|
|
535
677
|
## License
|