keyring-chatbot-agent-sdk 1.0.0

package/.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+    "recommendations": [
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode"
+    ]
+}

package/README.md

@@ -0,0 +1,490 @@
+# Keyring Chatbot Agent SDK
+
+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.
+
+## Features
+
+- 🤖 **AI-Powered Chat** — Natural language understanding via Moralis Cortex (GPT-4.1-mini)
+- 💱 **Token Swaps** — Best-price routing powered by deBridge
+- 🖼️ **NFT Management** — View and transfer ERC721 / ERC1155 NFTs
+- 💰 **Token Operations** — Send tokens, approve spending, wrap/unwrap native tokens
+- 📊 **Trending Tokens** — Real-time trending data per chain
+- 🔗 **Multi-Chain** — Ethereum, Optimism, BNB Chain, Polygon, Base, Arbitrum, Avalanche, Linea
+- 🌐 **Internationalization** — English, Japanese, Chinese UI
+- ⚡ **Built with Vite** — Optimized ES module and UMD builds
+- 🔧 **Full TypeScript** — Complete type declarations included
+
+---
+
+## Installation
+
+```bash
+npm install keyring-chatbot-agent-sdk-test
+# or
+yarn add keyring-chatbot-agent-sdk-test
+```
+
+**Peer dependencies** (React 17, 18, or 19):
+
+```bash
+npm install react react-dom
+```
+
+---
+
+## Quick Start (React)
+
+```tsx
+import { ChatWidget } from 'keyring-chatbot-agent-sdk-test';
+import type {
+  Transaction,
+  TransactionResult,
+} from 'keyring-chatbot-agent-sdk-test';
+
+function App() {
+  const handleTransaction = async (
+    tx: Transaction
+  ): Promise<TransactionResult> => {
+    try {
+      // Sign and send via your wallet provider (wagmi, ethers.js, viem, etc.)
+      const hash = await walletClient.sendTransaction(tx);
+      return { status: 'success', transactionHash: hash };
+    } catch (err: unknown) {
+      return { status: 'fail', error: (err as Error).message };
+    }
+  };
+
+  return (
+    <ChatWidget
+      account={{ address: '0x...your-wallet-address', chainId: 10 }}
+      onTransaction={handleTransaction}
+    />
+  );
+}
+```
+
+---
+
+## React — Full API
+
+### `<ChatWidget />` Props
+
+| Prop            | Type                                              | Default          | Required | Description                                                                                                                  |
+| --------------- | ------------------------------------------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `account`       | `Account`                                         | `undefined`      | No       | Connected wallet. Pass `undefined` when no wallet is connected.                                                              |
+| `onTransaction` | `(tx: Transaction) => Promise<TransactionResult>` | `undefined`      | No\*     | Called when the chatbot needs to sign/send a transaction.                                                                    |
+| `position`      | `'bottom-right'` \| `'bottom-left'`               | `'bottom-right'` | No       | Corner where the floating button appears.                                                                                    |
+| `theme`         | `ChatWidgetTheme`                                 | `{}`             | No       | Visual customization.                                                                                                        |
+| `defaultOpen`   | `boolean`                                         | `false`          | No       | Open the chat modal on first render.                                                                                         |
+| `onOpen`        | `() => void`                                      | —                | No       | Callback fired when the modal opens.                                                                                         |
+| `onClose`       | `() => void`                                      | —                | No       | Callback fired when the modal closes.                                                                                        |
+| `language`      | `'en'` \| `'ja'` \| `'cn'`                        | `'en'`           | No       | UI language (English, Japanese, Chinese).                                                                                    |
+| `rpcUrls`       | `Record<number, string>`                          | —                | No       | Per-chain RPC URL overrides (`chainId → URL`). Takes priority over built-in defaults for balance queries and gas estimation. |
+
+> \* `onTransaction` is required to execute on-chain actions (swap, send, approve, etc.). Without it, the AI can still answer questions and display information.
+
+### Basic example
+
+```tsx
+import { ChatWidget } from 'keyring-chatbot-agent-sdk-test';
+
+function App() {
+  return (
+    <ChatWidget
+      account={{ address: userAddress, chainId: 10 }}
+      onTransaction={handleTransaction}
+      language="en"
+      position="bottom-right"
+    />
+  );
+}
+```
+
+### Full example with all props
+
+```tsx
+import { ChatWidget } from 'keyring-chatbot-agent-sdk-test';
+import type {
+  Transaction,
+  TransactionResult,
+} from 'keyring-chatbot-agent-sdk-test';
+
+function App() {
+  const handleTransaction = async (
+    tx: Transaction
+  ): Promise<TransactionResult> => {
+    try {
+      const hash = await walletClient.sendTransaction(tx);
+      return { status: 'success', transactionHash: hash };
+    } catch (err: unknown) {
+      return { status: 'fail', error: (err as Error).message };
+    }
+  };
+
+  return (
+    <ChatWidget
+      account={{ address: userAddress, chainId: 10 }}
+      onTransaction={handleTransaction}
+      position="bottom-right"
+      language="en"
+      defaultOpen={false}
+      theme={{
+        primaryColor: '#5B7FFF',
+        buttonSize: 60,
+        zIndex: 9999,
+      }}
+      rpcUrls={{
+        1: 'https://mainnet.infura.io/v3/YOUR_KEY',
+        10: 'https://optimism-mainnet.infura.io/v3/YOUR_KEY',
+        56: 'https://bsc-dataseed.binance.org',
+        137: 'https://polygon-rpc.com',
+        8453: 'https://mainnet.base.org',
+        42161: 'https://arb1.arbitrum.io/rpc',
+        43114: 'https://api.avax.network/ext/bc/C/rpc',
+        59144: 'https://rpc.linea.build',
+      }}
+      onOpen={() => console.log('Chat opened')}
+      onClose={() => console.log('Chat closed')}
+    />
+  );
+}
+```
+
+### Usage with wagmi v2
+
+```tsx
+import { useSendTransaction, useAccount } from 'wagmi';
+import { ChatWidget } from 'keyring-chatbot-agent-sdk-test';
+import type {
+  Transaction,
+  TransactionResult,
+} from 'keyring-chatbot-agent-sdk-test';
+
+function App() {
+  const { address, chainId } = useAccount();
+  const { sendTransactionAsync } = useSendTransaction();
+
+  const handleTransaction = async (
+    tx: Transaction
+  ): Promise<TransactionResult> => {
+    try {
+      const hash = await sendTransactionAsync({
+        to: tx.to as `0x${string}`,
+        data: tx.data as `0x${string}`,
+        value: BigInt(tx.value || '0'),
+      });
+      return { status: 'success', transactionHash: hash };
+    } catch (err: unknown) {
+      return { status: 'fail', error: (err as Error).message };
+    }
+  };
+
+  return (
+    <ChatWidget
+      account={address ? { address, chainId: chainId ?? 1 } : undefined}
+      onTransaction={handleTransaction}
+    />
+  );
+}
+```
+
+---
+
+## HTML — Web Component
+
+The SDK ships a **Web Component** build (`chat-widget-wc`) that can be dropped into any HTML page without a React build pipeline.
+
+The web component supports visual configuration via HTML attributes (`position`, `primary-color`, `button-size`, `z-index`, `default-open`).
+
+### Via CDN — UMD script tag
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>My dApp</title>
+  </head>
+  <body>
+    <h1>My Web3 App</h1>
+
+    <!-- 1. Load the bundle -->
+    <script src="https://unpkg.com/keyring-chatbot-agent-sdk-test/dist/chat-widget-wc.umd.js"></script>
+
+    <!-- 2. Place the custom element -->
+    <chat-widget
+      position="bottom-right"
+      primary-color="#5B7FFF"
+      button-size="60"
+      z-index="9999"
+    ></chat-widget>
+  </body>
+</html>
+```
+
+### Via CDN — ES module
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>My dApp</title>
+  </head>
+  <body>
+    <h1>My Web3 App</h1>
+
+    <chat-widget position="bottom-right" primary-color="#5B7FFF"></chat-widget>
+
+    <script type="module">
+      import 'https://unpkg.com/keyring-chatbot-agent-sdk-test/dist/chat-widget-wc.es.js';
+    </script>
+  </body>
+</html>
+```
+
+### Via local `node_modules`
+
+```html
+<script src="./node_modules/keyring-chatbot-agent-sdk-test/dist/chat-widget-wc.umd.js"></script>
+
+<chat-widget position="bottom-right"></chat-widget>
+```
+
+### Via local `dist/` (after building from source)
+
+```html
+<script src="./dist/chat-widget-wc.umd.js"></script>
+
+<chat-widget
+  position="bottom-right"
+  primary-color="#5B7FFF"
+  button-size="60"
+></chat-widget>
+```
+
+### Web Component — HTML Attributes
+
+| Attribute       | Type      | Default          | Description                                   |
+| --------------- | --------- | ---------------- | --------------------------------------------- |
+| `position`      | `string`  | `'bottom-right'` | `'bottom-right'` or `'bottom-left'`           |
+| `primary-color` | `string`  | `'#007bff'`      | Widget accent color (hex or CSS color)        |
+| `button-size`   | `number`  | `60`             | Floating button diameter in pixels            |
+| `z-index`       | `number`  | `9999`           | CSS `z-index` of the widget                   |
+| `default-open`  | `boolean` | `false`          | Set to `"true"` to open the chat on page load |
+
+---
+
+## Type Definitions
+
+```typescript
+interface Account {
+  address: string; // Wallet address (0x…)
+  chainId: number | string; // EIP-155 chain ID
+}
+
+interface Transaction {
+  from: string;
+  to: string;
+  data: string; // ABI-encoded calldata (hex)
+  value: string; // Native amount in wei (decimal or hex string)
+  gasLimit?: string;
+  gasPrice?: string;
+  maxFeePerGas?: string;
+  maxPriorityFeePerGas?: string;
+  nonce?: number;
+  chainId?: number | string;
+}
+
+interface TransactionResult {
+  status: 'success' | 'fail';
+  transactionHash?: string; // Present on success
+  error?: string; // Present on failure
+}
+
+interface ChatWidgetTheme {
+  primaryColor?: string; // Hex / CSS color string
+  buttonSize?: number; // Floating button size in px
+  zIndex?: number; // CSS z-index
+}
+
+type Language = 'en' | 'ja' | 'cn';
+```
+
+---
+
+## Supported Chains
+
+| Chain     | Chain ID |
+| --------- | -------- |
+| Ethereum  | 1        |
+| Optimism  | 10       |
+| BNB Chain | 56       |
+| Polygon   | 137      |
+| Base      | 8453     |
+| Arbitrum  | 42161    |
+| Avalanche | 43114    |
+| Linea     | 59144    |
+
+---
+
+## AI Capabilities
+
+The embedded AI (GPT-4.1-mini via Moralis Cortex) understands natural language and routes to on-chain actions automatically:
+
+| User intent                      | Action                                |
+| -------------------------------- | ------------------------------------- |
+| "Swap 1 ETH to USDC"             | Token swap via deBridge               |
+| "Swap max USDT to ETH"           | Swap with full-balance resolution     |
+| "Buy WBTC"                       | Buy flow with trending token lookup   |
+| "Send 10 USDC to 0x…"            | ERC-20 transfer                       |
+| "Send 0.05 ETH to 0x…"           | Native token transfer                 |
+| "Wrap 1 ETH" / "Unwrap 0.5 WETH" | Wrap / unwrap native token            |
+| "Show my NFTs"                   | Display NFT gallery                   |
+| "Send my Bored Ape #1234 to 0x…" | ERC-721 / ERC-1155 transfer           |
+| "What is the gas fee?"           | General blockchain Q&A                |
+| "What tokens are trending?"      | Trending tokens list with buy buttons |
+
+### Smart Swap Flow
+
+The AI handles missing parameters gracefully:
+
+| Parameters available          | Behaviour                                      |
+| ----------------------------- | ---------------------------------------------- |
+| token_in + token_out + amount | Full auto-swap: estimation → confirm → execute |
+| token_in + token_out only     | Shows 25 / 50 / 75 / 100 % amount selector     |
+| token_out only                | Shows wallet balances to choose source token   |
+| token_in only                 | Shows trending tokens to choose destination    |
+| Neither                       | Asks user to specify both tokens               |
+| ERC-20 needs approval         | Prompts Approve step before swap               |
+| Insufficient balance / fee    | Warning message, no confirmation prompt        |
+
+---
+
+## Build Outputs
+
+| File                         | Format | Use case                                   |
+| ---------------------------- | ------ | ------------------------------------------ |
+| `dist/chat-widget.es.js`     | ESM    | React / Vite / bundler                     |
+| `dist/chat-widget.umd.js`    | UMD    | CommonJS / `require`                       |
+| `dist/chat-widget-wc.es.js`  | ESM    | Web Component via `<script type="module">` |
+| `dist/chat-widget-wc.umd.js` | UMD    | Web Component via `<script src>` / CDN     |
+| `dist/lib.d.ts`              | Types  | TypeScript declarations                    |
+
+### Package exports map
+
+```json
+{
+  ".": {
+    "import": "dist/chat-widget.es.js",
+    "require": "dist/chat-widget.umd.js",
+    "types": "dist/lib.d.ts"
+  },
+  "./web-component": {
+    "import": "dist/chat-widget-wc.es.js",
+    "require": "dist/chat-widget-wc.umd.js"
+  }
+}
+```
+
+---
+
+## Development
+
+```bash
+# Clone
+git clone git@bitbucket.org:bacoorteam/keyring-chatbot-agent-sdk.git
+cd keyring-chatbot-agent-sdk
+
+# Install dependencies
+yarn install
+
+# Start demo dev server
+yarn dev
+
+# Build both React and Web Component bundles
+yarn build
+
+# Build React bundle only
+yarn build:react
+
+# Build Web Component bundle only
+yarn build:wc
+
+# Watch mode (auto-rebuild React bundle on change)
+yarn watch
+
+# Lint
+yarn lint
+yarn lint:fix
+
+# Format
+yarn format
+```
+
+---
+
+## Project Structure
+
+```
+src/
+├── components/
+│   ├── ActionForm.tsx          # Inline transaction forms (send, approve, …)
+│   ├── ChatButton.tsx          # Floating action button
+│   ├── ChatModal.tsx           # Chat UI + all AI action logic
+│   ├── ChatWidget.tsx          # Root component — public API entry point
+│   ├── MessageContent.tsx      # Markdown message renderer
+│   ├── ScrollToBottomButton.tsx
+│   └── WalletUserInfo.tsx
+├── constants/
+│   ├── agentActions.ts         # All AgentActionType definitions + form schemas
+│   ├── chains.ts               # Supported chain configs (DATA_CHAIN)
+│   ├── storage.ts              # LocalStorage key constants
+│   └── systemPrompt.ts         # AI system prompt builder
+├── contexts/
+│   ├── ConfigContext.tsx       # RPC URLs + theme config context
+│   ├── ConnectContext.tsx      # Wallet account context
+│   └── LanguageContext.tsx     # i18n language context
+├── hooks/
+│   └── useChatMessages.ts      # Chat message state management
+├── services/
+│   ├── BaseApi.ts              # Base HTTP client
+│   ├── deBridge.ts             # deBridge swap quote + transaction API
+│   ├── moralis.ts              # Moralis AI chat, wallet balances, NFTs, metadata
+│   ├── token.ts                # Token info + trending data
+│   └── web3.ts                 # Transaction builder, fee estimation, allowance check
+├── types/
+│   └── index.ts                # All public TypeScript interfaces
+├── lib.tsx                     # React library entry point
+└── web-component.tsx           # Web Component entry point
+```
+
+---
+
+## Publishing
+
+```bash
+# 1. Bump version in package.json
+# 2. Build
+yarn build
+
+# 3. Login to npm
+npm login
+
+# 4. Publish
+npm publish
+```
+
+---
+
+## License
+
+ISC
+
+## Repository
+
+[Bitbucket — keyring-chatbot-agent-sdk](https://bitbucket.org/bacoorteam/keyring-chatbot-agent-sdk)
+
+## Issues
+
+[Issue tracker](https://bitbucket.org/bacoorteam/keyring-chatbot-agent-sdk/issues)