@plasius/analytics 1.0.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
@@ -14,6 +14,10 @@ Local-space analytics primitives for browser apps and reusable React components.
14
14
 
15
15
  - Queue interaction events locally (in-memory + `localStorage` backup)
16
16
  - Flush analytics batches to a configurable endpoint
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
17
21
  - Browser-lifecycle flush support (`visibilitychange`, `pagehide`, `sendBeacon`)
18
22
  - React provider and hooks for component-level event instrumentation
19
23
 
@@ -26,9 +30,12 @@ npm install @plasius/analytics
26
30
  ## Core API
27
31
 
28
32
  ```ts
29
- import { createLocalSpaceAnalyticsClient } from "@plasius/analytics";
33
+ import {
34
+ createBackendAnalyticsClient,
35
+ createFrontendAnalyticsClient,
36
+ } from "@plasius/analytics";
30
37
 
31
- const analytics = createLocalSpaceAnalyticsClient({
38
+ const frontendAnalytics = createFrontendAnalyticsClient({
32
39
  source: "sharedcomponents",
33
40
  endpoint: "https://analytics.example.com/collect",
34
41
  defaultContext: {
@@ -36,7 +43,12 @@ const analytics = createLocalSpaceAnalyticsClient({
36
43
  },
37
44
  });
38
45
 
39
- analytics.track({
46
+ const backendAnalytics = createBackendAnalyticsClient({
47
+ source: "plasius-ltd-site-api",
48
+ endpoint: "https://analytics.example.com/collect",
49
+ });
50
+
51
+ frontendAnalytics.track({
40
52
  component: "Header",
41
53
  action: "nav_click",
42
54
  label: "About",
@@ -46,9 +58,54 @@ analytics.track({
46
58
  },
47
59
  });
48
60
 
49
- await analytics.flush();
61
+ backendAnalytics.track({
62
+ component: "VideoWorker",
63
+ action: "job_completed",
64
+ requestId: "req-123",
65
+ context: { worker: "render" },
66
+ });
67
+
68
+ await frontendAnalytics.flush();
69
+ await backendAnalytics.flush();
70
+ ```
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();
50
101
  ```
51
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
+
52
109
  ## React API
53
110
 
54
111
  ```tsx
@@ -75,6 +132,7 @@ function SaveButton() {
75
132
  <AnalyticsProvider
76
133
  source="sharedcomponents"
77
134
  endpoint="https://analytics.example.com/collect"
135
+ channel="frontend"
78
136
  >
79
137
  <SaveButton />
80
138
  </AnalyticsProvider>;
@@ -87,21 +145,37 @@ function SaveButton() {
87
145
  ```json
88
146
  {
89
147
  "source": "sharedcomponents",
148
+ "channel": "frontend",
149
+ "runtime": "browser",
90
150
  "sentAt": 1735300000000,
91
151
  "events": [
92
152
  {
93
153
  "id": "event_xxx",
94
154
  "source": "sharedcomponents",
155
+ "channel": "frontend",
156
+ "runtime": "browser",
95
157
  "sessionId": "session_xxx",
96
158
  "timestamp": 1735300000000,
159
+ "kind": "error",
97
160
  "component": "Header",
98
- "action": "nav_click",
99
- "label": "About",
100
- "href": "/about",
101
- "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
+ },
102
171
  "context": {
103
- "application": "white-label-portal",
104
- "feature": "navigation"
172
+ "analyticsChannel": "frontend",
173
+ "analyticsRuntime": "browser",
174
+ "feature": "checkout",
175
+ "errorFingerprint": "err_abc123",
176
+ "errorBoundary": "CheckoutBoundary",
177
+ "errorSeverity": "error",
178
+ "errorHandled": true
105
179
  }
106
180
  }
107
181
  ]