@bytexbyte/nxtlinq-ai-agent-sdk 1.2.2 → 1.2.3

package/README.md

@@ -1,282 +1,236 @@
 # Nxtlinq AI Agent SDK
 
-A powerful SDK for building intelligent conversation applications with Nxtlinq AI Agent.
-
-## Features
-
-- 💬 Real-time chat interface with AI Agent
-- 🎯 Preset messages for quick interactions
-- 🛠️ Tool integration support
-- 🔄 Automatic retry mechanism for failed requests
-- 📱 Responsive and modern UI design
-- 🎨 Customizable styling
-- 🔌 Easy integration with React applications
-- 🔒 Secure authentication and API key management
-- 👛 MetaMask wallet integration
-- 🔐 AIT (AI Identity Token) management
-- 🔑 Permission-based access control
-- 🔍 Enhanced error handling and debugging
-- ⚡ Improved async operation handling
-- 🔔 Unified notification system with Modal prompts
-
-## Installation
+A React SDK designed for Nxtlinq AI Agent, providing complete wallet connection, AIT management, and AI conversation functionality.
+
+## 🚀 Features
+
+- **Modular Design**: Clear code structure, easy to maintain and extend
+- **Wallet Integration**: Support for MetaKeep wallet connection and verification
+- **AIT Management**: Complete AIT (AI Identity Token) creation and management
+- **Permission Control**: Fine-grained permission management and validation
+- **Real-time Chat**: Real-time conversation functionality with AI Agent
+- **Type Safety**: Complete TypeScript type definitions
+- **Responsive UI**: Modern user interface design
+
+## 📦 Installation
 
 ```bash
-npm install @bytexbyte/nxtlinq-ai-agent-sdk@1.1.9
-# or
-yarn add @bytexbyte/nxtlinq-ai-agent-sdk@1.1.9
+npm install @bytexbyte/nxtlinq-ai-agent-sdk
 ```
 
-## Quick Start
+## 🎯 Quick Start
+
+### Basic Usage
 
 ```tsx
 import { ChatBot } from '@bytexbyte/nxtlinq-ai-agent-sdk';
 
 function App() {
-  const handleMessage = (message) => {
-    console.log('Received new message:', message);
-  };
-
-  const handleToolUse = async (toolUse) => {
-    console.log('Tool use:', toolUse);
-    return {
-      id: Date.now().toString(),
-      content: 'Tool execution response',
-      role: 'assistant',
-      timestamp: new Date().toISOString()
-    };
-  };
-
-  const presetMessages = [
-    { text: 'Hello, how can you help me?' },
-    { text: 'I want to add a new member' },
-    { text: 'I want to view the analytics page' },
-    { text: 'I want to change my name' }
-  ];
-
   return (
     <ChatBot
       serviceId="your-service-id"
       apiKey="your-api-key"
       apiSecret="your-api-secret"
-      onMessage={handleMessage}
-      onToolUse={handleToolUse}
-      presetMessages={presetMessages}
-      onVerifyWallet={async () => {
-        // Implement Berify.me verification
-        return { token: 'verification-token' };
+      onMessage={(message) => console.log('New message:', message)}
+      onError={(error) => console.error('Error:', error)}
+      onToolUse={async (toolUse) => {
+        // Handle tool calls
+        console.log('Tool use:', toolUse);
       }}
     />
   );
 }
 ```
 
