guideai-app 0.4.1 → 0.4.2-2

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
+

package/VISIT_COUNT_TESTING.md

@@ -0,0 +1,453 @@
+# Visit Count Testing - Manual Test Checklist
+
+This document contains manual testing procedures for scenarios that cannot be fully automated in unit/integration tests.
+
+## Prerequisites
+
+Before testing, ensure you have:
+- [ ] Built the GuideAI package (`npm run build`)
+- [ ] Access to the test site
+- [ ] Multiple browsers installed (Chrome, Firefox, Safari, Edge)
+- [ ] Mobile device or browser DevTools mobile emulation
+- [ ] Browser DevTools open to inspect localStorage
+
+## Understanding Visit Count Behavior
+
+**Expected Behavior:**
+- `visitCount` starts at `1` on first visit
+- `visitCount` increments when user returns after **30+ minutes**
+- `visitCount` persists in `localStorage` (survives browser close/reopen)
+- `sessionId` is stored in `sessionStorage` (cleared on browser/tab close)
+
+**When visitCount resets to 1 (treated as first-time user):**
+1. ✅ Switching browsers (Chrome → Firefox)
+2. ✅ Using incognito/private browsing mode
+3. ✅ Switching devices (Desktop → Mobile)
+4. ✅ Clearing browser data
+
+---
+
+## Test Suite 1: Cross-Browser Testing
+
+### Test 1.1: Chrome to Firefox Switch
+
+**Purpose:** Verify that switching browsers treats user as first-time user.
+
+**Steps:**
+1. Open Chrome browser
+2. Navigate to test site
+3. Open DevTools → Console
+4. Check visitCount: `localStorage.getItem('guideai_user_metadata')`
+   - **Expected:** `visitCount: 1`
+5. Note the sessionId
+6. Close Chrome
+7. Open Firefox browser
+8. Navigate to same test site
+9. Check visitCount in Firefox DevTools
+   - **Expected:** `visitCount: 1` (treated as new user)
+   - **Expected:** Different sessionId
+
+**Result:** ☐ PASS ☐ FAIL
+
+**Notes:**
+```
+Chrome visitCount: ___
+Firefox visitCount: ___
+```
+
+---
+
+### Test 1.2: Chrome to Safari Switch
+
+**Purpose:** Verify cross-browser isolation.
+
+**Steps:**
+1. Open Chrome, visit test site
+2. Manually increment visitCount (login or wait 31+ min and reload)
+3. Verify visitCount is now `2` or higher in Chrome
+4. Open Safari, visit test site
+5. Check visitCount in Safari
+   - **Expected:** `visitCount: 1` (Safari has its own localStorage)
+
+**Result:** ☐ PASS ☐ FAIL
+
+**Notes:**
+```
+Chrome visitCount: ___
+Safari visitCount: ___
+```
+
+---
+
+## Test Suite 2: Incognito/Private Mode
+
+### Test 2.1: Regular to Incognito Switch
+
+**Purpose:** Verify incognito mode always treats user as first-time user.
+
+**Steps:**
+1. Open Chrome in regular mode
+2. Visit test site
+3. Check visitCount
+   - **Expected:** `visitCount: 1`
+4. Manually increment visitCount to `3`: 
+   ```javascript
+   window.GuideAI.metadata.trackVisitManually()
+   window.GuideAI.metadata.trackVisitManually()
+   ```
+5. Verify visitCount is now `3`
+6. Open Chrome in Incognito mode (Cmd/Ctrl + Shift + N)
+7. Visit same test site
+8. Check visitCount in incognito
+   - **Expected:** `visitCount: 1`
+
+**Result:** ☐ PASS ☐ FAIL
+
+---
+
+### Test 2.2: Multiple Incognito Sessions
+
+**Purpose:** Verify each incognito window is isolated.
+
+**Steps:**
+1. Open Incognito Window 1
+2. Visit test site, verify visitCount = 1
+3. Increment visitCount to 2
+4. Close Incognito Window 1
+5. Open new Incognito Window 2
+6. Visit test site
+7. Check visitCount
+   - **Expected:** `visitCount: 1` (fresh incognito = fresh storage)
+
+**Result:** ☐ PASS ☐ FAIL
+
+---
+
+## Test Suite 3: Mobile and Desktop
+
+### Test 3.1: Desktop to Mobile Device Switch
+
+**Purpose:** Verify different devices have separate visitCount.
+
+**Steps:**
+1. On Desktop Chrome, visit test site
+2. Increment visitCount to `3`
+3. Note the visitCount and firstVisit timestamp
+4. On Mobile device (actual phone), visit same test site
+5. Check visitCount on mobile
+   - **Expected:** `visitCount: 1` (different device = different localStorage)
+6. On Mobile, increment visitCount to `2`
+7. Return to Desktop, refresh page
+8. Check visitCount on desktop
+   - **Expected:** Still `3` (unchanged by mobile activity)
+
+**Result:** ☐ PASS ☐ FAIL
+
+**Notes:**
+```
+Desktop visitCount: ___
+Mobile visitCount: ___
+```
+
+---
+
+### Test 3.2: Desktop to Mobile Browser Emulation
+
+**Purpose:** Verify behavior using DevTools mobile emulation.
+
+**Steps:**
+1. Open Chrome DevTools → Device Toolbar (Cmd/Ctrl + Shift + M)
+2. Select iPhone or Android device
+3. Visit test site
+4. Check visitCount
+   - **Expected:** Reads from same localStorage as desktop (should be same count)
+   - **Note:** DevTools emulation does NOT create separate storage
+
+**Result:** ☐ PASS ☐ FAIL
+
+**Important:** This test demonstrates that DevTools emulation ≠ real mobile device testing.
+
+---
+
+## Test Suite 4: Clearing Browser Data
+
+### Test 4.1: Clear All Browsing Data
+
+**Purpose:** Verify clearing data resets visitCount.
+
+**Steps:**
+1. Visit test site, increment visitCount to `5`
+2. Go to Chrome Settings → Privacy → Clear browsing data
+3. Select "All time" and check "Cookies and other site data" + "Cached images and files"
+4. Click "Clear data"
+5. Revisit test site
+6. Check visitCount
+   - **Expected:** `visitCount: 1` (treated as first-time user)
+   - **Expected:** New firstVisit timestamp
+
+**Result:** ☐ PASS ☐ FAIL
+
+---
+
+### Test 4.2: Clear Only Cookies (Keep Cache)
+
+**Purpose:** Verify visitCount is tied to localStorage (cookies).
+
+**Steps:**
+1. Visit test site, visitCount = 1
+2. Clear only "Cookies and other site data" (NOT cache)
+3. Revisit test site
+4. Check visitCount
+   - **Expected:** `visitCount: 1` (localStorage cleared with cookies)
+
+**Result:** ☐ PASS ☐ FAIL
+
+---
+
+## Test Suite 5: Real-World User Flows
+
+### Test 5.1: Morning Visit, Evening Visit (Same Day)
+
+**Purpose:** Verify visitCount behavior across a single day.
+
+**Steps:**
+1. **Morning (9 AM):** Visit test site, visitCount = 1
+2. **Afternoon (2 PM, 5 hours later):** 
+   - Close browser completely
+   - Reopen browser, visit test site
+   - **Expected:** visitCount still = 1 (within 30-min window from last activity)
+3. **Evening (10 PM, 8 hours after afternoon visit):**
+   - Reopen browser (ensure 30+ min since last visit)
+   - Visit test site
+   - **Expected:** visitCount = 2 (exceeded 30-min timeout)
+
+**Result:** ☐ PASS ☐ FAIL
+
+**Alternative:** Speed up using DevTools:
+```javascript
+// Manually set lastVisit to 31 minutes ago
+const data = JSON.parse(localStorage.getItem('guideai_user_metadata'));
+data.metadata.lastVisit = Date.now() - (31 * 60 * 1000);
+localStorage.setItem('guideai_user_metadata', JSON.stringify(data));
+// Refresh page - visitCount should increment
+```
+
+---
+
+### Test 5.2: Multiple Tabs Open Simultaneously
+
+**Purpose:** Verify visitCount is shared across tabs.
+
+**Steps:**
+1. Open Tab 1, visit test site
+2. Check visitCount in Tab 1
+   - **Expected:** `visitCount: 1`
+3. Open Tab 2 (Cmd/Ctrl + T), visit test site
+4. Check visitCount in Tab 2
+   - **Expected:** `visitCount: 1` (shared localStorage)
+5. In Tab 1, run:
+   ```javascript
+   window.GuideAI.metadata.trackVisitManually()
+   ```
+6. In Tab 2, refresh page
+7. Check visitCount in Tab 2
+   - **Expected:** `visitCount: 2` (sees update from Tab 1)
+
+**Result:** ☐ PASS ☐ FAIL
+
+---
+
+### Test 5.3: User Login Flow
+
+**Purpose:** Verify login correctly increments visitCount.
+
+**Steps:**
+1. Visit test site (not logged in), visitCount = 1
+2. Simulate login:
+   ```javascript
+   window.GuideAI.metadata.resetSessionVisitTracking()
+   window.GuideAI.metadata.trackVisitManually()
+   window.GuideAI.metadata.trackLogin({ email: 'test@example.com' })
+   ```
+3. Check visitCount
+   - **Expected:** `visitCount: 2`
+4. Check loginCount
+   - **Expected:** `loginCount: 1`
+
+**Result:** ☐ PASS ☐ FAIL
+
+---
+
+## Test Suite 6: Edge Cases
+
+### Test 6.1: Rapid Page Refreshes
+
+**Purpose:** Verify rapid refreshes don't inflate visitCount.
+
+**Steps:**
+1. Visit test site, visitCount = 1
+2. Press F5 (refresh) 10 times rapidly
+3. Check visitCount after each refresh
+   - **Expected:** `visitCount: 1` (unchanged)
+
+**Result:** ☐ PASS ☐ FAIL
+
+---
+
+### Test 6.2: Browser Crash Recovery
+
+**Purpose:** Verify visitCount persists after browser crash.
+
+**Steps:**
+1. Visit test site, visitCount = 1
+2. Increment to visitCount = 3
+3. Force browser crash (Task Manager → End Task on browser)
+4. Reopen browser
+5. Visit test site
+6. Check visitCount
+   - **Expected:** `visitCount: 3` (persisted in localStorage)
+   - Within 30 min: stays at 3
+   - After 30+ min: increments to 4
+
+**Result:** ☐ PASS ☐ FAIL
+
+---
+
+## Test Suite 7: POC First-Time User Detection
+
+### Test 7.1: First-Time User Onboarding
+
+**Purpose:** Verify first-time user detection for onboarding flow.
+
+**Steps:**
+1. Clear all browser data
+2. Visit test site
+3. Check if onboarding appears (based on `visitCount === 1`)
+   - **Expected:** Onboarding shown
+4. Close browser, reopen within 30 min
+5. Visit test site again
+6. Check if onboarding appears
+   - **Expected:** Onboarding STILL shown (visitCount still 1)
+7. Wait 31+ minutes (or manually set lastVisit to 31 min ago)
+8. Visit test site
+9. Check visitCount
+   - **Expected:** `visitCount: 2`
+   - **Expected:** Onboarding NOT shown (returning user)
+
+**Result:** ☐ PASS ☐ FAIL
+
+---
+
+## Utility Commands
+
+### Inspect localStorage
+```javascript
+// Get full metadata
+JSON.parse(localStorage.getItem('guideai_user_metadata'))
+
+// Get just visitCount
+const data = JSON.parse(localStorage.getItem('guideai_user_metadata'))
+console.log('visitCount:', data.metadata.visitCount)
+
+// Get sessionId
+const data = JSON.parse(localStorage.getItem('guideai_user_metadata'))
+console.log('sessionId:', data.metadata.sessionId)
+```
+
+### Manually Set visitCount
+```javascript
+const data = JSON.parse(localStorage.getItem('guideai_user_metadata'))
+data.metadata.visitCount = 5
+localStorage.setItem('guideai_user_metadata', JSON.stringify(data))
+location.reload()
+```
+
+### Simulate 31 Minutes Ago
+```javascript
+const data = JSON.parse(localStorage.getItem('guideai_user_metadata'))
+data.metadata.lastVisit = Date.now() - (31 * 60 * 1000)
+localStorage.setItem('guideai_user_metadata', JSON.stringify(data))
+location.reload() // visitCount should increment
+```
+
+### Force Visit Increment
+```javascript
+window.GuideAI.metadata.trackVisitManually()
+```
+
+### Clear All Data
+```javascript
+localStorage.clear()
+sessionStorage.clear()
+location.reload()
+```
+
+---
+
+## Summary Checklist
+
+After completing all tests, verify these scenarios PASS:
+
+- [ ] **Cross-Browser:** Chrome → Firefox = visitCount resets to 1
+- [ ] **Incognito Mode:** Always treated as first-time user (visitCount = 1)
+- [ ] **Mobile → Desktop:** Separate visitCount on different devices
+- [ ] **Clear Data:** Clearing browser data resets visitCount
+- [ ] **Same Browser, Multiple Sessions (< 30 min):** visitCount unchanged
+- [ ] **Same Browser, Multiple Sessions (> 30 min):** visitCount increments
+- [ ] **Multiple Tabs:** visitCount shared via localStorage
+- [ ] **Login Flow:** Login correctly increments visitCount
+- [ ] **First-Time User Detection:** `visitCount === 1` correctly identifies new users
+
+---
+
+## Test Results Summary
+
+| Test | Status | Notes |
+|------|--------|-------|
+| Cross-Browser (Chrome → Firefox) | ☐ PASS ☐ FAIL | |
+| Incognito Mode | ☐ PASS ☐ FAIL | |
+| Desktop → Mobile | ☐ PASS ☐ FAIL | |
+| Clear Browser Data | ☐ PASS ☐ FAIL | |
+| Same Session (< 30 min) | ☐ PASS ☐ FAIL | |
+| New Session (> 30 min) | ☐ PASS ☐ FAIL | |
+| Multiple Tabs | ☐ PASS ☐ FAIL | |
+| Login Flow | ☐ PASS ☐ FAIL | |
+| First-Time User Detection | ☐ PASS ☐ FAIL | |
+
+**Date Tested:** __________  
+**Tester Name:** __________  
+**Browser Versions Tested:**
+- Chrome: __________
+- Firefox: __________
+- Safari: __________
+- Mobile: __________
+
+---
+
+## Troubleshooting
+
+### visitCount not incrementing after 30+ minutes
+- Check that `trackVisits: true` in GuideAI config
+- Verify `sessionTimeout` is set to 30 * 60 * 1000 (default)
+- Check console for errors
+
+### visitCount incrementing on every page load
+- Check if localStorage is disabled in browser
+- Verify localStorage is not being cleared by extensions
+- Check for errors in browser console
+
+### Different visitCount in different tabs
+- This should NOT happen - localStorage is shared
+- If this occurs, check for localStorage corruption
+- Clear all data and retest
+
+---
+
+## Conclusion
+
+These manual tests complement the automated unit/integration tests and validate that visitCount behaves correctly in real-world scenarios. The current implementation is **"good enough"** for the POC if all tests pass, acknowledging that users will be treated as first-time users when:
+1. Switching browsers
+2. Using incognito mode
+3. Switching devices
+4. Clearing browser data
+