guideai-app 0.2.4 → 0.2.6

package/metadata-tracking-example.md

@@ -0,0 +1,324 @@
+# User Metadata Tracking - Implementation Guide
+
+## Overview
+
+The GuideAI package now includes comprehensive user metadata tracking capabilities designed for integration with Overproof. This system tracks the following metadata:
+
+- **User's First Visit** - Timestamp of the first time the user interacted with GuideAI
+- **User's Last Visit** - Timestamp of the most recent user interaction
+- **User Logins** - Count and timestamp of login events
+- **User Type** - Classification of the user (agent, admin, manager, customer, guest, etc.)
+- **Customer Type** - Type of customer (individual, business, enterprise, etc.)
+- **Customer License** - License identifier for the customer
+
+## Basic Usage
+
+### 1. Basic Integration
+
+```typescript
+import { GuideAI } from 'guide-ai-package';
+
+function App() {
+  return (
+    <GuideAI 
+      organizationKey="your-org-key"
+      metadata={{
+        config: {
+          trackVisits: true,
+          trackLogins: true,
+          syncInterval: 30000, // Sync every 30 seconds
+          storage: 'localStorage'
+        },
+        initialUserData: {
+          userType: 'agent',
+          customerType: 'business',
+          customerLicense: 'OVERPRF-12345'
+        },
+        onMetadataUpdate: (metadata) => {
+          console.log('Metadata updated:', metadata);
+          // Send to your analytics system
+        }
+      }}
+    />
+  );
+}
+```
+
+### 2. Tracking User Login Events
+
+```typescript
+import { useRef } from 'react';
+
+function LoginComponent() {
+  const guideAIRef = useRef();
+
+  const handleLogin = async (userInfo) => {
+    // Your login logic here
+    const loginResult = await performLogin(userInfo);
+    
+    if (loginResult.success) {
+      // Track the login with GuideAI
+      guideAIRef.current?.trackLogin({
+        userId: loginResult.userId,
+        userType: loginResult.userType,
+        customerType: loginResult.customerType,
+        customerLicense: loginResult.license
+      });
+    }
+  };
+
+  return (
+    <div>
+      <GuideAI 
+        ref={guideAIRef}
+        organizationKey="your-org-key"
+        metadata={{
+          config: { trackLogins: true }
+        }}
+      />
+      <button onClick={handleLogin}>Login</button>
+    </div>
+  );
+}
+```
+
+### 3. Updating User Information
+
+```typescript
+function UserProfileComponent() {
+  const guideAIRef = useRef();
+
+  const updateUserProfile = (newUserData) => {
+    // Update user profile in your system
+    saveUserProfile(newUserData);
+    
+    // Update GuideAI metadata
+    guideAIRef.current?.updateUserInfo({
+      userType: newUserData.role,
+      customerType: newUserData.accountType,
+      customerLicense: newUserData.license,
+      customFields: {
+        department: newUserData.department,
+        region: newUserData.region
+      }
+    });
+  };
+
+  return (
+    <GuideAI 
+      ref={guideAIRef}
+      organizationKey="your-org-key"
+      metadata={{
+        config: {
+          customFields: ['department', 'region'],
+          collectBrowserInfo: true
+        }
+      }}
+    />
+  );
+}
+```
+
+## Configuration Options
+
+### MetadataConfig
+
+```typescript
+interface MetadataConfig {
+  // Whether to automatically track visits (default: true)
+  trackVisits?: boolean;
+  
+  // Whether to automatically track logins (default: true)
+  trackLogins?: boolean;
+  
+  // How often to sync metadata to backend in milliseconds (default: 30000)
+  syncInterval?: number;
+  
+  // Storage strategy (default: 'localStorage')
+  storage?: 'localStorage' | 'sessionStorage' | 'memory';
+  
+  // Custom metadata fields to collect
+  customFields?: string[];
+  
+  // Whether to collect browser information (default: true)
+  collectBrowserInfo?: boolean;
+  
+  // Whether to collect user agent (default: true)
+  collectUserAgent?: boolean;
+}
+```
+
+### UserMetadata Structure
+
+```typescript
+interface UserMetadata {
+  // Core identification
+  userId?: string;
+  userType?: 'agent' | 'admin' | 'manager' | 'customer' | 'guest' | string;
+  
+  // Customer-specific metadata
+  customerType?: 'individual' | 'business' | 'enterprise' | string;
+  customerLicense?: string;
+  
+  // Visit tracking (automatically managed)
+  firstVisit?: number; // timestamp
+  lastVisit?: number; // timestamp
+  visitCount?: number;
+  
+  // Login tracking (requires manual tracking)
+  loginCount?: number;
+  lastLogin?: number; // timestamp
+  
+  // Session metadata (automatically managed)
+  organizationKey: string;
+  sessionId?: string;
+  
+  // Browser information (automatically collected if enabled)
+  userAgent?: string;
+  browserInfo?: {
+    name?: string;
+    version?: string;
+    platform?: string;
+  };
+  
+  // Custom fields for Overproof-specific needs
+  customFields?: Record<string, string | number | boolean>;
+}
+```
+
+## API Integration
+
+The system automatically sends metadata updates to these endpoints:
+
+### POST `/user-metadata`
+Sends complete user metadata object when initially collected.
+
+### POST `/metadata-updates` 
+Sends batched metadata updates periodically.
+
+### PATCH `/users/{userId}/metadata`
+Updates specific user metadata when userId is available.
+
+## Backend Implementation
+
+You'll need to implement these endpoints in your backend:
+
+```typescript
+// Example Express.js implementation
+app.post('/api/user-metadata', (req, res) => {
+  const { organizationKey, metadata, timestamp } = req.body;
+  
+  // Store metadata in your database
+  await UserMetadata.upsert({
+    organizationKey,
+    userId: metadata.userId || 'anonymous',
+    ...metadata,
+    lastUpdated: new Date(timestamp)
+  });
+  
+  res.json({ success: true });
+});
+
+app.post('/api/metadata-updates', (req, res) => {
+  const { organizationKey, updates, batchTimestamp } = req.body;
+  
+  // Process batch updates
+  for (const update of updates) {
+    await processMetadataUpdate(organizationKey, update);
+  }
+  
+  res.json({ success: true });
+});
+```
+
+## Privacy Considerations
+
+- **User Agent Collection**: Can be disabled via `collectUserAgent: false`
+- **Browser Info Collection**: Can be disabled via `collectBrowserInfo: false`
+- **Custom Fields**: Only fields specified in `customFields` array are collected
+- **Storage**: Can be set to `'memory'` for session-only storage without persistence
+
+## Testing
+
+```typescript
+// Get current metadata
+const metadata = guideAIRef.current?.getMetadata();
+console.log('Current metadata:', metadata);
+
+// Force sync metadata now
+await guideAIRef.current?.syncMetadata();
+
+// Track custom events
+guideAIRef.current?.trackCustomEvent('document_viewed', {
+  documentType: 'policy',
+  documentId: 'POL-12345'
+});
+```
+
+## Overproof Integration Example
+
+```typescript
+function OverproofApp() {
+  const guideAIRef = useRef();
+
+  // Track when user logs into Overproof
+  const handleOverproofLogin = (user) => {
+    guideAIRef.current?.trackLogin({
+      userId: user.id,
+      userType: user.role, // 'agent', 'admin', etc.
+      customerType: user.accountType,
+      customerLicense: user.licenseNumber,
+      customFields: {
+        agencyId: user.agencyId,
+        territory: user.territory,
+        permissions: user.permissions.join(',')
+      }
+    });
+  };
+
+  // Track when user profile is updated
+  const handleProfileUpdate = (updatedProfile) => {
+    guideAIRef.current?.updateUserInfo({
+      userType: updatedProfile.role,
+      customerLicense: updatedProfile.licenseNumber,
+      customFields: {
+        agencyId: updatedProfile.agencyId,
+        territory: updatedProfile.territory
+      }
+    });
+  };
+
+  return (
+    <GuideAI 
+      ref={guideAIRef}
+      organizationKey="overproof-org-key"
+      metadata={{
+        config: {
+          trackVisits: true,
+          trackLogins: true,
+          syncInterval: 15000, // More frequent syncing for Overproof
+          customFields: ['agencyId', 'territory', 'permissions'],
+          collectBrowserInfo: true
+        },
+        onMetadataUpdate: (metadata) => {
+          // Send to Overproof analytics
+          window.OverproofAnalytics?.track('guideai_metadata_update', metadata);
+        }
+      }}
+    />
+  );
+}
+```
+
+## Storage and Data Persistence
+
+- **localStorage**: Persists across browser sessions (default)
+- **sessionStorage**: Persists only for current session
+- **memory**: No persistence, data lost on page refresh
+
+Metadata is automatically:
+- Saved locally based on storage configuration
+- Synced to backend at configured intervals
+- Restored when user returns (if using persistent storage)
+
+This implementation provides a robust foundation for tracking user metadata in the Overproof environment while maintaining flexibility for other use cases.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guideai-app",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "AI-powered guide component for React applications",
   "main": "dist/GuideAI.js",
   "types": "dist/GuideAI.d.ts",

