guideai-app 0.3.3 → 0.3.4

package/README.md

@@ -1,321 +1,202 @@
-# GuideAI - AI-Powered Guide Component
+# Guide AI
 
-A React component that provides an AI-powered guide assistant for any webpage. Features voice and text conversation, element highlighting, and conversation persistence.
+A React component that provides AI-powered guidance with voice interaction, text input, and element highlighting capabilities.
 
-## 🚀 Quick Start
-
-### 1. Install the Package
+## Installation
 
 ```bash
 npm install guideai-app
+# or
+yarn add guideai-app
 ```
 
-### 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
+## 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"
-        onError={(error, context) => console.error('GuideAI Error:', error, context)}
+        position={{ bottom: '2rem', right: '2rem' }}
+        onError={(error) => console.error(error)}
       />
     </div>
   );
 }
 ```
 
-### 4. Advanced Configuration
+## Props
 
-```jsx
-import React from 'react';
-import GuideAI from 'guideai-app';
+| 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) |
 
-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>
-  );
+### Position Object
+
+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;
 }
 ```
 
-## 📋 Props Reference
+### Transcript Configuration Object
 
-### Required Props
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `organizationKey` | `string` | Your organization's unique identifier |
-
-### 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%)'
-}}
+```typescript
+transcript?: {
+  enabled?: boolean;           // Show transcript (default: true)
+  showToggleButton?: boolean;  // Show transcript toggle (default: true)
+  position?: 'right' | 'left' | 'top' | 'bottom'; // Transcript position
+}
 ```
 
-### Transcript Options
+### Input Configuration Object
 
-```jsx
-transcript={{
-  enabled: boolean,        // Show transcript by default
-  showToggleButton: boolean // Show toggle button for transcript
-}}
+```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
+}
 ```
 
-### Input Options
+### Examples
 
+**Basic usage:**
 ```jsx
-input={{
-  defaultMode: 'voice' | 'text',  // Default input mode
-  enableTextInput: boolean,       // Enable text input option
-  placeholder: string             // Text input placeholder
-}}
+<GuideAI 
+  organizationKey="your-org-key"
+  position={{ bottom: '4rem', left: '50%', marginLeft: '-30px' }}
+/>
 ```
 
-### Metadata Options
-
+**With text input enabled by default:**
 ```jsx
-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
-  }
-}}
+<GuideAI 
+  organizationKey="your-org-key"
+  position={{ top: '20px', right: '20px' }}
+  input={{
+    defaultMode: 'text',
+    placeholder: "Ask me anything..."
+  }}
+/>
 ```
 
-## 🎯 Features
-
-### 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
-
-### Conversation Persistence
-- Conversations are automatically saved and restored on page refresh
-- Messages persist for 30 minutes by default
-- Seamless conversation continuation
-
-### Element Highlighting
-- AI can highlight and interact with page elements
-- Visual cursor guidance for user actions
-- Support for CSS selectors and XPath
-
-### Transcript Display
-- Real-time conversation transcript
-- Toggle visibility with the transcript button
-- Message timestamps and sender identification
-
-### 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();
+**Full configuration:**
+```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 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();
-```
+## Text Input Feature
 
-## 🎨 Styling
+GuideAI now supports both voice and text input modes, giving users flexible ways to interact with the AI assistant.
 
-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.
+### Features
 
-### Custom Positioning Examples
+- **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
 
-```jsx
-// Top-right corner
-<GuideAI 
-  organizationKey="your-key"
-  position={{ top: '20px', right: '20px' }}
-/>
+### Input Props
 
-// Bottom-left corner
-<GuideAI 
-  organizationKey="your-key"
-  position={{ bottom: '20px', left: '20px' }}
-/>
+| 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 |
 
-// Centered on the right
-<GuideAI 
-  organizationKey="your-key"
-  position={{ 
-    top: '50%', 
-    right: '20px', 
-    transform: 'translateY(-50%)' 
-  }}
-/>
-```
+### How to Use Text Input
 
-## 🚨 Error Handling
+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
 
-The component includes comprehensive error handling:
+### Accessibility Features
 
-```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 });
-  }}
-/>
-```
+- **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
 
-## 🔒 Security
+## Transcript Feature
 
-- 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
+GuideAI includes a beautiful transcript interface that displays conversations between users and the AI in a transparent Apple-style box.
 
-## 📱 Browser Support
+### Features
 
-- Chrome 88+
-- Firefox 85+
-- Safari 14+
-- Edge 88+
+- **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
 
-## 🛠️ Development
+### How to Use
 
-### Building from Source
+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
 
-```bash
-git clone <repository>
-cd guide-ai-package
-npm install
-npm run build
-```
+### Transcript Interface
 
-### Testing
+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
-npm run dev  # Start development server
-```
+### Styling
 
-## 📄 License
+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
 
-ISC License
+## Migration from Voice-Only Versions
 
-## 🤝 Support
+If you're upgrading from a voice-only version:
 
-For support and questions, please refer to the documentation or contact the development team.
+- **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