@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/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 SemanticJourneyAttributeDefinition, type SemanticJourneyAttributeValue, type SemanticJourneyBooleanAttributeDefinition, type SemanticJourneyBrowserObserverConfig, type SemanticJourneyCatalog, type SemanticJourneyCatalogOptions, type SemanticJourneyCatalogue, type SemanticJourneyCategory, type SemanticJourneyClient, type SemanticJourneyClientConfig, type SemanticJourneyCompleteness, type SemanticJourneyConsequenceReceipt, type SemanticJourneyContext, type SemanticJourneyDropReason, type SemanticJourneyEnumAttributeDefinition, type SemanticJourneyEvent, type SemanticJourneyEventDefinition, type SemanticJourneyEventId, type SemanticJourneyEventInput, type SemanticJourneyEvidence, type SemanticJourneyEvidenceCode, type SemanticJourneyId, type SemanticJourneyModality, type SemanticJourneyNumberAttributeDefinition, type SemanticJourneyOutcome, type SemanticJourneyPhase, type SemanticJourneyPrivacyMetadata, type SemanticJourneyProducerId, type SemanticJourneyReplay, type SemanticJourneyRequestLink, type SemanticJourneyRetryDelay, type SemanticJourneySpanId, type SemanticJourneyStep, type SemanticJourneyTarget, type SemanticJourneyTraceContext, type SemanticJourneyTraceFlags, type SemanticJourneyTraceId, type SemanticJourneyTrackOptions, SemanticJourneyTransportError, type SemanticJourneyTransportErrorCode, SemanticJourneyValidationError, type SemanticJourneyValidationErrorCode, type TrackInteractionDetails, USEFUL_METRIC_EVENT_DEFINITIONS, type 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, projectUsefulMetric, reconstructSemanticJourney, serializeSemanticJourneyReceipts, useAnalytics, useComponentInteractionTracker, validateSemanticJourneyEventInput };
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 SemanticJourneyAttributeDefinition, type SemanticJourneyAttributeValue, type SemanticJourneyBooleanAttributeDefinition, type SemanticJourneyBrowserObserverConfig, type SemanticJourneyCatalog, type SemanticJourneyCatalogOptions, type SemanticJourneyCatalogue, type SemanticJourneyCategory, type SemanticJourneyClient, type SemanticJourneyClientConfig, type SemanticJourneyCompleteness, type SemanticJourneyConsequenceReceipt, type SemanticJourneyContext, type SemanticJourneyDropReason, type SemanticJourneyEnumAttributeDefinition, type SemanticJourneyEvent, type SemanticJourneyEventDefinition, type SemanticJourneyEventId, type SemanticJourneyEventInput, type SemanticJourneyEvidence, type SemanticJourneyEvidenceCode, type SemanticJourneyId, type SemanticJourneyModality, type SemanticJourneyNumberAttributeDefinition, type SemanticJourneyOutcome, type SemanticJourneyPhase, type SemanticJourneyPrivacyMetadata, type SemanticJourneyProducerId, type SemanticJourneyReplay, type SemanticJourneyRequestLink, type SemanticJourneyRetryDelay, type SemanticJourneySpanId, type SemanticJourneyStep, type SemanticJourneyTarget, type SemanticJourneyTraceContext, type SemanticJourneyTraceFlags, type SemanticJourneyTraceId, type SemanticJourneyTrackOptions, SemanticJourneyTransportError, type SemanticJourneyTransportErrorCode, SemanticJourneyValidationError, type SemanticJourneyValidationErrorCode, type TrackInteractionDetails, USEFUL_METRIC_EVENT_DEFINITIONS, type 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, projectUsefulMetric, reconstructSemanticJourney, serializeSemanticJourneyReceipts, useAnalytics, useComponentInteractionTracker, validateSemanticJourneyEventInput };
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;