@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 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