guideai-app 0.3.0 → 0.3.3

package/README.md

@@ -1,202 +1,321 @@
-# Guide AI
+# GuideAI - AI-Powered Guide Component
 
-A React component that provides AI-powered guidance with voice interaction, text input, and element highlighting capabilities.
+A React component that provides an AI-powered guide assistant for any webpage. Features voice and text conversation, element highlighting, and conversation persistence.
 
-## Installation
+## 🚀 Quick Start
+
+### 1. Install the Package
 
 ```bash
 npm install guideai-app
-# or
-yarn add guideai-app
 ```
 
-## Usage
+### 2. Environment Variables (Optional)
+
+If you plan to use Gemini AI features, set the following environment variable:
+
+```bash
+# In your .env file or environment
+GEMINI_API_KEY=your_gemini_api_key_here
+```
+
+**Note**: The package will work without this key, but some AI features may be limited.
+
+### 3. Basic Usage
 
 ```jsx
+import React from 'react';
 import GuideAI from 'guideai-app';
 
 function App() {
   return (
     <div>
+      <h1>My Website</h1>
+      <p>Welcome to my site!</p>
+      
       <GuideAI 
         organizationKey="your-organization-key"
-        position={{ bottom: '2rem', right: '2rem' }}
-        onError={(error) => console.error(error)}
+        onError={(error, context) => console.error('GuideAI Error:', error, context)}
       />
     </div>
   );
 }
 ```
 
-## Props
-
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `organizationKey` | `string` | Yes | Your organization key for workflows |
-| `position` | `object` | No | Positioning configuration for the component |
-| `onError` | `function` | No | Error handler callback |
-| `transcript` | `object` | No | Transcript feature configuration |
-| `input` | `object` | No | Input mode configuration (voice/text) |
+### 4. Advanced Configuration
 