package/text-input-usage.md

@@ -0,0 +1,321 @@
+# Text Input Feature - Usage Guide
+
+## Overview
+
+The GuideAI package now supports text input as an alternative to voice input, allowing users to type messages instead of speaking. This feature provides better accessibility and accommodates different user preferences.
+
+## Features
+
+✅ **Text Input Box**: Clean, modern text area for typing messages  
+✅ **Input Mode Toggle**: Switch between voice and text input modes  
+✅ **Keyboard Shortcuts**: Send messages with Enter key  
+✅ **Configurable Interface**: Customize placeholder text and default mode  
+✅ **Programmatic Control**: Global API methods to control input mode  
+✅ **Seamless Integration**: Works with existing conversation and transcript features  
+
+## Configuration Options
+
+### Basic Configuration
+
+```typescript
+<GuideAI
+  organizationKey="your-org-key"
+  input={{
+    enableTextInput: true,        // Enable text input option
+    showInputToggle: true,        // Show voice/text toggle button
+    defaultMode: 'voice',         // Start with voice (default)
+    placeholder: "Type here..."   // Custom placeholder text
+  }}
+/>
+```
+
+### Configuration Interface
+
+```typescript
+interface InputConfig {
+  // Whether to enable text input functionality
+  enableTextInput?: boolean; // default: false
+  
+  // Whether to show the voice/text toggle button
+  showInputToggle?: boolean; // default: true
+  
+  // Default input mode when conversation starts
+  defaultMode?: 'voice' | 'text'; // default: 'voice'
+  
+  // Placeholder text for the text input field
+  placeholder?: string; // default: "Type your message..."
+}
+```
+
+## Usage Examples
+
+### 1. Enable Text Input with Default Settings
+
+```typescript
+<GuideAI
+  organizationKey="your-org-key"
+  input={{
+    enableTextInput: true
+  }}
+/>
+```
+
+### 2. Start with Text Input Mode
+
+```typescript
+<GuideAI
+  organizationKey="your-org-key"
+  input={{
+    enableTextInput: true,
+    defaultMode: 'text',
+    placeholder: "What can I help you with?"
+  }}
+/>
+```
+
+### 3. Text-Only Mode (No Voice)
+
+```typescript
+<GuideAI
+  organizationKey="your-org-key"
+  input={{
+    enableTextInput: true,
+    showInputToggle: false,  // Hide toggle button
+    defaultMode: 'text'
+  }}
+/>
+```
+
+### 4. Custom Placeholder and Configuration
+
+```typescript
+<GuideAI
+  organizationKey="your-org-key"
+  input={{
+    enableTextInput: true,
+    showInputToggle: true,
+    defaultMode: 'voice',
+    placeholder: "Ask me anything about your insurance policy..."
+  }}
+/>
+```
+
+## User Interface
+
+### Unified Input Interface
+
+- **Display**: Single microphone button
+- **Action**: Click mic to start conversation and show transcript
+- **Text Input**: Available in the transcript box when enabled
+- **Voice & Text**: Both options available simultaneously once conversation starts
+
+### Text Input Box
+
+- **Position**: Integrated at the bottom of the transcript box
+- **Design**: Matches transcript styling with dark theme and glass effect
+- **Components**:
+  - Compact textarea (2 rows by default)
+  - Send button with 📤 icon
+  - Seamlessly integrated with transcript design
+
+## User Interactions
+
+### User Flow
+
+1. **Click Microphone**: Click the mic button to start conversation
+2. **Transcript Appears**: Conversation transcript box opens automatically
+3. **Choose Input Method**: 
+   - **Voice**: Speak directly (microphone is active)
+   - **Text**: Type in the text input area at bottom of transcript
+4. **Seamless Switching**: Use voice and text interchangeably in same conversation
+
+### Sending Text Messages
+
+1. **Enter Key**: Press Enter to send (Shift+Enter for new line)
+2. **Send Button**: Click the 📤 button
+3. **Programmatically**: Use `window.GuideAI.input.sendText()`
+
+### Visual Feedback
+
+- **Active Text Mode**: Text input appears at bottom of transcript with fade-in animation
+- **Button States**: Send button disabled when input is empty
+- **Focus States**: Enhanced border and background when textarea is focused
+- **Integrated Design**: Text input seamlessly blends with transcript box styling
+
+## Programmatic Control
+
+### Global API Methods
+
+Access input controls via `window.GuideAI.input`:
+
+```typescript
+// Toggle between voice and text input
+window.GuideAI.input.toggleMode();
+
+// Set specific input mode
+window.GuideAI.input.setMode('text');
+window.GuideAI.input.setMode('voice');
+
+// Get current input mode
+const currentMode = window.GuideAI.input.getMode();
+console.log('Current mode:', currentMode); // 'voice' or 'text'
+
+// Send text message programmatically
+window.GuideAI.input.sendText("Hello, can you help me?");
+```
+
+### Integration Examples
+
+#### Custom Toggle Interface
+
+```typescript
+function MyCustomControls() {
+  const [inputMode, setInputMode] = useState('voice');
+
+  const handleModeToggle = () => {
+    window.GuideAI.input.toggleMode();
+    setInputMode(window.GuideAI.input.getMode());
+  };
+
+  return (
+    <div>
+      <button onClick={handleModeToggle}>
+        Current Mode: {inputMode}
+      </button>
+    </div>
+  );
+}
+```
+
+#### Auto-Switch to Text on Mobile
+
+```typescript
+useEffect(() => {
+  const isMobile = /Android|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
+  
+  if (isMobile) {
+    // Switch to text mode on mobile devices
+    window.GuideAI.input.setMode('text');
+  }
+}, []);
+```
+
+#### Keyboard Shortcuts
+
+```typescript
+useEffect(() => {
+  const handleKeyPress = (event) => {
+    // Switch input mode with Ctrl/Cmd + I
+    if ((event.ctrlKey || event.metaKey) && event.key === 'i') {
+      event.preventDefault();
+      window.GuideAI.input.toggleMode();
+    }
+  };
+
+  document.addEventListener('keydown', handleKeyPress);
+  return () => document.removeEventListener('keydown', handleKeyPress);
+}, []);
+```
+
+## Technical Implementation
+
+### Message Flow
+
+1. **Text Input**: User types message and presses Enter or clicks Send
+2. **Message Logging**: Text is logged to conversation history
+3. **AI Communication**: Message sent to AI via WebRTC data channel
+4. **Response Generation**: AI processes text and generates response
+5. **Audio Response**: AI responds with voice (maintains voice output)
+
+### Data Channel Protocol
+
+Text messages use the same WebRTC protocol as voice:
+
+```typescript
+// Message structure sent to AI
+{
+  type: "conversation.item.create",
+  item: {
+    type: "message",
+    role: "user",
+    content: [{
+      type: "input_text",
+      text: "User's typed message"
+    }]
+  }
+}
+```
+
+## Styling and Customization
+
+### CSS Classes
+
+- `.guideai-icon-wrapper` - Main microphone button
+- `.guideai-transcript-text-input` - Text input container integrated into transcript
+- `.guideai-transcript-input-field` - Textarea element
+- `.guideai-transcript-send-button` - Send button
+- `.guideai-transcript-send-icon` - Send button icon
+
+### Custom Styling Example
+
+```css
+/* Custom text input styling */
+.guideai-transcript-input-field {
+  font-family: 'Your Custom Font', sans-serif;
+  border-radius: 12px;
+}
+
+.guideai-transcript-send-button {
+  background: linear-gradient(45deg, #ff6b6b, #ee5a52);
+}
+```
+
+## Accessibility Features
+
+- **Keyboard Navigation**: Full keyboard support
+- **Screen Readers**: Proper ARIA labels and semantic HTML
+- **Focus Management**: Clear focus indicators
+- **Alternative Input**: Text alternative for voice-only interface
+
+## Best Practices
+
+### For Implementation
+
+1. **Test Both Modes**: Ensure voice and text modes work seamlessly
+2. **Mobile Optimization**: Consider defaulting to text on mobile
+3. **Clear Instructions**: Provide users with clear mode indicators
+4. **Error Handling**: Handle cases where WebRTC isn't available
+
+### For User Experience
+
+1. **Mode Persistence**: Consider remembering user's preferred mode
+2. **Visual Feedback**: Ensure users know which mode is active
+3. **Quick Switching**: Make it easy to switch between modes
+4. **Responsive Design**: Ensure text input works on all screen sizes
+
+## Troubleshooting
+
+### Text Input Not Appearing
+
+Check that:
+1. `enableTextInput` is set to `true`
+2. Conversation is active
+3. Input mode is set to 'text'
+4. CSS styles are loaded
+
+### Toggle Button Not Showing
+
+Ensure:
+1. `showInputToggle` is not set to `false`
+2. `enableTextInput` is `true`
+3. Conversation is active
+
+### Messages Not Sending
+
+Verify:
+1. WebRTC connection is established
+2. Conversation is active
+3. Input is not empty
+4. No JavaScript errors in console
+
+This text input feature provides a comprehensive alternative to voice input while maintaining the seamless conversation experience that GuideAI is known for.