guideai-app 0.4.1 → 0.4.2-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

@@ -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.