keyring-chatbot-agent-sdk-test 0.0.14 → 0.0.16

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 (4) hide show
  1. package/README.md +334 -296
  2. package/dist/chat-widget.es.js +226 -210
  3. package/dist/chat-widget.umd.js +19 -19
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -1,452 +1,490 @@
1
1
  # Keyring Chatbot Agent SDK
2
2
 
3
- An AI-powered Web3 chatbot SDK for React applications. This SDK provides a floating chat widget with advanced blockchain capabilities including token swaps, NFT management, and AI-powered assistance.
3
+ An AI-powered Web3 chatbot SDK for React applications. Provides a floating chat widget with on-chain capabilities: token swaps, NFT management, token transfers, and AI-driven assistance.
4
4
 
5
5
  ## Features
6
6
 
7
- - 🤖 **AI-Powered Assistant** - Natural language processing via Moralis Cortex (GPT-4)
8
- - 💱 **Token Swaps** - Seamless token swaps powered by deBridge
9
- - 🖼️ **NFT Management** - View and send NFTs (ERC721 & ERC1155)
10
- - 💰 **Token Operations** - Send tokens, approve spending, wrap/unwrap native tokens
11
- - 📊 **Trending Tokens** - Real-time trending token data
12
- - 🔗 **Multi-Chain Support** - Ethereum, Optimism, BSC, Polygon, Base, Arbitrum
13
- - 💬 **Beautiful UI** - Modern gradient design with responsive chat interface
14
- - ⚡ **Built with Vite** - Optimized for performance
15
- - 🔧 **TypeScript Support** - Full type definitions included
16
- - 🎯 **Easy Integration** - Simple setup with flexible configuration
7
+ - 🤖 **AI-Powered Chat** — Natural language understanding via Moralis Cortex (GPT-4.1-mini)
8
+ - 💱 **Token Swaps** — Best-price routing powered by deBridge
9
+ - 🖼️ **NFT Management** — View and transfer ERC721 / ERC1155 NFTs
10
+ - 💰 **Token Operations** — Send tokens, approve spending, wrap/unwrap native tokens
11
+ - 📊 **Trending Tokens** — Real-time trending data per chain
12
+ - 🔗 **Multi-Chain** — Ethereum, Optimism, BNB Chain, Polygon, Base, Arbitrum, Avalanche, Linea
13
+ - 🌐 **Internationalization** — English, Japanese, Chinese UI
14
+ - ⚡ **Built with Vite** — Optimized ES module and UMD builds
15
+ - 🔧 **Full TypeScript** — Complete type declarations included
16
+
17
+ ---
17
18
 
18
19
  ## Installation
19
20
 
20
21
  ```bash
21
- npm install keyring-chatbot-agent-sdk
22
+ npm install keyring-chatbot-agent-sdk-test
23
+ # or
24
+ yarn add keyring-chatbot-agent-sdk-test
22
25
  ```
23
26
 
24
- or
27
+ **Peer dependencies** (React 17, 18, or 19):
25
28
 
26
29
  ```bash
27
- yarn add keyring-chatbot-agent-sdk
30
+ npm install react react-dom
28
31
  ```
29
32
 
30
- ## Usage
33
+ ---
31
34
 
32
- ### Basic Setup with React
35
+ ## Quick Start (React)
33
36
 
