@plasius/analytics 1.3.0 → 1.3.2
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 +9 -0
- package/dist/index.cjs +7 -7
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +3 -159
- package/dist/index.d.ts +3 -159
- package/dist/index.js +4 -4
- package/dist/index.js.map +1 -1
- package/dist/metrics-B7L9phdM.d.cts +159 -0
- package/dist/metrics-B7L9phdM.d.ts +159 -0
- package/dist/metrics.cjs +123 -0
- package/dist/metrics.cjs.map +1 -0
- package/dist/metrics.d.cts +1 -0
- package/dist/metrics.d.ts +1 -0
- package/dist/metrics.js +97 -0
- package/dist/metrics.js.map +1 -0
- package/package.json +7 -1
package/dist/index.d.cts
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import { S as SemanticJourneyEventDefinition, a as SemanticJourneyCatalogOptions, b as SemanticJourneyCatalog, c as SemanticJourneyEventInput, V as ValidatedSemanticJourneyEventInput, d as SemanticJourneyContext, e as SemanticJourneyTraceFlags, f as SemanticJourneyTraceContext, g as SEMANTIC_JOURNEY_STRICT_POLICY_VERSION, h as SemanticJourneyOutcome, i as SemanticJourneyCatalogue, j as SemanticJourneyEvent } from './metrics-B7L9phdM.cjs';
|
|
2
|
+
export { k as SemanticJourneyAttributeDefinition, l as SemanticJourneyAttributeValue, m as SemanticJourneyBooleanAttributeDefinition, n as SemanticJourneyCategory, o as SemanticJourneyEnumAttributeDefinition, p as SemanticJourneyEventId, q as SemanticJourneyId, r as SemanticJourneyModality, s as SemanticJourneyNumberAttributeDefinition, t as SemanticJourneyPhase, u as SemanticJourneyPrivacyMetadata, v as SemanticJourneyProducerId, w as SemanticJourneySpanId, x as SemanticJourneyTarget, y as SemanticJourneyTraceId, U as USEFUL_METRIC_EVENT_DEFINITIONS, z as projectUsefulMetric } from './metrics-B7L9phdM.cjs';
|
|
1
3
|
import * as react from 'react';
|
|
2
4
|
import { ReactNode } from 'react';
|
|
3
5
|
|
|
@@ -161,145 +163,6 @@ declare function createFrontendAnalyticsClient(config: ChannelPinnedConfig): Loc
|
|
|
161
163
|
declare function createBackendAnalyticsClient(config: ChannelPinnedConfig): LocalSpaceAnalyticsClient;
|
|
162
164
|
declare function createNoopLocalSpaceAnalyticsClient(source?: string, channel?: AnalyticsChannel): LocalSpaceAnalyticsClient;
|
|
163
165
|
|
|
164
|
-
/** A cryptographically random, episode-scoped journey identifier. */
|
|
165
|
-
type SemanticJourneyId = string;
|
|
166
|
-
/** A W3C-compatible trace identifier. */
|
|
167
|
-
type SemanticJourneyTraceId = string;
|
|
168
|
-
/** A W3C-compatible span identifier. */
|
|
169
|
-
type SemanticJourneySpanId = string;
|
|
170
|
-
/** A cryptographically random semantic event identifier. */
|
|
171
|
-
type SemanticJourneyEventId = string;
|
|
172
|
-
/** A cryptographically random, runtime-local producer identifier. */
|
|
173
|
-
type SemanticJourneyProducerId = string;
|
|
174
|
-
/** Package-owned strict privacy policy version used by every v2 event/batch. */
|
|
175
|
-
declare const SEMANTIC_JOURNEY_STRICT_POLICY_VERSION: "strict.v1";
|
|
176
|
-
/** The bounded categories understood by semantic journey reconstruction. */
|
|
177
|
-
type SemanticJourneyCategory = "interaction" | "navigation" | "request" | "command" | "state" | "presentation" | "dependency" | "error";
|
|
178
|
-
/** The lifecycle phase represented by a semantic event. */
|
|
179
|
-
type SemanticJourneyPhase = "intent" | "start" | "progress" | "end" | "effect";
|
|
180
|
-
/** The bounded outcome represented by a semantic event. */
|
|
181
|
-
type SemanticJourneyOutcome = "unknown" | "success" | "failure" | "cancelled" | "denied";
|
|
182
|
-
/** A privacy-safe interaction modality. */
|
|
183
|
-
type SemanticJourneyModality = "pointer" | "keyboard" | "touch" | "voice" | "gesture" | "system";
|
|
184
|
-
/** A catalogue-controlled semantic target. It never contains DOM-derived text. */
|
|
185
|
-
interface SemanticJourneyTarget {
|
|
186
|
-
readonly type: string;
|
|
187
|
-
readonly id: string;
|
|
188
|
-
}
|
|
189
|
-
/** The only value kinds admitted to semantic event attributes. */
|
|
190
|
-
type SemanticJourneyAttributeValue = boolean | number | string;
|
|
191
|
-
/** Privacy evidence attached to every accepted semantic event. */
|
|
192
|
-
interface SemanticJourneyPrivacyMetadata {
|
|
193
|
-
readonly mode: "strict";
|
|
194
|
-
readonly policyVersion: typeof SEMANTIC_JOURNEY_STRICT_POLICY_VERSION;
|
|
195
|
-
readonly droppedAttributeCount: number;
|
|
196
|
-
}
|
|
197
|
-
/**
|
|
198
|
-
* Version 2 semantic evidence. This is additive to the legacy
|
|
199
|
-
* `LocalSpaceAnalyticsEvent` contract and intentionally contains no arbitrary
|
|
200
|
-
* context object.
|
|
201
|
-
*/
|
|
202
|
-
interface SemanticJourneyEvent {
|
|
203
|
-
readonly schemaVersion: "2.0";
|
|
204
|
-
readonly eventId: SemanticJourneyEventId;
|
|
205
|
-
readonly journeyId: SemanticJourneyId;
|
|
206
|
-
readonly traceId: SemanticJourneyTraceId;
|
|
207
|
-
readonly spanId: SemanticJourneySpanId;
|
|
208
|
-
readonly parentSpanId?: SemanticJourneySpanId;
|
|
209
|
-
readonly causedByEventId?: SemanticJourneyEventId;
|
|
210
|
-
readonly producerId: SemanticJourneyProducerId;
|
|
211
|
-
readonly producerSequence: number;
|
|
212
|
-
readonly occurredAtEpochMs: number;
|
|
213
|
-
readonly source: string;
|
|
214
|
-
readonly channel: "frontend" | "backend";
|
|
215
|
-
readonly runtime: "browser" | "server";
|
|
216
|
-
readonly name: string;
|
|
217
|
-
readonly category: SemanticJourneyCategory;
|
|
218
|
-
readonly phase: SemanticJourneyPhase;
|
|
219
|
-
readonly outcome: SemanticJourneyOutcome;
|
|
220
|
-
readonly modality?: SemanticJourneyModality;
|
|
221
|
-
readonly target?: SemanticJourneyTarget;
|
|
222
|
-
readonly attributes: Readonly<Record<string, SemanticJourneyAttributeValue>>;
|
|
223
|
-
readonly privacy: SemanticJourneyPrivacyMetadata;
|
|
224
|
-
}
|
|
225
|
-
/** Input accepted by the strict semantic catalogue validator. */
|
|
226
|
-
interface SemanticJourneyEventInput {
|
|
227
|
-
name: string;
|
|
228
|
-
category: SemanticJourneyCategory;
|
|
229
|
-
phase: SemanticJourneyPhase;
|
|
230
|
-
outcome: SemanticJourneyOutcome;
|
|
231
|
-
modality?: SemanticJourneyModality;
|
|
232
|
-
target?: SemanticJourneyTarget;
|
|
233
|
-
attributes?: Readonly<Record<string, unknown>>;
|
|
234
|
-
}
|
|
235
|
-
/** A normalized input proven to conform to one catalogue definition. */
|
|
236
|
-
interface ValidatedSemanticJourneyEventInput {
|
|
237
|
-
name: string;
|
|
238
|
-
category: SemanticJourneyCategory;
|
|
239
|
-
phase: SemanticJourneyPhase;
|
|
240
|
-
outcome: SemanticJourneyOutcome;
|
|
241
|
-
modality?: SemanticJourneyModality;
|
|
242
|
-
target?: SemanticJourneyTarget;
|
|
243
|
-
attributes: Readonly<Record<string, SemanticJourneyAttributeValue>>;
|
|
244
|
-
droppedAttributeCount: 0;
|
|
245
|
-
}
|
|
246
|
-
/** A registered, bounded enum attribute. */
|
|
247
|
-
interface SemanticJourneyEnumAttributeDefinition {
|
|
248
|
-
type: "enum";
|
|
249
|
-
values: readonly string[];
|
|
250
|
-
}
|
|
251
|
-
/** A registered boolean attribute. */
|
|
252
|
-
interface SemanticJourneyBooleanAttributeDefinition {
|
|
253
|
-
type: "boolean";
|
|
254
|
-
}
|
|
255
|
-
/** A registered number with mandatory finite lower and upper bounds. */
|
|
256
|
-
interface SemanticJourneyNumberAttributeDefinition {
|
|
257
|
-
type: "number";
|
|
258
|
-
min: number;
|
|
259
|
-
max: number;
|
|
260
|
-
integer?: boolean;
|
|
261
|
-
}
|
|
262
|
-
/** The closed set of supported catalogue attribute definitions. */
|
|
263
|
-
type SemanticJourneyAttributeDefinition = SemanticJourneyEnumAttributeDefinition | SemanticJourneyBooleanAttributeDefinition | SemanticJourneyNumberAttributeDefinition;
|
|
264
|
-
/** A semantic event definition registered by application developers. */
|
|
265
|
-
interface SemanticJourneyEventDefinition {
|
|
266
|
-
readonly category: SemanticJourneyCategory;
|
|
267
|
-
readonly attributes?: Readonly<Record<string, SemanticJourneyAttributeDefinition>>;
|
|
268
|
-
readonly targets?: readonly SemanticJourneyTarget[];
|
|
269
|
-
readonly effects?: readonly string[];
|
|
270
|
-
}
|
|
271
|
-
/** Reviewed, immutable dimensions shared by one semantic catalogue. */
|
|
272
|
-
interface SemanticJourneyCatalogOptions {
|
|
273
|
-
readonly sources: readonly string[];
|
|
274
|
-
}
|
|
275
|
-
/** An immutable, validated collection of semantic event definitions. */
|
|
276
|
-
interface SemanticJourneyCatalog {
|
|
277
|
-
readonly sources: readonly string[];
|
|
278
|
-
readonly definitions: Readonly<Record<string, Readonly<SemanticJourneyEventDefinition>>>;
|
|
279
|
-
}
|
|
280
|
-
/** British-English compatibility alias for `SemanticJourneyCatalog`. */
|
|
281
|
-
type SemanticJourneyCatalogue = SemanticJourneyCatalog;
|
|
282
|
-
/** W3C trace flags supported by the strict journey context parser. */
|
|
283
|
-
type SemanticJourneyTraceFlags = "00" | "01";
|
|
284
|
-
/** A strictly parsed W3C traceparent context. */
|
|
285
|
-
interface SemanticJourneyTraceContext {
|
|
286
|
-
version: "00";
|
|
287
|
-
traceId: SemanticJourneyTraceId;
|
|
288
|
-
spanId: SemanticJourneySpanId;
|
|
289
|
-
traceFlags: SemanticJourneyTraceFlags;
|
|
290
|
-
}
|
|
291
|
-
/**
|
|
292
|
-
* Local causal context. `journeyId` is private to the runtime and is never
|
|
293
|
-
* included by traceparent formatting.
|
|
294
|
-
*/
|
|
295
|
-
interface SemanticJourneyContext {
|
|
296
|
-
journeyId: SemanticJourneyId;
|
|
297
|
-
traceId: SemanticJourneyTraceId;
|
|
298
|
-
spanId: SemanticJourneySpanId;
|
|
299
|
-
parentSpanId?: SemanticJourneySpanId;
|
|
300
|
-
traceFlags: SemanticJourneyTraceFlags;
|
|
301
|
-
}
|
|
302
|
-
|
|
303
166
|
/** Stable, non-sensitive validation reason codes suitable for control flow. */
|
|
304
167
|
type SemanticJourneyValidationErrorCode = "invalid-input" | "invalid-token";
|
|
305
168
|
/** An intentionally generic error that never embeds rejected input. */
|
|
@@ -434,25 +297,6 @@ declare class SemanticJourneyAggregateStore {
|
|
|
434
297
|
private sortedCounters;
|
|
435
298
|
}
|
|
436
299
|
|
|
437
|
-
/**
|
|
438
|
-
* Fixed useful-metric catalogue entries for host catalogue composition and
|
|
439
|
-
* collector allowlists. Buckets are part of event names so they survive the
|
|
440
|
-
* existing aggregate wire format, which deliberately does not carry attributes.
|
|
441
|
-
* This is not a collector or sender and has no browser/network side effects.
|
|
442
|
-
*/
|
|
443
|
-
declare const USEFUL_METRIC_EVENT_DEFINITIONS: Readonly<Record<string, Readonly<SemanticJourneyEventDefinition>>>;
|
|
444
|
-
/**
|
|
445
|
-
* Projects one observation into a catalogue-controlled, identity-free event.
|
|
446
|
-
* Accepts exactly { metric } for a counter or { metric, value } for a duration
|
|
447
|
-
* in milliseconds (CLS is unitless). Rejects unknown/extra fields, accessors,
|
|
448
|
-
* invalid numbers and legacy raw NFR payloads without reflecting their values.
|
|
449
|
-
*
|
|
450
|
-
* The host evaluates remote enablement, bounds observation frequency, tracks
|
|
451
|
-
* this result with its semantic client, and owns disposal. Episode observations
|
|
452
|
-
* are anonymous in-memory activity counts, never unique users or sessions.
|
|
453
|
-
*/
|
|
454
|
-
declare function projectUsefulMetric(input: unknown): SemanticJourneyEventInput | null;
|
|
455
|
-
|
|
456
300
|
/** Bounded aggregate request passed to an injectable transport. */
|
|
457
301
|
interface SemanticJourneyAggregateTransportRequest {
|
|
458
302
|
readonly endpoint: string;
|
|
@@ -693,4 +537,4 @@ interface TrackInteractionDetails extends Omit<LocalSpaceAnalyticsEvent, "compon
|
|
|
693
537
|
}
|
|
694
538
|
declare function useComponentInteractionTracker(component: string, baseContext?: AnalyticsContext): (action: string, details?: TrackInteractionDetails) => void;
|
|
695
539
|
|
|
696
|
-
export { type AnalyticsChannel, type AnalyticsContext, type AnalyticsContextValue, type AnalyticsErrorSeverity, type AnalyticsEventKind, AnalyticsProvider, type AnalyticsProviderProps, type AnalyticsRuntime, type AnalyticsTransport, type AnalyticsTransportRequest, type CreateSemanticJourneyAggregateBatchOptions, type DefaultSemanticJourneyTransportOptions, type LocalSpaceAnalyticsClient, type LocalSpaceAnalyticsConfig, type LocalSpaceAnalyticsErrorDetails, type LocalSpaceAnalyticsEvent, type LocalSpaceAnalyticsRecord, type LocalSpaceErrorReportInput, type LocalSpaceErrorReportingConfig, type LocalSpaceIssueReport, type LocalSpaceIssueThresholdTrigger, type RandomByteSource, type ResolvedLocalSpaceAnalyticsConfig, type ResolvedLocalSpaceErrorReportingConfig, SEMANTIC_JOURNEY_AGGREGATE_SCHEMA_VERSION, SEMANTIC_JOURNEY_RECEIPT_HEADER, SEMANTIC_JOURNEY_RECEIPT_MAX_BYTES, SEMANTIC_JOURNEY_RECEIPT_MAX_COUNT, SEMANTIC_JOURNEY_RECEIPT_VERSION, SEMANTIC_JOURNEY_STRICT_POLICY_VERSION, type SemanticJourneyAggregateBatch, type SemanticJourneyAggregateCounter, type SemanticJourneyAggregateSnapshot, SemanticJourneyAggregateStore, type SemanticJourneyAggregateStoreOptions, type SemanticJourneyAggregateTransport, type SemanticJourneyAggregateTransportRequest, type
|
|
540
|
+
export { type AnalyticsChannel, type AnalyticsContext, type AnalyticsContextValue, type AnalyticsErrorSeverity, type AnalyticsEventKind, AnalyticsProvider, type AnalyticsProviderProps, type AnalyticsRuntime, type AnalyticsTransport, type AnalyticsTransportRequest, type CreateSemanticJourneyAggregateBatchOptions, type DefaultSemanticJourneyTransportOptions, type LocalSpaceAnalyticsClient, type LocalSpaceAnalyticsConfig, type LocalSpaceAnalyticsErrorDetails, type LocalSpaceAnalyticsEvent, type LocalSpaceAnalyticsRecord, type LocalSpaceErrorReportInput, type LocalSpaceErrorReportingConfig, type LocalSpaceIssueReport, type LocalSpaceIssueThresholdTrigger, type RandomByteSource, type ResolvedLocalSpaceAnalyticsConfig, type ResolvedLocalSpaceErrorReportingConfig, SEMANTIC_JOURNEY_AGGREGATE_SCHEMA_VERSION, SEMANTIC_JOURNEY_RECEIPT_HEADER, SEMANTIC_JOURNEY_RECEIPT_MAX_BYTES, SEMANTIC_JOURNEY_RECEIPT_MAX_COUNT, SEMANTIC_JOURNEY_RECEIPT_VERSION, SEMANTIC_JOURNEY_STRICT_POLICY_VERSION, type SemanticJourneyAggregateBatch, type SemanticJourneyAggregateCounter, type SemanticJourneyAggregateSnapshot, SemanticJourneyAggregateStore, type SemanticJourneyAggregateStoreOptions, type SemanticJourneyAggregateTransport, type SemanticJourneyAggregateTransportRequest, type SemanticJourneyBrowserObserverConfig, SemanticJourneyCatalog, SemanticJourneyCatalogOptions, SemanticJourneyCatalogue, type SemanticJourneyClient, type SemanticJourneyClientConfig, type SemanticJourneyCompleteness, type SemanticJourneyConsequenceReceipt, SemanticJourneyContext, type SemanticJourneyDropReason, SemanticJourneyEvent, SemanticJourneyEventDefinition, SemanticJourneyEventInput, type SemanticJourneyEvidence, type SemanticJourneyEvidenceCode, SemanticJourneyOutcome, type SemanticJourneyReplay, type SemanticJourneyRequestLink, type SemanticJourneyRetryDelay, type SemanticJourneyStep, SemanticJourneyTraceContext, SemanticJourneyTraceFlags, type SemanticJourneyTrackOptions, SemanticJourneyTransportError, type SemanticJourneyTransportErrorCode, SemanticJourneyValidationError, type SemanticJourneyValidationErrorCode, type TrackInteractionDetails, ValidatedSemanticJourneyEventInput, assertSemanticSource, assertSemanticToken, createBackendAnalyticsClient, createChildJourneyContext, createDefaultSemanticJourneyAggregateTransport, createEventId, createFrontendAnalyticsClient, createJourneyContext, createJourneyId, createLocalSpaceAnalyticsClient, createNoopLocalSpaceAnalyticsClient, createProducerId, createRequestJourneyContext, createSecureRandomHex, createSemanticJourneyClient, createSpanId, createTraceId, defineJourneyEvent, defineSemanticJourneyCatalog, formatTraceparent, getJourneyEventDefinition, isEventId, isJourneyId, isJourneyToken, isProducerId, isSecureSemanticJourneyEndpoint, isSemanticSource, isSemanticToken, isSpanId, isTraceId, observeSemanticJourneyInteractions, parseSemanticJourneyReceipts, parseTraceparent, reconstructSemanticJourney, serializeSemanticJourneyReceipts, useAnalytics, useComponentInteractionTracker, validateSemanticJourneyEventInput };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import { S as SemanticJourneyEventDefinition, a as SemanticJourneyCatalogOptions, b as SemanticJourneyCatalog, c as SemanticJourneyEventInput, V as ValidatedSemanticJourneyEventInput, d as SemanticJourneyContext, e as SemanticJourneyTraceFlags, f as SemanticJourneyTraceContext, g as SEMANTIC_JOURNEY_STRICT_POLICY_VERSION, h as SemanticJourneyOutcome, i as SemanticJourneyCatalogue, j as SemanticJourneyEvent } from './metrics-B7L9phdM.js';
|
|
2
|
+
export { k as SemanticJourneyAttributeDefinition, l as SemanticJourneyAttributeValue, m as SemanticJourneyBooleanAttributeDefinition, n as SemanticJourneyCategory, o as SemanticJourneyEnumAttributeDefinition, p as SemanticJourneyEventId, q as SemanticJourneyId, r as SemanticJourneyModality, s as SemanticJourneyNumberAttributeDefinition, t as SemanticJourneyPhase, u as SemanticJourneyPrivacyMetadata, v as SemanticJourneyProducerId, w as SemanticJourneySpanId, x as SemanticJourneyTarget, y as SemanticJourneyTraceId, U as USEFUL_METRIC_EVENT_DEFINITIONS, z as projectUsefulMetric } from './metrics-B7L9phdM.js';
|
|
1
3
|
import * as react from 'react';
|
|
2
4
|
import { ReactNode } from 'react';
|
|
3
5
|
|
|
@@ -161,145 +163,6 @@ declare function createFrontendAnalyticsClient(config: ChannelPinnedConfig): Loc
|
|
|
161
163
|
declare function createBackendAnalyticsClient(config: ChannelPinnedConfig): LocalSpaceAnalyticsClient;
|
|
162
164
|
declare function createNoopLocalSpaceAnalyticsClient(source?: string, channel?: AnalyticsChannel): LocalSpaceAnalyticsClient;
|
|
163
165
|
|
|
164
|
-
/** A cryptographically random, episode-scoped journey identifier. */
|
|
165
|
-
type SemanticJourneyId = string;
|
|
166
|
-
/** A W3C-compatible trace identifier. */
|
|
167
|
-
type SemanticJourneyTraceId = string;
|
|
168
|
-
/** A W3C-compatible span identifier. */
|
|
169
|
-
type SemanticJourneySpanId = string;
|
|
170
|
-
/** A cryptographically random semantic event identifier. */
|
|
171
|
-
type SemanticJourneyEventId = string;
|
|
172
|
-
/** A cryptographically random, runtime-local producer identifier. */
|
|
173
|
-
type SemanticJourneyProducerId = string;
|
|
174
|
-
/** Package-owned strict privacy policy version used by every v2 event/batch. */
|
|
175
|
-
declare const SEMANTIC_JOURNEY_STRICT_POLICY_VERSION: "strict.v1";
|
|
176
|
-
/** The bounded categories understood by semantic journey reconstruction. */
|
|
177
|
-
type SemanticJourneyCategory = "interaction" | "navigation" | "request" | "command" | "state" | "presentation" | "dependency" | "error";
|
|
178
|
-
/** The lifecycle phase represented by a semantic event. */
|
|
179
|
-
type SemanticJourneyPhase = "intent" | "start" | "progress" | "end" | "effect";
|
|
180
|
-
/** The bounded outcome represented by a semantic event. */
|
|
181
|
-
type SemanticJourneyOutcome = "unknown" | "success" | "failure" | "cancelled" | "denied";
|
|
182
|
-
/** A privacy-safe interaction modality. */
|
|
183
|
-
type SemanticJourneyModality = "pointer" | "keyboard" | "touch" | "voice" | "gesture" | "system";
|
|
184
|
-
/** A catalogue-controlled semantic target. It never contains DOM-derived text. */
|
|
185
|
-
interface SemanticJourneyTarget {
|
|
186
|
-
readonly type: string;
|
|
187
|
-
readonly id: string;
|
|
188
|
-
}
|
|
189
|
-
/** The only value kinds admitted to semantic event attributes. */
|
|
190
|
-
type SemanticJourneyAttributeValue = boolean | number | string;
|
|
191
|
-
/** Privacy evidence attached to every accepted semantic event. */
|
|
192
|
-
interface SemanticJourneyPrivacyMetadata {
|
|
193
|
-
readonly mode: "strict";
|
|
194
|
-
readonly policyVersion: typeof SEMANTIC_JOURNEY_STRICT_POLICY_VERSION;
|
|
195
|
-
readonly droppedAttributeCount: number;
|
|
196
|
-
}
|
|
197
|
-
/**
|
|
198
|
-
* Version 2 semantic evidence. This is additive to the legacy
|
|
199
|
-
* `LocalSpaceAnalyticsEvent` contract and intentionally contains no arbitrary
|
|
200
|
-
* context object.
|
|
201
|
-
*/
|
|
202
|
-
interface SemanticJourneyEvent {
|
|
203
|
-
readonly schemaVersion: "2.0";
|
|
204
|
-
readonly eventId: SemanticJourneyEventId;
|
|
205
|
-
readonly journeyId: SemanticJourneyId;
|
|
206
|
-
readonly traceId: SemanticJourneyTraceId;
|
|
207
|
-
readonly spanId: SemanticJourneySpanId;
|
|
208
|
-
readonly parentSpanId?: SemanticJourneySpanId;
|
|
209
|
-
readonly causedByEventId?: SemanticJourneyEventId;
|
|
210
|
-
readonly producerId: SemanticJourneyProducerId;
|
|
211
|
-
readonly producerSequence: number;
|
|
212
|
-
readonly occurredAtEpochMs: number;
|
|
213
|
-
readonly source: string;
|
|
214
|
-
readonly channel: "frontend" | "backend";
|
|
215
|
-
readonly runtime: "browser" | "server";
|
|
216
|
-
readonly name: string;
|
|
217
|
-
readonly category: SemanticJourneyCategory;
|
|
218
|
-
readonly phase: SemanticJourneyPhase;
|
|
219
|
-
readonly outcome: SemanticJourneyOutcome;
|
|
220
|
-
readonly modality?: SemanticJourneyModality;
|
|
221
|
-
readonly target?: SemanticJourneyTarget;
|
|
222
|
-
readonly attributes: Readonly<Record<string, SemanticJourneyAttributeValue>>;
|
|
223
|
-
readonly privacy: SemanticJourneyPrivacyMetadata;
|
|
224
|
-
}
|
|
225
|
-
/** Input accepted by the strict semantic catalogue validator. */
|
|
226
|
-
interface SemanticJourneyEventInput {
|
|
227
|
-
name: string;
|
|
228
|
-
category: SemanticJourneyCategory;
|
|
229
|
-
phase: SemanticJourneyPhase;
|
|
230
|
-
outcome: SemanticJourneyOutcome;
|
|
231
|
-
modality?: SemanticJourneyModality;
|
|
232
|
-
target?: SemanticJourneyTarget;
|
|
233
|
-
attributes?: Readonly<Record<string, unknown>>;
|
|
234
|
-
}
|
|
235
|
-
/** A normalized input proven to conform to one catalogue definition. */
|
|
236
|
-
interface ValidatedSemanticJourneyEventInput {
|
|
237
|
-
name: string;
|
|
238
|
-
category: SemanticJourneyCategory;
|
|
239
|
-
phase: SemanticJourneyPhase;
|
|
240
|
-
outcome: SemanticJourneyOutcome;
|
|
241
|
-
modality?: SemanticJourneyModality;
|
|
242
|
-
target?: SemanticJourneyTarget;
|
|
243
|
-
attributes: Readonly<Record<string, SemanticJourneyAttributeValue>>;
|
|
244
|
-
droppedAttributeCount: 0;
|
|
245
|
-
}
|
|
246
|
-
/** A registered, bounded enum attribute. */
|
|
247
|
-
interface SemanticJourneyEnumAttributeDefinition {
|
|
248
|
-
type: "enum";
|
|
249
|
-
values: readonly string[];
|
|
250
|
-
}
|
|
251
|
-
/** A registered boolean attribute. */
|
|
252
|
-
interface SemanticJourneyBooleanAttributeDefinition {
|
|
253
|
-
type: "boolean";
|
|
254
|
-
}
|
|
255
|
-
/** A registered number with mandatory finite lower and upper bounds. */
|
|
256
|
-
interface SemanticJourneyNumberAttributeDefinition {
|
|
257
|
-
type: "number";
|
|
258
|
-
min: number;
|
|
259
|
-
max: number;
|
|
260
|
-
integer?: boolean;
|
|
261
|
-
}
|
|
262
|
-
/** The closed set of supported catalogue attribute definitions. */
|
|
263
|
-
type SemanticJourneyAttributeDefinition = SemanticJourneyEnumAttributeDefinition | SemanticJourneyBooleanAttributeDefinition | SemanticJourneyNumberAttributeDefinition;
|
|
264
|
-
/** A semantic event definition registered by application developers. */
|
|
265
|
-
interface SemanticJourneyEventDefinition {
|
|
266
|
-
readonly category: SemanticJourneyCategory;
|
|
267
|
-
readonly attributes?: Readonly<Record<string, SemanticJourneyAttributeDefinition>>;
|
|
268
|
-
readonly targets?: readonly SemanticJourneyTarget[];
|
|
269
|
-
readonly effects?: readonly string[];
|
|
270
|
-
}
|
|
271
|
-
/** Reviewed, immutable dimensions shared by one semantic catalogue. */
|
|
272
|
-
interface SemanticJourneyCatalogOptions {
|
|
273
|
-
readonly sources: readonly string[];
|
|
274
|
-
}
|
|
275
|
-
/** An immutable, validated collection of semantic event definitions. */
|
|
276
|
-
interface SemanticJourneyCatalog {
|
|
277
|
-
readonly sources: readonly string[];
|
|
278
|
-
readonly definitions: Readonly<Record<string, Readonly<SemanticJourneyEventDefinition>>>;
|
|
279
|
-
}
|
|
280
|
-
/** British-English compatibility alias for `SemanticJourneyCatalog`. */
|
|
281
|
-
type SemanticJourneyCatalogue = SemanticJourneyCatalog;
|
|
282
|
-
/** W3C trace flags supported by the strict journey context parser. */
|
|
283
|
-
type SemanticJourneyTraceFlags = "00" | "01";
|
|
284
|
-
/** A strictly parsed W3C traceparent context. */
|
|
285
|
-
interface SemanticJourneyTraceContext {
|
|
286
|
-
version: "00";
|
|
287
|
-
traceId: SemanticJourneyTraceId;
|
|
288
|
-
spanId: SemanticJourneySpanId;
|
|
289
|
-
traceFlags: SemanticJourneyTraceFlags;
|
|
290
|
-
}
|
|
291
|
-
/**
|
|
292
|
-
* Local causal context. `journeyId` is private to the runtime and is never
|
|
293
|
-
* included by traceparent formatting.
|
|
294
|
-
*/
|
|
295
|
-
interface SemanticJourneyContext {
|
|
296
|
-
journeyId: SemanticJourneyId;
|
|
297
|
-
traceId: SemanticJourneyTraceId;
|
|
298
|
-
spanId: SemanticJourneySpanId;
|
|
299
|
-
parentSpanId?: SemanticJourneySpanId;
|
|
300
|
-
traceFlags: SemanticJourneyTraceFlags;
|
|
301
|
-
}
|
|
302
|
-
|
|
303
166
|
/** Stable, non-sensitive validation reason codes suitable for control flow. */
|
|
304
167
|
type SemanticJourneyValidationErrorCode = "invalid-input" | "invalid-token";
|
|
305
168
|
/** An intentionally generic error that never embeds rejected input. */
|
|
@@ -434,25 +297,6 @@ declare class SemanticJourneyAggregateStore {
|
|
|
434
297
|
private sortedCounters;
|
|
435
298
|
}
|
|
436
299
|
|
|
437
|
-
/**
|
|
438
|
-
* Fixed useful-metric catalogue entries for host catalogue composition and
|
|
439
|
-
* collector allowlists. Buckets are part of event names so they survive the
|
|
440
|
-
* existing aggregate wire format, which deliberately does not carry attributes.
|
|
441
|
-
* This is not a collector or sender and has no browser/network side effects.
|
|
442
|
-
*/
|
|
443
|
-
declare const USEFUL_METRIC_EVENT_DEFINITIONS: Readonly<Record<string, Readonly<SemanticJourneyEventDefinition>>>;
|
|
444
|
-
/**
|
|
445
|
-
* Projects one observation into a catalogue-controlled, identity-free event.
|
|
446
|
-
* Accepts exactly { metric } for a counter or { metric, value } for a duration
|
|
447
|
-
* in milliseconds (CLS is unitless). Rejects unknown/extra fields, accessors,
|
|
448
|
-
* invalid numbers and legacy raw NFR payloads without reflecting their values.
|
|
449
|
-
*
|
|
450
|
-
* The host evaluates remote enablement, bounds observation frequency, tracks
|
|
451
|
-
* this result with its semantic client, and owns disposal. Episode observations
|
|
452
|
-
* are anonymous in-memory activity counts, never unique users or sessions.
|
|
453
|
-
*/
|
|
454
|
-
declare function projectUsefulMetric(input: unknown): SemanticJourneyEventInput | null;
|
|
455
|
-
|
|
456
300
|
/** Bounded aggregate request passed to an injectable transport. */
|
|
457
301
|
interface SemanticJourneyAggregateTransportRequest {
|
|
458
302
|
readonly endpoint: string;
|
|
@@ -693,4 +537,4 @@ interface TrackInteractionDetails extends Omit<LocalSpaceAnalyticsEvent, "compon
|
|
|
693
537
|
}
|
|
694
538
|
declare function useComponentInteractionTracker(component: string, baseContext?: AnalyticsContext): (action: string, details?: TrackInteractionDetails) => void;
|
|
695
539
|
|
|
696
|
-
export { type AnalyticsChannel, type AnalyticsContext, type AnalyticsContextValue, type AnalyticsErrorSeverity, type AnalyticsEventKind, AnalyticsProvider, type AnalyticsProviderProps, type AnalyticsRuntime, type AnalyticsTransport, type AnalyticsTransportRequest, type CreateSemanticJourneyAggregateBatchOptions, type DefaultSemanticJourneyTransportOptions, type LocalSpaceAnalyticsClient, type LocalSpaceAnalyticsConfig, type LocalSpaceAnalyticsErrorDetails, type LocalSpaceAnalyticsEvent, type LocalSpaceAnalyticsRecord, type LocalSpaceErrorReportInput, type LocalSpaceErrorReportingConfig, type LocalSpaceIssueReport, type LocalSpaceIssueThresholdTrigger, type RandomByteSource, type ResolvedLocalSpaceAnalyticsConfig, type ResolvedLocalSpaceErrorReportingConfig, SEMANTIC_JOURNEY_AGGREGATE_SCHEMA_VERSION, SEMANTIC_JOURNEY_RECEIPT_HEADER, SEMANTIC_JOURNEY_RECEIPT_MAX_BYTES, SEMANTIC_JOURNEY_RECEIPT_MAX_COUNT, SEMANTIC_JOURNEY_RECEIPT_VERSION, SEMANTIC_JOURNEY_STRICT_POLICY_VERSION, type SemanticJourneyAggregateBatch, type SemanticJourneyAggregateCounter, type SemanticJourneyAggregateSnapshot, SemanticJourneyAggregateStore, type SemanticJourneyAggregateStoreOptions, type SemanticJourneyAggregateTransport, type SemanticJourneyAggregateTransportRequest, type
|
|
540
|
+
export { type AnalyticsChannel, type AnalyticsContext, type AnalyticsContextValue, type AnalyticsErrorSeverity, type AnalyticsEventKind, AnalyticsProvider, type AnalyticsProviderProps, type AnalyticsRuntime, type AnalyticsTransport, type AnalyticsTransportRequest, type CreateSemanticJourneyAggregateBatchOptions, type DefaultSemanticJourneyTransportOptions, type LocalSpaceAnalyticsClient, type LocalSpaceAnalyticsConfig, type LocalSpaceAnalyticsErrorDetails, type LocalSpaceAnalyticsEvent, type LocalSpaceAnalyticsRecord, type LocalSpaceErrorReportInput, type LocalSpaceErrorReportingConfig, type LocalSpaceIssueReport, type LocalSpaceIssueThresholdTrigger, type RandomByteSource, type ResolvedLocalSpaceAnalyticsConfig, type ResolvedLocalSpaceErrorReportingConfig, SEMANTIC_JOURNEY_AGGREGATE_SCHEMA_VERSION, SEMANTIC_JOURNEY_RECEIPT_HEADER, SEMANTIC_JOURNEY_RECEIPT_MAX_BYTES, SEMANTIC_JOURNEY_RECEIPT_MAX_COUNT, SEMANTIC_JOURNEY_RECEIPT_VERSION, SEMANTIC_JOURNEY_STRICT_POLICY_VERSION, type SemanticJourneyAggregateBatch, type SemanticJourneyAggregateCounter, type SemanticJourneyAggregateSnapshot, SemanticJourneyAggregateStore, type SemanticJourneyAggregateStoreOptions, type SemanticJourneyAggregateTransport, type SemanticJourneyAggregateTransportRequest, type SemanticJourneyBrowserObserverConfig, SemanticJourneyCatalog, SemanticJourneyCatalogOptions, SemanticJourneyCatalogue, type SemanticJourneyClient, type SemanticJourneyClientConfig, type SemanticJourneyCompleteness, type SemanticJourneyConsequenceReceipt, SemanticJourneyContext, type SemanticJourneyDropReason, SemanticJourneyEvent, SemanticJourneyEventDefinition, SemanticJourneyEventInput, type SemanticJourneyEvidence, type SemanticJourneyEvidenceCode, SemanticJourneyOutcome, type SemanticJourneyReplay, type SemanticJourneyRequestLink, type SemanticJourneyRetryDelay, type SemanticJourneyStep, SemanticJourneyTraceContext, SemanticJourneyTraceFlags, type SemanticJourneyTrackOptions, SemanticJourneyTransportError, type SemanticJourneyTransportErrorCode, SemanticJourneyValidationError, type SemanticJourneyValidationErrorCode, type TrackInteractionDetails, ValidatedSemanticJourneyEventInput, assertSemanticSource, assertSemanticToken, createBackendAnalyticsClient, createChildJourneyContext, createDefaultSemanticJourneyAggregateTransport, createEventId, createFrontendAnalyticsClient, createJourneyContext, createJourneyId, createLocalSpaceAnalyticsClient, createNoopLocalSpaceAnalyticsClient, createProducerId, createRequestJourneyContext, createSecureRandomHex, createSemanticJourneyClient, createSpanId, createTraceId, defineJourneyEvent, defineSemanticJourneyCatalog, formatTraceparent, getJourneyEventDefinition, isEventId, isJourneyId, isJourneyToken, isProducerId, isSecureSemanticJourneyEndpoint, isSemanticSource, isSemanticToken, isSpanId, isTraceId, observeSemanticJourneyInteractions, parseSemanticJourneyReceipts, parseTraceparent, reconstructSemanticJourney, serializeSemanticJourneyReceipts, useAnalytics, useComponentInteractionTracker, validateSemanticJourneyEventInput };
|
package/dist/index.js
CHANGED
|
@@ -1946,7 +1946,7 @@ var duration = (category) => ({
|
|
|
1946
1946
|
buckets: durationBuckets,
|
|
1947
1947
|
maximum: 864e5
|
|
1948
1948
|
});
|
|
1949
|
-
var metrics = {
|
|
1949
|
+
var metrics = /* @__PURE__ */ (() => ({
|
|
1950
1950
|
"page.load": duration("presentation"),
|
|
1951
1951
|
"route.ready": duration("presentation"),
|
|
1952
1952
|
"world.ready": duration("presentation"),
|
|
@@ -1985,11 +1985,11 @@ var metrics = {
|
|
|
1985
1985
|
"error.resource": { category: "error", outcome: "failure" },
|
|
1986
1986
|
"error.render": { category: "error", outcome: "failure" },
|
|
1987
1987
|
"error.unhandled": { category: "error", outcome: "failure" }
|
|
1988
|
-
};
|
|
1989
|
-
var USEFUL_METRIC_EVENT_DEFINITIONS = Object.freeze(Object.fromEntries(Object.entries(metrics).flatMap(([metric, definition]) => {
|
|
1988
|
+
}))();
|
|
1989
|
+
var USEFUL_METRIC_EVENT_DEFINITIONS = /* @__PURE__ */ (() => Object.freeze(Object.fromEntries(Object.entries(metrics).flatMap(([metric, definition]) => {
|
|
1990
1990
|
const names = definition.buckets ? definition.buckets.map(([, bucket]) => `metric.${metric}.${bucket}`) : [`metric.${metric}`];
|
|
1991
1991
|
return names.map((name) => [name, Object.freeze({ category: definition.category })]);
|
|
1992
|
-
})));
|
|
1992
|
+
}))))();
|
|
1993
1993
|
function projectUsefulMetric(input) {
|
|
1994
1994
|
try {
|
|
1995
1995
|
if (typeof input !== "object" || input === null || Array.isArray(input)) return null;
|