@bytexbyte/nxtlinq-ai-agent-sdk 1.4.7 → 1.5.0

package/README.md

@@ -1,25 +1,14 @@
-# Nxtlinq AI Agent SDK
+# nxtlinq AI Agent SDK
 
-A powerful AI Agent SDK that supports multiple AI model switching, wallet connection, permission management, and more.
-
-## 🚀 What's New in v1.2.4
-
-- **🎯 AI Model Switching**: Real-time switching between multiple AI models during conversations
-- **🤖 Multi-Model Support**: Support for Nova, Claude, ChatGPT, Llama, and Gemini
-- **🎨 Enhanced UI**: Model selector dropdown and model badges for messages
-- **💾 Persistent Preferences**: Model selection saved in localStorage
-- **🔧 Improved API**: Enhanced API client with dynamic model endpoints
+A comprehensive SDK for integrating AI agents with wallet verification capabilities.
 
 ## Features
 
-- 🤖 **Multiple AI Models Support**: Supports Nova, Claude, ChatGPT, Llama, Gemini, and other AI models
-- 🔄 **Real-time Model Switching**: Users can switch AI models at any time during conversations
-- 👛 **Wallet Integration**: Supports MetaKeep wallet connection and verification
-- 🔐 **Permission Management**: AIT (AI Identity Token) based permission control system
-- 💬 **Real-time Chat**: Context-aware conversation functionality
-- 🎨 **Customizable UI**: Complete UI components and style customization options
-- 📱 **Responsive Design**: Works seamlessly across different screen sizes
-- 🔒 **Type Safety**: Full TypeScript support with comprehensive type definitions
+- 🤖 AI-powered chat interface
+- 🔐 Built-in BerifyMe wallet verification
+- 🎨 Customizable UI components
+- 🔧 Tool integration support
+- 📱 Responsive design
 
 ## Installation
 
@@ -31,6 +20,8 @@ yarn add @bytexbyte/nxtlinq-ai-agent-sdk
 
 ## Quick Start
 
+### Basic Usage
+
 ```tsx
 import { ChatBot } from '@bytexbyte/nxtlinq-ai-agent-sdk';
 
@@ -40,163 +31,36 @@ function App() {
       serviceId="your-service-id"
       apiKey="your-api-key"
       apiSecret="your-api-secret"
-      // Enable AI model switching
-      showModelSelector={true}
-      defaultModelIndex={0} // Start with Claude (default)
-      onModelChange={(model) => {
-        console.log('Switched to:', model.label);
-        // Track model usage
-        analytics.track('model_changed', { model: model.value });
-      }}
     />
   );
 }
 ```
 
-### Model Selection Options
-
-The SDK provides two ways to control which AI models are available:
-
-#### 1. Default Models (4 models)
-
-By default, the SDK shows these 4 AI models:
-- Claude
-- ChatGPT  
-- Llama
-- Gemini
-
-```tsx
-<ChatBot
-  serviceId="your-service-id"
-  apiKey="your-api-key"
-  apiSecret="your-api-secret"
-  showModelSelector={true}
-/>
-```
-
-#### 2. Custom Models
-
-To specify exactly which models to show:
-
-```tsx
-<ChatBot
-  serviceId="your-service-id"
-  apiKey="your-api-key"
-  apiSecret="your-api-secret"
-  availableModels={[
-    { label: 'Claude', value: 'claude' },
-    { label: 'ChatGPT', value: 'open-ai' },
-    { label: 'Nova', value: 'nova' },
-    // Only show the models you want
-  ]}
-  showModelSelector={true}
-/>
-```
-
-### Real-world Usage Examples
+### With Built-in BerifyMe Support
 