34
37
  ```tsx
35
- import { ChatWidget, ConnectProvider } from 'keyring-chatbot-agent-sdk';
38
+ import { ChatWidget } from 'keyring-chatbot-agent-sdk-test';
39
+ import type {
40
+ Transaction,
41
+ TransactionResult,
42
+ } from 'keyring-chatbot-agent-sdk-test';
36
43
 
37
44
  function App() {
38
- const account = {
39
- address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb', // User wallet address
40
- chainId: 1, // Chain ID (1 = Ethereum mainnet)
41
- };
42
-
43
- const handleTransaction = async (tx: Transaction) => {
44
- // Handle transaction signing and submission
45
- console.log('Transaction:', tx);
46
- // Return TransactionResult object after processing
47
- return { status: 'success' as const, transactionHash: '0x...' };
45
+ const handleTransaction = async (
46
+ tx: Transaction
47
+ ): Promise<TransactionResult> => {
48
+ try {
49
+ // Sign and send via your wallet provider (wagmi, ethers.js, viem, etc.)
50
+ const hash = await walletClient.sendTransaction(tx);
51
+ return { status: 'success', transactionHash: hash };
52
+ } catch (err: unknown) {
53
+ return { status: 'fail', error: (err as Error).message };
54
+ }
48
55
  };
49
56
 
50
57
  return (
51
- <ConnectProvider account={account}>
52
- <div>
53
- <h1>My dApp</h1>
54
- <ChatWidget position="bottom-right" onTransaction={handleTransaction} />
55
- </div>
56
- </ConnectProvider>
58
+ <ChatWidget
59
+ account={{ address: '0x...your-wallet-address', chainId: 10 }}
60
+ onTransaction={handleTransaction}
61
+ />
57
62
  );
58
63
  }
64
+ ```
65
+
66
+ ---
67
+
68
+ ## React — Full API
69
+
70
+ ### `<ChatWidget />` Props
59
71
 
60
- export default App;
72
+ | Prop | Type | Default | Required | Description |
73
+ | --------------- | ------------------------------------------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
74
+ | `account` | `Account` | `undefined` | No | Connected wallet. Pass `undefined` when no wallet is connected. |
75
+ | `onTransaction` | `(tx: Transaction) => Promise<TransactionResult>` | `undefined` | No\* | Called when the chatbot needs to sign/send a transaction. |
76
+ | `position` | `'bottom-right'` \| `'bottom-left'` | `'bottom-right'` | No | Corner where the floating button appears. |
77
+ | `theme` | `ChatWidgetTheme` | `{}` | No | Visual customization. |
78
+ | `defaultOpen` | `boolean` | `false` | No | Open the chat modal on first render. |
79
+ | `onOpen` | `() => void` | — | No | Callback fired when the modal opens. |
80
+ | `onClose` | `() => void` | — | No | Callback fired when the modal closes. |
81
+ | `language` | `'en'` \| `'ja'` \| `'cn'` | `'en'` | No | UI language (English, Japanese, Chinese). |
82
+ | `rpcUrls` | `Record<number, string>` | — | No | Per-chain RPC URL overrides (`chainId → URL`). Takes priority over built-in defaults for balance queries and gas estimation. |
83
+
84
+ > \* `onTransaction` is required to execute on-chain actions (swap, send, approve, etc.). Without it, the AI can still answer questions and display information.
85
+
86
+ ### Basic example
87
+
88
+ ```tsx
89
+ import { ChatWidget } from 'keyring-chatbot-agent-sdk-test';
90
+
91
+ function App() {
92
+ return (
93
+ <ChatWidget
94
+ account={{ address: userAddress, chainId: 10 }}
95
+ onTransaction={handleTransaction}
96
+ language="en"
97
+ position="bottom-right"
98
+ />
99
+ );
100
+ }
61
101
  ```
62
102
 
63
- ### Advanced Configuration
103
+ ### Full example with all props
64
104
 