-### Position Object
+```jsx
+import React from 'react';
+import GuideAI from 'guideai-app';
 
-The `position` prop accepts an object with CSS positioning properties:
-
-```typescript
-position?: {
-  top?: string;
-  right?: string;
-  bottom?: string;
-  left?: string;
-  marginTop?: string;
-  marginRight?: string;
-  marginBottom?: string;
-  marginLeft?: string;
-  transform?: string;
+function App() {
+  return (
+    <div>
+      <h1>My Website</h1>
+      
+      <GuideAI 
+        organizationKey="your-organization-key"
+        position={{
+          bottom: '20px',
+          right: '20px'
+        }}
+        onError={(error, context) => console.error('GuideAI Error:', error, context)}
+        transcript={{
+          enabled: true,
+          showToggleButton: true
+        }}
+        input={{
+          defaultMode: 'voice', // 'voice' or 'text'
+          enableTextInput: true,
+          placeholder: "Type your message..."
+        }}
+        metadata={{
+          initialUserData: {
+            userId: 'user123',
+            organizationKey: 'your-org',
+            userType: 'customer'
+          },
+          config: {
+            trackVisits: true,
+            trackInteractions: true
+          }
+        }}
+      />
+    </div>
+  );
 }
 ```
 
-### Transcript Configuration Object
+## 📋 Props Reference
 
-```typescript
-transcript?: {
-  enabled?: boolean;           // Show transcript (default: true)
-  showToggleButton?: boolean;  // Show transcript toggle (default: true)
-  position?: 'right' | 'left' | 'top' | 'bottom'; // Transcript position
-}
-```
+### Required Props
 
-### Input Configuration Object
+| Prop | Type | Description |
+|------|------|-------------|
+| `organizationKey` | `string` | Your organization's unique identifier |
 
-```typescript
-input?: {
-  enableTextInput?: boolean;    // Enable text input (default: true)
-  showInputToggle?: boolean;    // Show mode toggle button (default: true)  
-  defaultMode?: 'voice' | 'text'; // Default input mode (default: 'voice')
-  placeholder?: string;         // Text input placeholder
-}
+### Optional Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `position` | `object` | `{ bottom: '20px', right: '20px' }` | CSS positioning for the component |
+| `onError` | `function` | `console.error` | Error handler function |
+| `transcript` | `object` | `{ enabled: true, showToggleButton: true }` | Transcript display options |
+| `input` | `object` | `{ defaultMode: 'voice', enableTextInput: true }` | Input mode configuration |
+| `metadata` | `object` | `{}` | User metadata and tracking options |
+
+### Position Object
+
+```jsx
+position={{
+  top?: string,        // e.g., '20px'
+  right?: string,      // e.g., '20px'
+  bottom?: string,     // e.g., '20px'
+  left?: string,       // e.g., '20px'
+  marginTop?: string,  // e.g., '10px'
+  marginRight?: string,
+  marginBottom?: string,
+  marginLeft?: string,
+  transform?: string   // e.g., 'translateY(-50%)'
+}}
 ```
 
-### Examples
+### Transcript Options
 
-**Basic usage:**
 ```jsx
-<GuideAI 
-  organizationKey="your-org-key"
-  position={{ bottom: '4rem', left: '50%', marginLeft: '-30px' }}
-/>
+transcript={{
+  enabled: boolean,        // Show transcript by default
+  showToggleButton: boolean // Show toggle button for transcript
+}}
 ```
 
-**With text input enabled by default:**
+### Input Options
+
 ```jsx
-<GuideAI 
-  organizationKey="your-org-key"
-  position={{ top: '20px', right: '20px' }}
-  input={{
-    defaultMode: 'text',
-    placeholder: "Ask me anything..."
-  }}
-/>
+input={{
+  defaultMode: 'voice' | 'text',  // Default input mode
+  enableTextInput: boolean,       // Enable text input option
+  placeholder: string             // Text input placeholder
+}}
 ```
 
-**Full configuration:**
+### Metadata Options
+
 ```jsx
-<GuideAI 
-  organizationKey="your-organization-key"
-  position={{ bottom: '2rem', right: '2rem' }}
-  transcript={{
-    enabled: true,
-    showToggleButton: true
-  }}
-  input={{
-    enableTextInput: true,
-    defaultMode: 'voice',
-    placeholder: "Type your message..."
-  }}
-  onError={(error) => console.error(error)}
-/>
+metadata={{
+  initialUserData: {
+    userId: string,           // User identifier
+    organizationKey: string,  // Organization key
+    userType: string          // User type (e.g., 'customer', 'admin')
+  },
+  config: {
+    trackVisits: boolean,     // Track page visits
+    trackInteractions: boolean // Track user interactions
+  }
+}}
 ```
 
-## Text Input Feature
+## 🎯 Features
 
-GuideAI now supports both voice and text input modes, giving users flexible ways to interact with the AI assistant.
+### Voice & Text Conversation
+- **Voice Mode**: Click the microphone to start voice conversation
+- **Text Mode**: Type messages directly in the text input
+- **Toggle**: Switch between voice and text modes
 
-### Features
+### Conversation Persistence
+- Conversations are automatically saved and restored on page refresh
+- Messages persist for 30 minutes by default
+- Seamless conversation continuation
 
-- **Dual Input Modes**: Switch seamlessly between voice and text input
-- **Text Input Interface**: Clean text area integrated into the transcript box
-- **Input Mode Toggle**: Dedicated button to switch between voice and text modes
-- **Real-time Text Chat**: Type messages and receive AI responses instantly
-- **Keyboard Shortcuts**: Press Enter to send messages quickly
-- **Auto-enabled**: Text input is enabled by default for better accessibility
+### Element Highlighting
+- AI can highlight and interact with page elements
+- Visual cursor guidance for user actions
+- Support for CSS selectors and XPath
 
-### Input Props
+### Transcript Display
+- Real-time conversation transcript
+- Toggle visibility with the transcript button
+- Message timestamps and sender identification
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `enableTextInput` | boolean | `true` | Enable text input functionality |
-| `showInputToggle` | boolean | `true` | Show the voice/text mode toggle button |
-| `defaultMode` | `'voice' \| 'text'` | `'voice'` | Default input mode when conversation starts |
-| `placeholder` | string | `"Type your message..."` | Placeholder text for the text input field |
+### User Tracking
+- Visit tracking and analytics
+- User interaction monitoring
+- Metadata collection and syncing
+
+## 🔧 API Methods
+
+The component exposes several methods through the global `window.GuideAI` object:
+
+### Transcript Control
+```javascript
+// Toggle transcript visibility
+window.GuideAI.transcript.toggle();
+
+// Show transcript
+window.GuideAI.transcript.show();
+
+// Hide transcript
+window.GuideAI.transcript.hide();
+
+// Check if transcript is visible
+const isVisible = window.GuideAI.transcript.isVisible();
+```
+
+### Metadata Tracking
+```javascript
+// Track user login
+window.GuideAI.metadata.trackLogin({
+  userId: 'user123',
+  userType: 'customer'
+});
+
+// Update user information
+window.GuideAI.metadata.updateUserInfo({
+  userId: 'user123',
+  preferences: { theme: 'dark' }
+});
+
+// Track custom events
+window.GuideAI.metadata.trackCustomEvent('button_click', {
+  buttonId: 'submit',
+  page: 'checkout'
+});
+
+// Get current metadata
+const metadata = window.GuideAI.metadata.getMetadata();
+
+// Force sync metadata
+await window.GuideAI.metadata.syncMetadata();
+
+// Reset session tracking (call on login)
+window.GuideAI.metadata.resetSessionVisitTracking();
+
+// Manually track a visit
+window.GuideAI.metadata.trackVisitManually();
+```
+
+## 🎨 Styling
+
+The component includes its own styles and will automatically inject them. The component uses fixed positioning by default and will appear in the bottom-right corner.
+
+### Custom Positioning Examples
+
+```jsx
+// Top-right corner
+<GuideAI 
+  organizationKey="your-key"
+  position={{ top: '20px', right: '20px' }}
+/>
 
-### How to Use Text Input
+// Bottom-left corner
+<GuideAI 
+  organizationKey="your-key"
+  position={{ bottom: '20px', left: '20px' }}
+/>
 
-1. **Start a Conversation**: Click the GuideAI button to begin
-2. **Switch to Text Mode**: Click the toggle button next to the main GuideAI button
-3. **Type Your Message**: Use the text area at the bottom of the transcript box
-4. **Send Message**: Press Enter or click the send button
-5. **Switch Back**: Click the toggle button again to return to voice mode
+// Centered on the right
+<GuideAI 
+  organizationKey="your-key"
+  position={{ 
+    top: '50%', 
+    right: '20px', 
+    transform: 'translateY(-50%)' 
+  }}
+/>
+```
 
-### Accessibility Features
+## 🚨 Error Handling
 
-- **Keyboard Navigation**: Full keyboard support for text input
-- **Default Enabled**: Text input works out of the box without configuration
-- **Fallback Support**: Automatically enables text mode if microphone access is denied
-- **Visual Indicators**: Clear visual feedback for active input mode
+The component includes comprehensive error handling:
 
-## Transcript Feature
+```jsx
+<GuideAI 
+  organizationKey="your-key"
+  onError={(error, context) => {
+    console.error('GuideAI Error:', error);
+    console.log('Context:', context);
+    
+    // Send to your error tracking service
+    // analytics.track('guideai_error', { error, context });
+  }}
+/>
+```
 
-GuideAI includes a beautiful transcript interface that displays conversations between users and the AI in a transparent Apple-style box.
+## 🔒 Security
 
-### Features
+- All API calls are made to secure endpoints
+- User data is handled according to privacy standards
+- No sensitive information is logged or stored locally
+- Conversations are encrypted in transit
 
-- **Glassmorphism Design**: Transparent background with backdrop blur effects
-- **Apple-style Interface**: Clean, modern design inspired by Apple's UI principles
-- **Real-time Updates**: Messages appear as they're exchanged
-- **Timestamps**: Each message shows when it was sent
-- **Auto-scroll**: Automatically scrolls to the latest messages
-- **Responsive**: Works perfectly on all device sizes
+## 📱 Browser Support
 
-### How to Use
+- Chrome 88+
+- Firefox 85+
+- Safari 14+
+- Edge 88+
 
-1. Start a conversation with GuideAI by clicking the microphone button
-2. The transcript automatically appears as an overlay when the conversation begins
-3. The transcript shows all messages with clear visual distinction between user and AI messages
-4. Messages appear in real-time as the conversation progresses
-5. Click the "×" button or click outside the transcript to close it
-6. The transcript automatically closes when the conversation ends
+## 🛠️ Development
 
-### Transcript Interface
+### Building from Source
 
-The transcript interface includes:
-- **Header**: Shows "Conversation Transcript" with a close button
-- **Messages**: Chat-like interface with different styles for user and AI messages
-- **Timestamps**: Each message displays the time it was sent
-- **Footer**: Shows the total number of messages in the conversation
+```bash
+git clone <repository>
+cd guide-ai-package
+npm install
+npm run build
+```
+
+### Testing
 
-### Styling
+```bash
+npm run dev  # Start development server
+```
 
-The transcript uses modern CSS features including:
-- `backdrop-filter: blur()` for the glassmorphism effect
-- CSS animations for smooth transitions
-- Responsive design that adapts to different screen sizes
-- Custom scrollbar styling for a polished look
+## 📄 License
 
-## Migration from Voice-Only Versions
+ISC License
 
-If you're upgrading from a voice-only version:
+## 🤝 Support
 
-- **No Breaking Changes**: Existing implementations continue to work unchanged
-- **Text Input Enabled**: Text input is now available by default
-- **Disable if Needed**: Set `input={{ enableTextInput: false }}` to disable text input
-- **Voice Still Default**: Voice mode remains the default interaction method
+For support and questions, please refer to the documentation or contact the development team.