guideai-app 0.3.0 → 0.3.3

package/text-input-usage.md

@@ -1,321 +0,0 @@
-# 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.

package/transcript-toggle-usage.md

@@ -1,267 +0,0 @@
-# Transcript Toggle Feature - Usage Guide
-
-## Overview
-
-The GuideAI package now includes a transcript toggle feature that allows users to show/hide the conversation transcript and provides programmatic control over transcript visibility.
-
-## Features
-
-✅ **Toggle Button**: Optional button that appears in the transcript area (bottom-right corner)  
-✅ **Programmatic Control**: Global API methods to control transcript visibility  
-✅ **Configurable Default State**: Set whether transcript shows by default  
-✅ **Auto-Show/Hide**: Configure whether transcript automatically appears with conversations  
-✅ **Visual Feedback**: Clear visual indicators for transcript state  
-
-## Configuration Options
-
-### Basic Configuration
-
-```typescript
-<GuideAI
-  organizationKey="your-org-key"
-  transcript={{
-    enabled: true,           // Show transcript by default (default: true)
-    showToggleButton: true,  // Show the toggle button (default: true)
-    position: 'right'        // Position of transcript (default: 'right')
-  }}
-/>
-```
-
-### Configuration Options
-
-```typescript
-interface TranscriptConfig {
-  // Whether to show transcript by default when conversations start
-  enabled?: boolean; // default: true
-  
-  // Whether to show the toggle button near the main icon
-  showToggleButton?: boolean; // default: true
-  
-  // Position of the transcript box (future enhancement)
-  position?: 'right' | 'left' | 'top' | 'bottom'; // default: 'right'
-}
-```
-
-## Usage Examples
-
-### 1. Default Configuration (Transcript Enabled)
-
-```typescript
-// Transcript shows by default with toggle button
-<GuideAI organizationKey="your-org-key" />
-```
-
-### 2. Transcript Disabled by Default
-
-```typescript
-<GuideAI
-  organizationKey="your-org-key"
-  transcript={{
-    enabled: false,          // Don't show by default
-    showToggleButton: true   // But provide toggle button
-  }}
-/>
-```
-
-### 3. No Toggle Button (Manual Control Only)
-
-```typescript
-<GuideAI
-  organizationKey="your-org-key"
-  transcript={{
-    enabled: true,
-    showToggleButton: false  // Hide the toggle button
-  }}
-/>
-```
-
-### 4. Completely Hidden Transcript
-
-```typescript
-<GuideAI
-  organizationKey="your-org-key"
-  transcript={{
-    enabled: false,
-    showToggleButton: false  // No button, no auto-show
-  }}
-/>
-```
-
-## Programmatic Control
-
-### Global API Methods
-
-Access transcript controls via the global `window.GuideAI.transcript` object:
-
-```typescript
-// Toggle transcript visibility
-window.GuideAI.transcript.toggle();
-
-// Show transcript
-window.GuideAI.transcript.show();
-
-// Hide transcript
-window.GuideAI.transcript.hide();
-
-// Check if transcript is currently visible
-const isVisible = window.GuideAI.transcript.isVisible();
-console.log('Transcript visible:', isVisible);
-```
-
-### Integration Examples
-
-#### Custom Toggle Button
-
-```typescript
-function MyCustomControls() {
-  const [transcriptVisible, setTranscriptVisible] = useState(false);
-
-  const handleToggle = () => {
-    window.GuideAI.transcript.toggle();
-    setTranscriptVisible(window.GuideAI.transcript.isVisible());
-  };
-
-  return (
-    <button onClick={handleToggle}>
-      {transcriptVisible ? 'Hide' : 'Show'} Transcript
-    </button>
-  );
-}
-```
-
-#### Keyboard Shortcuts
-
-```typescript
-useEffect(() => {
-  const handleKeyPress = (event) => {
-    // Toggle transcript with Ctrl/Cmd + T
-    if ((event.ctrlKey || event.metaKey) && event.key === 't') {
-      event.preventDefault();
-      window.GuideAI.transcript.toggle();
-    }
-  };
-
-  document.addEventListener('keydown', handleKeyPress);
-  return () => document.removeEventListener('keydown', handleKeyPress);
-}, []);
-```
-
-#### Auto-Hide on Mobile
-
-```typescript
-useEffect(() => {
-  const isMobile = window.innerWidth < 768;
-  
-  if (isMobile) {
-    // Hide transcript on mobile by default
-    window.GuideAI.transcript.hide();
-  }
-}, []);
-```
-
-## Visual Design
-
-### Toggle Button
-
-- **Position**: Appears as a floating circular button in the bottom-right corner, above the transcript area
-- **Icons**: 📄 (when visible) / 📋 (when hidden)
-- **Hover Effects**: Scales up and shows tooltip
-- **Animation**: Smooth fade-in when conversation starts
-- **Design**: Dark themed button with blur effect to match transcript styling
-
-### States
-
-- **Visible**: 📄 icon with full opacity
-- **Hidden**: 📋 icon with reduced opacity
-- **Hover**: Scale animation and enhanced shadow
-
-## Behavior Details
-
-### When Toggle Button Appears
-
-The toggle button only shows when:
-1. `showToggleButton` is not set to `false`
-2. A conversation is active (`isConversationActive === true`)
-3. There are messages in the conversation (`allMessages.length > 0`)
-
-### Auto-Show/Hide Logic
-
-- **Conversation Start**: If `enabled !== false`, transcript shows automatically
-- **Conversation End**: If `enabled !== false`, transcript hides automatically
-- **Manual Toggle**: User's manual toggle state persists until next conversation start/end
-
-### Persistence
-
-The transcript toggle state does **not** persist across page reloads - it resets to the configured default (`enabled` setting).
-
-## Advanced Integration
-
-### Custom Positioning (Future Enhancement)
-
-```typescript
-// Future feature - custom transcript positioning
-<GuideAI
-  transcript={{
-    position: 'left',  // Position transcript on the left side
-    enabled: true
-  }}
-/>
-```
-
-### Event Listeners (Future Enhancement)
-
-```typescript
-// Future feature - listen to transcript visibility changes
-window.GuideAI.transcript.onVisibilityChange((isVisible) => {
-  console.log('Transcript visibility changed:', isVisible);
-  // Update your UI accordingly
-});
-```
-
-## Troubleshooting
-
-### Toggle Button Not Appearing
-
-Check that:
-1. `showToggleButton` is not set to `false`
-2. A conversation is active
-3. Messages exist in the conversation
-4. CSS styles are loaded properly
-
-### Programmatic Methods Not Working
-
-Ensure:
-1. GuideAI has finished initializing
-2. You're calling methods after component mount
-3. The global API is available: `window.GuideAI.transcript`
-
-### Styling Issues
-
-The toggle button uses these CSS classes:
-- `.guideai-transcript-toggle` - Main button container
-- `.guideai-transcript-icon` - Icon styling
-- `.guideai-transcript-icon.visible` - When transcript is visible
-- `.guideai-transcript-icon.hidden` - When transcript is hidden
-
-## Migration Guide
-
-### Existing Implementations
-
-If you're using GuideAI without transcript config, no changes needed:
-```typescript
-// This continues to work - transcript enabled by default
-<GuideAI organizationKey="your-org-key" />
-```
-
-### To Disable Transcript
-
-```typescript
-// Old: No way to disable
-// New: Explicit control
-<GuideAI
-  organizationKey="your-org-key"
-  transcript={{ enabled: false }}
-/>
-```
-
-This implementation provides flexible control over transcript visibility while maintaining backward compatibility with existing code.

package/types/index.d.ts

@@ -1,24 +0,0 @@
-export interface ConversationItem {
-    event_id?: string;
-    type: string;
-    previous_item_id: string | null;
-    item: Record<string, any>;
-    timestamp: number;
-}
-export type RecordingStatus = 'idle' | 'recording' | 'processing' | 'playing' | 'initializing';
-export interface GuideAIProps {
-    apiKey?: string;
-    organizationKey: string;
-    position?: {
-        top?: string;
-        right?: string;
-        bottom?: string;
-        left?: string;
-        marginTop?: string;
-        marginRight?: string;
-        marginBottom?: string;
-        marginLeft?: string;
-        transform?: string;
-    };
-    onError?: (error: string | Error, context?: string) => void;
-}