65
105
  ```tsx
66
- import { ChatWidget, ConnectProvider } from 'keyring-chatbot-agent-sdk';
106
+ import { ChatWidget } from 'keyring-chatbot-agent-sdk-test';
107
+ import type {
108
+ Transaction,
109
+ TransactionResult,
110
+ } from 'keyring-chatbot-agent-sdk-test';
67
111
 
68
112
  function App() {
69
- const account = {
70
- address: userWalletAddress,
71
- chainId: currentChainId,
113
+ const handleTransaction = async (
114
+ tx: Transaction
115
+ ): Promise<TransactionResult> => {
116
+ try {
117
+ const hash = await walletClient.sendTransaction(tx);
118
+ return { status: 'success', transactionHash: hash };
119
+ } catch (err: unknown) {
120
+ return { status: 'fail', error: (err as Error).message };
121
+ }
72
122
  };
73
123
 
74
- const customTheme = {
75
- primaryColor: '#5B7FFF',
76
- buttonSize: 60,
77
- zIndex: 9999,
124
+ return (
125
+ <ChatWidget
126
+ account={{ address: userAddress, chainId: 10 }}
127
+ onTransaction={handleTransaction}
128
+ position="bottom-right"
129
+ language="en"
130
+ defaultOpen={false}
131
+ theme={{
132
+ primaryColor: '#5B7FFF',
133
+ buttonSize: 60,
134
+ zIndex: 9999,
135
+ }}
136
+ rpcUrls={{
137
+ 1: 'https://mainnet.infura.io/v3/YOUR_KEY',
138
+ 10: 'https://optimism-mainnet.infura.io/v3/YOUR_KEY',
139
+ 56: 'https://bsc-dataseed.binance.org',
140
+ 137: 'https://polygon-rpc.com',
141
+ 8453: 'https://mainnet.base.org',
142
+ 42161: 'https://arb1.arbitrum.io/rpc',
143
+ 43114: 'https://api.avax.network/ext/bc/C/rpc',
144
+ 59144: 'https://rpc.linea.build',
145
+ }}
146
+ onOpen={() => console.log('Chat opened')}
147
+ onClose={() => console.log('Chat closed')}
148
+ />
149
+ );
150
+ }
151
+ ```
152
+
153
+ ### Usage with wagmi v2
154
+
155
+ ```tsx
156
+ import { useSendTransaction, useAccount } from 'wagmi';
157
+ import { ChatWidget } from 'keyring-chatbot-agent-sdk-test';
158
+ import type {
159
+ Transaction,
160
+ TransactionResult,
161
+ } from 'keyring-chatbot-agent-sdk-test';
162
+
163
+ function App() {
164
+ const { address, chainId } = useAccount();
165
+ const { sendTransactionAsync } = useSendTransaction();
166
+
167
+ const handleTransaction = async (
168
+ tx: Transaction
169
+ ): Promise<TransactionResult> => {
170
+ try {
171
+ const hash = await sendTransactionAsync({
172
+ to: tx.to as `0x${string}`,
173
+ data: tx.data as `0x${string}`,
174
+ value: BigInt(tx.value || '0'),
175
+ });
176
+ return { status: 'success', transactionHash: hash };
177
+ } catch (err: unknown) {
178
+ return { status: 'fail', error: (err as Error).message };
179
+ }
78
180
  };
79
181
 
80
182
  return (
81
- <ConnectProvider account={account}>
82
- <ChatWidget
83
- position="bottom-right"
84
- theme={customTheme}
85
- defaultOpen={false}
86
- onOpen={() => console.log('Chat opened')}
87
- onClose={() => console.log('Chat closed')}
88
- onTransaction={handleTransaction}
89
- />
90
- </ConnectProvider>
183
+ <ChatWidget
184
+ account={address ? { address, chainId: chainId ?? 1 } : undefined}
185
+ onTransaction={handleTransaction}
186
+ />
91
187
  );
92
188
  }
93
189
  ```
94
190
 
95
- ### Usage with HTML (Web Component)
191
+ ---
192
+
193
+ ## HTML — Web Component
96
194
 
97
- For applications without React, you can use the Web Component version:
195
+ The SDK ships a **Web Component** build (`chat-widget-wc`) that can be dropped into any HTML page without a React build pipeline.
98
196
 
99
- #### Using CDN (unpkg)
197
+ The web component supports visual configuration via HTML attributes (`position`, `primary-color`, `button-size`, `z-index`, `default-open`).
198
+
199
+ ### Via CDN — UMD script tag
100
200
 
