@tracelog/capture-web 2.0.0 → 2.1.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/CHANGELOG.md CHANGED
@@ -18,6 +18,24 @@ patch, and neither requires reading your code.
18
18
  Entries after 1.0.0 are drafted from the commits that touched this package and
19
19
  edited before release.
20
20
 
21
+ ## [2.1.0](https://github.com/nacorga/tracelog-sdk/compare/capture-web@2.0.1...capture-web@2.1.0) (2026-10-06)
22
+
23
+
24
+ ### Added
25
+
26
+ * **capture-core:** a conversion's items, day and recurrence, and a step's items ([98a5dd6](https://github.com/nacorga/tracelog-sdk/commit/98a5dd6daa131cbc92ddf8ad271a53bc243d4e72))
27
+ * **capture-web:** step takes its items as a third argument ([32eddbf](https://github.com/nacorga/tracelog-sdk/commit/32eddbfa4023eaff4dfb24e4b80c081266b3dd50))
28
+
29
+
30
+ ### Fixed
31
+
32
+ * **capture-web:** the bundle carries no comments ([da8d145](https://github.com/nacorga/tracelog-sdk/commit/da8d145e9bb8ac5bece5e9a59fb0f1e47bc212e3))
33
+
34
+ ## [2.0.1](https://github.com/nacorga/tracelog-sdk/compare/capture-web@2.0.0...capture-web@2.0.1) (2026-10-02)
35
+
36
+
37
+ * **capture-web:** Synchronize tracelog-sdk versions
38
+
21
39
  ## [2.0.0](https://github.com/nacorga/tracelog-sdk/compare/capture-web@1.3.1...capture-web@2.0.0) (2026-10-01)
22
40
 
23
41
 
package/README.md CHANGED
@@ -22,13 +22,13 @@ as they are served.
22
22
  <!-- x-release-please-start-version -->
23
23
 
24
24
  ```bash
25
- npm install --save-exact @tracelog/capture-web@2.0.0
25
+ npm install --save-exact @tracelog/capture-web@2.1.0
26
26
  ```
27
27
 
28
28
  Without a build step, the same runtime as a script tag:
29
29
 
30
30
  ```html
31
- <script src="https://cdn.tracelog.io/v/2.0.0/tracelog.js"></script>
31
+ <script src="https://cdn.tracelog.io/v/2.1.0/tracelog.js"></script>
32
32
  ```
33
33
 
34
34
  <!-- x-release-please-end -->
@@ -69,14 +69,14 @@ visitors nothing.
69
69
 
70
70
  That is all of it, and it is what the major version protects.
71
71
 
72
- | Call | Does |
73
- | --------------------------------- | ------------------------------------------------------------------ |
74
- | `TraceLog.init(options)` | Configures the runtime. `key` is the project's public key. |
75
- | `TraceLog.consent.grant()` | Allows capture. Queued delivery begins. |
76
- | `TraceLog.consent.deny()` | Keeps the runtime inert. |
77
- | `TraceLog.consent.state()` | `"unknown" \| "granted" \| "denied"`. |
78
- | `TraceLog.step(name, context?)` | A declared step of the conversion path. |
79
- | `TraceLog.conversion(name, opts)` | A declared conversion. `opts.identifier` is its stable identifier. |
72
+ | Call | Does |
73
+ | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
74
+ | `TraceLog.init(options)` | Configures the runtime. `key` is the project's public key. |
75
+ | `TraceLog.consent.grant()` | Allows capture. Queued delivery begins. |
76
+ | `TraceLog.consent.deny()` | Keeps the runtime inert. |
77
+ | `TraceLog.consent.state()` | `"unknown" \| "granted" \| "denied"`. |
78
+ | `TraceLog.step(name, context?, opts?)` | A declared step of the conversion path. `opts.items` are the items it shows. |
79
+ | `TraceLog.conversion(name, opts)` | A declared conversion. `opts.identifier` is its stable identifier. `opts.items`, `opts.scheduledFor` and `opts.recurring` say what it was for. |
80
80
 
81
81
  `init` also accepts `mode: "verification"`, which a distributed platform artifact
82
82
  declares for its platform's own test order. A site's own snippet never sets it —
@@ -101,6 +101,10 @@ The events your tracking plan declares, with their context. Not page views, not
101
101
  clicks, not scroll, not keystrokes. Errors are captured only when they occur
102
102
  inside the conversion path, attached to the step where they happened.
103
103
 
104
+ A conversion may carry its items, the day a booking is for and whether it
105
+ recurs, and a step the items it shows; a malformed one is left out and the
106
+ event sent without it.
107
+
104
108
  Beside each conversion, which GA4, Meta and Google Ads tags the page requested
105
109
  just before and after it — the tag's kind, its id and, for Meta, the event —
106
110
  read from the browser's own record of the page's requests and, for the one
@@ -7,17 +7,34 @@ export interface InitOptions {
7
7
  mode?: "verification";
8
8
  }
9
9
 
10
+ export interface Item {
11
+ id: string;
12
+ name: string;
13
+ category?: string;
14
+ quantity: number;
15
+ /** The price of one unit; on a conversion, in its currency. */
16
+ price?: number;
17
+ }
18
+
19
+ export interface StepOptions {
20
+ items?: Item[];
21
+ }
22
+
10
23
  export interface ConversionOptions {
11
24
  identifier: string;
12
25
  value?: number;
13
26
  currency?: string;
14
27
  context?: object;
28
+ items?: Item[];
29
+ /** The day a booking is for, YYYY-MM-DD. */
30
+ scheduledFor?: string;
31
+ recurring?: boolean;
15
32
  }
16
33
 
17
34
  declare const TraceLog: {
18
35
  init(options: InitOptions): void;
19
36
  consent: { grant(): void; deny(): void; state(): ConsentState };
20
- step(name: string, context?: object): void;
37
+ step(name: string, context?: object, options?: StepOptions): void;
21
38
  conversion(name: string, options: ConversionOptions): void;
22
39
  };
23
40
 
@@ -3,22 +3,19 @@ const MAX_BATCH_BYTES = 262144;
3
3
  const MAX_BATCH_EVENTS = 50;
4
4
  const MAX_CONTEXT_BYTES = 8192;
5
5
  const MAX_ERROR_MESSAGE_BYTES = 1024;
6
+ const MAX_ITEMS = 100;
7
+ const MAX_ITEMS_BYTES = 16384;
8
+ const MAX_ITEM_TEXT_LENGTH = 256;
6
9
  const MAX_TAG_SIGHTINGS = 16;
7
10
  const TAG_SIGHTINGS_CONTEXT_KEY = "__tl.tags";
8
- const TAG_ID_PATTERNS = {"ga4":"^G-[A-Z0-9]{4,15}$","meta":"^[0-9]{6,20}$","google_ads":"^AW-[0-9]{6,15}(?:/[A-Za-z0-9_-]{1,64})?$"};
11
+ const TAG_ID_PATTERNS = { "ga4": "^G-[A-Z0-9]{4,15}$", "meta": "^[0-9]{6,20}$", "google_ads": "^AW-[0-9]{6,15}(?:/[A-Za-z0-9_-]{1,64})?$" };
9
12
  const TAG_EVENT_PATTERN = "^[A-Za-z0-9_]{1,64}$";
10
- const tagSightingKinds = ["ga4","meta","google_ads"];
13
+ const tagSightingKinds = ["ga4", "meta", "google_ads"];
11
14
  const CONSENT_KEY = "__tl.c";
12
15
  const SESSION_KEY = "__tl.s";
13
16
  const ACTIVITY_KEY = "__tl.a";
14
17
  const QUEUE_KEY = "__tl.q";
15
- /** The namespace the runtime owns, in storage and in an event's context. */
16
18
  const RUNTIME_KEY_PREFIX = "__tl.";
17
- /**
18
- * How many events wait in memory before consent. A platform artifact that
19
- * buffers its own platform's events ahead of this engine holds the same line,
20
- * so the number is exported rather than mirrored.
21
- */
22
19
  const PRE_CONSENT_CAP = 100;
23
20
  const QUEUE_CAP = 200;
24
21
  const SESSION_INACTIVITY_MS = 30 * 60 * 1000;
@@ -27,29 +24,13 @@ const RETRY_BASE_MS = 1000;
27
24
  const RETRY_CAP_MS = 60 * 1000;
28
25
  const CIRCUIT_FAILURE_THRESHOLD = 5;
29
26
  const CIRCUIT_PROBE_MS = 60 * 1000;
30
- /**
31
- * What the browser lets `keepalive` bodies in flight add up to. Every send
32
- * uses `keepalive`, so no navigation cancels one, and every send fits what is
33
- * left of this beside the sends already in flight ([spec/capture.md]
34
- * § Delivery). It is below the contract's `MAX_BATCH_BYTES`, so it is the
35
- * batch budget too.
36
- */
37
27
  const KEEPALIVE_BUDGET_BYTES = 64 * 1024;
38
28
  const EVENT_NAME_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
39
29
  const PUBLIC_KEY_PATTERN = /^tl_pk_[a-z2-7]{26}$/;
40
- /**
41
- * The contract states these inside its schemas (`conversionEventSchema`,
42
- * `currencySchema`) and exports no constant for them; the schemas themselves
43
- * are not imported because zod is not part of the runtime a visitor loads.
44
- */
45
30
  const MAX_IDENTIFIER_LENGTH = 256;
46
31
  const CURRENCY_PATTERN = /^[A-Z]{3}$/;
32
+ const DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
47
33
  const textEncoder = new TextEncoder();
48
- /**
49
- * The tag sighting window around a conversion ([spec/capture.md] § Tag
50
- * sightings). Ten seconds after is almost twice the longest hold measured:
51
- * GA4 was measured holding a purchase 5.0 to 5.6 seconds.
52
- */
53
34
  const TAG_SIGHTING_BEFORE_MS = 30000;
54
35
  const TAG_SIGHTING_AFTER_MS = 10000;
55
36
  function safeGet(storage, key) {
@@ -65,7 +46,6 @@ function safeSet(storage, key, value) {
65
46
  storage.setItem(key, value);
66
47
  }
67
48
  catch {
68
- // Capture must never break the host page when storage is unavailable.
69
49
  }
70
50
  }
71
51
  function safeRemove(storage, key) {
@@ -73,7 +53,6 @@ function safeRemove(storage, key) {
73
53
  storage.removeItem(key);
74
54
  }
75
55
  catch {
76
- // Capture must never break the host page when storage is unavailable.
77
56
  }
78
57
  }
79
58
  function emptyQueue() {
@@ -124,8 +103,8 @@ function uuidv7(at) {
124
103
  bytes[index] = timestamp % 256;
125
104
  timestamp = Math.floor(timestamp / 256);
126
105
  }
127
- bytes[6] = 0x70 | (bytes[6] & 0x0f);
128
- bytes[8] = 0x80 | (bytes[8] & 0x3f);
106
+ bytes[6] = 112 | (bytes[6] & 15);
107
+ bytes[8] = 128 | (bytes[8] & 63);
129
108
  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0"));
130
109
  return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
131
110
  }
@@ -169,21 +148,56 @@ function truncateUtf8(value, maxBytes) {
169
148
  }
170
149
  return value.slice(0, low);
171
150
  }
151
+ function isAmount(value) {
152
+ return typeof value === "number" && Number.isFinite(value) && value >= 0;
153
+ }
172
154
  function isConversionValid(options) {
173
155
  return (options.identifier.length >= 1 &&
174
156
  options.identifier.length <= MAX_IDENTIFIER_LENGTH &&
175
- (options.value === undefined ||
176
- (Number.isFinite(options.value) && options.value >= 0)) &&
157
+ (options.value === undefined || isAmount(options.value)) &&
177
158
  (options.currency === undefined || CURRENCY_PATTERN.test(options.currency)));
178
159
  }
160
+ function isItemText(value) {
161
+ return (typeof value === "string" &&
162
+ value.length >= 1 &&
163
+ value.length <= MAX_ITEM_TEXT_LENGTH);
164
+ }
165
+ function itemsOf(value) {
166
+ if (!Array.isArray(value) || value.length < 1 || value.length > MAX_ITEMS)
167
+ return undefined;
168
+ const items = [];
169
+ for (const item of value) {
170
+ if (typeof item !== "object" || item === null)
171
+ return undefined;
172
+ const { id, name, category, quantity, price } = item;
173
+ if (!isItemText(id) ||
174
+ !isItemText(name) ||
175
+ (category !== undefined && !isItemText(category)) ||
176
+ !Number.isSafeInteger(quantity) ||
177
+ quantity < 1 ||
178
+ (price !== undefined && !isAmount(price)))
179
+ return undefined;
180
+ items.push({
181
+ id,
182
+ name,
183
+ ...(category === undefined ? {} : { category }),
184
+ quantity: quantity,
185
+ ...(price === undefined ? {} : { price }),
186
+ });
187
+ }
188
+ return serializedBytes(items) <= MAX_ITEMS_BYTES ? items : undefined;
189
+ }
190
+ function scheduledForOf(value) {
191
+ if (typeof value !== "string" || !DAY_PATTERN.test(value))
192
+ return undefined;
193
+ const day = new Date(`${value}T00:00:00.000Z`);
194
+ return !Number.isNaN(day.getTime()) && day.toISOString().startsWith(value)
195
+ ? value
196
+ : undefined;
197
+ }
179
198
  function serializedBytes(value) {
180
199
  return textEncoder.encode(JSON.stringify(value)).byteLength;
181
200
  }
182
- /**
183
- * As many events as fit `room`, oldest first. An event that alone exceeds the
184
- * whole keepalive budget can never be sent; one that only exceeds what the
185
- * sends in flight leave waits for them.
186
- */
187
201
  function batchFrom(events, room) {
188
202
  const selected = [];
189
203
  const unsendable = [];
@@ -212,21 +226,9 @@ function createCaptureEngine(ports, acquisition) {
212
226
  let config = { key: "", endpoint: "/v1/events" };
213
227
  let pending = [];
214
228
  let lastDeclaredName;
215
- /**
216
- * Every send in flight, by count, by bytes and by the union of their event
217
- * ids: a step taken and a page hide send beside one rather than wait for
218
- * it, so there can be several, each must leave the others' events alone,
219
- * and together they stay within the keepalive budget.
220
- */
221
229
  let sendsInFlight = 0;
222
230
  let bytesInFlight = 0;
223
231
  const inFlight = new Set();
224
- /**
225
- * The conversions this page emitted and holds for their tag sighting
226
- * window: the instant each was emitted, and whether its report can be
227
- * complete. In memory only — a held conversion is in the stored queue like
228
- * any other, and a reload sends it as it is.
229
- */
230
232
  const held = new Map();
231
233
  let flushTimer;
232
234
  let consecutiveFailures = 0;
@@ -275,11 +277,6 @@ function createCaptureEngine(ports, acquisition) {
275
277
  addDrop(queue, "invalid_event");
276
278
  writeQueue(ports.storage, queue);
277
279
  }
278
- /**
279
- * `buffered` is a conversion made before consent was granted and emitted
280
- * at the grant: its window is placed there, after the conversion itself,
281
- * so its report is never complete.
282
- */
283
280
  function emit(pendingEvent, buffered = false) {
284
281
  if (!EVENT_NAME_PATTERN.test(pendingEvent.name)) {
285
282
  recordInvalidEvent();
@@ -307,16 +304,20 @@ function createCaptureEngine(ports, acquisition) {
307
304
  }
308
305
  if (pendingEvent.kind === "step") {
309
306
  const context = jsonContext(pendingEvent.context);
307
+ const items = itemsOf(pendingEvent.options?.items);
310
308
  persistEvent({
311
309
  ...baseEvent(now, session.id),
312
310
  kind: "step",
313
311
  name: pendingEvent.name,
314
312
  ...(context === undefined ? {} : { context }),
313
+ ...(items === undefined ? {} : { items }),
315
314
  });
316
315
  }
317
316
  else {
318
317
  const options = pendingEvent.options;
319
318
  const context = jsonContext(options.context);
319
+ const items = itemsOf(options.items);
320
+ const scheduledFor = scheduledForOf(options.scheduledFor);
320
321
  const base = baseEvent(now, session.id);
321
322
  if (acquisition.mode !== "verification" &&
322
323
  ports.sightings?.observing() === true) {
@@ -332,6 +333,11 @@ function createCaptureEngine(ports, acquisition) {
332
333
  ? {}
333
334
  : { currency: options.currency }),
334
335
  ...(context === undefined ? {} : { context }),
336
+ ...(items === undefined ? {} : { items }),
337
+ ...(scheduledFor === undefined ? {} : { scheduledFor }),
338
+ ...(typeof options.recurring === "boolean"
339
+ ? { recurring: options.recurring }
340
+ : {}),
335
341
  });
336
342
  }
337
343
  lastDeclaredName = pendingEvent.name;
@@ -347,21 +353,11 @@ function createCaptureEngine(ports, acquisition) {
347
353
  emit(pendingEvent);
348
354
  sendTaken();
349
355
  }
350
- /**
351
- * A step, and a conversion that is not held, leaves when it is taken: a
352
- * click that navigates to another site may fire no hide event at all, and a
353
- * send started by the click itself is the one that arrives ([spec/capture.md]
354
- * § Delivery). An open circuit keeps it queued for the probe.
355
- */
356
356
  function sendTaken() {
357
357
  if (circuit !== "closed" || !PUBLIC_KEY_PATTERN.test(config.key))
358
358
  return;
359
359
  void sendNow();
360
360
  }
361
- /**
362
- * Sends at once what is queued and in no send in flight, beside any send in
363
- * flight, within what the keepalive budget has left.
364
- */
365
361
  async function sendNow() {
366
362
  const queue = readQueue(ports.storage);
367
363
  const ready = queue.events.filter((event) => !held.has(event.eventId) && !inFlight.has(event.eventId));
@@ -378,10 +374,6 @@ function createCaptureEngine(ports, acquisition) {
378
374
  addDrop(queue, "invalid_event", unsendable.length);
379
375
  writeQueue(ports.storage, queue);
380
376
  }
381
- /**
382
- * Gives each held conversion whose window has closed — or every one, at
383
- * page hide — the report of what the port saw around it, and lets it go.
384
- */
385
377
  function release(all) {
386
378
  if (held.size === 0)
387
379
  return;
@@ -393,7 +385,6 @@ function createCaptureEngine(ports, acquisition) {
393
385
  let reported = false;
394
386
  for (const [eventId, hold] of due) {
395
387
  held.delete(eventId);
396
- // Gone from the queue — sent by another tab, or dropped by overflow.
397
388
  const event = queue.events.find((candidate) => candidate.eventId === eventId);
398
389
  const answer = event === undefined
399
390
  ? null
@@ -420,7 +411,6 @@ function createCaptureEngine(ports, acquisition) {
420
411
  if (reported)
421
412
  writeQueue(ports.storage, queue);
422
413
  }
423
- /** Until the earliest held conversion's window closes. */
424
414
  function untilRelease() {
425
415
  const now = ports.clock.now().getTime();
426
416
  let earliest = Number.POSITIVE_INFINITY;
@@ -433,11 +423,6 @@ function createCaptureEngine(ports, acquisition) {
433
423
  release(hidden);
434
424
  if (!initialized || consentState !== "granted")
435
425
  return;
436
- /**
437
- * A page being hidden gets no later chance, so it sends what no send in
438
- * flight carries at once, whatever the circuit's state, and the answer is
439
- * read as any other's.
440
- */
441
426
  if (hidden) {
442
427
  if (PUBLIC_KEY_PATTERN.test(config.key))
443
428
  await sendNow();
@@ -471,11 +456,6 @@ function createCaptureEngine(ports, acquisition) {
471
456
  }
472
457
  await deliver(batch);
473
458
  }
474
- /**
475
- * One send, and its answer. It removes from the stored queue exactly what
476
- * it carried, by its own read, filter and write at the moment it settles,
477
- * so a send beside it keeps what it delivered.
478
- */
479
459
  async function deliver(batch) {
480
460
  const carried = new Set(batch.events.map((event) => event.eventId));
481
461
  const bytes = serializedBytes(batch);
@@ -502,14 +482,6 @@ function createCaptureEngine(ports, acquisition) {
502
482
  scheduleFlush(currentQueue.events.length === 0 ? FLUSH_INTERVAL_MS : 0);
503
483
  return;
504
484
  }
505
- /**
506
- * A 4xx is the server's word that this batch will never be accepted —
507
- * except a 429, which is the server's word that it will be accepted
508
- * later: the ingestion limit is per public key, shared by every visitor
509
- * of one site, so a busy minute answers 429 to visitors whose events
510
- * are sound. Dropping those is silent loss ([spec/capture.md]
511
- * § Delivery); they take the retry path with everything else transient.
512
- */
513
485
  if (response.status >= 400 &&
514
486
  response.status < 500 &&
515
487
  response.status !== 429) {
@@ -550,12 +522,6 @@ function createCaptureEngine(ports, acquisition) {
550
522
  endpoint: options.endpoint ?? "/v1/events",
551
523
  };
552
524
  initialized = true;
553
- /**
554
- * Only a denial is remembered; a grant is the integrator's on every load
555
- * while consent stands, so it never outlives the banner that gave it
556
- * ([spec/capture.md] § Consent first). A grant an earlier runtime
557
- * stored is deleted. A second init keeps the decision this page made.
558
- */
559
525
  if (consentState !== "unknown")
560
526
  return;
561
527
  const storedConsent = safeGet(ports.storage, CONSENT_KEY);
@@ -599,11 +565,12 @@ function createCaptureEngine(ports, acquisition) {
599
565
  return consentState;
600
566
  },
601
567
  },
602
- step(name, context) {
568
+ step(name, context, options) {
603
569
  capture({
604
570
  kind: "step",
605
571
  name,
606
572
  ...(context === undefined ? {} : { context }),
573
+ ...(options === undefined ? {} : { options }),
607
574
  });
608
575
  },
609
576
  conversion(name, options) {
@@ -653,31 +620,12 @@ function createCaptureEngine(ports, acquisition) {
653
620
  },
654
621
  };
655
622
  }
656
- /**
657
- * The browser's clock, and the one file in this package allowed to read it
658
- * ([CLAUDE.md] § Invariants: time is injected). `capture-core` declares the
659
- * port and reads no clock at all — it runs inside sandboxes that have none —
660
- * so the implementation lives here, with the runtime that has a `Date`.
661
- */
662
623
  const systemClock = {
663
624
  now: () => new Date(Date.now()),
664
625
  };
665
- /**
666
- * A Resource Timing entry's start, on the system clock: its reading minus the
667
- * entry's monotonic age. `performance.timeOrigin` would be a second clock, and
668
- * it can disagree with this one by as much as the machine's clock drifted
669
- * since the page loaded; the age is read on one clock and the instant on the
670
- * other, so a sighting and the conversion it is compared with are dated alike
671
- * ([spec/capture.md] § Tag sightings).
672
- */
673
626
  function instantOfEntry(startTime) {
674
627
  return new Date(systemClock.now().getTime() - (performance.now() - startTime));
675
628
  }
676
- /**
677
- * How many matches the port keeps. A page making more tag requests than this
678
- * inside one window is one whose report the port declines to give, never one
679
- * it gives short.
680
- */
681
629
  const TAG_SIGHTING_MEMORY = 100;
682
630
  const ga4IdPattern = new RegExp(TAG_ID_PATTERNS.ga4);
683
631
  const metaIdPattern = new RegExp(TAG_ID_PATTERNS.meta);
@@ -689,7 +637,6 @@ function onMetaEndpoint(url) {
689
637
  return ((host === "facebook.com" || host.endsWith(".facebook.com")) &&
690
638
  (url.pathname === "/tr" || url.pathname === "/tr/"));
691
639
  }
692
- /** A request on Meta's endpoint whose pixel id does not fit is Meta, unread. */
693
640
  function metaMatch(id, event) {
694
641
  return id !== null && metaIdPattern.test(id)
695
642
  ? {
@@ -701,15 +648,6 @@ function metaMatch(id, event) {
701
648
  }
702
649
  : { unread: "meta" };
703
650
  }
704
- /**
705
- * The matching table ([spec/capture.md] § Tag sightings): GA4 and Google Ads
706
- * key on the path and the id, so a regional host and a first-party tagging
707
- * domain that keeps the path both match; Meta keys on its host as well. What
708
- * is answered is the tag's kind, its id and Meta's event — nothing else of
709
- * the URL, which carries the page address and the vendor's client id. Meta's
710
- * beacon leaves an entry named by its bare endpoint, which names no pixel:
711
- * that is Meta, unread.
712
- */
713
651
  function matchTagRequest(url) {
714
652
  let parsed;
715
653
  try {
@@ -743,13 +681,6 @@ function matchTagRequest(url) {
743
681
  }
744
682
  return null;
745
683
  }
746
- /**
747
- * Meta's long request in Chrome: a form posted into a hidden frame, which
748
- * leaves no Resource Timing entry ([spec/capture.md] § Tag sightings, _Meta's
749
- * long request_). Two fields are asked for, the ones that name the pixel and
750
- * the event, and nothing else of the form is read: its other fields carry the
751
- * visitor's identifiers, hashed.
752
- */
753
684
  function matchTagForm(form) {
754
685
  let action;
755
686
  try {
@@ -760,30 +691,14 @@ function matchTagForm(form) {
760
691
  }
761
692
  if (!onMetaEndpoint(action))
762
693
  return null;
763
- const id = form.querySelector('input[name="id"]');
764
- const event = form.querySelector('input[name="ev"]');
694
+ const id = form.querySelector("input[name=\"id\"]");
695
+ const event = form.querySelector("input[name=\"ev\"]");
765
696
  return metaMatch(id?.value ?? null, event?.value ?? null);
766
697
  }
767
- /**
768
- * The browser's own record of the page's requests, read through a buffered
769
- * `PerformanceObserver` once consent is granted and never before — and, for
770
- * the one request that record leaves out, the forms the page's body gains,
771
- * read through a `MutationObserver` on the body's own children. Nothing is
772
- * wrapped, patched or replaced — no `fetch`, no beacon, no vendor's global —
773
- * because the runtime runs on somebody else's page and nothing it does may
774
- * change what another script sees.
775
- */
776
698
  function createTagSightingPort() {
777
699
  let observer;
778
700
  let bodyObserver;
779
- /**
780
- * From when the body's children were watched, on the system clock: minus
781
- * infinity when observation began before the body existed, and so saw every
782
- * form a script added to it; undefined while no body observer runs — never
783
- * created, still waiting for the body, or failed.
784
- */
785
701
  let watchedFrom;
786
- /** Ordered by `at`, oldest first; at most `TAG_SIGHTING_MEMORY`. */
787
702
  let matches = [];
788
703
  function remember(match, at) {
789
704
  if (match === null)
@@ -800,10 +715,6 @@ function createTagSightingPort() {
800
715
  remember(matchTagRequest(entry.name), instantOfEntry(entry.startTime).getTime());
801
716
  }
802
717
  }
803
- /**
804
- * One observer, on the body's children and nothing below them. Before the
805
- * body exists it watches the root's children for the body, and moves to it.
806
- */
807
718
  function watchBody() {
808
719
  try {
809
720
  const document = window.document;
@@ -829,7 +740,6 @@ function createTagSightingPort() {
829
740
  }
830
741
  }
831
742
  catch {
832
- // Capture must never break the host page.
833
743
  }
834
744
  });
835
745
  if (body === null) {
@@ -845,12 +755,9 @@ function createTagSightingPort() {
845
755
  watchedFrom = undefined;
846
756
  }
847
757
  }
848
- /** What was matched inside the window around `at`, or null. */
849
758
  function within(at) {
850
759
  if (observer === undefined)
851
760
  return null;
852
- // What the browser recorded and has not delivered yet: a page being
853
- // hidden may not run the callback before the conversion leaves.
854
761
  record(observer.takeRecords());
855
762
  const from = at.getTime() - TAG_SIGHTING_BEFORE_MS;
856
763
  const to = at.getTime() + TAG_SIGHTING_AFTER_MS;
@@ -922,7 +829,6 @@ function createTagSightingPort() {
922
829
  };
923
830
  }
924
831
  const WEB_PUBLIC_KEY_PATTERN = /^tl_pk_[a-z2-7]{26}$/;
925
- /** The tab's verification nonce, in `sessionStorage`, written at the grant. */
926
832
  const VERIFICATION_KEY = "__tl.v";
927
833
  class MemoryStorage {
928
834
  constructor() {
@@ -944,13 +850,7 @@ let engine;
944
850
  let verification;
945
851
  let configValid = false;
946
852
  let listenersInstalled = false;
947
- /**
948
- * Calls made before `init`, made in order once it has run, up to the same 100
949
- * the engine holds before consent; past that they are dropped
950
- * ([spec/capture.md] § Consent first).
951
- */
952
853
  let early = [];
953
- /** True when there is no engine yet, and the call was held, or dropped. */
954
854
  function heldForInit(call) {
955
855
  if (engine !== undefined)
956
856
  return false;
@@ -966,12 +866,6 @@ function browserStorage() {
966
866
  return new MemoryStorage();
967
867
  }
968
868
  }
969
- /**
970
- * A page opened from a verification session carries the marker and has an
971
- * opener. Once consent is granted there, the tab keeps the nonce, so the mark
972
- * follows it to the site's next pages and back from a payment taken
973
- * elsewhere, to the same origin ([spec/capture.md] § Verification mode).
974
- */
975
869
  function verificationMode() {
976
870
  const nonce = new URL(window.location.href).searchParams.get("__tl_verify");
977
871
  if (nonce !== null && nonce.length > 0 && window.opener !== null) {
@@ -982,7 +876,6 @@ function verificationMode() {
982
876
  kept = window.sessionStorage.getItem(VERIFICATION_KEY);
983
877
  }
984
878
  catch {
985
- // An unreadable tab storage keeps no mark.
986
879
  }
987
880
  return kept === null || kept.length === 0
988
881
  ? undefined
@@ -997,7 +890,6 @@ function keepVerification(keep) {
997
890
  }
998
891
  }
999
892
  catch {
1000
- // A tab that cannot keep it marks this page only.
1001
893
  }
1002
894
  }
1003
895
  function landingPage() {
@@ -1178,10 +1070,10 @@ const TraceLog = {
1178
1070
  return engine?.consent.state() ?? "unknown";
1179
1071
  },
1180
1072
  },
1181
- step(name, context) {
1182
- if (heldForInit(() => TraceLog.step(name, context)))
1073
+ step(name, context, options) {
1074
+ if (heldForInit(() => TraceLog.step(name, context, options)))
1183
1075
  return;
1184
- engine?.step(name, context);
1076
+ engine?.step(name, context, options);
1185
1077
  reportDiagnostic();
1186
1078
  },
1187
1079
  conversion(name, options) {
@@ -4,22 +4,19 @@ const MAX_BATCH_BYTES = 262144;
4
4
  const MAX_BATCH_EVENTS = 50;
5
5
  const MAX_CONTEXT_BYTES = 8192;
6
6
  const MAX_ERROR_MESSAGE_BYTES = 1024;
7
+ const MAX_ITEMS = 100;
8
+ const MAX_ITEMS_BYTES = 16384;
9
+ const MAX_ITEM_TEXT_LENGTH = 256;
7
10
  const MAX_TAG_SIGHTINGS = 16;
8
11
  const TAG_SIGHTINGS_CONTEXT_KEY = "__tl.tags";
9
- const TAG_ID_PATTERNS = {"ga4":"^G-[A-Z0-9]{4,15}$","meta":"^[0-9]{6,20}$","google_ads":"^AW-[0-9]{6,15}(?:/[A-Za-z0-9_-]{1,64})?$"};
12
+ const TAG_ID_PATTERNS = { "ga4": "^G-[A-Z0-9]{4,15}$", "meta": "^[0-9]{6,20}$", "google_ads": "^AW-[0-9]{6,15}(?:/[A-Za-z0-9_-]{1,64})?$" };
10
13
  const TAG_EVENT_PATTERN = "^[A-Za-z0-9_]{1,64}$";
11
- const tagSightingKinds = ["ga4","meta","google_ads"];
14
+ const tagSightingKinds = ["ga4", "meta", "google_ads"];
12
15
  const CONSENT_KEY = "__tl.c";
13
16
  const SESSION_KEY = "__tl.s";
14
17
  const ACTIVITY_KEY = "__tl.a";
15
18
  const QUEUE_KEY = "__tl.q";
16
- /** The namespace the runtime owns, in storage and in an event's context. */
17
19
  const RUNTIME_KEY_PREFIX = "__tl.";
18
- /**
19
- * How many events wait in memory before consent. A platform artifact that
20
- * buffers its own platform's events ahead of this engine holds the same line,
21
- * so the number is exported rather than mirrored.
22
- */
23
20
  const PRE_CONSENT_CAP = 100;
24
21
  const QUEUE_CAP = 200;
25
22
  const SESSION_INACTIVITY_MS = 30 * 60 * 1000;
@@ -28,29 +25,13 @@ const RETRY_BASE_MS = 1000;
28
25
  const RETRY_CAP_MS = 60 * 1000;
29
26
  const CIRCUIT_FAILURE_THRESHOLD = 5;
30
27
  const CIRCUIT_PROBE_MS = 60 * 1000;
31
- /**
32
- * What the browser lets `keepalive` bodies in flight add up to. Every send
33
- * uses `keepalive`, so no navigation cancels one, and every send fits what is
34
- * left of this beside the sends already in flight ([spec/capture.md]
35
- * § Delivery). It is below the contract's `MAX_BATCH_BYTES`, so it is the
36
- * batch budget too.
37
- */
38
28
  const KEEPALIVE_BUDGET_BYTES = 64 * 1024;
39
29
  const EVENT_NAME_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
40
30
  const PUBLIC_KEY_PATTERN = /^tl_pk_[a-z2-7]{26}$/;
41
- /**
42
- * The contract states these inside its schemas (`conversionEventSchema`,
43
- * `currencySchema`) and exports no constant for them; the schemas themselves
44
- * are not imported because zod is not part of the runtime a visitor loads.
45
- */
46
31
  const MAX_IDENTIFIER_LENGTH = 256;
47
32
  const CURRENCY_PATTERN = /^[A-Z]{3}$/;
33
+ const DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
48
34
  const textEncoder = new TextEncoder();
49
- /**
50
- * The tag sighting window around a conversion ([spec/capture.md] § Tag
51
- * sightings). Ten seconds after is almost twice the longest hold measured:
52
- * GA4 was measured holding a purchase 5.0 to 5.6 seconds.
53
- */
54
35
  const TAG_SIGHTING_BEFORE_MS = 30000;
55
36
  const TAG_SIGHTING_AFTER_MS = 10000;
56
37
  function safeGet(storage, key) {
@@ -66,7 +47,6 @@ function safeSet(storage, key, value) {
66
47
  storage.setItem(key, value);
67
48
  }
68
49
  catch {
69
- // Capture must never break the host page when storage is unavailable.
70
50
  }
71
51
  }
72
52
  function safeRemove(storage, key) {
@@ -74,7 +54,6 @@ function safeRemove(storage, key) {
74
54
  storage.removeItem(key);
75
55
  }
76
56
  catch {
77
- // Capture must never break the host page when storage is unavailable.
78
57
  }
79
58
  }
80
59
  function emptyQueue() {
@@ -125,8 +104,8 @@ function uuidv7(at) {
125
104
  bytes[index] = timestamp % 256;
126
105
  timestamp = Math.floor(timestamp / 256);
127
106
  }
128
- bytes[6] = 0x70 | (bytes[6] & 0x0f);
129
- bytes[8] = 0x80 | (bytes[8] & 0x3f);
107
+ bytes[6] = 112 | (bytes[6] & 15);
108
+ bytes[8] = 128 | (bytes[8] & 63);
130
109
  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0"));
131
110
  return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
132
111
  }
@@ -170,21 +149,56 @@ function truncateUtf8(value, maxBytes) {
170
149
  }
171
150
  return value.slice(0, low);
172
151
  }
152
+ function isAmount(value) {
153
+ return typeof value === "number" && Number.isFinite(value) && value >= 0;
154
+ }
173
155
  function isConversionValid(options) {
174
156
  return (options.identifier.length >= 1 &&
175
157
  options.identifier.length <= MAX_IDENTIFIER_LENGTH &&
176
- (options.value === undefined ||
177
- (Number.isFinite(options.value) && options.value >= 0)) &&
158
+ (options.value === undefined || isAmount(options.value)) &&
178
159
  (options.currency === undefined || CURRENCY_PATTERN.test(options.currency)));
179
160
  }
161
+ function isItemText(value) {
162
+ return (typeof value === "string" &&
163
+ value.length >= 1 &&
164
+ value.length <= MAX_ITEM_TEXT_LENGTH);
165
+ }
166
+ function itemsOf(value) {
167
+ if (!Array.isArray(value) || value.length < 1 || value.length > MAX_ITEMS)
168
+ return undefined;
169
+ const items = [];
170
+ for (const item of value) {
171
+ if (typeof item !== "object" || item === null)
172
+ return undefined;
173
+ const { id, name, category, quantity, price } = item;
174
+ if (!isItemText(id) ||
175
+ !isItemText(name) ||
176
+ (category !== undefined && !isItemText(category)) ||
177
+ !Number.isSafeInteger(quantity) ||
178
+ quantity < 1 ||
179
+ (price !== undefined && !isAmount(price)))
180
+ return undefined;
181
+ items.push({
182
+ id,
183
+ name,
184
+ ...(category === undefined ? {} : { category }),
185
+ quantity: quantity,
186
+ ...(price === undefined ? {} : { price }),
187
+ });
188
+ }
189
+ return serializedBytes(items) <= MAX_ITEMS_BYTES ? items : undefined;
190
+ }
191
+ function scheduledForOf(value) {
192
+ if (typeof value !== "string" || !DAY_PATTERN.test(value))
193
+ return undefined;
194
+ const day = new Date(`${value}T00:00:00.000Z`);
195
+ return !Number.isNaN(day.getTime()) && day.toISOString().startsWith(value)
196
+ ? value
197
+ : undefined;
198
+ }
180
199
  function serializedBytes(value) {
181
200
  return textEncoder.encode(JSON.stringify(value)).byteLength;
182
201
  }
183
- /**
184
- * As many events as fit `room`, oldest first. An event that alone exceeds the
185
- * whole keepalive budget can never be sent; one that only exceeds what the
186
- * sends in flight leave waits for them.
187
- */
188
202
  function batchFrom(events, room) {
189
203
  const selected = [];
190
204
  const unsendable = [];
@@ -213,21 +227,9 @@ function createCaptureEngine(ports, acquisition) {
213
227
  let config = { key: "", endpoint: "/v1/events" };
214
228
  let pending = [];
215
229
  let lastDeclaredName;
216
- /**
217
- * Every send in flight, by count, by bytes and by the union of their event
218
- * ids: a step taken and a page hide send beside one rather than wait for
219
- * it, so there can be several, each must leave the others' events alone,
220
- * and together they stay within the keepalive budget.
221
- */
222
230
  let sendsInFlight = 0;
223
231
  let bytesInFlight = 0;
224
232
  const inFlight = new Set();
225
- /**
226
- * The conversions this page emitted and holds for their tag sighting
227
- * window: the instant each was emitted, and whether its report can be
228
- * complete. In memory only — a held conversion is in the stored queue like
229
- * any other, and a reload sends it as it is.
230
- */
231
233
  const held = new Map();
232
234
  let flushTimer;
233
235
  let consecutiveFailures = 0;
@@ -276,11 +278,6 @@ function createCaptureEngine(ports, acquisition) {
276
278
  addDrop(queue, "invalid_event");
277
279
  writeQueue(ports.storage, queue);
278
280
  }
279
- /**
280
- * `buffered` is a conversion made before consent was granted and emitted
281
- * at the grant: its window is placed there, after the conversion itself,
282
- * so its report is never complete.
283
- */
284
281
  function emit(pendingEvent, buffered = false) {
285
282
  if (!EVENT_NAME_PATTERN.test(pendingEvent.name)) {
286
283
  recordInvalidEvent();
@@ -308,16 +305,20 @@ function createCaptureEngine(ports, acquisition) {
308
305
  }
309
306
  if (pendingEvent.kind === "step") {
310
307
  const context = jsonContext(pendingEvent.context);
308
+ const items = itemsOf(pendingEvent.options?.items);
311
309
  persistEvent({
312
310
  ...baseEvent(now, session.id),
313
311
  kind: "step",
314
312
  name: pendingEvent.name,
315
313
  ...(context === undefined ? {} : { context }),
314
+ ...(items === undefined ? {} : { items }),
316
315
  });
317
316
  }
318
317
  else {
319
318
  const options = pendingEvent.options;
320
319
  const context = jsonContext(options.context);
320
+ const items = itemsOf(options.items);
321
+ const scheduledFor = scheduledForOf(options.scheduledFor);
321
322
  const base = baseEvent(now, session.id);
322
323
  if (acquisition.mode !== "verification" &&
323
324
  ports.sightings?.observing() === true) {
@@ -333,6 +334,11 @@ function createCaptureEngine(ports, acquisition) {
333
334
  ? {}
334
335
  : { currency: options.currency }),
335
336
  ...(context === undefined ? {} : { context }),
337
+ ...(items === undefined ? {} : { items }),
338
+ ...(scheduledFor === undefined ? {} : { scheduledFor }),
339
+ ...(typeof options.recurring === "boolean"
340
+ ? { recurring: options.recurring }
341
+ : {}),
336
342
  });
337
343
  }
338
344
  lastDeclaredName = pendingEvent.name;
@@ -348,21 +354,11 @@ function createCaptureEngine(ports, acquisition) {
348
354
  emit(pendingEvent);
349
355
  sendTaken();
350
356
  }
351
- /**
352
- * A step, and a conversion that is not held, leaves when it is taken: a
353
- * click that navigates to another site may fire no hide event at all, and a
354
- * send started by the click itself is the one that arrives ([spec/capture.md]
355
- * § Delivery). An open circuit keeps it queued for the probe.
356
- */
357
357
  function sendTaken() {
358
358
  if (circuit !== "closed" || !PUBLIC_KEY_PATTERN.test(config.key))
359
359
  return;
360
360
  void sendNow();
361
361
  }
362
- /**
363
- * Sends at once what is queued and in no send in flight, beside any send in
364
- * flight, within what the keepalive budget has left.
365
- */
366
362
  async function sendNow() {
367
363
  const queue = readQueue(ports.storage);
368
364
  const ready = queue.events.filter((event) => !held.has(event.eventId) && !inFlight.has(event.eventId));
@@ -379,10 +375,6 @@ function createCaptureEngine(ports, acquisition) {
379
375
  addDrop(queue, "invalid_event", unsendable.length);
380
376
  writeQueue(ports.storage, queue);
381
377
  }
382
- /**
383
- * Gives each held conversion whose window has closed — or every one, at
384
- * page hide — the report of what the port saw around it, and lets it go.
385
- */
386
378
  function release(all) {
387
379
  if (held.size === 0)
388
380
  return;
@@ -394,7 +386,6 @@ function createCaptureEngine(ports, acquisition) {
394
386
  let reported = false;
395
387
  for (const [eventId, hold] of due) {
396
388
  held.delete(eventId);
397
- // Gone from the queue — sent by another tab, or dropped by overflow.
398
389
  const event = queue.events.find((candidate) => candidate.eventId === eventId);
399
390
  const answer = event === undefined
400
391
  ? null
@@ -421,7 +412,6 @@ function createCaptureEngine(ports, acquisition) {
421
412
  if (reported)
422
413
  writeQueue(ports.storage, queue);
423
414
  }
424
- /** Until the earliest held conversion's window closes. */
425
415
  function untilRelease() {
426
416
  const now = ports.clock.now().getTime();
427
417
  let earliest = Number.POSITIVE_INFINITY;
@@ -434,11 +424,6 @@ function createCaptureEngine(ports, acquisition) {
434
424
  release(hidden);
435
425
  if (!initialized || consentState !== "granted")
436
426
  return;
437
- /**
438
- * A page being hidden gets no later chance, so it sends what no send in
439
- * flight carries at once, whatever the circuit's state, and the answer is
440
- * read as any other's.
441
- */
442
427
  if (hidden) {
443
428
  if (PUBLIC_KEY_PATTERN.test(config.key))
444
429
  await sendNow();
@@ -472,11 +457,6 @@ function createCaptureEngine(ports, acquisition) {
472
457
  }
473
458
  await deliver(batch);
474
459
  }
475
- /**
476
- * One send, and its answer. It removes from the stored queue exactly what
477
- * it carried, by its own read, filter and write at the moment it settles,
478
- * so a send beside it keeps what it delivered.
479
- */
480
460
  async function deliver(batch) {
481
461
  const carried = new Set(batch.events.map((event) => event.eventId));
482
462
  const bytes = serializedBytes(batch);
@@ -503,14 +483,6 @@ function createCaptureEngine(ports, acquisition) {
503
483
  scheduleFlush(currentQueue.events.length === 0 ? FLUSH_INTERVAL_MS : 0);
504
484
  return;
505
485
  }
506
- /**
507
- * A 4xx is the server's word that this batch will never be accepted —
508
- * except a 429, which is the server's word that it will be accepted
509
- * later: the ingestion limit is per public key, shared by every visitor
510
- * of one site, so a busy minute answers 429 to visitors whose events
511
- * are sound. Dropping those is silent loss ([spec/capture.md]
512
- * § Delivery); they take the retry path with everything else transient.
513
- */
514
486
  if (response.status >= 400 &&
515
487
  response.status < 500 &&
516
488
  response.status !== 429) {
@@ -551,12 +523,6 @@ function createCaptureEngine(ports, acquisition) {
551
523
  endpoint: options.endpoint ?? "/v1/events",
552
524
  };
553
525
  initialized = true;
554
- /**
555
- * Only a denial is remembered; a grant is the integrator's on every load
556
- * while consent stands, so it never outlives the banner that gave it
557
- * ([spec/capture.md] § Consent first). A grant an earlier runtime
558
- * stored is deleted. A second init keeps the decision this page made.
559
- */
560
526
  if (consentState !== "unknown")
561
527
  return;
562
528
  const storedConsent = safeGet(ports.storage, CONSENT_KEY);
@@ -600,11 +566,12 @@ function createCaptureEngine(ports, acquisition) {
600
566
  return consentState;
601
567
  },
602
568
  },
603
- step(name, context) {
569
+ step(name, context, options) {
604
570
  capture({
605
571
  kind: "step",
606
572
  name,
607
573
  ...(context === undefined ? {} : { context }),
574
+ ...(options === undefined ? {} : { options }),
608
575
  });
609
576
  },
610
577
  conversion(name, options) {
@@ -654,31 +621,12 @@ function createCaptureEngine(ports, acquisition) {
654
621
  },
655
622
  };
656
623
  }
657
- /**
658
- * The browser's clock, and the one file in this package allowed to read it
659
- * ([CLAUDE.md] § Invariants: time is injected). `capture-core` declares the
660
- * port and reads no clock at all — it runs inside sandboxes that have none —
661
- * so the implementation lives here, with the runtime that has a `Date`.
662
- */
663
624
  const systemClock = {
664
625
  now: () => new Date(Date.now()),
665
626
  };
666
- /**
667
- * A Resource Timing entry's start, on the system clock: its reading minus the
668
- * entry's monotonic age. `performance.timeOrigin` would be a second clock, and
669
- * it can disagree with this one by as much as the machine's clock drifted
670
- * since the page loaded; the age is read on one clock and the instant on the
671
- * other, so a sighting and the conversion it is compared with are dated alike
672
- * ([spec/capture.md] § Tag sightings).
673
- */
674
627
  function instantOfEntry(startTime) {
675
628
  return new Date(systemClock.now().getTime() - (performance.now() - startTime));
676
629
  }
677
- /**
678
- * How many matches the port keeps. A page making more tag requests than this
679
- * inside one window is one whose report the port declines to give, never one
680
- * it gives short.
681
- */
682
630
  const TAG_SIGHTING_MEMORY = 100;
683
631
  const ga4IdPattern = new RegExp(TAG_ID_PATTERNS.ga4);
684
632
  const metaIdPattern = new RegExp(TAG_ID_PATTERNS.meta);
@@ -690,7 +638,6 @@ function onMetaEndpoint(url) {
690
638
  return ((host === "facebook.com" || host.endsWith(".facebook.com")) &&
691
639
  (url.pathname === "/tr" || url.pathname === "/tr/"));
692
640
  }
693
- /** A request on Meta's endpoint whose pixel id does not fit is Meta, unread. */
694
641
  function metaMatch(id, event) {
695
642
  return id !== null && metaIdPattern.test(id)
696
643
  ? {
@@ -702,15 +649,6 @@ function metaMatch(id, event) {
702
649
  }
703
650
  : { unread: "meta" };
704
651
  }
705
- /**
706
- * The matching table ([spec/capture.md] § Tag sightings): GA4 and Google Ads
707
- * key on the path and the id, so a regional host and a first-party tagging
708
- * domain that keeps the path both match; Meta keys on its host as well. What
709
- * is answered is the tag's kind, its id and Meta's event — nothing else of
710
- * the URL, which carries the page address and the vendor's client id. Meta's
711
- * beacon leaves an entry named by its bare endpoint, which names no pixel:
712
- * that is Meta, unread.
713
- */
714
652
  function matchTagRequest(url) {
715
653
  let parsed;
716
654
  try {
@@ -744,13 +682,6 @@ function matchTagRequest(url) {
744
682
  }
745
683
  return null;
746
684
  }
747
- /**
748
- * Meta's long request in Chrome: a form posted into a hidden frame, which
749
- * leaves no Resource Timing entry ([spec/capture.md] § Tag sightings, _Meta's
750
- * long request_). Two fields are asked for, the ones that name the pixel and
751
- * the event, and nothing else of the form is read: its other fields carry the
752
- * visitor's identifiers, hashed.
753
- */
754
685
  function matchTagForm(form) {
755
686
  let action;
756
687
  try {
@@ -761,30 +692,14 @@ function matchTagForm(form) {
761
692
  }
762
693
  if (!onMetaEndpoint(action))
763
694
  return null;
764
- const id = form.querySelector('input[name="id"]');
765
- const event = form.querySelector('input[name="ev"]');
695
+ const id = form.querySelector("input[name=\"id\"]");
696
+ const event = form.querySelector("input[name=\"ev\"]");
766
697
  return metaMatch(id?.value ?? null, event?.value ?? null);
767
698
  }
768
- /**
769
- * The browser's own record of the page's requests, read through a buffered
770
- * `PerformanceObserver` once consent is granted and never before — and, for
771
- * the one request that record leaves out, the forms the page's body gains,
772
- * read through a `MutationObserver` on the body's own children. Nothing is
773
- * wrapped, patched or replaced — no `fetch`, no beacon, no vendor's global —
774
- * because the runtime runs on somebody else's page and nothing it does may
775
- * change what another script sees.
776
- */
777
699
  function createTagSightingPort() {
778
700
  let observer;
779
701
  let bodyObserver;
780
- /**
781
- * From when the body's children were watched, on the system clock: minus
782
- * infinity when observation began before the body existed, and so saw every
783
- * form a script added to it; undefined while no body observer runs — never
784
- * created, still waiting for the body, or failed.
785
- */
786
702
  let watchedFrom;
787
- /** Ordered by `at`, oldest first; at most `TAG_SIGHTING_MEMORY`. */
788
703
  let matches = [];
789
704
  function remember(match, at) {
790
705
  if (match === null)
@@ -801,10 +716,6 @@ function createTagSightingPort() {
801
716
  remember(matchTagRequest(entry.name), instantOfEntry(entry.startTime).getTime());
802
717
  }
803
718
  }
804
- /**
805
- * One observer, on the body's children and nothing below them. Before the
806
- * body exists it watches the root's children for the body, and moves to it.
807
- */
808
719
  function watchBody() {
809
720
  try {
810
721
  const document = window.document;
@@ -830,7 +741,6 @@ function createTagSightingPort() {
830
741
  }
831
742
  }
832
743
  catch {
833
- // Capture must never break the host page.
834
744
  }
835
745
  });
836
746
  if (body === null) {
@@ -846,12 +756,9 @@ function createTagSightingPort() {
846
756
  watchedFrom = undefined;
847
757
  }
848
758
  }
849
- /** What was matched inside the window around `at`, or null. */
850
759
  function within(at) {
851
760
  if (observer === undefined)
852
761
  return null;
853
- // What the browser recorded and has not delivered yet: a page being
854
- // hidden may not run the callback before the conversion leaves.
855
762
  record(observer.takeRecords());
856
763
  const from = at.getTime() - TAG_SIGHTING_BEFORE_MS;
857
764
  const to = at.getTime() + TAG_SIGHTING_AFTER_MS;
@@ -923,7 +830,6 @@ function createTagSightingPort() {
923
830
  };
924
831
  }
925
832
  const WEB_PUBLIC_KEY_PATTERN = /^tl_pk_[a-z2-7]{26}$/;
926
- /** The tab's verification nonce, in `sessionStorage`, written at the grant. */
927
833
  const VERIFICATION_KEY = "__tl.v";
928
834
  class MemoryStorage {
929
835
  constructor() {
@@ -945,13 +851,7 @@ let engine;
945
851
  let verification;
946
852
  let configValid = false;
947
853
  let listenersInstalled = false;
948
- /**
949
- * Calls made before `init`, made in order once it has run, up to the same 100
950
- * the engine holds before consent; past that they are dropped
951
- * ([spec/capture.md] § Consent first).
952
- */
953
854
  let early = [];
954
- /** True when there is no engine yet, and the call was held, or dropped. */
955
855
  function heldForInit(call) {
956
856
  if (engine !== undefined)
957
857
  return false;
@@ -967,12 +867,6 @@ function browserStorage() {
967
867
  return new MemoryStorage();
968
868
  }
969
869
  }
970
- /**
971
- * A page opened from a verification session carries the marker and has an
972
- * opener. Once consent is granted there, the tab keeps the nonce, so the mark
973
- * follows it to the site's next pages and back from a payment taken
974
- * elsewhere, to the same origin ([spec/capture.md] § Verification mode).
975
- */
976
870
  function verificationMode() {
977
871
  const nonce = new URL(window.location.href).searchParams.get("__tl_verify");
978
872
  if (nonce !== null && nonce.length > 0 && window.opener !== null) {
@@ -983,7 +877,6 @@ function verificationMode() {
983
877
  kept = window.sessionStorage.getItem(VERIFICATION_KEY);
984
878
  }
985
879
  catch {
986
- // An unreadable tab storage keeps no mark.
987
880
  }
988
881
  return kept === null || kept.length === 0
989
882
  ? undefined
@@ -998,7 +891,6 @@ function keepVerification(keep) {
998
891
  }
999
892
  }
1000
893
  catch {
1001
- // A tab that cannot keep it marks this page only.
1002
894
  }
1003
895
  }
1004
896
  function landingPage() {
@@ -1179,10 +1071,10 @@ const TraceLog = {
1179
1071
  return engine?.consent.state() ?? "unknown";
1180
1072
  },
1181
1073
  },
1182
- step(name, context) {
1183
- if (heldForInit(() => TraceLog.step(name, context)))
1074
+ step(name, context, options) {
1075
+ if (heldForInit(() => TraceLog.step(name, context, options)))
1184
1076
  return;
1185
- engine?.step(name, context);
1077
+ engine?.step(name, context, options);
1186
1078
  reportDiagnostic();
1187
1079
  },
1188
1080
  conversion(name, options) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tracelog/capture-web",
3
- "version": "2.0.0",
3
+ "version": "2.1.0",
4
4
  "description": "The TraceLog browser capture runtime: consent-first, pinned per version.",
5
5
  "keywords": [
6
6
  "conversion",
@@ -45,8 +45,9 @@
45
45
  "access": "public"
46
46
  },
47
47
  "devDependencies": {
48
- "@tracelog/capture-core": "2.0.0",
49
- "@tracelog/event-contract": "2.0.0"
48
+ "typescript": "5.9.3",
49
+ "@tracelog/capture-core": "2.1.0",
50
+ "@tracelog/event-contract": "2.1.0"
50
51
  },
51
52
  "scripts": {
52
53
  "build": "tsc -p tsconfig.build.json && node build.mjs",