guideai-app 0.3.5 → 0.4.2

package/PII_HASHING_STORIES_SUMMARY.md

@@ -0,0 +1,275 @@
+# PII Hashing - Story Summary
+
+**Epic Goal:** Implement client-side PII hashing to prevent sensitive data from appearing in logs, monitoring tools, and backend systems.
+
+---
+
+## Frontend Stories (Guide AI Package)
+
+### ✅ FE-1: Create PII Hashing Utility
+**Points:** 3 | **Priority:** P0 | **Dependencies:** None
+
+Create `src/utils/pii.ts` with:
+- `hashEmail()` - Hash email using SHA-256
+- `hashPII()` - Generic PII hashing function
+- `isHashed()` - Check if value is already hashed
+- TypeScript types and JSDoc
+- Works with Web Crypto API
+
+**Deliverables:**
+- New file: `src/utils/pii.ts`
+- TypeScript types for hashed data
+- Documentation
+
+---
+
+### ✅ FE-2: Update UserMetadataTracker to Hash Emails  
+**Points:** 5 | **Priority:** P0 | **Dependencies:** FE-1
+
+Update `src/metric/metadata-tracker.tsx`:
+- Hash emails in `updateUserInfo()`
+- Hash emails in `trackLogin()`
+- Hash emails in all `trackVisit*()` methods
+- Hash emails in `trackCustomEvent()`
+- Store hashed emails in localStorage
+- Add migration logic for existing data
+- Graceful error handling
+
+**Deliverables:**
+- Modified: `src/metric/metadata-tracker.tsx`
+- All emails hashed before storage/transmission
+- Backward compatible
+
+---
+
+### ✅ FE-3: Update API Layer for Hashed Identifiers
+**Points:** 3 | **Priority:** P0 | **Dependencies:** FE-1, FE-2
+
+Update API types and validation:
+- Add `emailHash` field to `UserMetadata` type
+- Deprecate `email` field (keep for backward compatibility)
+- Add validation in `sendMetadataUpdates()` (dev mode)
+- Ensure no plain-text emails in API calls
+- Update JSDoc comments
+
+**Deliverables:**
+- Modified: `src/types/metadata.types.ts`
+- Modified: `src/utils/api.ts`
+- API request validation
+
+---
+
+### ✅ FE-4: Add Privacy Configuration Options
+**Points:** 2 | **Priority:** P1 | **Dependencies:** FE-1, FE-2
+
+Add config options to `MetadataConfig`:
+- `enablePIIHashing: boolean` (default: true)
+- `piiFields: string[]` (default: ['email'])
+- `allowPlainTextFallback: boolean` (default: false)
+
+**Deliverables:**
+- Modified: `src/types/metadata.types.ts`
+- Configuration documentation
+- Usage examples
+
+---
+
+### ✅ FE-5: Add Unit & Integration Tests
+**Points:** 5 | **Priority:** P0 | **Dependencies:** FE-1, FE-2, FE-3
+
+Create comprehensive test coverage:
+- Unit tests for `pii.ts` utilities
+- Unit tests for metadata tracker hashing
+- Integration tests for end-to-end flow
+- Test error handling and edge cases
+- Verify no plain-text in API calls
+
+**Deliverables:**
+- New file: `src/utils/pii.test.ts`
+- New file: `src/metric/metadata-tracker.pii.test.ts`
+- 90%+ code coverage
+- All tests passing in CI
+
+---
+
+## Backend Stories (High Level - Other Repo)
+
+### 🔧 BE-1: Update API Endpoints for Hashed Email Handling
+**Points:** 8 | **Priority:** P0
+
+**What:**
+- Update `/initialize-session` endpoint to accept `emailHash`
+- Update `/metadata-updates` endpoint to process `emailHash`
+- Add hash format validation (64 hex chars)
+- Ensure backward compatibility during migration
+- Update API documentation
+
+**Technical Notes:**
+- Accept both `email` and `emailHash` during transition
+- Validate hash format: `/^[a-f0-9]{64}$/i`
+- No plain-text emails in logs
+
+---
+
+### 🔧 BE-2: Create Email Hash Mapping System
+**Points:** 13 | **Priority:** P0
+
+**What:**
+- Create `email_mappings` table
+- Store: `emailHash → encryptedEmail`
+- Implement encryption at rest (AES-256-GCM)
+- Use KMS for key management
+- Add Redis cache for frequently accessed mappings
+- Implement audit logging
+- Create internal API for email lookup
+
+**Database Schema:**
+```sql
+email_mappings (
+  email_hash: VARCHAR(64) PRIMARY KEY,
+  encrypted_email: BYTEA,
+  encryption_key_id: VARCHAR(50),
+  organization_key: VARCHAR(100),
+  first_seen: TIMESTAMP,
+  last_seen: TIMESTAMP
+)
+```
+
+---
+
+### 🔧 BE-3: Update Database Schema
+**Points:** 5 | **Priority:** P0
+
+**What:**
+- Add `email_hash` column to relevant tables
+- Migrate existing plain-text emails to hashes
+- Create indexes on `email_hash`
+- Update all queries to use `email_hash`
+- Keep `email` column temporarily for backward compatibility
+
+**Migration Strategy:**
+1. Add new column
+2. Backfill hashes (incremental)
+3. Create indexes
+4. Update application code
+5. (Future) Drop old email column
+
+---
+
+### 🔧 BE-4: Add Email Retrieval & Notification Logic
+**Points:** 8 | **Priority:** P1
+
+**What:**
+- Create service for secure email retrieval
+- Implement notification service using email lookup
+- Add authentication/authorization
+- Implement audit logging for email access
+- Add rate limiting
+- Monitoring/alerts for suspicious access
+
+**Access Control:**
+- Only notification service can retrieve emails
+- Service-to-service authentication
+- Rate limit: 100 lookups/minute per service
+- IP whitelisting
+
+---
+
+## Story Point Summary
+
+| Team | Total Points | Stories |
+|------|--------------|---------|
+| **Frontend** | **18 points** | 5 stories |
+| **Backend** | **34 points** | 4 stories |
+| **TOTAL** | **52 points** | 9 stories |
+
+---
+
+## Sprint Allocation (Example)
+
+### Sprint 1: Core Implementation
+- FE-1: Create PII Hashing Utility (3 pts)
+- FE-2: Update UserMetadataTracker (5 pts)
+- BE-1: Update API Endpoints (8 pts)
+- **Total: 16 points**
+
+### Sprint 2: Integration & Mapping
+- FE-3: Update API Layer (3 pts)
+- FE-4: Add Privacy Config (2 pts)
+- BE-2: Email Hash Mapping System (13 pts)
+- **Total: 18 points**
+
+### Sprint 3: Testing & Deployment
+- FE-5: Tests (5 pts)
+- BE-3: Database Schema (5 pts)
+- BE-4: Email Retrieval Logic (8 pts)
+- **Total: 18 points**
+
+---
+
+## Critical Path
+
+```
+FE-1 (PII Utils)
+  ↓
+FE-2 (Metadata Tracker) + BE-1 (API Endpoints)
+  ↓
+FE-3 (API Layer) + BE-2 (Email Mapping)
+  ↓
+FE-5 (Tests) + BE-3 (DB Schema) + BE-4 (Email Retrieval)
+  ↓
+Integration Testing
+  ↓
+Production Deployment
+```
+
+---
+
+## Quick Checklist
+
+**Before Starting:**
+- [ ] Product approval for privacy changes
+- [ ] Security review of approach
+- [ ] Backend team capacity confirmed
+- [ ] Database migration plan reviewed
+
+**During Development:**
+- [ ] Daily syncs between FE/BE teams
+- [ ] Test in staging after each story
+- [ ] Security scanning of new code
+- [ ] Performance testing
+
+**Before Production:**
+- [ ] All tests passing
+- [ ] Privacy audit completed
+- [ ] Rollback plan documented
+- [ ] Monitoring configured
+- [ ] Team trained on new system
+
+---
+
+## Key Decisions Needed
+
+1. **Migration Timeline:** How long to support both `email` and `emailHash`?
+2. **Rollout Strategy:** Big bang or gradual rollout?
+3. **Old Data:** Migrate existing emails in DB or only new data?
+4. **Other PII:** Should we hash other fields (userId, customerLicense)?
+5. **Encryption Keys:** Where to store? AWS KMS? Vault?
+
+---
+
+## Success Criteria
+
+✅ No plain-text emails in server logs  
+✅ No plain-text emails in API requests  
+✅ All notifications still work  
+✅ < 50ms latency impact  
+✅ 99.9% uptime during migration  
+✅ Privacy audit passed
+
+---
+
+**Created:** [Date]  
+**Owner:** [Name]  
+**Status:** Ready for Planning
+