101
201
  ```html
102
202
  <!DOCTYPE html>
103
203
  <html lang="en">
104
204
  <head>
105
205
  <meta charset="UTF-8" />
106
- <meta name="viewport" content="width=device-width, initial-scale=1.0" />
107
- <title>My Web3 App</title>
206
+ <title>My dApp</title>
108
207
  </head>
109
208
  <body>
110
- <h1>Welcome to My dApp</h1>
209
+ <h1>My Web3 App</h1>
111
210
 
112
- <!-- Import Web Component -->
113
- <script src="https://unpkg.com/keyring-chatbot-agent-sdk/dist/chat-widget-wc.umd.js"></script>
211
+ <!-- 1. Load the bundle -->
212
+ <script src="https://unpkg.com/keyring-chatbot-agent-sdk-test/dist/chat-widget-wc.umd.js"></script>
114
213
 
115
- <!-- Use custom element -->
214
+ <!-- 2. Place the custom element -->
116
215
  <chat-widget
117
216
  position="bottom-right"
118
217
  primary-color="#5B7FFF"
119
218
  button-size="60"
120
219
  z-index="9999"
121
220
  ></chat-widget>
122
-
123
- <script>
124
- // Set account data
125
- const widget = document.querySelector('chat-widget');
126
- widget.account = {
127
- address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
128
- chainId: 1,
129
- };
130
-
131
- // Handle transactions
132
- widget.addEventListener('transaction', async (event) => {
133
- const tx = event.detail;
134
- console.log('Transaction:', tx);
135
-
136
- // Process transaction with your wallet provider
137
- // Return result by setting the result property
138
- widget.transactionResult = 'success'; // or 'fail'
139
- });
140
-
141
- // Listen to open/close events
142
- widget.addEventListener('open', () => console.log('Chat opened'));
143
- widget.addEventListener('close', () => console.log('Chat closed'));
144
- </script>
145
- </body>
146
- </html>
147
- ```
148
-
149
- #### Using Local File
150
-
151
- ```html
152
- <!DOCTYPE html>
153
- <html lang="en">
154
- <head>
155
- <meta charset="UTF-8" />
156
- <title>My Web3 App</title>
157
- </head>
158
- <body>
159
- <h1>My dApp</h1>
160
-
161
- <!-- Import from local installation -->
162
- <script src="./node_modules/keyring-chatbot-agent-sdk/dist/chat-widget-wc.umd.js"></script>
163
-
164
- <chat-widget position="bottom-right"></chat-widget>
165
221
  </body>
166
222
  </html>
167
223
  ```
168
224
 
169
- #### Using ES Module Import
225
+ ### Via CDN — ES module
170
226
 
171
227
  ```html
172
228
  <!DOCTYPE html>
173
229
  <html lang="en">
174
230
  <head>
175
231
  <meta charset="UTF-8" />
176
- <title>My Web3 App</title>
232
+ <title>My dApp</title>
177
233
  </head>
178
234
  <body>
179
- <h1>My dApp</h1>
235
+ <h1>My Web3 App</h1>
180
236
 
181
- <chat-widget position="bottom-right"></chat-widget>
237
+ <chat-widget position="bottom-right" primary-color="#5B7FFF"></chat-widget>
182
238
 
183
239
  <script type="module">
184
- import 'https://unpkg.com/keyring-chatbot-agent-sdk/dist/chat-widget-wc.es.js';
185
-
186
- const widget = document.querySelector('chat-widget');
187
- widget.account = {
188
- address: userWalletAddress,
189
- chainId: currentChainId,
190
- };
240
+ import 'https://unpkg.com/keyring-chatbot-agent-sdk-test/dist/chat-widget-wc.es.js';
191
241
  </script>
192
242
  </body>
193
243
  </html>
194
244
  ```
195
245
 
196
- #### Web Component Attributes
197
-
198
- | Attribute | Type | Default | Description |
199
- | --------------- | --------- | ---------------- | ----------------------------------------- |
200
- | `position` | `string` | `'bottom-right'` | Position: 'bottom-right' or 'bottom-left' |
201
- | `primary-color` | `string` | `'#5B7FFF'` | Primary color (hex) |
202
- | `button-size` | `number` | `60` | Button size in pixels |
203
- | `z-index` | `number` | `9999` | z-index for positioning |
204
- | `default-open` | `boolean` | `false` | Whether chat is open by default |
246
+ ### Via local `node_modules`
205
247
 
206
- #### Web Component Properties
207
-
208
- ```javascript
209
- const widget = document.querySelector('chat-widget');
210
-
211
- // Set account
212
- widget.account = {
213
- address: '0x...',
214
- chainId: 1,
215
- };
248
+ ```html
249
+ <script src="./node_modules/keyring-chatbot-agent-sdk-test/dist/chat-widget-wc.umd.js"></script>
216
250
 