-#### For Basic Users (4 models only)
-```tsx
-<ChatBot
-  serviceId="your-service-id"
-  apiKey="your-api-key"
-  apiSecret="your-api-secret"
-  // Default shows only 4 basic models
-  showModelSelector={true}
-/>
-```
-
-#### For Premium Users (all models)
-```tsx
-import { ChatBot, ALL_AVAILABLE_MODELS } from '@bytexbyte/nxtlinq-ai-agent-sdk';
-
-<ChatBot
-  serviceId="your-service-id"
-  apiKey="your-api-key"
-  apiSecret="your-api-secret"
-  // Show all available models
-  availableModels={ALL_AVAILABLE_MODELS}
-  showModelSelector={true}
-/>
-```
-
-#### For Enterprise Users (custom selection)
-```tsx
-<ChatBot
-  serviceId="your-service-id"
-  apiKey="your-api-key"
-  apiSecret="your-api-secret"
-  // Enterprise users only show Claude and Nova
-  availableModels={[
-    { label: 'Claude', value: 'claude' },
-    { label: 'Nova', value: 'nova' },
-  ]}
-  showModelSelector={true}
-/>
-```
-
-### Custom Model Configuration
+The SDK now includes built-in BerifyMe wallet verification, making integration extremely simple:
 
 ```tsx
 import { ChatBot } from '@bytexbyte/nxtlinq-ai-agent-sdk';
 
 function App() {
-  // Custom available AI models
-  const customModels = [
-    { label: 'Nova', value: 'nova' },
-    { label: 'Claude', value: 'claude' },
-    { label: 'ChatGPT', value: 'open-ai' },
-    // Add more models as needed
-  ];
-
   return (
     <ChatBot
       serviceId="your-service-id"
       apiKey="your-api-key"
       apiSecret="your-api-secret"
-      availableModels={customModels}
-      defaultModelIndex={1} // Default to Claude
-      showModelSelector={true}
-      onModelChange={(model) => {
-        console.log('Model changed to:', model.label);
-      }}
+      // requireWalletIDVVerification defaults to true - wallet verification is required
     />
   );
 }
 ```
 
-### Extended Models Configuration
+### Built-in Wallet Verification (Recommended)
 
-```tsx
-import { ChatBot } from '@bytexbyte/nxtlinq-ai-agent-sdk';
-
-function App() {
-  return (
-    <ChatBot
-      serviceId="your-service-id"
-      apiKey="your-api-key"
-      apiSecret="your-api-secret"
-      // Show all models including Nova
-      availableModels={[
-        { label: 'Claude', value: 'claude' },
-        { label: 'ChatGPT', value: 'open-ai' },
-        { label: 'Llama', value: 'llama' },
-        { label: 'Gemini', value: 'gemini' },
-        { label: 'Nova', value: 'nova' },
-      ]}
-      defaultModelIndex={0}
-      showModelSelector={true}
-      onModelChange={(model) => {
-        console.log('Model changed to:', model.label);
-        // Update user preferences
-        localStorage.setItem('preferred-model', model.value);
-      }}
-```
-
-### Advanced Configuration
+The SDK automatically handles wallet verification. No need to implement `onVerifyWallet` manually:
 
 ```tsx
-import { ChatBot, DEFAULT_AI_MODELS } from '@bytexbyte/nxtlinq-ai-agent-sdk';
+import { ChatBot } from '@bytexbyte/nxtlinq-ai-agent-sdk';
 
 function App() {
   return (
@@ -204,434 +68,113 @@ function App() {
       serviceId="your-service-id"
       apiKey="your-api-key"
       apiSecret="your-api-secret"
-      // AI Model configuration (default models only)
-      availableModels={DEFAULT_AI_MODELS}
-      defaultModelIndex={0}
-      showModelSelector={true}
-      onModelChange={(model) => {
-        console.log('Model changed to:', model.label);
-        // Update user preferences
-        localStorage.setItem('preferred-model', model.value);
-      }}
-      // Preset messages
-      presetMessages={[
-        { text: 'Hello, how can you help me?', autoSend: true },
-        { text: 'I want to switch to a different AI model.', autoSend: false },
-        { text: 'What are the differences between the available models?', autoSend: false }
-      ]}
-      // Callback functions
-      onMessage={(message) => {
-        console.log('New message:', {
-          content: message.content,
-          role: message.role,
-          model: message.metadata?.model,
-          timestamp: message.timestamp
-        });
-      }}
-      onError={(error) => {
-        console.error('ChatBot error:', error);
-        // Add error reporting
-        errorReporting.captureException(error);
-      }}
-      onToolUse={async (toolUse) => {
-        console.log('Tool used:', toolUse);
-        // Handle tool calls
-        return {
-          id: Date.now().toString(),
-          content: 'Tool executed successfully',
-          role: 'assistant',
-          timestamp: new Date().toISOString()
-        };
-      }}
-      // Wallet verification
-      onVerifyWallet={async () => {
-        // Custom wallet verification logic
-        return { token: 'your-token' };
-      }}
-      // Permission group
-      permissionGroup="default"
-      // UI configuration
-      placeholder="Type your message..."
-      className="custom-chatbot"
-      maxRetries={3}
-      retryDelay={1000}
+      // Built-in wallet verification - no onVerifyWallet needed!
     />
   );
 }
 ```
 
