guideai-app 0.4.2 → 0.4.3

package/.workflow-test

@@ -0,0 +1 @@
+# Workflow Test

package/PRODUCTION_RELEASE.md

@@ -0,0 +1,126 @@
+# Production Release Guide - guideai-app npm Package
+
+This guide covers how to publish production releases of `guideai-app` to the public npm registry.
+
+## Prerequisites
+
+- [ ] Changes merged and tested on `development` branch
+- [ ] Ready to create a production release
+- [ ] npm account with publish access to `guideai-app`
+
+## Release Process
+
+### 1. Merge Development to Production
+
+```bash
+git checkout production
+git pull origin production
+git merge development
+```
+
+Resolve any conflicts if needed.
+
+### 2. Update Version Number
+
+**Option A: Use npm version command (Recommended)**
+
+```bash
+cd guide-ai-package
+npm version patch  # 0.4.2 → 0.4.3
+# or
+npm version minor  # 0.4.2 → 0.5.0
+# or
+npm version major  # 0.4.2 → 1.0.0
+```
+
+This automatically:
+- Updates package.json
+- Creates a git commit
+- Creates a git tag
+
+Then push:
+```bash
+git push origin production --follow-tags
+```
+
+**Option B: Manual update**
+
+If you prefer manual control:
+
+1. Edit `guide-ai-package/package.json`:
+```json
+{
+  "name": "guideai-app",
+  "version": "0.4.3",  // ← Increment this
+  ...
+}
+```
+
+2. Commit:
+```bash
+git add guide-ai-package/package.json
+git commit -m "chore: bump version to 0.4.3"
+git push origin production
+```
+
+### 4. Build the Package
+
+```bash
+cd guide-ai-package
+npm run build
+```
+
+Verify build completes successfully.
+
+### 5. Publish to npm Registry
+
+```bash
+npm publish --registry https://registry.npmjs.org/
+```
+
+**Important:** The `--registry` flag ensures publication to npm, not GitHub Packages.
+
+### 6. Verify Publication
+
+```bash
+npm view guideai-app
+
+# Should show your new version as 'latest'
+```
+
+### 7. Tag the Release (Optional but Recommended)
+
+```bash
+git tag -a v0.4.3 -m "Release v0.4.3"
+git push origin v0.4.3
+```
+
+## After Release
+
+- [ ] New version available at https://www.npmjs.com/package/guideai-app
+- [ ] Customers can install with `npm install guideai-app@0.4.3`
+- [ ] Update guideaisite production environment to use new version
+
+## Notes
+
+- **Dev releases** (beta tags) are automated via GitHub Actions → GitHub Packages
+- **Production releases** are manual via this process → npm registry
+- This ensures production releases are intentional and controlled
+- The scoped package `@guideai/guideai-app` on GitHub Packages is separate and unaffected
+
+## Troubleshooting
+
+**Error: "You must be logged in to publish packages"**
+```bash
+npm login
+# Follow prompts to authenticate
+```
+
+**Error: "You do not have permission to publish"**
+- Verify your npm account has publish access to `guideai-app`
+- Contact package maintainer to add you
+
+**Wrong package published:**
+- You can unpublish within 72 hours: `npm unpublish guideai-app@VERSION`
+- After 72 hours, must deprecate: `npm deprecate guideai-app@VERSION "reason"`
+

package/README.md

@@ -1,6 +1,6 @@
 # Guide AI
 
-A React component that provides AI-powered guidance with voice interaction, text input, and element highlighting capabilities.
+An AI-powered voice assistant component for React applications. Guide AI provides intelligent voice interactions, helping users navigate and complete tasks within your application.
 
 ## Installation
 
@@ -10,29 +10,11 @@ npm install guideai-app
 yarn add guideai-app
 ```
 
-## Usage
-
-### Basic Usage
-
-```jsx
-import GuideAI from 'guideai-app';
-
-function App() {
-  return (
-    <div>
-      <GuideAI 
-        organizationKey="your-organization-key"
-        position={{ bottom: '2rem', right: '2rem' }}
-        onError={(error) => console.error(error)}
-      />
-    </div>
-  );
-}
-```
-
-### With Workflow Triggers
+## Basic Usage
 
 ```jsx