217
- // Set transaction result (after handling transaction event)
218
- widget.transactionResult = 'success'; // or 'fail'
251
+ <chat-widget position="bottom-right"></chat-widget>
219
252
  ```
220
253
 
221
- #### Web Component Events
254
+ ### Via local `dist/` (after building from source)
222
255
 
223
- ```javascript
224
- const widget = document.querySelector('chat-widget');
225
-
226
- // Transaction event
227
- widget.addEventListener('transaction', (event) => {
228
- const tx = event.detail; // { from, to, data, value, chainId }
229
- // Handle transaction...
230
- });
256
+ ```html
257
+ <script src="./dist/chat-widget-wc.umd.js"></script>
231
258
 
232
- // Open/Close events
233
- widget.addEventListener('open', () => console.log('Opened'));
234
- widget.addEventListener('close', () => console.log('Closed'));
259
+ <chat-widget
260
+ position="bottom-right"
261
+ primary-color="#5B7FFF"
262
+ button-size="60"
263
+ ></chat-widget>
235
264
  ```
236
265
 
237
- ### Props Reference
266
+ ### Web Component — HTML Attributes
238
267
 
239
- #### ChatWidget Props
268
+ | Attribute | Type | Default | Description |
269
+ | --------------- | --------- | ---------------- | --------------------------------------------- |
270
+ | `position` | `string` | `'bottom-right'` | `'bottom-right'` or `'bottom-left'` |
271
+ | `primary-color` | `string` | `'#007bff'` | Widget accent color (hex or CSS color) |
272
+ | `button-size` | `number` | `60` | Floating button diameter in pixels |
273
+ | `z-index` | `number` | `9999` | CSS `z-index` of the widget |
274
+ | `default-open` | `boolean` | `false` | Set to `"true"` to open the chat on page load |
240
275
 
241
- | Prop | Type | Default | Description |
242
- | --------------- | --------------------------------------------------- | ---------------- | --------------------------------------------------------- |
243
- | `position` | `'bottom-right'` \| `'bottom-left'` | `'bottom-right'` | Position of the chat button |
244
- | `theme` | `ChatWidgetTheme` | Default theme | Custom theme configuration |
245
- | `defaultOpen` | `boolean` | `false` | Whether chat is open by default |
246
- | `onOpen` | `() => void` | - | Callback when chat opens |
247
- | `onClose` | `() => void` | - | Callback when chat closes |
248
- | `account` | `Account` | - | Wallet account info (can be provided via ConnectProvider) |
249
- | `onTransaction` | `(tx: Transaction) => Promise<TransactionResult>` | **Required** | Transaction handler |
276
+ ---
250
277
 
251
- #### Account Type
278
+ ## Type Definitions
252
279
 
253
280
  ```typescript
254
281
  interface Account {
255
- address: string; // Wallet address
256
- chainId: number; // Chain ID (1, 10, 56, 137, 8453, 42161)
282
+ address: string; // Wallet address (0x…)
283
+ chainId: number; // EIP-155 chain ID
257
284
  }
258
- ```
259
-
260
- #### Transaction Type
261
285
 
262
- ```typescript
263
286
  interface Transaction {
264
- from: string; // Sender address
265
- to: string; // Contract/recipient address
266
- data: string; // Encoded transaction data
267
- value: string; // Native token value in wei
268
- chainId: number; // Chain ID
287
+ from: string;
288
+ to: string;
289
+ data: string; // ABI-encoded calldata (hex)
290
+ value: string; // Native amount in wei (decimal or hex string)
291
+ gasLimit?: string;
292
+ gasPrice?: string;
293
+ maxFeePerGas?: string;
294
+ maxPriorityFeePerGas?: string;
295
+ nonce?: number;
296
+ chainId?: number;
269
297
  }
270
- ```
271
-
272
- #### TransactionResult Type
273
298
 
274
- ```typescript
275
299
  interface TransactionResult {
276
300
  status: 'success' | 'fail';
277
- transactionHash?: string; // Optional transaction hash on success
278
- error?: string; // Optional error message on failure
301
+ transactionHash?: string; // Present on success
302
+ error?: string; // Present on failure
279
303
  }
280
- ```
281
304
 