-## API Reference
-
-### ChatBot Props
-
-| Property | Type | Default | Required | Description |
-|----------|------|---------|----------|-------------|
-| `serviceId` | `string` | - | ✅ | Service ID |
-| `apiKey` | `string` | - | ✅ | API Key |
-| `apiSecret` | `string` | - | ✅ | API Secret |
-| `availableModels` | `AIModel[]` | - | ❌ | Custom AI models list (highest priority) |
-| `defaultModelIndex` | `number` | `0` | ❌ | Default selected model index |
-| `showModelSelector` | `boolean` | `true` | ❌ | Whether to show model selector |
-| `onModelChange` | `(model: AIModel) => void` | - | ❌ | Model change callback |
-| `presetMessages` | `PresetMessage[]` | `[]` | ❌ | Preset messages list |
-| `placeholder` | `string` | `'Type a message...'` | ❌ | Input placeholder |
-| `className` | `string` | `''` | ❌ | Custom CSS class name |
-| `maxRetries` | `number` | `3` | ❌ | Maximum retry attempts |
-| `retryDelay` | `number` | `1000` | ❌ | Retry delay (milliseconds) |
-| `onMessage` | `(message: Message) => void` | - | ❌ | Message callback |
-| `onError` | `(error: Error) => void` | - | ❌ | Error callback |
-| `onToolUse` | `(toolUse: ToolUse) => Promise<Message \| void>` | - | ❌ | Tool use callback |
-| `onVerifyWallet` | `() => Promise<{token: string} \| undefined>` | - | ❌ | Wallet verification callback |
-| `permissionGroup` | `string` | - | ❌ | Permission group name |
-
-### AIModel Type
-
-```typescript
-interface AIModel {
-  label: string;  // Display name (e.g., "Nova", "Claude")
-  value: string;  // Model identifier (e.g., "nova", "claude")
-}
-```
-
-### Model Configuration Priority
-
-The SDK uses the following priority order to determine which models to show:
+**What happens automatically:**
+1. ✅ Check for existing token in URL parameters
+2. ✅ Open BerifyMe modal when verification is needed
+3. ✅ Handle verification completion and token extraction
+4. ✅ Clean up modal and state management
+5. ✅ Return token to the system for wallet verification
 
-1. **`availableModels`** (highest priority) - If provided, only these models will be shown
-2. **Default** - Shows only the 4 basic models
+### Skip Wallet Verification Check
 
-### Available Models Reference
+If you want to allow users to set AIT permissions without wallet verification, you can disable the verification check:
 
