@plasius/analytics 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -15,6 +15,9 @@ Local-space analytics primitives for browser apps and reusable React components.
15
15
  - Queue interaction events locally (in-memory + `localStorage` backup)
16
16
  - Flush analytics batches to a configurable endpoint
17
17
  - Support frontend and backend analytics channels simultaneously
18
+ - Report crash/error-boundary events with structured payloads
19
+ - Sanitize error reports to reduce accidental PII leakage
20
+ - Trigger threshold callbacks for automated remediation workflows
18
21
  - Browser-lifecycle flush support (`visibilitychange`, `pagehide`, `sendBeacon`)
19
22
  - React provider and hooks for component-level event instrumentation
20
23
 
@@ -66,6 +69,43 @@ await frontendAnalytics.flush();
66
69
  await backendAnalytics.flush();
67
70
  ```
68
71
 
72
+ ## Crash Reporting
73
+
74
+ ```ts
75
+ import { createFrontendAnalyticsClient } from "@plasius/analytics";
76
+
77
+ const analytics = createFrontendAnalyticsClient({
78
+ source: "sharedcomponents",
79
+ endpoint: "https://analytics.example.com/collect",
80
+ errorReporting: {
81
+ thresholdCount: 5,
82
+ thresholdWindowMs: 300000,
83
+ onThresholdReached: ({ report }) => {
84
+ // Hook into your automation system (ticket/task/alert)
85
+ console.log("error threshold reached", report.fingerprint, report.count);
86
+ },
87
+ },
88
+ });
89
+
90
+ analytics.reportError({
91
+ boundary: "CheckoutBoundary",
92
+ error: new Error("Payment failed"),
93
+ context: {
94
+ feature: "checkout",
95
+ ipAddress: "198.51.100.10",
96
+ sessionToken: "opaque-session-token",
97
+ },
98
+ });
99
+
100
+ const issueReports = analytics.getIssueReports();
101
+ ```
102
+
103
+ Error reporting is secure-by-default. When `secureEndpointOnly` is enabled (default), crash reports are sent only to `https` endpoints (or localhost for development).
104
+ PII/private-data handling for crash payloads is delegated to `@plasius/schema` as the source of truth:
105
+ - crash context is normalized, sensitive keys are identified, and a machine/session identity envelope is built.
106
+ - the identity envelope is passed through schema `prepareForStorage`, which applies field-level hashing/redaction policies before transport.
107
+ - non-sensitive diagnostics remain available as mixed typed fields for debugging.
108
+
69
109
  ## React API
70
110
 
71
111
  ```tsx
@@ -116,17 +156,26 @@ function SaveButton() {
116
156
  "runtime": "browser",
117
157
  "sessionId": "session_xxx",
118
158
  "timestamp": 1735300000000,
159
+ "kind": "error",
119
160
  "component": "Header",
120
- "action": "nav_click",
121
- "requestId": "req-123",
122
- "label": "About",
123
- "href": "/about",
124
- "variant": "desktop",
161
+ "action": "error_boundary_caught",
162
+ "label": "err_abc123",
163
+ "error": {
164
+ "boundary": "CheckoutBoundary",
165
+ "name": "Error",
166
+ "message": "Payment failed",
167
+ "fingerprint": "err_abc123",
168
+ "handled": true,
169
+ "severity": "error"
170
+ },
125
171
  "context": {
126
172
  "analyticsChannel": "frontend",
127
173
  "analyticsRuntime": "browser",
128
- "application": "white-label-portal",
129
- "feature": "navigation"
174
+ "feature": "checkout",
175
+ "errorFingerprint": "err_abc123",
176
+ "errorBoundary": "CheckoutBoundary",
177
+ "errorSeverity": "error",
178
+ "errorHandled": true
130
179
  }
131
180
  }
132
181
  ]