282
- #### Theme Configuration
283
-
284
- ```typescript
285
305
  interface ChatWidgetTheme {
286
- primaryColor?: string; // Primary color (hex)
287
- buttonSize?: number; // Button size in pixels
288
- zIndex?: number; // z-index for positioning
306
+ primaryColor?: string; // Hex / CSS color string
307
+ buttonSize?: number; // Floating button size in px
308
+ zIndex?: number; // CSS z-index
289
309
  }
290
- ```
291
-
292
- ## Supported Chains
293
310
 
294
- - **Ethereum** (chainId: 1)
295
- - **Optimism** (chainId: 10)
296
- - **BNB Chain** (chainId: 56)
297
- - **Polygon** (chainId: 137)
298
- - **Base** (chainId: 8453)
299
- - **Arbitrum** (chainId: 42161)
300
-
301
- ## Capabilities
302
-
303
- ### AI Actions
311
+ type Language = 'en' | 'ja' | 'cn';
312
+ ```
304
313
 
305
- The chatbot AI can understand and execute:
314
+ ---
306
315
 
307
- - 💬 **General Chat** - Answer questions about crypto and blockchain
308
- - 💰 **Buy/Swap Tokens** - "Swap 1 ETH to USDC" or "Buy WBTC"
309
- - 📤 **Send Tokens** - "Send 10 USDC to 0x..."
310
- - 🖼️ **View NFTs** - "Show my NFTs"
311
- - 📤 **Send NFTs** - "Send my NFT #123 to 0x..."
312
- - ✅ **Approve Tokens** - Automatic approval handling for swaps
313
- - 🔄 **Wrap/Unwrap** - "Wrap 1 ETH" or "Unwrap 0.5 WETH"
316
+ ## Supported Chains
314
317
 
315
- ### Features
318
+ | Chain | Chain ID |
319
+ | --------- | -------- |
320
+ | Ethereum | 1 |
321
+ | Optimism | 10 |
322
+ | BNB Chain | 56 |
323
+ | Polygon | 137 |
324
+ | Base | 8453 |
325
+ | Arbitrum | 42161 |
326
+ | Avalanche | 43114 |
327
+ | Linea | 59144 |
328
+
329
+ ---
330
+
331
+ ## AI Capabilities
332
+
333
+ The embedded AI (GPT-4.1-mini via Moralis Cortex) understands natural language and routes to on-chain actions automatically:
334
+
335
+ | User intent | Action |
336
+ | -------------------------------- | ------------------------------------- |
337
+ | "Swap 1 ETH to USDC" | Token swap via deBridge |
338
+ | "Swap max USDT to ETH" | Swap with full-balance resolution |
339
+ | "Buy WBTC" | Buy flow with trending token lookup |
340
+ | "Send 10 USDC to 0x…" | ERC-20 transfer |
341
+ | "Send 0.05 ETH to 0x…" | Native token transfer |
342
+ | "Wrap 1 ETH" / "Unwrap 0.5 WETH" | Wrap / unwrap native token |
343
+ | "Show my NFTs" | Display NFT gallery |
344
+ | "Send my Bored Ape #1234 to 0x…" | ERC-721 / ERC-1155 transfer |
345
+ | "What is the gas fee?" | General blockchain Q&A |
346
+ | "What tokens are trending?" | Trending tokens list with buy buttons |
347
+
348
+ ### Smart Swap Flow
349
+
350
+ The AI handles missing parameters gracefully:
351
+
352
+ | Parameters available | Behaviour |
353
+ | ----------------------------- | ---------------------------------------------- |
354
+ | token_in + token_out + amount | Full auto-swap: estimation → confirm → execute |
355
+ | token_in + token_out only | Shows 25 / 50 / 75 / 100 % amount selector |
356
+ | token_out only | Shows wallet balances to choose source token |
357
+ | token_in only | Shows trending tokens to choose destination |
358
+ | Neither | Asks user to specify both tokens |
359
+ | ERC-20 needs approval | Prompts Approve step before swap |
360
+ | Insufficient balance / fee | Warning message, no confirmation prompt |
361
+
362
+ ---
363
+
364
+ ## Build Outputs
365
+
366
+ | File | Format | Use case |
367
+ | ---------------------------- | ------ | ------------------------------------------ |
368
+ | `dist/chat-widget.es.js` | ESM | React / Vite / bundler |
369
+ | `dist/chat-widget.umd.js` | UMD | CommonJS / `require` |
370
+ | `dist/chat-widget-wc.es.js` | ESM | Web Component via `<script type="module">` |
371
+ | `dist/chat-widget-wc.umd.js` | UMD | Web Component via `<script src>` / CDN |
372
+ | `dist/lib.d.ts` | Types | TypeScript declarations |
373
+
374
+ ### Package exports map
375
+
376
+ ```json
377
+ {
378
+ ".": {
379
+ "import": "dist/chat-widget.es.js",
380
+ "require": "dist/chat-widget.umd.js",
381
+ "types": "dist/lib.d.ts"
382
+ },
383
+ "./web-component": {
384
+ "import": "dist/chat-widget-wc.es.js",
385
+ "require": "dist/chat-widget-wc.umd.js"
386
+ }
387
+ }
388
+ ```
316
389
 
317
- - **Smart Token Resolution** - AI automatically resolves token symbols to addresses
318
- - **Trending Tokens** - View trending tokens on current chain
319
- - **Wallet Balance** - Real-time wallet balance display
320
- - **Multi-step Flows** - Guided swap flows with approval handling
321
- - **NFT Images** - Display NFT images from metadata
322
- - **Transaction Preview** - See swap details before confirming
323
- - **Gas Estimation** - View estimated gas fees
390
+ ---
324
391
 
325
392
  ## Development
326
393
 
327
- ### Clone Repository
328
-
329
394
  ```bash