-You can import `ALL_AVAILABLE_MODELS` to see all available models:
-
-```typescript
-import { ALL_AVAILABLE_MODELS } from '@bytexbyte/nxtlinq-ai-agent-sdk';
-
-// Use all available models
-availableModels={ALL_AVAILABLE_MODELS}
-
-// Or select specific models from the list
-availableModels={[
-  ALL_AVAILABLE_MODELS[0], // Claude
-  ALL_AVAILABLE_MODELS[4], // Nova
-]}
+```tsx
+<ChatBot
+  serviceId="your-service-id"
+  apiKey="your-api-key"
+  apiSecret="your-api-secret"
+  requireWalletIDVVerification={false} // Skip wallet IDV verification check
+/>
 ```
 
-### Default AI Models
-
-```typescript
-const DEFAULT_AI_MODELS = [
-  { label: 'Claude', value: 'claude' },
-  { label: 'ChatGPT', value: 'open-ai' },
-  { label: 'Llama', value: 'llama' },
-  { label: 'Gemini', value: 'gemini' },
-];
-
-// All available models for reference
-const ALL_AVAILABLE_MODELS = [
-  { label: 'Claude', value: 'claude' },
-  { label: 'ChatGPT', value: 'open-ai' },
-  { label: 'Llama', value: 'llama' },
-  { label: 'Gemini', value: 'gemini' },
-  { label: 'Nova', value: 'nova' },
-];
-```
+**Note**: When `requireWalletIDVVerification: false`, users can connect and sign in with their wallet, then directly set AIT permissions without going through the wallet IDV verification process.
 
-### Message Type with Model Metadata
-
-```typescript
-interface Message {
-  id: string;
-  content: string;
-  role: 'user' | 'assistant';
-  timestamp: string;
-  metadata?: {
-    model?: string;           // AI model used
-    permissions?: string[];   // User permissions
-    issuedBy?: string;        // Wallet address
-    toolUse?: {              // Tool call information
-      name: string;
-      input: Record<string, any>;
-    };
-  };
-}
-```
+**Default Behavior**: `requireWalletIDVVerification` defaults to `true`, meaning wallet verification is required by default for security.
 
-## Component Usage
+## Benefits of Built-in BerifyMe Support
 
-### Using Components Individually
+✅ **Always Available**: Built-in BerifyMe support is always enabled - no configuration needed!
 
-```tsx
-import { 
-  ChatBotProvider, 
-  ChatBotUI, 
-  ModelSelector,
-  MessageList,
-  MessageInput 
-} from '@bytexbyte/nxtlinq-ai-agent-sdk';
-
-function CustomChatBot() {
-  return (
-    <ChatBotProvider
-      serviceId="your-service-id"
-      apiKey="your-api-key"
-      apiSecret="your-api-secret"
-    >
-      <div className="custom-chatbot-container">
-        <ChatBotUI />
-      </div>
-    </ChatBotProvider>
-  );
-}
-```
+✅ **No onVerifyWallet Needed**: SDK automatically handles wallet verification - no callback implementation required
 
-### Custom Layout with Model Selector
+✅ **Simplified Integration**: No need to manually handle DOM manipulation, React roots, or modal lifecycle
 
-```tsx
-import { 
-  ChatBotProvider, 
-  useChatBot,
-  ModelSelector,
-  MessageList,
-  MessageInput 
-} from '@bytexbyte/nxtlinq-ai-agent-sdk';
-
-function CustomLayout() {
-  const { isOpen, setIsOpen } = useChatBot();
-
-  if (!isOpen) {
-    return (
-      <button onClick={() => setIsOpen(true)}>
-        Open AI Agent
-      </button>
-    );
-  }
+✅ **Automatic SDK Loading**: SDK automatically loads BerifyMe dependencies when needed
 
-  return (
-    <div className="custom-layout">
-      <header>
-        <h3>AI Assistant</h3>
-        <ModelSelector />
-        <button onClick={() => setIsOpen(false)}>Close</button>
-      </header>
-      <MessageList />
-      <MessageInput />
-    </div>
-  );
-}
+✅ **Built-in Error Handling**: Comprehensive error handling and fallback mechanisms
 
