@plasius/analytics 1.3.3 → 1.4.0

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
@@ -37,7 +37,12 @@ Local-space analytics primitives for browser apps and reusable React components.
37
37
  npm install @plasius/analytics
38
38
  ```
39
39
 
40
- ## Core API
40
+ ## Legacy Core API
41
+
42
+ The API below is a compatibility surface, not the privacy-safe event NFR path.
43
+ New integrations should use the opt-in semantic client and approved aggregate
44
+ contract below. The Plasius site is retiring unrestricted legacy ingestion;
45
+ do not forward these legacy records to the semantic endpoint.
41
46
 
42
47
  ```ts
43
48
  import {
@@ -83,6 +88,79 @@ await backendAnalytics.flush();
83
88
 
84
89
  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.
85
90
 
91
+ ### Reviewed aggregate views (2.1)
92
+
93
+ For screen/action or world/metric breakdowns, explicitly opt in to catalogue-owned
94
+ projections. An ordinary event attribute is **not** automatically uploaded:
95
+
96
+ ```ts
97
+ import {
98
+ defineSemanticJourneyCatalog,
99
+ defineSemanticJourneyAggregatePolicy,
100
+ createSemanticJourneyAggregateValidator,
101
+ createSemanticJourneyClient,
102
+ } from "@plasius/analytics";
103
+
104
+ const catalogue = defineSemanticJourneyCatalog({
105
+ "ui.control.activate": {
106
+ category: "interaction",
107
+ attributes: {
108
+ screen: { type: "enum", values: ["home", "generator"] },
109
+ action: { type: "enum", values: ["select", "retry"] },
110
+ },
111
+ },
112
+ }, { sources: ["plasius.site"] });
113
+ const aggregatePolicy = defineSemanticJourneyAggregatePolicy(catalogue, {
114
+ bindings: [{ source: "plasius.site", channel: "frontend", runtime: "browser" }],
115
+ projections: {
116
+ "ui.control.activate": { "screen-action": ["screen", "action"] },
117
+ },
118
+ });
119
+ declare const analyticsConsentAndRemotePermission: boolean;
120
+ const client = createSemanticJourneyClient({
121
+ catalogue, aggregatePolicy, source: "plasius.site", channel: "frontend", runtime: "browser",
122
+ enabled: analyticsConsentAndRemotePermission,
123
+ aggregateEndpoint: "/api/analytics/semantic-aggregates",
124
+ });
125
+ client.track({ name: "ui.control.activate", category: "interaction", phase: "intent",
126
+ outcome: "success", attributes: { screen: "home", action: "select" } });
127
+
128
+ // Receiving hosts compile the same policy, then validate a bounded JSON body.
129
+ const validateAggregate = createSemanticJourneyAggregateValidator(aggregatePolicy);
130
+ // On consent withdrawal: client.destroy(); (discard, cancel; no flush).
131
+ ```
132
+
133
+ Each 2.1 counter contains a `view` and its exact registered enum `dimensions`.
134
+ The independent `total` view has no dimensions. Never sum across views. Missing
135
+ optional attributes omit their view; unknown fields/values reject the event.
136
+ Numeric/boolean attributes, private context, targets and causal IDs are not
137
+ projectable. Hosts must review the meaning of their finite tokens; grammar is
138
+ not an anonymity guarantee.
139
+
140
+ Policies allow at most 128 exact producer bindings, eight views per event, four
141
+ enum dimensions per view and 4,096 value combinations per view. The generated
142
+ validator rejects duplicate counter keys, unsafe counts, unknown fields and
143
+ payloads above 500 rows/64 KiB; bound HTTP reads before parsing as well.
144
+
145
+ The shared client keeps one retry snapshot and original observation hours, with
146
+ projected rows bounded by its queue count/byte/age settings (default 1,000 rows,
147
+ 1 MiB, 30 minutes). To preserve consistency, expiry discards the whole pending
148
+ hour when its oldest row expires, potentially discarding newer observations in
149
+ that hour. Drops are reported, not silently retained. Projected clients default
150
+ to two 48-KiB batches per 60-second flush, two retries and five-second deadlines.
151
+ Client construction rejects `aggregateMaxBytes` if the budget cannot fit every
152
+ approved single-row envelope, including maximum safe counters and diagnostics.
153
+ Standalone projected stores validate their `maxBatchBytes` ceiling the same way;
154
+ per-batch overrides must fit the policy and remain within that ceiling.
155
+ No policy means unchanged strict 2.0 output. The validator explicitly supports
156
+ strict 2.0 input; it does not accept unrestricted legacy event packets.
157
+
158
+ Hosts own consent and remote controls, storage/retention, deduplication,
159
+ processing and low-volume report suppression. Shipping this SDK enables none of
160
+ those production behaviours. See [projection design](docs/design/aggregate-projections.md).
161
+
162
+ ### Local causal capture and receipts
163
+
86
164
  The client defaults to disabled. Hosts must pass the remotely resolved `platform.analytics.semantic-journeys.enabled` decision:
87
165
 
88
166
  ```ts