395
+ # Clone
330
396
  git clone git@bitbucket.org:bacoorteam/keyring-chatbot-agent-sdk.git
331
397
  cd keyring-chatbot-agent-sdk
332
- ```
333
-
334
- ### Install Dependencies
335
398
 
336
- ```bash
399
+ # Install dependencies
337
400
  yarn install
338
- ```
339
401
 
340
- ### Build Library
402
+ # Start demo dev server
403
+ yarn dev
341
404
 
342
- ```bash
405
+ # Build both React and Web Component bundles
343
406
  yarn build
344
- ```
345
-
346
- This creates two builds:
347
407
 
348
- - **React Component** - `dist/chat-widget.es.js` & `dist/chat-widget.umd.js`
349
- - **Web Component** - `dist/chat-widget-wc.es.js` & `dist/chat-widget-wc.umd.js`
408
+ # Build React bundle only
409
+ yarn build:react
350
410
 
351
- ### Development Mode
411
+ # Build Web Component bundle only
412
+ yarn build:wc
352
413
 
353
- ```bash
354
- yarn dev
355
- ```
414
+ # Watch mode (auto-rebuild React bundle on change)
415
+ yarn watch
356
416
 
357
- ### Watch Mode (Auto-rebuild)
417
+ # Lint
418
+ yarn lint
419
+ yarn lint:fix
358
420
 
359
- ```bash
360
- yarn watch
421
+ # Format
422
+ yarn format
361
423
  ```
362
424
 
425
+ ---
426
+
363
427
  ## Project Structure
364
428
 
365
429
  ```
366
430
  src/
367
431
  ├── components/
368
- │ ├── ActionForm.tsx # Transaction action forms
369
- │ ├── ChatButton.tsx # Floating chat button
370
- │ ├── ChatModal.tsx # Main chat modal with AI logic
371
- │ ├── ChatWidget.tsx # Root component
372
- │ └── MessageContent.tsx # Message renderer with markdown
432
+ │ ├── ActionForm.tsx # Inline transaction forms (send, approve, …)
433
+ │ ├── ChatButton.tsx # Floating action button
434
+ │ ├── ChatModal.tsx # Chat UI + all AI action logic
435
+ │ ├── ChatWidget.tsx # Root component — public API entry point
436
+ │ ├── MessageContent.tsx # Markdown message renderer
437
+ │ ├── ScrollToBottomButton.tsx
438
+ │ └── WalletUserInfo.tsx
373
439
  ├── constants/
