@plasius/analytics 1.1.16 → 1.2.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 +71 -0
- package/dist/index.cjs +2673 -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 +2631 -1
- package/dist/index.js.map +1 -1
- package/package.json +11 -10
package/dist/index.d.cts
CHANGED
|
@@ -161,6 +161,487 @@ declare function createFrontendAnalyticsClient(config: ChannelPinnedConfig): Loc
|
|
|
161
161
|
declare function createBackendAnalyticsClient(config: ChannelPinnedConfig): LocalSpaceAnalyticsClient;
|
|
162
162
|
declare function createNoopLocalSpaceAnalyticsClient(source?: string, channel?: AnalyticsChannel): LocalSpaceAnalyticsClient;
|
|
163
163
|
|
|
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
|
+
/** Stable, non-sensitive validation reason codes suitable for control flow. */
|
|
304
|
+
type SemanticJourneyValidationErrorCode = "invalid-input" | "invalid-token";
|
|
305
|
+
/** An intentionally generic error that never embeds rejected input. */
|
|
306
|
+
declare class SemanticJourneyValidationError extends Error {
|
|
307
|
+
readonly code: SemanticJourneyValidationErrorCode;
|
|
308
|
+
constructor(code: SemanticJourneyValidationErrorCode);
|
|
309
|
+
}
|
|
310
|
+
/** Returns whether a value conforms to the bounded semantic token grammar. */
|
|
311
|
+
declare function isSemanticToken(value: unknown): value is string;
|
|
312
|
+
/** Compatibility alias for `isSemanticToken`. */
|
|
313
|
+
declare const isJourneyToken: typeof isSemanticToken;
|
|
314
|
+
/** Returns whether a source name uses the bounded semantic token grammar. */
|
|
315
|
+
declare const isSemanticSource: typeof isSemanticToken;
|
|
316
|
+
/** Asserts the bounded token grammar without embedding the rejected value. */
|
|
317
|
+
declare function assertSemanticToken(value: unknown, _field?: string): asserts value is string;
|
|
318
|
+
/** Asserts the source token grammar without embedding the rejected value. */
|
|
319
|
+
declare const assertSemanticSource: typeof assertSemanticToken;
|
|
320
|
+
/** Creates an immutable semantic catalogue after validating every definition. */
|
|
321
|
+
declare function defineSemanticJourneyCatalog(definitions: Readonly<Record<string, SemanticJourneyEventDefinition>>, options: SemanticJourneyCatalogOptions): SemanticJourneyCatalog;
|
|
322
|
+
/** Creates a one-event immutable catalogue. */
|
|
323
|
+
declare function defineJourneyEvent(name: string, definition: SemanticJourneyEventDefinition, options: SemanticJourneyCatalogOptions): SemanticJourneyCatalog;
|
|
324
|
+
/** Looks up a registered event definition without accepting invalid tokens. */
|
|
325
|
+
declare function getJourneyEventDefinition(catalogue: SemanticJourneyCatalog, name: unknown): Readonly<SemanticJourneyEventDefinition> | undefined;
|
|
326
|
+
/**
|
|
327
|
+
* Validates and normalizes event input using a fail-closed catalogue policy.
|
|
328
|
+
* Unknown fields and attributes reject the whole input; errors never echo input.
|
|
329
|
+
*/
|
|
330
|
+
declare function validateSemanticJourneyEventInput(catalogue: SemanticJourneyCatalog, input: SemanticJourneyEventInput): ValidatedSemanticJourneyEventInput;
|
|
331
|
+
|
|
332
|
+
/** Injectable cryptographically secure byte source used by ID generators. */
|
|
333
|
+
type RandomByteSource = (byteLength: number) => Uint8Array;
|
|
334
|
+
/**
|
|
335
|
+
* Creates lowercase random hex using global Web Crypto or an injected secure
|
|
336
|
+
* source. Requests are deliberately bounded to prevent accidental allocation.
|
|
337
|
+
*/
|
|
338
|
+
declare function createSecureRandomHex(byteLength: number, randomBytes?: RandomByteSource): string;
|
|
339
|
+
/** Creates a 32-hex, non-zero local journey identifier. */
|
|
340
|
+
declare function createJourneyId(randomBytes?: RandomByteSource): string;
|
|
341
|
+
/** Creates a 32-hex, non-zero W3C trace identifier. */
|
|
342
|
+
declare function createTraceId(randomBytes?: RandomByteSource): string;
|
|
343
|
+
/** Creates a 32-hex, non-zero semantic event identifier. */
|
|
344
|
+
declare function createEventId(randomBytes?: RandomByteSource): string;
|
|
345
|
+
/** Creates a 16-hex, non-zero W3C span identifier. */
|
|
346
|
+
declare function createSpanId(randomBytes?: RandomByteSource): string;
|
|
347
|
+
/** Creates a 16-hex, non-zero runtime producer identifier. */
|
|
348
|
+
declare function createProducerId(randomBytes?: RandomByteSource): string;
|
|
349
|
+
/** Returns whether a value is a valid 32-hex, non-zero journey identifier. */
|
|
350
|
+
declare function isJourneyId(value: unknown): value is string;
|
|
351
|
+
/** Returns whether a value is a valid 32-hex, non-zero trace identifier. */
|
|
352
|
+
declare function isTraceId(value: unknown): value is string;
|
|
353
|
+
/** Returns whether a value is a valid 32-hex, non-zero event identifier. */
|
|
354
|
+
declare function isEventId(value: unknown): value is string;
|
|
355
|
+
/** Returns whether a value is a valid 16-hex, non-zero span identifier. */
|
|
356
|
+
declare function isSpanId(value: unknown): value is string;
|
|
357
|
+
/** Returns whether a value is a valid 16-hex, non-zero producer identifier. */
|
|
358
|
+
declare function isProducerId(value: unknown): value is string;
|
|
359
|
+
/** Creates a new local-private journey and its root trace/span context. */
|
|
360
|
+
declare function createJourneyContext(randomBytes?: RandomByteSource, traceFlags?: SemanticJourneyTraceFlags): SemanticJourneyContext;
|
|
361
|
+
/** Creates a child span while retaining the local journey and trace. */
|
|
362
|
+
declare function createChildJourneyContext(parent: SemanticJourneyContext, randomBytes?: RandomByteSource): SemanticJourneyContext;
|
|
363
|
+
/**
|
|
364
|
+
* Creates a request-scoped trace for an outbound request. Cross-request
|
|
365
|
+
* causality remains local; only this fresh traceparent crosses the boundary.
|
|
366
|
+
*/
|
|
367
|
+
declare function createRequestJourneyContext(parent: SemanticJourneyContext, randomBytes?: RandomByteSource): SemanticJourneyContext;
|
|
368
|
+
/** Formats a strict W3C traceparent without serializing any local journey ID. */
|
|
369
|
+
declare function formatTraceparent(context: Pick<SemanticJourneyTraceContext, "traceId" | "spanId" | "traceFlags">): string;
|
|
370
|
+
/**
|
|
371
|
+
* Strictly parses a version-00 W3C traceparent. Malformed or all-zero inbound
|
|
372
|
+
* identifiers return `null` so callers can safely restart the context.
|
|
373
|
+
*/
|
|
374
|
+
declare function parseTraceparent(value: unknown): SemanticJourneyTraceContext | null;
|
|
375
|
+
|
|
376
|
+
/** Wire schema used by unlinkable semantic aggregate batches. */
|
|
377
|
+
declare const SEMANTIC_JOURNEY_AGGREGATE_SCHEMA_VERSION: "2.0-aggregate";
|
|
378
|
+
/** One low-cardinality event-name/outcome count. */
|
|
379
|
+
interface SemanticJourneyAggregateCounter {
|
|
380
|
+
readonly eventName: string;
|
|
381
|
+
readonly outcome: SemanticJourneyOutcome;
|
|
382
|
+
readonly count: number;
|
|
383
|
+
}
|
|
384
|
+
/** Aggregate-only payload that deliberately contains no causal identifiers. */
|
|
385
|
+
interface SemanticJourneyAggregateBatch {
|
|
386
|
+
readonly schemaVersion: typeof SEMANTIC_JOURNEY_AGGREGATE_SCHEMA_VERSION;
|
|
387
|
+
readonly batchId: string;
|
|
388
|
+
readonly source: string;
|
|
389
|
+
readonly channel: AnalyticsChannel;
|
|
390
|
+
readonly runtime: AnalyticsRuntime;
|
|
391
|
+
readonly timeBucket: string;
|
|
392
|
+
readonly policyVersion: typeof SEMANTIC_JOURNEY_STRICT_POLICY_VERSION;
|
|
393
|
+
readonly dropped: number;
|
|
394
|
+
readonly coalesced: number;
|
|
395
|
+
readonly counters: readonly SemanticJourneyAggregateCounter[];
|
|
396
|
+
}
|
|
397
|
+
/** Current in-memory aggregate state for diagnostics and tests. */
|
|
398
|
+
interface SemanticJourneyAggregateSnapshot {
|
|
399
|
+
readonly dropped: number;
|
|
400
|
+
readonly coalesced: number;
|
|
401
|
+
readonly counters: readonly SemanticJourneyAggregateCounter[];
|
|
402
|
+
}
|
|
403
|
+
/** Immutable dimensions attached to every batch from one aggregate store. */
|
|
404
|
+
interface SemanticJourneyAggregateStoreOptions {
|
|
405
|
+
readonly catalogue: SemanticJourneyCatalog;
|
|
406
|
+
readonly source: string;
|
|
407
|
+
readonly channel: AnalyticsChannel;
|
|
408
|
+
readonly runtime: AnalyticsRuntime;
|
|
409
|
+
}
|
|
410
|
+
/** Count, byte, identity, and time controls for constructing one batch. */
|
|
411
|
+
interface CreateSemanticJourneyAggregateBatchOptions {
|
|
412
|
+
readonly batchId: string;
|
|
413
|
+
readonly nowEpochMs: number;
|
|
414
|
+
readonly maxCounters: number;
|
|
415
|
+
readonly maxBytes: number;
|
|
416
|
+
}
|
|
417
|
+
/**
|
|
418
|
+
* Holds only unlinkable aggregate counters. Individual event and causal
|
|
419
|
+
* identifiers are deliberately not accepted by this store.
|
|
420
|
+
*/
|
|
421
|
+
declare class SemanticJourneyAggregateStore {
|
|
422
|
+
private readonly counters;
|
|
423
|
+
private readonly options;
|
|
424
|
+
private dropped;
|
|
425
|
+
private coalesced;
|
|
426
|
+
constructor(options: SemanticJourneyAggregateStoreOptions);
|
|
427
|
+
record(eventName: string, outcome: SemanticJourneyOutcome, count?: number): void;
|
|
428
|
+
recordDropped(count?: number): void;
|
|
429
|
+
recordCoalesced(count?: number): void;
|
|
430
|
+
snapshot(): SemanticJourneyAggregateSnapshot;
|
|
431
|
+
createBatch(options: CreateSemanticJourneyAggregateBatchOptions): SemanticJourneyAggregateBatch | null;
|
|
432
|
+
acknowledge(batch: SemanticJourneyAggregateBatch): void;
|
|
433
|
+
clear(): void;
|
|
434
|
+
private sortedCounters;
|
|
435
|
+
}
|
|
436
|
+
|
|
437
|
+
/** Bounded aggregate request passed to an injectable transport. */
|
|
438
|
+
interface SemanticJourneyAggregateTransportRequest {
|
|
439
|
+
readonly endpoint: string;
|
|
440
|
+
readonly body: string;
|
|
441
|
+
readonly headers: Readonly<Record<string, string>>;
|
|
442
|
+
readonly signal: AbortSignal;
|
|
443
|
+
readonly keepalive?: boolean;
|
|
444
|
+
}
|
|
445
|
+
/** Transport contract for one unlinkable aggregate batch. */
|
|
446
|
+
type SemanticJourneyAggregateTransport = (request: SemanticJourneyAggregateTransportRequest) => Promise<void>;
|
|
447
|
+
/** Stable transport failure classes that never contain request data. */
|
|
448
|
+
type SemanticJourneyTransportErrorCode = "aborted" | "network_failure" | "rejected";
|
|
449
|
+
/** Generic, bounded aggregate transport failure. */
|
|
450
|
+
declare class SemanticJourneyTransportError extends Error {
|
|
451
|
+
readonly code: SemanticJourneyTransportErrorCode;
|
|
452
|
+
readonly retryable: boolean;
|
|
453
|
+
readonly status?: number | undefined;
|
|
454
|
+
readonly retryAfterMs?: number | undefined;
|
|
455
|
+
constructor(code: SemanticJourneyTransportErrorCode, retryable: boolean, status?: number | undefined, retryAfterMs?: number | undefined);
|
|
456
|
+
}
|
|
457
|
+
/** Returns whether an endpoint is HTTPS, same-origin-relative, or localhost. */
|
|
458
|
+
declare function isSecureSemanticJourneyEndpoint(endpoint: string, baseUrl?: string): boolean;
|
|
459
|
+
/** Dependencies used by the default Fetch-based aggregate transport. */
|
|
460
|
+
interface DefaultSemanticJourneyTransportOptions {
|
|
461
|
+
readonly fetch?: typeof globalThis.fetch;
|
|
462
|
+
readonly baseUrl?: string;
|
|
463
|
+
readonly now?: () => number;
|
|
464
|
+
}
|
|
465
|
+
/** Creates a Fetch transport with TLS enforcement and bounded retry metadata. */
|
|
466
|
+
declare function createDefaultSemanticJourneyAggregateTransport(options?: DefaultSemanticJourneyTransportOptions): SemanticJourneyAggregateTransport;
|
|
467
|
+
|
|
468
|
+
/** Response header carrying bounded semantic backend consequences. */
|
|
469
|
+
declare const SEMANTIC_JOURNEY_RECEIPT_HEADER = "x-plasius-journey-receipt";
|
|
470
|
+
/** Current consequence receipt format version. */
|
|
471
|
+
declare const SEMANTIC_JOURNEY_RECEIPT_VERSION: "1";
|
|
472
|
+
/** Maximum number of consequences permitted in one response header. */
|
|
473
|
+
declare const SEMANTIC_JOURNEY_RECEIPT_MAX_COUNT = 4;
|
|
474
|
+
/** Maximum encoded consequence header size. */
|
|
475
|
+
declare const SEMANTIC_JOURNEY_RECEIPT_MAX_BYTES = 512;
|
|
476
|
+
type ReceiptOutcome = SemanticJourneyEventInput["outcome"];
|
|
477
|
+
type ReceiptPhase = SemanticJourneyEventInput["phase"];
|
|
478
|
+
/** A catalogue-controlled backend consequence safe to return to a client. */
|
|
479
|
+
interface SemanticJourneyConsequenceReceipt {
|
|
480
|
+
readonly version: typeof SEMANTIC_JOURNEY_RECEIPT_VERSION;
|
|
481
|
+
readonly name: string;
|
|
482
|
+
readonly outcome: ReceiptOutcome;
|
|
483
|
+
readonly phase: ReceiptPhase;
|
|
484
|
+
readonly effect: string;
|
|
485
|
+
}
|
|
486
|
+
/**
|
|
487
|
+
* Serializes trusted backend consequence codes into a canonical bounded header.
|
|
488
|
+
* Invalid developer input fails with a generic error that never includes the
|
|
489
|
+
* rejected value.
|
|
490
|
+
*/
|
|
491
|
+
declare function serializeSemanticJourneyReceipts(receipts: readonly SemanticJourneyConsequenceReceipt[], catalogue: SemanticJourneyCatalogue): string;
|
|
492
|
+
/**
|
|
493
|
+
* Parses an untrusted consequence header with all-or-nothing validation.
|
|
494
|
+
* Missing or malformed input returns an empty list and is never reflected in an
|
|
495
|
+
* exception, log message, or result value.
|
|
496
|
+
*/
|
|
497
|
+
declare function parseSemanticJourneyReceipts(header: string | null | undefined, catalogue: SemanticJourneyCatalogue): SemanticJourneyConsequenceReceipt[];
|
|
498
|
+
|
|
499
|
+
/** The confidence level of a deterministic semantic journey reconstruction. */
|
|
500
|
+
type SemanticJourneyCompleteness = "complete" | "partial" | "invalid";
|
|
501
|
+
/** A bounded reason why a reconstruction is incomplete or invalid. */
|
|
502
|
+
type SemanticJourneyEvidenceCode = "empty-journey" | "invalid-event" | "evidence-limit" | "missing-parent" | "missing-cause" | "sequence-gap" | "sequence-fork" | "cycle" | "mixed-journey";
|
|
503
|
+
/** Structured, token-only uncertainty attached to a reconstruction. */
|
|
504
|
+
interface SemanticJourneyEvidence {
|
|
505
|
+
readonly code: SemanticJourneyEvidenceCode;
|
|
506
|
+
readonly severity: "partial" | "invalid";
|
|
507
|
+
readonly explanation: string;
|
|
508
|
+
readonly eventId?: string;
|
|
509
|
+
readonly relatedEventId?: string;
|
|
510
|
+
readonly spanId?: string;
|
|
511
|
+
readonly producerId?: string;
|
|
512
|
+
readonly producerSequence?: number;
|
|
513
|
+
readonly expectedSequence?: number;
|
|
514
|
+
readonly observedSequence?: number;
|
|
515
|
+
readonly observedCount?: number;
|
|
516
|
+
readonly eventIds?: readonly string[];
|
|
517
|
+
}
|
|
518
|
+
/** A privacy-safe event projection used by replay-style inference. */
|
|
519
|
+
interface SemanticJourneyStep {
|
|
520
|
+
readonly eventId: string;
|
|
521
|
+
readonly traceId: string;
|
|
522
|
+
readonly spanId: string;
|
|
523
|
+
readonly parentSpanId?: string;
|
|
524
|
+
readonly causedByEventId?: string;
|
|
525
|
+
readonly producerId: string;
|
|
526
|
+
readonly producerSequence: number;
|
|
527
|
+
readonly occurredAtEpochMs: number;
|
|
528
|
+
readonly source: string;
|
|
529
|
+
readonly channel: SemanticJourneyEvent["channel"];
|
|
530
|
+
readonly runtime: SemanticJourneyEvent["runtime"];
|
|
531
|
+
readonly name: string;
|
|
532
|
+
readonly category: SemanticJourneyEvent["category"];
|
|
533
|
+
readonly phase: SemanticJourneyEvent["phase"];
|
|
534
|
+
readonly outcome: SemanticJourneyEvent["outcome"];
|
|
535
|
+
readonly modality?: NonNullable<SemanticJourneyEvent["modality"]>;
|
|
536
|
+
readonly target?: {
|
|
537
|
+
readonly type: string;
|
|
538
|
+
readonly id: string;
|
|
539
|
+
};
|
|
540
|
+
readonly predecessorEventIds: readonly string[];
|
|
541
|
+
readonly explanation: string;
|
|
542
|
+
}
|
|
543
|
+
/** A deterministic reconstruction of exactly one semantic journey. */
|
|
544
|
+
interface SemanticJourneyReplay {
|
|
545
|
+
readonly journeyId?: string;
|
|
546
|
+
readonly completeness: SemanticJourneyCompleteness;
|
|
547
|
+
readonly steps: readonly SemanticJourneyStep[];
|
|
548
|
+
readonly evidence: readonly SemanticJourneyEvidence[];
|
|
549
|
+
}
|
|
550
|
+
/**
|
|
551
|
+
* Reconstructs one strictly validated semantic journey without copying event
|
|
552
|
+
* attributes. Causal references and producer order take precedence over
|
|
553
|
+
* timestamps, which are used only as deterministic topological tie-breakers.
|
|
554
|
+
* Any runtime-invalid event or exceeded work bound fails closed.
|
|
555
|
+
*/
|
|
556
|
+
declare function reconstructSemanticJourney(catalogue: SemanticJourneyCatalog, events: readonly SemanticJourneyEvent[]): SemanticJourneyReplay;
|
|
557
|
+
|
|
558
|
+
/** Configuration for explicit, delegated browser semantic observation. */
|
|
559
|
+
interface SemanticJourneyBrowserObserverConfig {
|
|
560
|
+
/** The registered, bounded event catalogue used to admit semantic names. */
|
|
561
|
+
readonly catalogue: SemanticJourneyCatalogue;
|
|
562
|
+
/** Receives a safe semantic input; callback failures never affect the page. */
|
|
563
|
+
readonly onEvent: (event: SemanticJourneyEventInput) => void;
|
|
564
|
+
/** Delegation root. Defaults to the current document in browser runtimes. */
|
|
565
|
+
readonly root?: Document | Element;
|
|
566
|
+
/** Allows a remotely resolved rollout decision to disable all listeners. */
|
|
567
|
+
readonly enabled: boolean;
|
|
568
|
+
}
|
|
569
|
+
/**
|
|
570
|
+
* Installs delegated semantic interaction listeners on one root.
|
|
571
|
+
*
|
|
572
|
+
* Only explicit `data-plasius-event`, `data-plasius-target-type`, and
|
|
573
|
+
* `data-plasius-target-id` annotations are inspected. DOM content, form values,
|
|
574
|
+
* URLs, low-level input data, and arbitrary attributes are never read.
|
|
575
|
+
*
|
|
576
|
+
* @returns A function that removes every installed listener.
|
|
577
|
+
*/
|
|
578
|
+
declare function observeSemanticJourneyInteractions(config: SemanticJourneyBrowserObserverConfig): () => void;
|
|
579
|
+
|
|
580
|
+
/** Stable reasons for locally discarded semantic evidence. */
|
|
581
|
+
type SemanticJourneyDropReason = "invalid" | "queue-limit" | "expired" | "transport-rejected";
|
|
582
|
+
/** Injectable cancellable delay used by bounded retry logic. */
|
|
583
|
+
type SemanticJourneyRetryDelay = (delayMs: number, signal: AbortSignal) => Promise<void>;
|
|
584
|
+
/** Optional causal link supplied when recording an event. */
|
|
585
|
+
interface SemanticJourneyTrackOptions {
|
|
586
|
+
readonly causedByEventId?: string;
|
|
587
|
+
}
|
|
588
|
+
/** A safe outbound request link whose private journey ID is never serialized. */
|
|
589
|
+
interface SemanticJourneyRequestLink {
|
|
590
|
+
readonly requestEvent: SemanticJourneyEvent;
|
|
591
|
+
readonly traceparent: string;
|
|
592
|
+
complete(consequenceReceiptHeader: string | null | undefined): readonly SemanticJourneyEvent[];
|
|
593
|
+
}
|
|
594
|
+
/** Configuration for a local-private semantic journey producer. */
|
|
595
|
+
interface SemanticJourneyClientConfig {
|
|
596
|
+
readonly catalogue: SemanticJourneyCatalog;
|
|
597
|
+
readonly source: string;
|
|
598
|
+
readonly channel?: AnalyticsChannel;
|
|
599
|
+
readonly runtime?: AnalyticsRuntime;
|
|
600
|
+
readonly enabled?: boolean;
|
|
601
|
+
readonly aggregateEndpoint?: string;
|
|
602
|
+
readonly aggregateBaseUrl?: string;
|
|
603
|
+
readonly aggregateTransport?: SemanticJourneyAggregateTransport;
|
|
604
|
+
readonly autoFlush?: boolean;
|
|
605
|
+
readonly aggregateFlushIntervalMs?: number;
|
|
606
|
+
readonly aggregateMaxCounters?: number;
|
|
607
|
+
readonly aggregateMaxBytes?: number;
|
|
608
|
+
readonly maxBatchesPerFlush?: number;
|
|
609
|
+
readonly maxQueueEvents?: number;
|
|
610
|
+
readonly maxQueueBytes?: number;
|
|
611
|
+
readonly maxEventAgeMs?: number;
|
|
612
|
+
readonly episodeIdleMs?: number;
|
|
613
|
+
readonly coalesceWindowMs?: number;
|
|
614
|
+
readonly requestTimeoutMs?: number;
|
|
615
|
+
readonly maxRetries?: number;
|
|
616
|
+
readonly retryBaseDelayMs?: number;
|
|
617
|
+
readonly retryMaxDelayMs?: number;
|
|
618
|
+
readonly randomBytes?: RandomByteSource;
|
|
619
|
+
readonly now?: () => number;
|
|
620
|
+
readonly retryDelay?: SemanticJourneyRetryDelay;
|
|
621
|
+
readonly onDrop?: (reason: SemanticJourneyDropReason) => void;
|
|
622
|
+
}
|
|
623
|
+
/** Public operations exposed by a local-private semantic journey producer. */
|
|
624
|
+
interface SemanticJourneyClient {
|
|
625
|
+
readonly source: string;
|
|
626
|
+
readonly channel: AnalyticsChannel;
|
|
627
|
+
readonly runtime: AnalyticsRuntime;
|
|
628
|
+
track(input: SemanticJourneyEventInput, options?: SemanticJourneyTrackOptions): SemanticJourneyEvent | undefined;
|
|
629
|
+
beginRequest(input: SemanticJourneyEventInput, options?: SemanticJourneyTrackOptions): SemanticJourneyRequestLink | undefined;
|
|
630
|
+
getEvents(): readonly SemanticJourneyEvent[];
|
|
631
|
+
reconstruct(): SemanticJourneyReplay;
|
|
632
|
+
flush(): Promise<void>;
|
|
633
|
+
rotate(): void;
|
|
634
|
+
clear(): void;
|
|
635
|
+
destroy(): void;
|
|
636
|
+
}
|
|
637
|
+
/**
|
|
638
|
+
* Creates an opt-in, local-private semantic journey client.
|
|
639
|
+
*
|
|
640
|
+
* Individual events remain in bounded memory. `flush()` serializes only the
|
|
641
|
+
* aggregate counter schema, never the local event or causal identifiers.
|
|
642
|
+
*/
|
|
643
|
+
declare function createSemanticJourneyClient(inputConfig: SemanticJourneyClientConfig): SemanticJourneyClient;
|
|
644
|
+
|
|
164
645
|
interface AnalyticsProviderProps {
|
|
165
646
|
children: ReactNode;
|
|
166
647
|
source?: string;
|
|
@@ -193,4 +674,4 @@ interface TrackInteractionDetails extends Omit<LocalSpaceAnalyticsEvent, "compon
|
|
|
193
674
|
}
|
|
194
675
|
declare function useComponentInteractionTracker(component: string, baseContext?: AnalyticsContext): (action: string, details?: TrackInteractionDetails) => void;
|
|
195
676
|
|
|
196
|
-
export { type AnalyticsChannel, type AnalyticsContext, type AnalyticsContextValue, type AnalyticsErrorSeverity, type AnalyticsEventKind, AnalyticsProvider, type AnalyticsProviderProps, type AnalyticsRuntime, type AnalyticsTransport, type AnalyticsTransportRequest, type LocalSpaceAnalyticsClient, type LocalSpaceAnalyticsConfig, type LocalSpaceAnalyticsErrorDetails, type LocalSpaceAnalyticsEvent, type LocalSpaceAnalyticsRecord, type LocalSpaceErrorReportInput, type LocalSpaceErrorReportingConfig, type LocalSpaceIssueReport, type LocalSpaceIssueThresholdTrigger, type ResolvedLocalSpaceAnalyticsConfig, type ResolvedLocalSpaceErrorReportingConfig, type TrackInteractionDetails, createBackendAnalyticsClient, createFrontendAnalyticsClient, createLocalSpaceAnalyticsClient, createNoopLocalSpaceAnalyticsClient, useAnalytics, useComponentInteractionTracker };
|
|
677
|
+
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, 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, reconstructSemanticJourney, serializeSemanticJourneyReceipts, useAnalytics, useComponentInteractionTracker, validateSemanticJourneyEventInput };
|