keyring-chatbot-agent 1.0.7 → 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.
Files changed (7) hide show
  1. package/README.md +163 -73
  2. package/dist/chat-widget-wc.es.js +46 -56
  3. package/dist/chat-widget-wc.umd.js +2 -2
  4. package/dist/chat-widget.es.js +45 -55
  5. package/dist/chat-widget.umd.js +2 -2
  6. package/dist/lib.d.ts +24 -1
  7. package/package.json +9 -3
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 { Transaction, TransactionResult } from 'keyring-chatbot-agent';
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 { Transaction, TransactionResult } from 'keyring-chatbot-agent';
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 { Transaction, TransactionResult } from 'keyring-chatbot-agent';
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 | Type | Default | Required | Description |
153
- | --------------- | ------------------------------------------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
154
- | `account` | `Account` | `undefined` | No | Connected wallet. Omit when no wallet is connected. |
155
- | `onTransaction` | `(tx: Transaction) => Promise<TransactionResult>` | `undefined` | \* | Called when the chatbot needs to sign/send a transaction. |
156
- | `position` | `'bottom-right'` \| `'bottom-left'` | `'bottom-right'` | No | Corner where the floating button appears. |
157
- | `language` | `'en'` \| `'ja'` \| `'cn'` | `'en'` | No | UI language. |
158
- | `theme` | `ChatWidgetTheme` | `{}` | No | Visual customization (color, size, z-index). |
159
- | `defaultOpen` | `boolean` | `false` | No | Open the chat modal on first render. |
160
- | `rpcUrls` | `Record<number, string>` | — | No | Per-chain RPC URL overrides. Takes priority over built-in defaults for balance queries and gas estimation. |
161
- | `onOpen` | `() => void` | — | No | Callback fired when the modal opens. |
162
- | `onClose` | `() => void` | — | No | Callback fired when the modal closes. |
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 | Type | Description |
190
- | --------------- | ------------------------------------------------- | ------------------------------------- |
191
- | `account` | `{ address: string; chainId: number }` | Connected wallet info |
192
- | `onTransaction` | `(tx: Transaction) => Promise<TransactionResult>` | Transaction signing / sending handler |
193
- | `rpcUrls` | `Record<number, string>` | Per-chain RPC URL overrides |
194
- | `onOpen` | `() => void` | Callback fired when the modal opens |
195
- | `onClose` | `() => void` | Callback fired when the modal closes |
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
 
@@ -478,43 +608,6 @@ The AI handles missing parameters gracefully:
478
608
  }
479
609
  ```
480
610
 
481
- ---
482
-
483
- ## Development
484
-
485
- ```bash
486
- # Clone
487
- git clone git@bitbucket.org:bacoorteam/keyring-chatbot-agent-sdk.git
488
- cd keyring-chatbot-agent-sdk
489
-
490
- # Install dependencies
491
- yarn install
492
-
493
- # Start demo dev server
494
- yarn dev
495
-
496
- # Build both React and Web Component bundles
497
- yarn build
498
-
499
- # Build React bundle only
500
- yarn build:react
501
-
502
- # Build Web Component bundle only
503
- yarn build:wc
504
-
505
- # Watch mode (auto-rebuild on change)
506
- yarn watch
507
-
508
- # Lint
509
- yarn lint
510
- yarn lint:fix
511
-
512
- # Format
513
- yarn format
514
- ```
515
-
516
- ---
517
-
518
611
  ## Project Structure
519
612
 
520
613
  ```
@@ -556,27 +649,24 @@ src/
556
649
  ## Publishing
557
650
 
558
651
  ```bash
559
- # 1. Bump version in package.json
560
- # 2. Build
561
- yarn build
652
+ # Build a specific package name and update README/.env/package.json accordingly
653
+ yarn build:package keyring-chatbot-agent
562
654
 
563
- # 3. Login to npm
564
- npm login
655
+ # Publish current package, then auto commit + tag
656
+ yarn publish:package
565
657
 
566
- # 4. Publish
567
- npm publish
658
+ # Build + publish all packages from SDK_PACKAGE_DATA, then push commits and tags
659
+ yarn publish:all
568
660
  ```
569
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
+
570
668
  ---
571
669
 
572
670
  ## License
573
671
 
574
672
  ISC
575
-
576
- ## Repository
577
-
578
- [Bitbucket — keyring-chatbot-agent-sdk](https://bitbucket.org/bacoorteam/keyring-chatbot-agent-sdk)
579
-
580
- ## Issues
581
-
582
- [Issue tracker](https://bitbucket.org/bacoorteam/keyring-chatbot-agent-sdk/issues)