-> **Note**: The SDK now includes a unified notification system. All success, error, warning, and info messages are displayed as Modal prompts in the top-right corner, providing a consistent and non-intrusive user experience.
-
-## Berify.me Integration
-
-The SDK supports Berify.me wallet verification for enhanced security:
+### Advanced Configuration
 
 ```tsx
 import { ChatBot } from '@bytexbyte/nxtlinq-ai-agent-sdk';
 
 function App() {
-  const handleVerifyWallet = async () => {
-    // Open Berify.me verification modal
-    const modal = window.open(
-      'https://berify.me/verify',
-      'BerifyMeModal',
-      'width=500,height=600'
-    );
-
-    return new Promise((resolve) => {
-      const handleMessage = (event) => {
-        if (event.origin === 'https://berify.me' && event.data.type === 'VERIFICATION_SUCCESS') {
-          window.removeEventListener('message', handleMessage);
-          modal?.close();
-          resolve({ token: event.data.token });
-        }
-      };
-
-      window.addEventListener('message', handleMessage);
-    });
-  };
-
   return (
     <ChatBot
       serviceId="your-service-id"
       apiKey="your-api-key"
       apiSecret="your-api-secret"
-      onVerifyWallet={handleVerifyWallet}
+      permissionGroup="default"
+      maxRetries={3}
+      retryDelay={1000}
+      placeholder="Type your message..."
+      presetMessages={[
+        { text: "Hello", autoSend: false },
+        { text: "Help", autoSend: true }
+      ]}
+      onVerifyWallet={async () => {
+        // Custom wallet verification logic
+        return { token: "verification-token" };
+      }}
     />
   );
 }
 ```
 
-## API Reference
-
-### ChatBot Component Props
-
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| serviceId | string | Yes | Your Nxtlinq service ID |
-| apiKey | string | Yes | Your Nxtlinq API key |
-| apiSecret | string | Yes | Your Nxtlinq API secret |
-| onMessage | (message: Message) => void | No | Callback when a new message is received |
-| onError | (error: Error) => void | No | Callback when an error occurs |
-| onToolUse | (toolUse: ToolUse) => Promise<Message \| void> | No | Callback for handling tool usage |
-| onVerifyWallet | () => Promise<{ token: string } \| undefined> | Yes | Callback for wallet verification |
-| presetMessages | PresetMessage[] | No | Array of preset messages to display |
-| placeholder | string | No | Input placeholder text (default: "Type a message...") |
-| className | string | No | Additional CSS class name |
-| maxRetries | number | No | Maximum number of retry attempts (default: 3) |
-| retryDelay | number | No | Delay between retries in milliseconds (default: 1000) |
-| permissionGroup | string | No | Permission group name for filtering permissions |
-
-### Notification System
-
-The SDK includes a unified notification system that displays Modal prompts for various operations:
-
-- **Success Notifications**: Green modal for successful operations (auto-hide after 3 seconds)
-- **Error Notifications**: Red modal for error messages (auto-hide after 5 seconds)
-- **Warning Notifications**: Orange modal for warnings (auto-hide after 4 seconds)
-- **Info Notifications**: Blue modal for informational messages (auto-hide after 3 seconds)
-
-All notifications appear in the top-right corner and can be manually dismissed by clicking the × button.
-
-## Types
-
-### Message
-```typescript
-interface Message {
-  id: string;
-  content: string;
-  role: 'user' | 'assistant';
-  timestamp: string;
-  button?: string;
-  error?: string;
-}
+## 🏗️ Project Structure
+
+```
+src/
+├── components/           # React Components
+│   ├── ChatBot.tsx      # Main component entry
+│   ├── context/         # Context and state management
+│   │   └── ChatBotContext.tsx
+│   ├── types/           # Type definitions
+│   │   └── ChatBotTypes.ts
+│   └── ui/              # UI Components
+│       ├── ChatBotUI.tsx
+│       ├── MessageList.tsx
+│       ├── MessageInput.tsx
+│       ├── PresetMessages.tsx
+│       ├── PermissionForm.tsx
+│       └── NotificationModal.tsx
+├── api/                 # API Layer
+│   └── nxtlinq-api.ts   # API Client
+├── core/                # Core functionality
+│   ├── metakeepClient.ts
+│   ├── lib/             # Utility libraries
+│   │   └── useLocalStorage.ts
+│   └── utils/           # Utility functions
+│       ├── walletUtils.ts
+│       ├── aitUtils.ts
+│       └── notificationUtils.ts
+├── types/               # Global type definitions
+│   ├── ait-api.ts
+│   └── window.d.ts
+└── index.ts             # Main entry file
 ```
 
-### PresetMessage
-```typescript
-interface PresetMessage {
-  text: string;
-  autoSend?: boolean;
-}
+## 🔧 API Reference
+
+### ChatBot Props
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `serviceId` | `string` | ✅ | Service ID |
+| `apiKey` | `string` | ✅ | API Key |
+| `apiSecret` | `string` | ✅ | API Secret |
+| `onMessage` | `(message: Message) => void` | ❌ | Message callback |
+| `onError` | `(error: Error) => void` | ❌ | Error callback |
+| `onToolUse` | `(toolUse: ToolUse) => Promise<Message \| void>` | ❌ | Tool use callback |
+| `presetMessages` | `PresetMessage[]` | ❌ | Preset messages |
+| `placeholder` | `string` | ❌ | Input placeholder |
+| `className` | `string` | ❌ | Custom CSS class |
+| `maxRetries` | `number` | ❌ | Maximum retry attempts |
+| `retryDelay` | `number` | ❌ | Retry delay |
+| `onVerifyWallet` | `() => Promise<{token: string} \| undefined>` | ❌ | Wallet verification callback |
+| `permissionGroup` | `string` | ❌ | Permission group |
+
+### Utility Functions
+
+#### Wallet Utilities
+
+```tsx
+import { connectWallet, disconnectWallet, validateToken } from '@bytexbyte/nxtlinq-ai-agent-sdk';
+
+// Connect wallet
+const { address, signer } = await connectWallet();
+
+// Disconnect wallet
+disconnectWallet();
+
+// Validate token
+const isValid = validateToken(token, address);
 ```
 