374
- │ ├── agentActions.ts # AI action definitions
375
- │ ├── chains.ts # Chain configurations
376
- │ ├── storage.ts # Storage keys
377
- │ └── systemPrompt.ts # AI system prompt builder
440
+ │ ├── agentActions.ts # All AgentActionType definitions + form schemas
441
+ │ ├── chains.ts # Supported chain configs (DATA_CHAIN)
442
+ │ ├── storage.ts # LocalStorage key constants
443
+ │ └── systemPrompt.ts # AI system prompt builder
378
444
  ├── contexts/
379
- │ ├── ConfigContext.tsx # Configuration context
380
- │ └── ConnectContext.tsx # Wallet connection context
445
+ │ ├── ConfigContext.tsx # RPC URLs + theme config context
446
+ │ ├── ConnectContext.tsx # Wallet account context
447
+ │ └── LanguageContext.tsx # i18n language context
381
448
  ├── hooks/
382
- │ └── useChatMessages.ts # Chat state management
449
+ │ └── useChatMessages.ts # Chat message state management
383
450
  ├── services/
384
- │ ├── BaseApi.ts # Base API client
385
- │ ├── deBridge.ts # deBridge swap API
386
- │ ├── moralis.ts # Moralis Web3 APIs
387
- │ ├── token.ts # Token data service
388
- │ └── web3.ts # Web3 transaction builder
389
- └── lib.tsx # Library entry point
451
+ │ ├── BaseApi.ts # Base HTTP client
452
+ │ ├── deBridge.ts # deBridge swap quote + transaction API
453
+ │ ├── moralis.ts # Moralis AI chat, wallet balances, NFTs, metadata
454
+ │ ├── token.ts # Token info + trending data
455
+ │ └── web3.ts # Transaction builder, fee estimation, allowance check
456
+ ├── types/
457
+ │ └── index.ts # All public TypeScript interfaces
458
+ ├── lib.tsx # React library entry point
459
+ └── web-component.tsx # Web Component entry point
390
460
  ```
391
461
 
392
- ## API Services
393
-
394
- ### Moralis Integration
395
-
396
- The SDK uses Moralis APIs for:
397
-
398
- - AI chat (Cortex GPT-4)
399
- - Wallet token balances
400
- - NFT collections
401
- - Token metadata
402
-
403
- ### deBridge Integration
462
+ ---
404
463
 
405
- Token swaps are powered by deBridge protocol for:
406
-
407
- - Cross-chain swaps
408
- - Best price routing
409
- - Low slippage
410
- - Automatic approval handling
411
-
412
- ## Build Configuration
413
-
414
- The project uses Vite in library mode:
415
-
416
- - **Entry points**: `src/lib.tsx` (React), `src/web-component.tsx` (Web Component)
417
- - **Output formats**: ES module and UMD
418
- - **External dependencies**: React and React-DOM (peer dependencies)
419
- - **TypeScript**: Full type support with `.d.ts` files
420
-
421
- ## Publishing to NPM
422
-
423
- 1. Update version in `package.json`
424
- 2. Build the project:
464
+ ## Publishing
425
465
 
426
466
  ```bash
467
+ # 1. Bump version in package.json
468
+ # 2. Build
427
469
  yarn build
428
- ```
429
470
 
430
- 3. Login to NPM:
431
-
432
- ```bash
471
+ # 3. Login to npm
433
472
  npm login
434
- ```
435
473
 
436
- 4. Publish:
437
-
438
- ```bash
474
+ # 4. Publish
439
475
  npm publish
440
476
  ```
441
477
 
478
+ ---
479
+
442
480
  ## License
443
481
 
444
482
  ISC
445
483
 
446
484
  ## Repository
447
485
 
448
- [Bitbucket - keyring-chatbot-agent-sdk](https://bitbucket.org/bacoorteam/keyring-chatbot-agent-sdk)
486
+ [Bitbucket — keyring-chatbot-agent-sdk](https://bitbucket.org/bacoorteam/keyring-chatbot-agent-sdk)
449
487
 
450
- ## Support
488
+ ## Issues
451
489
 
452
- For issues and feature requests, please use the [issue tracker](https://bitbucket.org/bacoorteam/keyring-chatbot-agent-sdk/issues).
490
+ [Issue tracker](https://bitbucket.org/bacoorteam/keyring-chatbot-agent-sdk/issues)