package/README.md

@@ -12,6 +12,8 @@ yarn add guideai-app
 
 ## Usage
 
+### Basic Usage
+
 ```jsx
 import GuideAI from 'guideai-app';
 
@@ -28,11 +30,31 @@ function App() {
 }
 ```
 
+### With Workflow Triggers
+
+```jsx
+import GuideAI from 'guideai-app';
+
+function App() {
+  return (
+    <div>
+      <GuideAI 
+        organizationKey="your-organization-key"
+        workflowKey="customer-support"
+        position={{ bottom: '2rem', right: '2rem' }}
+        onError={(error) => console.error(error)}
+      />
+    </div>
+  );
+}
+```
+
 ## Props
 
 | 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 |
@@ -192,6 +214,63 @@ The transcript uses modern CSS features including:
 - 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:
@@ -200,3 +279,53 @@ If you're upgrading from a voice-only version:
 - **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
+
+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
+
+### Example Workflows
+
+**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"
+
+### Backend Requirements
+
+You only need to implement the `initialize-session` endpoint, which returns workflows along with the prompt:
+
+```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"
+    }
+  ]
+}
+```
+
+For detailed implementation guide, see [workflow-trigger-usage.md](./workflow-trigger-usage.md).

package/SESSION_ID_VERIFICATION.md

