guideai-app 0.3.5 → 0.4.2-1

package/API_SESSIONID_TESTING.md

@@ -0,0 +1,215 @@
+# API SessionID Implementation - Testing Guide
+
+## ✅ Implementation Complete
+
+All metadata update methods now include `sessionId` in their data payloads to comply with backend validation requirements.
+
+## What Changed
+
+### UserMetadataTracker Updates
+All 5 methods that call `addPendingUpdate()` now include `sessionId` in the data object:
+
+1. ✅ **updateUserInfo()** - Line ~138
+2. ✅ **trackLogin()** - Line ~173  
+3. ✅ **trackVisitIfNewSession()** - Line ~211
+4. ✅ **trackVisitManually()** - Line ~274
+5. ✅ **trackCustomEvent()** - Line ~311
+
+### Event Tracking Status
+⚠️ **EventTracker removed** - Event tracking has been removed from the frontend package.
+
+## Testing Instructions
+
+### 1. Deploy/Test the Updated Package
+
+```bash
+# In testsite or wherever you're testing
+npm install ../guide-ai-package
+# or if already linked
+npm run dev
+```
+
+### 2. Open Browser DevTools
+
+**Chrome/Firefox:**
+- Press `F12` or `Cmd+Option+I` (Mac) / `Ctrl+Shift+I` (Windows)
+- Go to **Network** tab
+- Filter by: `metadata-updates` and `events`
+
+### 3. Test /metadata-updates Endpoint
+
+#### Trigger Metadata Updates:
+- **Visit tracking**: Refresh the page (should trigger visit)
+- **Login tracking**: Call `window.GuideAI.metadata.trackLogin()`
+- **User info**: Call `window.GuideAI.metadata.updateUserInfo({ email: 'test@example.com' })`
+
+#### Verify Request Payload:
+Click on the `/metadata-updates` request in Network tab → **Payload** tab:
+
+```json
+{
+  "organizationKey": "your-org-key",
+  "updates": [
+    {
+      "type": "visit",
+      "timestamp": 1234567890,
+      "data": {
+        "sessionId": "550e8400-e29b-41d4-a716-446655440000",  // ✅ MUST BE PRESENT
+        "firstVisit": 1234567890,
+        "lastVisit": 1234567890,
+        "visitCount": 1
+      }
+    }
+  ],
+  "batchTimestamp": 1234567890,
+  "updateCount": 1
+}
+```
+
+#### Expected Response:
+- ✅ **Status: 200** (Success)
+- ❌ **Status: 400** (If sessionId is missing - should NOT happen)
+
+### 4. Test /events Endpoint
+
+#### Trigger Events:
+- Click around the page
+- Focus on input fields
+- Submit forms
+- Navigate between pages
+
+#### Verify Request Payload:
+Click on the `/events` request in Network tab → **Payload** tab:
+
+```json
+{
+  "organizationKey": "your-org-key",
+  "events": [
+    {
+      "type": "click",
+      "timestamp": 1234567890,
+      "url": "https://example.com/page",
+      "sessionId": "550e8400-e29b-41d4-a716-446655440000",  // ✅ MUST BE PRESENT
+      "tagName": "BUTTON",
+      "className": "btn-primary",
+      "deviceType": "desktop",
+      "userAgent": "Mozilla/5.0..."
+    }
+  ],
+  "batchTimestamp": 1234567890,
+  "eventCount": 1
+}
+```
+
+#### Expected Response:
+- ✅ **Status: 200** (Success)
+- ❌ **Status: 400** (If sessionId is missing - should NOT happen)
+
+## Validation Checklist
+
+### /metadata-updates
+- [ ] sessionId appears in every `updates[].data` object
+- [ ] sessionId is a valid UUID format
+- [ ] sessionId matches the one in sessionStorage
+- [ ] API returns 200 (not 400)
+- [ ] Backend logs show no sessionId warnings
+
+### /events  
+- [ ] sessionId appears in every event object (at event level)
+- [ ] sessionId is a valid UUID format
+- [ ] sessionId matches the one in sessionStorage
+- [ ] API returns 200 (not 400)
+- [ ] Backend logs show no sessionId warnings
+
+### Cross-Request Consistency
+- [ ] Same sessionId across all events in same tab
+- [ ] Same sessionId across all metadata updates in same tab
+- [ ] Different sessionId in different browser tabs
+- [ ] New sessionId after closing and reopening tab
+
+## Common Issues & Solutions
+
+### Issue: 400 Error - "sessionId is required"
+**Cause**: sessionId is undefined or missing from data object  
+**Solution**: 
+1. Check sessionStorage has `guideai_session_id`
+2. Check `this.metadata.sessionId` is set in UserMetadataTracker
+3. Verify build was successful
+
+### Issue: sessionId is "undefined" string
+**Cause**: sessionId not initialized before first update  
+**Solution**: Ensure `init()` is called before any tracking methods
+
+### Issue: sessionId changes during session
+**Cause**: sessionStorage being cleared  
+**Solution**: Check for code that clears sessionStorage incorrectly
+
+## Testing Commands
+
+Open browser console and run:
+
+```javascript
+// Check current session ID
+console.log('Session ID:', sessionStorage.getItem('guideai_session_id'));
+
+// Check metadata tracker
+console.log('Metadata:', window.GuideAI?.metadata?.getMetadata());
+
+// Manually trigger login (to test metadata updates)
+window.GuideAI?.metadata?.trackLogin({ userId: 'test-123', email: 'test@example.com' });
+
+// Manually trigger custom event
+window.GuideAI?.metadata?.trackCustomEvent('test_event', { key: 'value' });
+
+// Check pending updates
+window.GuideAI?.metadata?.syncMetadata();
+```
+
+## Backend Validation
+
+Your backend should now:
+- ✅ Accept requests with sessionId in correct locations
+- ✅ Return 200 for valid requests
+- ✅ Return 400 if sessionId is missing (with helpful error message)
+- ✅ Log warnings if email/userId are missing (but still accept)
+
+## Success Criteria
+
+### All Must Pass:
+1. ✅ No 400 errors from /metadata-updates
+2. ✅ No 400 errors from /events  
+3. ✅ sessionId appears in all API calls
+4. ✅ sessionId is consistent within same browser tab
+5. ✅ sessionId format is valid UUID
+6. ✅ Backend accepts and processes all requests
+
+## Next Steps After Testing
+
+Once testing confirms everything works:
+
+1. **Commit the changes:**
+   ```bash
+   git add guide-ai-package/src/metric/metadata-tracker.tsx
+   git commit -m "feat: Add sessionId to metadata-updates API calls
+   
+   - Include sessionId in all MetadataUpdate.data objects
+   - Complies with backend validation requirements
+   - Fixes 400 errors from missing sessionId field"
+   ```
+
+2. **Push to your branch:**
+   ```bash
+   git push origin improvement/api-integration
+   ```
+
+3. **Create PR** with test results
+
+## Questions or Issues?
+
+If you encounter any problems during testing:
+- Check the browser console for errors
+- Check the Network tab for full request/response
+- Verify sessionStorage has `guideai_session_id`
+- Ensure you rebuilt and reloaded the package
+
+