@plasius/analytics 1.1.17 → 1.2.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 +76 -0
- package/dist/index.cjs +2677 -2
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +482 -1
- package/dist/index.d.ts +482 -1
- package/dist/index.js +2635 -1
- package/dist/index.js.map +1 -1
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -20,6 +20,9 @@ Local-space analytics primitives for browser apps and reusable React components.
|
|
|
20
20
|
- Trigger threshold callbacks for automated remediation workflows
|
|
21
21
|
- Browser-lifecycle flush support (`visibilitychange`, `pagehide`, `sendBeacon`)
|
|
22
22
|
- React provider and hooks for component-level event instrumentation
|
|
23
|
+
- Local-private semantic journeys that join frontend intent to backend consequence
|
|
24
|
+
- Aggregate-only adaptive batching with bounded queues, retries, and idempotency
|
|
25
|
+
- Deterministic replay-style inference with explicit causal gaps and uncertainty
|
|
23
26
|
|
|
24
27
|
## Install
|
|
25
28
|
|
|
@@ -69,6 +72,78 @@ await frontendAnalytics.flush();
|
|
|
69
72
|
await backendAnalytics.flush();
|
|
70
73
|
```
|
|
71
74
|
|
|
75
|
+
## Local-Private Semantic Journeys
|
|
76
|
+
|
|
77
|
+
Semantic journeys are an additive v2 API. The individual story remains in bounded, memory-only client state; `flush()` sends only coarse event-name/outcome counters. Aggregate payloads contain no journey, trace, event, producer, session, device, IP-derived, or user identifier.
|
|
78
|
+
|
|
79
|
+
The client defaults to disabled. Hosts must pass the remotely resolved `platform.analytics.semantic-journeys.enabled` decision:
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
import {
|
|
83
|
+
SEMANTIC_JOURNEY_RECEIPT_HEADER,
|
|
84
|
+
createSemanticJourneyClient,
|
|
85
|
+
defineSemanticJourneyCatalog,
|
|
86
|
+
} from "@plasius/analytics";
|
|
87
|
+
|
|
88
|
+
const catalogue = defineSemanticJourneyCatalog({
|
|
89
|
+
"checkout.submit": { category: "interaction" },
|
|
90
|
+
"checkout.create": { category: "request" },
|
|
91
|
+
"order.create": {
|
|
92
|
+
category: "command",
|
|
93
|
+
effects: ["policy-denied"],
|
|
94
|
+
},
|
|
95
|
+
}, { sources: ["site"] });
|
|
96
|
+
|
|
97
|
+
declare const semanticJourneysEnabled: boolean;
|
|
98
|
+
|
|
99
|
+
const journeys = createSemanticJourneyClient({
|
|
100
|
+
catalogue,
|
|
101
|
+
source: "site",
|
|
102
|
+
channel: "frontend",
|
|
103
|
+
runtime: "browser",
|
|
104
|
+
enabled: semanticJourneysEnabled,
|
|
105
|
+
aggregateEndpoint: "/api/analytics/semantic-aggregates",
|
|
106
|
+
});
|
|
107
|
+
|
|
108
|
+
const intent = journeys.track({
|
|
109
|
+
name: "checkout.submit",
|
|
110
|
+
category: "interaction",
|
|
111
|
+
phase: "intent",
|
|
112
|
+
outcome: "unknown",
|
|
113
|
+
modality: "keyboard",
|
|
114
|
+
});
|
|
115
|
+
|
|
116
|
+
const request = journeys.beginRequest(
|
|
117
|
+
{
|
|
118
|
+
name: "checkout.create",
|
|
119
|
+
category: "request",
|
|
120
|
+
phase: "start",
|
|
121
|
+
outcome: "unknown",
|
|
122
|
+
},
|
|
123
|
+
{ causedByEventId: intent?.eventId },
|
|
124
|
+
);
|
|
125
|
+
|
|
126
|
+
if (request) {
|
|
127
|
+
const response = await fetch("/api/orders", {
|
|
128
|
+
method: "POST",
|
|
129
|
+
headers: { traceparent: request.traceparent },
|
|
130
|
+
});
|
|
131
|
+
request.complete(response.headers.get(SEMANTIC_JOURNEY_RECEIPT_HEADER));
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
const replay = journeys.reconstruct();
|
|
135
|
+
await journeys.flush();
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Backends produce bounded, catalogue-validated consequence receipts with `serializeSemanticJourneyReceipts`. Each outbound request gets a fresh `traceparent`; neither the private journey ID nor an episode-wide trace crosses the boundary. Browser-wide semantic coverage is available through `observeSemanticJourneyInteractions`, which requires an explicit `enabled: true` rollout decision and observes only registered `data-plasius-event`, `data-plasius-target-type`, and `data-plasius-target-id` annotations without reading DOM text, form values, URLs, keys, pointer coordinates, or arbitrary attributes.
|
|
139
|
+
|
|
140
|
+
Catalogue names, sources, targets, effects, and enum values must be reviewed developer-owned semantic classes, never application/entity identifiers or user-provided content. Sources are admitted by the catalogue-wide allowlist; targets and backend effects are admitted by per-event allowlists. The privacy policy version is the package-owned `strict.v1` constant and is not caller-configurable. Unknown or unregistered fields reject the whole event without echoing rejected values. Aggregate Fetch transport omits credentials and referrers and rejects redirects. Uploaded individual journeys are intentionally not supported by this local-private client; any future controlled-server replay mode must be separately gated and governed as pseudonymous Personal Data.
|
|
141
|
+
|
|
142
|
+
Aggregate transport accepts RFC 9110 `Retry-After` integer delay-seconds and
|
|
143
|
+
HTTP dates, capped at five minutes; malformed numeric forms are ignored.
|
|
144
|
+
Runtime rollout inherits `governance.rfc-compliance-remediation.enabled`, with
|
|
145
|
+
the disabled state retaining the prior transport only during migration.
|
|
146
|
+
|
|
72
147
|
## Crash Reporting
|
|
73
148
|
|
|
74
149
|
```ts
|
|
@@ -195,6 +270,7 @@ npm run test:coverage
|
|
|
195
270
|
## Governance
|
|
196
271
|
|
|
197
272
|
- ADRs: [docs/adrs](./docs/adrs)
|
|
273
|
+
- Semantic journey design: [docs/design/privacy-safe-causal-journeys.md](./docs/design/privacy-safe-causal-journeys.md)
|
|
198
274
|
- Security policy: [SECURITY.md](./SECURITY.md)
|
|
199
275
|
- Legal docs: [legal](./legal)
|
|
200
276
|
|