-### ToolUse
-```typescript
-interface ToolUse {
-  name: string;
-  input: Record<string, any>;
-}
+#### AIT Utilities
+
+```tsx
+import { generateAITId, createAITMetadata, prepareAITCreation } from '@bytexbyte/nxtlinq-ai-agent-sdk';
+
+// Generate AIT ID
+const aitId = generateAITId(address);
+
+// Create AIT metadata
+const metadata = createAITMetadata(permissions, address);
+
+// Prepare AIT creation parameters
+const { aitId, metadata, metadataHash, createAITParams } = prepareAITCreation(
+  address, 
+  permissions, 
+  serviceId
+);
 ```
 
-### AIT
-```typescript
-interface AIT {
-  aitId: string;
-  controller: string;
-  metadata: AITMetadata;
-  metadataHash: string;
-  metadataCid: string;
-}
+#### Notification Utilities
 
-interface AITMetadata {
-  model: string;
-  permissions: string[];
-  issuedBy: string;
-  serviceId?: string;
-}
+```tsx
+import { createNotification, getNotificationIcon } from '@bytexbyte/nxtlinq-ai-agent-sdk';
+
+// Create notification
+const notification = createNotification('success', 'Operation successful');
+
+// Get notification icon
+const icon = getNotificationIcon('success'); // '✅'
 ```
 