-function App() {
-  return (
-    <ChatBotProvider
-      serviceId="your-service-id"
-      apiKey="your-api-key"
-      apiSecret="your-api-secret"
-    >
-      <CustomLayout />
-    </ChatBotProvider>
-  );
-}
-```
+✅ **Consistent UI**: Unified modal experience across all implementations
 
-## Style Customization
+✅ **Easy Configuration**: Simple configuration object with sensible defaults
 
-### CSS Classes
+✅ **Automatic Cleanup**: Modal cleanup and memory management handled automatically
 
-```css
-/* Main container */
-.nxtlinq-chatbot-container {
-  /* Custom styles */
-}
+✅ **Flexible IDV Verification**: Control whether to require wallet IDV verification before AIT operations
 
-/* Message list */
-.nxtlinq-message-list {
-  /* Custom styles */
-}
+✅ **Smart Suggestion Banner**: When verification is optional, shows helpful suggestion banner with 1-second delay to prevent flashing
 
-/* User message */
-.nxtlinq-user-message {
-  /* Custom styles */
-}
+## Configuration Options
 
-/* AI message */
-.nxtlinq-ai-message {
-  /* Custom styles */
-}
+### Built-in BerifyMe Support
 
-/* Model selector */
-.nxtlinq-model-selector {
-  /* Custom styles */
-}
+The built-in BerifyMe support requires no configuration - it automatically redirects to the current page after verification.
 
-/* Model badge */
-.nxtlinq-model-badge {
-  /* Custom styles */
-}
-```
+**Wallet Verification Options:**
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `requireWalletIDVVerification` | `boolean` | `true` | Whether to check wallet IDV verification status before AIT operations |
 
-### Inline Style Override
+### Configuration Examples
 
+#### Require Wallet Verification (Default)
 ```tsx
 <ChatBot
   serviceId="your-service-id"
   apiKey="your-api-key"
   apiSecret="your-api-secret"
-  className="my-custom-chatbot"
-  style={{
-    '--primary-color': '#007bff',
-    '--secondary-color': '#6c757d',
-    '--border-radius': '10px',
-    '--model-badge-bg': '#e3f2fd',
-    '--model-badge-color': '#1976d2'
-  }}
+  // requireWalletIDVVerification defaults to true
+  // Users must complete wallet verification before using AIT
 />
 ```
 
-## Event Handling
-
-### Model Change Events
-
+#### Make Wallet Verification Optional
 ```tsx
 <ChatBot
   serviceId="your-service-id"
   apiKey="your-api-key"
   apiSecret="your-api-secret"
