keyring-chatbot-agent-sdk-test 1.0.8 → 1.0.12
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 +144 -36
- package/dist/chat-widget-wc.es.js +47 -56
- package/dist/chat-widget-wc.umd.js +2 -2
- package/dist/chat-widget.es.js +47 -56
- package/dist/chat-widget.umd.js +2 -2
- package/dist/lib.d.ts +23 -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, and suggestion buttons
|
|
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
|
|
@@ -23,9 +24,9 @@ An AI-powered Web3 chatbot SDK. Provides a floating chat widget with on-chain ca
|
|
|
23
24
|
## Installation
|
|
24
25
|
|
|
25
26
|
```bash
|
|
26
|
-
npm install keyring-chatbot-agent
|
|
27
|
+
npm install keyring-chatbot-agent
|
|
27
28
|
# or
|
|
28
|
-
yarn add keyring-chatbot-agent
|
|
29
|
+
yarn add keyring-chatbot-agent
|
|
29
30
|
```
|
|
30
31
|
|
|
31
32
|
**Peer dependencies** (React 17, 18, or 19):
|
|
@@ -41,8 +42,8 @@ npm install react react-dom
|
|
|
41
42
|
### Basic example
|
|
42
43
|
|
|
43
44
|
```tsx
|
|
44
|
-
import { ChatWidget } from 'keyring-chatbot-agent
|
|
45
|
-
import type { Transaction, TransactionResult } from 'keyring-chatbot-agent
|
|
45
|
+
import { ChatWidget } from 'keyring-chatbot-agent';
|
|
46
|
+
import type { Transaction, TransactionResult } from 'keyring-chatbot-agent';
|
|
46
47
|
|
|
47
48
|
function App() {
|
|
48
49
|
const handleTransaction = async (
|
|
@@ -68,8 +69,8 @@ function App() {
|
|
|
68
69
|
### Full example
|
|
69
70
|
|
|
70
71
|
```tsx
|
|
71
|
-
import { ChatWidget } from 'keyring-chatbot-agent
|
|
72
|
-
import type { Transaction, TransactionResult } from 'keyring-chatbot-agent
|
|
72
|
+
import { ChatWidget } from 'keyring-chatbot-agent';
|
|
73
|
+
import type { Transaction, TransactionResult } from 'keyring-chatbot-agent';
|
|
73
74
|
|
|
74
75
|
function App() {
|
|
75
76
|
const handleTransaction = async (
|
|
@@ -95,6 +96,15 @@ function App() {
|
|
|
95
96
|
buttonSize: 60,
|
|
96
97
|
zIndex: 9999,
|
|
97
98
|
}}
|
|
99
|
+
chatTitle="Keyring Assistant"
|
|
100
|
+
welcomeMessage="How can I help you today?"
|
|
101
|
+
buttonIcon="https://your-cdn.com/chat-button.svg"
|
|
102
|
+
chatIcon="https://your-cdn.com/chat-header-logo.svg"
|
|
103
|
+
customSuggestions={[
|
|
104
|
+
{ text: 'Show my balance', icon: '💼' },
|
|
105
|
+
{ text: 'Swap ETH to USDC', icon: '🔄' },
|
|
106
|
+
{ text: 'What tokens are trending?' },
|
|
107
|
+
]}
|
|
98
108
|
rpcUrls={{
|
|
99
109
|
1: 'https://mainnet.infura.io/v3/YOUR_KEY',
|
|
100
110
|
10: 'https://optimism-mainnet.infura.io/v3/YOUR_KEY',
|
|
@@ -116,8 +126,8 @@ function App() {
|
|
|
116
126
|
|
|
117
127
|
```tsx
|
|
118
128
|
import { useSendTransaction, useAccount } from 'wagmi';
|
|
119
|
-
import { ChatWidget } from 'keyring-chatbot-agent
|
|
120
|
-
import type { Transaction, TransactionResult } from 'keyring-chatbot-agent
|
|
129
|
+
import { ChatWidget } from 'keyring-chatbot-agent';
|
|
130
|
+
import type { Transaction, TransactionResult } from 'keyring-chatbot-agent';
|
|
121
131
|
|
|
122
132
|
function App() {
|
|
123
133
|
const { address, chainId } = useAccount();
|
|
@@ -149,20 +159,76 @@ function App() {
|
|
|
149
159
|
|
|
150
160
|
### `<ChatWidget />` Props
|
|
151
161
|
|
|
152
|
-
| Prop
|
|
153
|
-
|
|
|
154
|
-
| `account`
|
|
155
|
-
| `onTransaction`
|
|
156
|
-
| `position`
|
|
157
|
-
| `language`
|
|
158
|
-
| `theme`
|
|
159
|
-
| `defaultOpen`
|
|
160
|
-
| `rpcUrls`
|
|
161
|
-
| `onOpen`
|
|
162
|
-
| `onClose`
|
|
162
|
+
| Prop | Type | Default | Required | Description |
|
|
163
|
+
| ------------------- | ------------------------------------------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
|
|
164
|
+
| `account` | `Account` | `undefined` | No | Connected wallet. Omit when no wallet is connected. |
|
|
165
|
+
| `onTransaction` | `(tx: Transaction) => Promise<TransactionResult>` | `undefined` | \* | Called when the chatbot needs to sign/send a transaction. |
|
|
166
|
+
| `position` | `'bottom-right'` \| `'bottom-left'` | `'bottom-right'` | No | Corner where the floating button appears. |
|
|
167
|
+
| `language` | `'en'` \| `'ja'` \| `'cn'` | `'en'` | No | UI language. |
|
|
168
|
+
| `theme` | `ChatWidgetTheme` | `{}` | No | Visual customization (color, size, z-index). |
|
|
169
|
+
| `defaultOpen` | `boolean` | `false` | No | Open the chat modal on first render. |
|
|
170
|
+
| `rpcUrls` | `Record<number, string>` | — | No | Per-chain RPC URL overrides. Takes priority over built-in defaults for balance queries and gas estimation. |
|
|
171
|
+
| `onOpen` | `() => void` | — | No | Callback fired when the modal opens. |
|
|
172
|
+
| `onClose` | `() => void` | — | No | Callback fired when the modal closes. |
|
|
173
|
+
| `chatTitle` | `string` | built-in title | No | Override the title shown in the modal header. |
|
|
174
|
+
| `welcomeMessage` | `string` | built-in message | No | Override the first assistant message shown in the conversation. |
|
|
175
|
+
| `customSuggestions` | `SuggestionButtonConfig[]` | built-in list | No | Replace the default quick suggestion buttons. Each item needs `text`; `icon` is optional. |
|
|
176
|
+
| `buttonIcon` | `string` | built-in icon | No | Custom image URL for the floating chat button icon. |
|
|
177
|
+
| `chatIcon` | `string` | built-in logo | No | Custom image URL for the modal header logo. |
|
|
163
178
|
|
|
164
179
|
> \* `onTransaction` is required to execute on-chain actions (swap, send, approve, etc.). Without it, the AI can still answer questions and display information.
|
|
165
180
|
|
|
181
|
+
### Chat UI customization
|
|
182
|
+
|
|
183
|
+
```tsx
|
|
184
|
+
<ChatWidget
|
|
185
|
+
account={{ address: userAddress, chainId: 10 }}
|
|
186
|
+
onTransaction={handleTransaction}
|
|
187
|
+
chatTitle="Keyring Pro"
|
|
188
|
+
welcomeMessage="Ask me about swaps, balances, or NFTs."
|
|
189
|
+
buttonIcon="https://your-cdn.com/button-icon.svg"
|
|
190
|
+
chatIcon="https://your-cdn.com/header-logo.svg"
|
|
191
|
+
customSuggestions={[
|
|
192
|
+
{ text: 'Check my portfolio', icon: '📊' },
|
|
193
|
+
{ text: 'Swap ETH to USDC', icon: '🔄' },
|
|
194
|
+
{ text: 'Show trending tokens' },
|
|
195
|
+
]}
|
|
196
|
+
/>
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
`customSuggestions` shape:
|
|
200
|
+
|
|
201
|
+
```ts
|
|
202
|
+
type SuggestionButtonConfig = {
|
|
203
|
+
text: string;
|
|
204
|
+
icon?: string;
|
|
205
|
+
};
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
### Clear chat history
|
|
209
|
+
|
|
210
|
+
You can clear the current chat history programmatically:
|
|
211
|
+
|
|
212
|
+
```tsx
|
|
213
|
+
import { ChatWidget, clearChat } from 'keyring-chatbot-agent';
|
|
214
|
+
|
|
215
|
+
function App() {
|
|
216
|
+
return (
|
|
217
|
+
<>
|
|
218
|
+
<button onClick={() => clearChat()}>Clear chat</button>
|
|
219
|
+
<ChatWidget
|
|
220
|
+
account={{ address: userAddress, chainId: 10 }}
|
|
221
|
+
onTransaction={handleTransaction}
|
|
222
|
+
/>
|
|
223
|
+
</>
|
|
224
|
+
);
|
|
225
|
+
}
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
### Origin whitelist behavior
|
|
229
|
+
|
|
230
|
+
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.
|
|
231
|
+
|
|
166
232
|
---
|
|
167
233
|
|
|
168
234
|
## HTML / Web Component Usage
|
|
@@ -186,13 +252,24 @@ Simple scalar values (strings, numbers, booleans) can be set directly on the HTM
|
|
|
186
252
|
|
|
187
253
|
Complex objects (`account`, `rpcUrls`, callbacks) are assigned as JavaScript properties on the element. Setting any property triggers an immediate re-render.
|
|
188
254
|
|
|
189
|
-
| Property
|
|
190
|
-
|
|
|
191
|
-
| `account`
|
|
192
|
-
| `onTransaction`
|
|
193
|
-
| `rpcUrls`
|
|
194
|
-
| `onOpen`
|
|
195
|
-
| `onClose`
|
|
255
|
+
| Property | Type | Description |
|
|
256
|
+
| ------------------- | ------------------------------------------------- | ------------------------------------- |
|
|
257
|
+
| `account` | `{ address: string; chainId: number }` | Connected wallet info |
|
|
258
|
+
| `onTransaction` | `(tx: Transaction) => Promise<TransactionResult>` | Transaction signing / sending handler |
|
|
259
|
+
| `rpcUrls` | `Record<number, string>` | Per-chain RPC URL overrides |
|
|
260
|
+
| `onOpen` | `() => void` | Callback fired when the modal opens |
|
|
261
|
+
| `onClose` | `() => void` | Callback fired when the modal closes |
|
|
262
|
+
| `chatTitle` | `string` | Custom modal header title |
|
|
263
|
+
| `welcomeMessage` | `string` | Custom first assistant message |
|
|
264
|
+
| `customSuggestions` | `{ text: string; icon?: string }[]` | Custom quick suggestion buttons |
|
|
265
|
+
| `buttonIcon` | `string` | Custom floating button icon URL |
|
|
266
|
+
| `chatIcon` | `string` | Custom modal header logo URL |
|
|
267
|
+
|
|
268
|
+
Web Component method:
|
|
269
|
+
|
|
270
|
+
| Method | Description |
|
|
271
|
+
| ------------- | -------------------------- |
|
|
272
|
+
| `clearChat()` | Clear current chat history |
|
|
196
273
|
|
|
197
274
|
### Via CDN — UMD script tag
|
|
198
275
|
|
|
@@ -205,7 +282,7 @@ Complex objects (`account`, `rpcUrls`, callbacks) are assigned as JavaScript pro
|
|
|
205
282
|
</head>
|
|
206
283
|
<body>
|
|
207
284
|
<!-- 1. Load the bundle -->
|
|
208
|
-
<script src="https://unpkg.com/keyring-chatbot-agent
|
|
285
|
+
<script src="https://unpkg.com/keyring-chatbot-agent/dist/chat-widget-wc.umd.js"></script>
|
|
209
286
|
|
|
210
287
|
<!-- 2. Place the custom element with basic attributes -->
|
|
211
288
|
<chat-widget
|
|
@@ -247,6 +324,19 @@ Complex objects (`account`, `rpcUrls`, callbacks) are assigned as JavaScript pro
|
|
|
247
324
|
10: 'https://optimism-mainnet.infura.io/v3/YOUR_KEY',
|
|
248
325
|
8453: 'https://mainnet.base.org',
|
|
249
326
|
};
|
|
327
|
+
|
|
328
|
+
widget.chatTitle = 'Keyring Assistant';
|
|
329
|
+
widget.welcomeMessage = 'How can I help you today?';
|
|
330
|
+
widget.buttonIcon = 'https://your-cdn.com/chat-button.svg';
|
|
331
|
+
widget.chatIcon = 'https://your-cdn.com/chat-header-logo.svg';
|
|
332
|
+
widget.customSuggestions = [
|
|
333
|
+
{ text: 'Show my balance', icon: '💼' },
|
|
334
|
+
{ text: 'Swap ETH to USDC', icon: '🔄' },
|
|
335
|
+
{ text: 'Show trending tokens' },
|
|
336
|
+
];
|
|
337
|
+
|
|
338
|
+
// Clear chat history when needed
|
|
339
|
+
widget.clearChat();
|
|
250
340
|
</script>
|
|
251
341
|
</body>
|
|
252
342
|
</html>
|
|
@@ -269,7 +359,7 @@ Complex objects (`account`, `rpcUrls`, callbacks) are assigned as JavaScript pro
|
|
|
269
359
|
></chat-widget>
|
|
270
360
|
|
|
271
361
|
<script type="module">
|
|
272
|
-
import 'https://unpkg.com/keyring-chatbot-agent
|
|
362
|
+
import 'https://unpkg.com/keyring-chatbot-agent/dist/chat-widget-wc.es.js';
|
|
273
363
|
|
|
274
364
|
const widget = document.getElementById('my-chat');
|
|
275
365
|
|
|
@@ -292,7 +382,7 @@ Complex objects (`account`, `rpcUrls`, callbacks) are assigned as JavaScript pro
|
|
|
292
382
|
<meta charset="UTF-8" />
|
|
293
383
|
<title>My dApp</title>
|
|
294
384
|
<script src="https://cdnjs.cloudflare.com/ajax/libs/ethers/6.13.0/ethers.umd.min.js"></script>
|
|
295
|
-
<script src="https://unpkg.com/keyring-chatbot-agent
|
|
385
|
+
<script src="https://unpkg.com/keyring-chatbot-agent/dist/chat-widget-wc.umd.js"></script>
|
|
296
386
|
</head>
|
|
297
387
|
<body>
|
|
298
388
|
<button id="connect-btn">Connect Wallet</button>
|
|
@@ -398,6 +488,19 @@ interface ChatWidgetTheme {
|
|
|
398
488
|
zIndex?: number; // CSS z-index
|
|
399
489
|
}
|
|
400
490
|
|
|
491
|
+
interface SuggestionButtonConfig {
|
|
492
|
+
text: string;
|
|
493
|
+
icon?: string;
|
|
494
|
+
}
|
|
495
|
+
|
|
496
|
+
interface ChatUICustomization {
|
|
497
|
+
chatTitle?: string;
|
|
498
|
+
welcomeMessage?: string;
|
|
499
|
+
suggestions?: SuggestionButtonConfig[];
|
|
500
|
+
buttonIcon?: string;
|
|
501
|
+
chatIcon?: string;
|
|
502
|
+
}
|
|
503
|
+
|
|
401
504
|
type Language = 'en' | 'ja' | 'cn';
|
|
402
505
|
```
|
|
403
506
|
|
|
@@ -519,17 +622,22 @@ src/
|
|
|
519
622
|
## Publishing
|
|
520
623
|
|
|
521
624
|
```bash
|
|
522
|
-
#
|
|
523
|
-
|
|
524
|
-
yarn build
|
|
625
|
+
# Build a specific package name and update README/.env/package.json accordingly
|
|
626
|
+
yarn build:package keyring-chatbot-agent
|
|
525
627
|
|
|
526
|
-
#
|
|
527
|
-
|
|
628
|
+
# Publish current package, then auto commit + tag
|
|
629
|
+
yarn publish:package
|
|
528
630
|
|
|
529
|
-
#
|
|
530
|
-
|
|
631
|
+
# Build + publish all packages from SDK_PACKAGE_DATA, then push commits and tags
|
|
632
|
+
yarn publish:all
|
|
531
633
|
```
|
|
532
634
|
|
|
635
|
+
Build/publish automation behavior:
|
|
636
|
+
|
|
637
|
+
- `build:package <package-name>` updates `README.md`, `package.json`, and `.env`, then runs the build.
|
|
638
|
+
- `publish:package` publishes the current package, creates a git commit, and creates a git tag in the form `<package>@<version>`.
|
|
639
|
+
- `publish:all` loops through all package names from `SDK_PACKAGE_DATA`, builds and publishes them one by one, then pushes commits and tags.
|
|
640
|
+
|
|
533
641
|
---
|
|
534
642
|
|
|
535
643
|
## License
|