+import React from 'react';
+import ReactDOM from 'react-dom';
 import GuideAI from 'guideai-app';
 
 function App() {
@@ -40,8 +22,9 @@ function App() {
     <div>
       <GuideAI 
         organizationKey="your-organization-key"
-        workflowKey="customer-support"
-        position={{ bottom: '2rem', right: '2rem' }}
+        React={React}
+        ReactDOM={ReactDOM}
+        position={{ bottom: '20px', right: '20px' }}
         onError={(error) => console.error(error)}
       />
     </div>
@@ -53,16 +36,15 @@ function App() {
 
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
-| `organizationKey` | `string` | Yes | Your organization key for workflows |
-| `workflowKey` | `string` | No | Workflow key for trigger-based 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) |
+| `organizationKey` | `string` | Yes | Your unique organization key |
+| `React` | `React` | Yes | React instance from your application |
+| `ReactDOM` | `ReactDOM` | Yes | ReactDOM instance from your application |
+| `position` | `object` | No | CSS positioning for the component (see below) |
+| `onError` | `function` | No | Error handler callback: `(error: string \| Error) => void` |
 
-### Position Object
+## Position Object
 
-The `position` prop accepts an object with CSS positioning properties:
+The `position` prop accepts an object with CSS positioning properties to control where the Guide AI button appears on your page:
 
 ```typescript
 position?: {
@@ -78,254 +60,87 @@ position?: {
 }
 ```
 
-### Transcript Configuration Object
-
-```typescript
-transcript?: {
-  enabled?: boolean;           // Show transcript (default: true)
-  showToggleButton?: boolean;  // Show transcript toggle (default: true)
-  position?: 'right' | 'left' | 'top' | 'bottom'; // Transcript position
-}
-```
-
-### Input Configuration Object
+### Position Examples
 
-```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
-}
+**Bottom-right corner:**
+```jsx
+<GuideAI 
+  organizationKey="your-org-key"
+  React={React}
+  ReactDOM={ReactDOM}
+  position={{ bottom: '20px', right: '20px' }}
+/>
 ```
 
-### Examples
-
-**Basic usage:**
+**Bottom-left corner:**
 ```jsx
 <GuideAI 
   organizationKey="your-org-key"
-  position={{ bottom: '4rem', left: '50%', marginLeft: '-30px' }}
+  React={React}
+  ReactDOM={ReactDOM}
+  position={{ bottom: '20px', left: '20px' }}
 />
 ```
 
-**With text input enabled by default:**
+**Centered at bottom:**
 ```jsx
 <GuideAI 
   organizationKey="your-org-key"
-  position={{ top: '20px', right: '20px' }}
-  input={{
-    defaultMode: 'text',
-    placeholder: "Ask me anything..."
+  React={React}
+  ReactDOM={ReactDOM}
+  position={{ 
+    bottom: '20px', 
+    left: '50%', 
+    transform: 'translateX(-50%)' 
   }}
 />
 ```
 
-**Full configuration:**
+**Top-right corner:**
 ```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)}
+  organizationKey="your-org-key"
+  React={React}
+  ReactDOM={ReactDOM}
+  position={{ top: '20px', right: '20px' }}
 />
 ```
 
-## Text Input Feature
-
-GuideAI now supports both voice and text input modes, giving users flexible ways to interact with the AI assistant.
-
-### Features
-
-- **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
-
-### Input Props
-
-| 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 |
-
-### How to Use Text Input
-
-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
-
-### Accessibility Features
-
-- **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
-
-## Transcript Feature
+## Complete Example
 
-GuideAI includes a beautiful transcript interface that displays conversations between users and the AI in a transparent Apple-style box.
-
-### Features
-
-- **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
-
-### How to Use
-
-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
-
-### Transcript Interface
-
-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
-
-### Styling
-
-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
-
-## Element Interaction Features
-
-GuideAI includes powerful element interaction capabilities that allow the AI to guide users by highlighting, hovering over, and clicking elements on the page.
-
-### Features
-
-- **Element Highlighting**: AI can highlight and click on specific page elements
-- **Hover Interactions**: AI can hover over elements with visual feedback
-- **Position Tracking**: Cursor follows elements that move or expand during interactions
-- **Multiple Selector Support**: Supports CSS selectors, XPath, and text-based selectors
-- **Extended Visual Feedback**: 3-second highlighting with enhanced animations
-
-### Supported Selector Types
-
-| Selector Type | Format | Example |
-|---------------|--------|---------|
-| **ID** | `#elementId` | `#sidebarMenu-button-goals` |
-| **Class** | `.className` | `.submit-button` |
-| **Attribute** | `[attribute="value"]` | `[data-testid="submit"]` |
-| **Complex CSS** | Any valid CSS | `button.primary[aria-label="Save"]` |
-| **Text-based** | `text:cssSelector:textContent` | `text:.MuiListItemText-root:Goal Sets` |
-| **XPath** | `//xpath` | `//button[contains(text(), 'Submit')]` |
-
-### Available Tools
-
-#### `highlight` Tool
-- **Purpose**: Moves cursor to elements and clicks them
-- **Use Case**: Guiding users through workflows by clicking interactive elements
-- **Visual Effect**: Blue cursor with click animations and visual feedback
-
-#### `hoverThenHighlight` Tool  
-- **Purpose**: Moves cursor to elements and hovers over them
-- **Use Case**: Demonstrating or highlighting elements without triggering clicks
-- **Visual Effect**: Orange hover effects with position tracking for dynamic elements
-
-### How It Works
-
-1. **AI Detection**: The AI analyzes user requests and determines which elements to interact with
-2. **Element Finding**: Uses advanced selector logic to locate elements on the page
-3. **Visual Animation**: Animated cursor moves from viewport center to target elements
-4. **Interaction**: Performs click or hover action with appropriate visual feedback
-5. **Position Tracking**: For hover actions, tracks element position changes for 3 seconds
-
-### Example Usage
-
-The AI can respond to user requests like:
-- "Click the save button" → Uses `highlight` tool to click elements
-- "Show me the navigation menu" → Uses `hoverThenHighlight` tool to highlight elements
-- "Test hover on the goals section" → Triggers predefined test sequence
-
-### Technical Implementation
-
-- **Files**: `selectElementAndClick.ts` (clicking) and `hoverAndHighlight.ts` (hovering)
-- **State Management**: Separate state tracking for click and hover operations
-- **Error Handling**: Graceful fallback when elements are not found
-- **Performance**: Optimized with 50ms position tracking intervals
-
-## Migration from Voice-Only Versions
-
-If you're upgrading from a voice-only version:
-
-- **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
-
-## Workflow Trigger Feature
-
-GuideAI now supports workflow triggers based on trigger words detected in user messages. This feature allows you to create dynamic workflows that are activated when specific keywords or phrases are mentioned by users.
-
-### Features
-
-- **Trigger Word Detection**: Automatically detect trigger words in user messages
-- **Workflow Integration**: Seamlessly integrate with your backend workflow system
-- **Dynamic Prompts**: Workflow-specific prompts from the initialize-session API
-- **Tool-based Triggers**: AI can call workflow triggers through function calls
-- **Configurable**: Support for multiple workflow keys and trigger patterns
-
-### How It Works
+```jsx
+import React from 'react';
+import ReactDOM from 'react-dom';
+import GuideAI from 'guideai-app';
 
-1. **Session Initialization**: When a conversation starts, the system calls `/initialize-session` with the `workflowKey` and receives a workflow-specific prompt
-2. **Trigger Word Detection**: The AI automatically analyzes user messages for trigger words and calls the `trigger_workflow` function when triggers are found
-3. **Workflow Execution**: Your backend receives the trigger request and executes workflow-specific actions
+function App() {
+  const handleError = (error) => {
+    console.error('GuideAI Error:', error);
+    // Add your custom error handling here
+  };
 
-### Example Workflows
+  return (
+    <div className="app">
+      <h1>My Application</h1>
+      
+      <GuideAI 
+        organizationKey="your-organization-key"
+        React={React}
+        ReactDOM={ReactDOM}
+        position={{ bottom: '40px', right: '40px' }}
+        onError={handleError}
+      />
+    </div>
+  );
+}
 
-**Customer Support**: Trigger words like "help", "support", "issue", "problem"
-**Sales Inquiry**: Trigger words like "pricing", "cost", "buy", "purchase"
-**Technical Support**: Trigger words like "error", "bug", "crash", "not working"
+export default App;
+```
 
-### Backend Requirements
+## Getting Your Organization Key
 
-You only need to implement the `initialize-session` endpoint, which returns workflows along with the prompt:
+To use Guide AI, you'll need an organization key. Contact the Guide AI team to get your key and set up your organization.
 
-```json
-{
-  "id": "conversation-uuid",
-  "ephemeralToken": "openai-realtime-token",
-  "prompt": "organization-prompt",
-  "workflows": [
-    {
-      "id": "workflow-uuid",
-      "name": "Customer Support Workflow",
-      "triggers": ["help", "support", "customer service"],
-      "organizationKey": "org-key-123",
-      "prompt": "You are a helpful customer support agent...",
-      "archived": false,
-      "createdAt": "2024-01-01T00:00:00.000Z",
-      "updatedAt": "2024-01-01T00:00:00.000Z"
-    }
-  ]
-}
-```
+## Support
 
-For detailed implementation guide, see [workflow-trigger-usage.md](./workflow-trigger-usage.md).
+For questions, issues, or feature requests, please contact the Guide AI team or visit our documentation.