@tracelog/lib 0.7.3 → 0.8.1

package/README.md

@@ -162,11 +162,13 @@ Each event contains a base structure with type-specific data:
 - `page_url`: Current page URL
 - `timestamp`: Unix timestamp in milliseconds
 - `referrer`: Document referrer (optional)
+- `from_page_url`: Previous page URL (optional)
 - `utm`: UTM parameters (source, medium, campaign, term, content)
 
 **Event-specific data:**
 
 - **`PAGE_VIEW`**: Navigation tracking
+  - `page_view.referrer`: Page referrer
   - `page_view.title`: Page title
   - `page_view.pathname`: URL pathname
   - `page_view.search`: Query string
@@ -176,7 +178,7 @@ Each event contains a base structure with type-specific data:
   - `click_data.x/y`: Viewport coordinates
   - `click_data.relativeX/relativeY`: Element-relative position
   - `click_data.tag/id/class`: Element identifiers
-  - `click_data.text/href/title`: Element content
+  - `click_data.text/href/title/alt`: Element content
   - `click_data.role/ariaLabel`: Accessibility attributes
   - `click_data.dataAttributes`: Data attributes
 
@@ -247,10 +249,46 @@ tracelog.init();
 console.log(tracelog.isInitialized()); // true
 ```
 
+## Error Handling & Event Persistence
+
+TraceLog uses a hybrid sendBeacon/fetch strategy with intelligent error handling:
+
+### Send Strategy
+
+- **Async events (normal operation)**: Uses `fetch` with full HTTP error detection
+  - Detects 4xx/5xx errors and handles them appropriately
+  - Returns detailed error information for debugging
+
+- **Sync events (page unload, session end)**: Uses `sendBeacon` for guaranteed delivery
+  - Browser queues the request even if the page is closing
+  - No HTTP error feedback available (limitation of sendBeacon API)
+
+### Error Handling
+
+- **Permanent errors (4xx)**: Events are discarded immediately
+  - `400 Bad Request`, `403 Forbidden`, `404 Not Found` → No persistence, no retry
+  - Prevents infinite retry loops for configuration issues (e.g., excluded IPs, invalid projects)
+
+- **Temporary errors (5xx, network failures)**: Events persist in localStorage
+  - `500`, `502`, `503`, `504` → Events saved for recovery on next page load
+  - Network failures → Events persist and recover automatically
+  - No automatic in-session retries to avoid performance impact
+
+- **Event expiry**: Persisted events expire after 2 hours to prevent stale data recovery
+
+### sendBeacon Limitations
+
+When using `sendBeacon` (page unload scenarios):
+- Browser only returns `true` (queued) or `false` (rejected)
+- No visibility into HTTP response codes (403, 500, etc.)
+- Events failing server-side validation won't be detected
+- Accepted events are persisted as fallback and cleared on next successful session
+
 ## Troubleshooting
 
 - **Session issues**: Check localStorage availability and session timeout
 - **Memory usage**: Reduce `sessionTimeout`, lower `samplingRate`, call `destroy()` on cleanup
+- **Events not sending**: Check browser console for `PermanentError` logs indicating 4xx errors
 - **CI failures**: Verify Playwright installation and Node.js ≥20
 
 ## Development & Contributing