-### ServicePermission
-```typescript
-interface ServicePermission {
-  id: string;
-  label: string;
-  description: string;
-  groups: string[];
+## 🔒 Permission Management
+
+The SDK supports fine-grained permission management:
+
+1. **Connect Wallet**: Users first need to connect their MetaKeep wallet
+2. **Signature Verification**: Users need to sign to verify their identity
+3. **AIT Configuration**: Users can select required permissions
+4. **Permission Validation**: Each tool call validates permissions
+
+## 🎨 Custom Styling
+
+You can add custom styles through the `className` property:
+
+```css
+.nxtlinq-chatbot {
+  /* Custom styles */
+  border-radius: 15px;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
 }
 ```
 
-## Features
-
-### Wallet Integration
-- MetaMask wallet connection
-- Berify.me wallet verification
-- Wallet-based authentication
-- AIT (AI Identity Token) generation and management
-
-### Authentication Flow
-1. Connect MetaMask wallet
-2. Verify wallet ownership (optional, via Berify.me)
-3. Sign in with wallet
-4. Generate and register AIT with required permissions
-5. Use AIT for authenticated operations
-
-### Enhanced Error Handling
-- Improved async operation handling
-- Better state management
-- Detailed error messages
-- Comprehensive debugging logs
-
-## Error Handling
-
-The SDK includes enhanced error handling with:
-- Automatic retry mechanism for failed requests
-- Error callback for custom error handling
-- User-friendly error messages
-- Wallet connection error handling
-- Authentication error handling
-- Detailed console logging for debugging
-
-## Best Practices
-
-1. Implement proper wallet verification logic
-2. Handle AIT permissions appropriately
-3. Set appropriate timeout values
-4. Implement error retry mechanisms
-5. Use context management to maintain conversation coherence
-6. Handle wallet connection errors gracefully
-7. Implement proper error handling for authentication flow
-8. Monitor console logs for debugging
-
-## Troubleshooting
-
-Having issues? Check our [Troubleshooting Guide](./TROUBLESHOOTING.md) which includes:
-
-- Common problems and solutions
-- Authentication debugging steps
-- Permission issue resolution
-- Best practice recommendations
+## 🐛 Troubleshooting
 
 ### Common Issues
 
-**Q: Still need to sign in after connecting wallet?**
-A: This is usually due to expired authentication tokens or address mismatches. Check browser console logs and refer to the [Troubleshooting Guide](./TROUBLESHOOTING.md) for detailed solutions.
+1. **Wallet Connection Failed**
+   - Ensure MetaKeep extension is installed
+   - Check network connection
+
+2. **Permission Validation Failed**
+   - Ensure AIT permissions are correctly configured
+   - Check service ID and API keys
+
+3. **Message Sending Failed**
+   - Check network connection
+   - Verify API key and secret
 
-**Q: Cannot use specific AI tool features?**
-A: Check AIT permission settings to ensure required tool permissions are included. See [Troubleshooting Guide](./TROUBLESHOOTING.md) for details.
+### Debug Mode
 
-## Changelog
+Enable debug mode to get more information:
 
-### v1.1.9
-- 🔧 Fixed async operation timing issues in wallet connection
-- 🐛 Improved state management for AIT validation
-- 📝 Enhanced error messages and debugging logs
-- ⚡ Better handling of authentication flow
+```tsx
+<ChatBot
+  // ... other props
+  onError={(error) => {
+    console.error('ChatBot Error:', error);
+  }}
+/>
+```
 
-## License
+## 📄 License
 
-Proprietary - All Rights Reserved
+MIT License
 
-Copyright (c) 2025 ByteXByte. All rights reserved.
+## 🤝 Contributing
 
-This software and associated documentation files (the "Software") are proprietary and confidential. The Software is protected by copyright laws and international copyright treaties, as well as other intellectual property laws and treaties.
+Issues and Pull Requests are welcome!
 
-Unauthorized copying, distribution, modification, public display, or public performance of the Software is strictly prohibited. The Software may only be used in accordance with the terms of a valid license agreement with ByteXByte.
+## 📞 Support
 
-For licensing inquiries, please contact: [Your Contact Information] 
+For questions, please contact:
+- Email: support@nxtlinq.ai
+- Documentation: https://docs.nxtlinq.ai 

package/dist/api/nxtlinq-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nxtlinq-api.d.ts","sourceRoot":"","sources":["../../src/api/nxtlinq-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAK1C,eAAO,MAAM,gBAAgB,GAAI,QAAQ,MAAM,EAAE,WAAW,MAAM,KAAG,MAwJpE,CAAC"}
+{"version":3,"file":"nxtlinq-api.d.ts","sourceRoot":"","sources":["../../src/api/nxtlinq-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAiL1C,eAAO,MAAM,gBAAgB,GAAI,QAAQ,MAAM,EAAE,WAAW,MAAM,KAAG,MASpE,CAAC"}