@@ -0,0 +1,122 @@
+# Session ID Implementation Verification Guide
+
+## Overview
+This guide helps you verify that the session ID tracking implementation is working correctly.
+
+## What Was Implemented
+
+### 1. Session Utility (`src/utils/session.ts`)
+- ✅ `getSessionId()` - Gets or creates session ID
+- ✅ `clearSessionId()` - Clears session ID (for testing)
+- ✅ `peekSessionId()` - Views session ID without creating one
+- ✅ Standard UUID v4 format
+- ✅ Stored in `sessionStorage['guideai_session_id']`
+
+### 2. UserMetadataTracker Updates
+- ✅ Session ID initialized in `init()` method
+- ✅ Session ID stored in metadata object
+- ✅ Session ID included in all metadata updates
+
+### 3. Exports
+- ✅ Session utility functions exported from main index
+- ✅ Available for external debugging and testing
+
+## Manual Verification Steps
+
+### Step 1: Check Session Storage
+1. Open your test site in a browser
+2. Open DevTools → Application → Session Storage
+3. Look for `guideai_session_id`
+4. Verify it contains a UUID (e.g., `550e8400-e29b-41d4-a716-446655440000`)
+
+### Step 2: Verify Persistence
+1. Navigate between different pages on your site
+2. Check that `guideai_session_id` remains the same
+3. Refresh the page - session ID should persist
+
+### Step 3: Verify New Session Creation
+1. Open a new tab to the same site
+2. Check Session Storage - should have a different `guideai_session_id`
+3. Close and reopen a tab - should generate a new `guideai_session_id`
+
+### Step 4: Verify Metadata Tracking
+Open the browser console and check logs:
+
+```javascript
+// UserMetadataTracker should log:
+// "Session ID initialized" with { sessionId: "..." }
+
+// metadata object should include sessionId
+```
+
+### Step 6: Programmatic Testing
+You can test session functions directly in the console:
+
+```javascript
+// Get current session ID
+const { getSessionId, peekSessionId, clearSessionId } = window.GuideAI || {};
+
+// View current session ID (if GuideAI exports are available)
+console.log('Current session:', peekSessionId());
+
+// Or directly from sessionStorage
+console.log('Session ID:', sessionStorage.getItem('guideai_session_id'));
+```
+
+## Expected Behavior
+
+### Session Lifecycle
+- **New Tab**: New session ID generated
+- **Page Navigation**: Session ID persists
+- **Page Refresh**: Session ID persists
+- **Tab Close**: Session ID cleared automatically
+- **Browser Restart**: New session IDs for all tabs
+
+### Data Inclusion
+- **UserMetadataTracker**: Metadata should include `sessionId` field
+- **API Calls**: Session ID should be sent to backend with metadata updates
+
+## Testing in Your Application
+
+Add this code to your test application to verify session tracking:
+
+```typescript
+import GuideAI, { getSessionId } from 'guideai-package';
+
+// In your component
+useEffect(() => {
+  // Log session ID on mount
+  console.log('Current GuideAI Session:', getSessionId());
+  
+  // Check sessionStorage directly
+  console.log('Session Storage:', sessionStorage.getItem('guideai_session_id'));
+}, []);
+```
+
+## Common Issues & Solutions
+
+### Issue: Session ID not appearing
+**Solution**: Ensure GuideAI component has mounted and initialized
+
+### Issue: Session ID changes on page refresh
+**Solution**: Verify you're using `sessionStorage` not `localStorage`
+
+### Issue: Same session ID across tabs
+**Solution**: This is expected behavior - each tab should have its own session ID
+
+## Phase 2 Features (Not Yet Implemented)
+
+These features are planned for future releases:
+- ❌ `session_start` metadata event
+- ❌ `session_end` metadata event  
+- ❌ Session duration tracking
+- ❌ Session-level analytics
+
+## Notes
+
+- Session ID uses browser's `crypto.randomUUID()` when available
+- Fallback UUID generation for older browsers
+- Global session key (not per-organization)
+- `conversationStartTime` remains for backward compatibility
+- Session utility handles SSR/non-browser environments gracefully
+