-  onModelChange={(model) => {
-    console.log('Model changed to:', model.label);
-    // Add analytics tracking
-    analytics.track('model_changed', {
-      model: model.value,
-      label: model.label,
-      timestamp: new Date().toISOString()
-    });
-  }}
+  requireWalletIDVVerification={false}
+  // Users can use AIT without wallet verification
+  // Helpful suggestion banner will appear for unverified wallets
 />
 ```
 
-### Message Events with Model Information
+## Advanced Features
 
-```tsx
-<ChatBot
-  serviceId="your-service-id"
-  apiKey="your-api-key"
-  apiSecret="your-api-secret"
-  onMessage={(message) => {
-    console.log('New message:', message);
-    // Track message with model info
-    if (message.role === 'user') {
-      analytics.track('user_message', {
-        content: message.content,
-        model: message.metadata?.model,
-        timestamp: message.timestamp
-      });
-    } else if (message.role === 'assistant') {
-      analytics.track('ai_response', {
-        model: message.metadata?.model,
-        hasToolUse: !!message.metadata?.toolUse,
-        timestamp: message.timestamp
-      });
-    }
-  }}
-/>
-```
+### IDV Suggestion Banner
 
-## Error Handling
+When `requireWalletIDVVerification: false`, the SDK shows a helpful suggestion banner for unverified wallets:
 
-```tsx
-<ChatBot
-  serviceId="your-service-id"
-  apiKey="your-api-key"
-  apiSecret="your-api-secret"
-  onError={(error) => {
-    console.error('ChatBot error:', error);
-    // Add error reporting
-    errorReporting.captureException(error);
-    
-    // Track error with context
-    analytics.track('chatbot_error', {
-      error: error.message,
-      stack: error.stack,
-      timestamp: new Date().toISOString()
-    });
-  }}
-/>
-```
+- **Smart Timing**: 1-second delay prevents flashing during wallet connection
+- **24-Hour Dismissal**: Users can dismiss the banner for 24 hours
+- **Persistent State**: Dismissal preference is saved in localStorage
+- **Responsive Design**: Banner adapts to different screen sizes
 
-## Best Practices
-
-### 1. Model Selection
-- Choose appropriate AI models based on use cases
-- Consider user preferences and requirements
-- Monitor model performance and usage
-
-### 2. Error Handling
-- Always provide `onError` callback to handle errors
-- Implement proper error reporting and monitoring
-- Provide fallback mechanisms for failed requests
-
-### 3. User Experience
-- Use preset messages to guide users
-- Provide clear model switching feedback
-- Maintain conversation context across model switches
-
-### 4. Performance Optimization
-- Set reasonable retry counts and delays
-- Implement proper loading states
-- Optimize for different network conditions
-
-### 5. Security
-- Keep API keys secure and use environment variables
-- Validate user permissions before tool calls
-- Implement proper wallet verification
-
-## Migration Guide
-
-### From v1.2.3 to v1.2.4
-
-1. **Update package version**:
-   ```bash
-   npm install @bytexbyte/nxtlinq-ai-agent-sdk@1.2.4
-   ```
-
-2. **Add model switching props** (optional):
-   ```tsx
-   <ChatBot
-     // ... existing props
-     showModelSelector={true}
-     onModelChange={(model) => console.log('Model:', model.label)}
-   />
-   ```
-
-3. **Update message handling** (if needed):
-   ```tsx
-   onMessage={(message) => {
-     // Now includes model information
-     console.log('Model used:', message.metadata?.model);
-   }}
-   ```
-
-## Changelog
-
-### v1.2.4 (Latest)
-- ✨ **NEW**: AI model switching functionality
-- ✨ **NEW**: Support for 5 AI models (Nova, Claude, ChatGPT, Llama, Gemini)
-- ✨ **NEW**: ModelSelector dropdown component
-- ✨ **NEW**: Model badges in messages
-- ✨ **NEW**: Persistent model preferences
-- 🔧 **IMPROVED**: Enhanced API client with dynamic endpoints
-- 🔧 **IMPROVED**: Better TypeScript types and interfaces
-- 📚 **UPDATED**: Comprehensive documentation and examples
-
-### v1.2.3
-- Initial release with basic functionality
+### Wallet Connection Flow
 
-## Support
-
-For questions, issues, or feature requests:
-- 📧 Email: support@nxtlinq.ai
-- 📖 Documentation: https://docs.nxtlinq.ai
-- 🐛 Issues: https://github.com/bytexbyte/nxtlinq-ai-agent-sdk/issues
+1. **Connect Wallet**: User connects their wallet
+2. **Sign In**: User signs in with wallet (if required)
+3. **Verification Check**: SDK checks if wallet is verified
+4. **Conditional Banner**: If verification is optional and wallet is unverified, show suggestion banner
+5. **User Choice**: User can verify wallet or continue without verification
 
-## License
+## Support
 
-MIT License - see [LICENSE](LICENSE) file for details. 
+For questions and support, please refer to the SDK documentation or contact the development team.