@tracelog/capture-web 2.3.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -18,6 +18,20 @@ 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.4.0](https://github.com/nacorga/tracelog-sdk/compare/capture-web@2.3.1...capture-web@2.4.0) (2026-10-26)
22
+
23
+
24
+ ### Added
25
+
26
+ * **capture-web:** the first in the published types ([154032e](https://github.com/nacorga/tracelog-sdk/commit/154032e137540c007771a3e60ad1657494b975af))
27
+
28
+ ## [2.3.1](https://github.com/nacorga/tracelog-sdk/compare/capture-web@2.3.0...capture-web@2.3.1) (2026-10-26)
29
+
30
+
31
+ ### Fixed
32
+
33
+ * **capture-web:** a deferred runtime rules out the Meta form it could not have missed ([aa0eb2b](https://github.com/nacorga/tracelog-sdk/commit/aa0eb2b3506d0ba7bfb9549e9a5f851af89b4577))
34
+
21
35
  ## [2.3.0](https://github.com/nacorga/tracelog-sdk/compare/capture-web@2.2.0...capture-web@2.3.0) (2026-10-17)
22
36
 
23
37
 
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.3.0
25
+ npm install --save-exact @tracelog/capture-web@2.4.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.3.0/tracelog.js"></script>
31
+ <script src="https://cdn.tracelog.io/v/2.4.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?, 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. |
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, and `opts.first` whether it is the person's first. |
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 —
@@ -104,9 +104,9 @@ views, not clicks, not scroll, not keystrokes. Errors are captured only when
104
104
  they occur inside the conversion path, attached to the step where they
105
105
  happened.
106
106
 
107
- A conversion may carry its items, the day a booking is for and whether it
108
- recurs, and a step the items it shows; a malformed one is left out and the
109
- event sent without it.
107
+ A conversion may carry its items, the day a booking is for, whether it recurs
108
+ and whether it is the person's first, and a step the items it shows; a
109
+ malformed one is left out and the event sent without it.
110
110
 
111
111
  Beside each conversion, which GA4, Meta and Google Ads tags the page requested
112
112
  just before and after it — the tag's kind, its id and, for Meta, the event —
@@ -29,6 +29,8 @@ export interface ConversionOptions {
29
29
  /** The day a booking is for, YYYY-MM-DD. */
30
30
  scheduledFor?: string;
31
31
  recurring?: boolean;
32
+ /** Whether the site's records hold no earlier conversion of this kind by the same person. */
33
+ first?: boolean;
32
34
  }
33
35
 
34
36
  declare const TraceLog: {
@@ -351,6 +351,7 @@ function createCaptureEngine(ports, acquisition) {
351
351
  ...(typeof options.recurring === "boolean"
352
352
  ? { recurring: options.recurring }
353
353
  : {}),
354
+ ...(typeof options.first === "boolean" ? { first: options.first } : {}),
354
355
  });
355
356
  }
356
357
  lastDeclaredName = pendingEvent.name;
@@ -644,6 +645,7 @@ function instantOfEntry(startTime) {
644
645
  return new Date(systemClock.now().getTime() - (performance.now() - startTime));
645
646
  }
646
647
  const TAG_SIGHTING_MEMORY = 100;
648
+ const RESOURCE_TIMING_BUFFER = 250;
647
649
  const ga4IdPattern = new RegExp(TAG_ID_PATTERNS.ga4);
648
650
  const metaIdPattern = new RegExp(TAG_ID_PATTERNS.meta);
649
651
  const adsIdPattern = new RegExp(TAG_ID_PATTERNS.google_ads);
@@ -654,6 +656,16 @@ function onMetaEndpoint(url) {
654
656
  return ((host === "facebook.com" || host.endsWith(".facebook.com")) &&
655
657
  (url.pathname === "/tr" || url.pathname === "/tr/"));
656
658
  }
659
+ function isMetaConfiguration(url) {
660
+ try {
661
+ const parsed = new URL(url);
662
+ return (parsed.hostname === "connect.facebook.net" &&
663
+ parsed.pathname.startsWith("/signals/config/"));
664
+ }
665
+ catch {
666
+ return false;
667
+ }
668
+ }
657
669
  function metaMatch(id, event) {
658
670
  return id !== null && metaIdPattern.test(id)
659
671
  ? {
@@ -716,6 +728,9 @@ function createTagSightingPort() {
716
728
  let observer;
717
729
  let bodyObserver;
718
730
  let watchedFrom;
731
+ let metaFrom = Number.POSITIVE_INFINITY;
732
+ let startedAt = 0;
733
+ let buffered = 0;
719
734
  let matches = [];
720
735
  function remember(match, at) {
721
736
  if (match === null)
@@ -729,7 +744,19 @@ function createTagSightingPort() {
729
744
  }
730
745
  function record(entries) {
731
746
  for (const entry of entries) {
732
- remember(matchTagRequest(entry.name), instantOfEntry(entry.startTime).getTime());
747
+ if (entry.startTime < startedAt)
748
+ buffered += 1;
749
+ const at = instantOfEntry(entry.startTime).getTime();
750
+ const match = matchTagRequest(entry.name);
751
+ remember(match, at);
752
+ const meta = match !== null &&
753
+ ("unread" in match ? match.unread : match.sighting.kind) === "meta";
754
+ if (meta) {
755
+ metaFrom = Math.min(metaFrom, at);
756
+ }
757
+ else if (isMetaConfiguration(entry.name)) {
758
+ metaFrom = Math.min(metaFrom, instantOfEntry(entry.startTime + entry.duration).getTime());
759
+ }
733
760
  }
734
761
  }
735
762
  function watchBody() {
@@ -796,6 +823,7 @@ function createTagSightingPort() {
796
823
  return;
797
824
  }
798
825
  const created = new Observer((list) => record(list.getEntries()));
826
+ startedAt = performance.now();
799
827
  created.observe({ type: "resource", buffered: true });
800
828
  observer = created;
801
829
  }
@@ -811,6 +839,8 @@ function createTagSightingPort() {
811
839
  bodyObserver?.disconnect();
812
840
  bodyObserver = undefined;
813
841
  watchedFrom = undefined;
842
+ metaFrom = Number.POSITIVE_INFINITY;
843
+ buffered = 0;
814
844
  matches = [];
815
845
  },
816
846
  observing() {
@@ -836,11 +866,12 @@ function createTagSightingPort() {
836
866
  },
837
867
  unreadAround(at) {
838
868
  const found = within(at);
839
- if (found === null ||
840
- watchedFrom === undefined ||
841
- watchedFrom > at.getTime() - TAG_SIGHTING_BEFORE_MS) {
869
+ if (found === null || watchedFrom === undefined)
870
+ return null;
871
+ const missedNone = watchedFrom <= at.getTime() - TAG_SIGHTING_BEFORE_MS ||
872
+ (watchedFrom <= metaFrom && buffered < RESOURCE_TIMING_BUFFER);
873
+ if (!missedNone)
842
874
  return null;
843
- }
844
875
  return tagSightingKinds.filter((kind) => found.some((match) => "unread" in match && match.unread === kind));
845
876
  },
846
877
  };
@@ -352,6 +352,7 @@ function createCaptureEngine(ports, acquisition) {
352
352
  ...(typeof options.recurring === "boolean"
353
353
  ? { recurring: options.recurring }
354
354
  : {}),
355
+ ...(typeof options.first === "boolean" ? { first: options.first } : {}),
355
356
  });
356
357
  }
357
358
  lastDeclaredName = pendingEvent.name;
@@ -645,6 +646,7 @@ function instantOfEntry(startTime) {
645
646
  return new Date(systemClock.now().getTime() - (performance.now() - startTime));
646
647
  }
647
648
  const TAG_SIGHTING_MEMORY = 100;
649
+ const RESOURCE_TIMING_BUFFER = 250;
648
650
  const ga4IdPattern = new RegExp(TAG_ID_PATTERNS.ga4);
649
651
  const metaIdPattern = new RegExp(TAG_ID_PATTERNS.meta);
650
652
  const adsIdPattern = new RegExp(TAG_ID_PATTERNS.google_ads);
@@ -655,6 +657,16 @@ function onMetaEndpoint(url) {
655
657
  return ((host === "facebook.com" || host.endsWith(".facebook.com")) &&
656
658
  (url.pathname === "/tr" || url.pathname === "/tr/"));
657
659
  }
660
+ function isMetaConfiguration(url) {
661
+ try {
662
+ const parsed = new URL(url);
663
+ return (parsed.hostname === "connect.facebook.net" &&
664
+ parsed.pathname.startsWith("/signals/config/"));
665
+ }
666
+ catch {
667
+ return false;
668
+ }
669
+ }
658
670
  function metaMatch(id, event) {
659
671
  return id !== null && metaIdPattern.test(id)
660
672
  ? {
@@ -717,6 +729,9 @@ function createTagSightingPort() {
717
729
  let observer;
718
730
  let bodyObserver;
719
731
  let watchedFrom;
732
+ let metaFrom = Number.POSITIVE_INFINITY;
733
+ let startedAt = 0;
734
+ let buffered = 0;
720
735
  let matches = [];
721
736
  function remember(match, at) {
722
737
  if (match === null)
@@ -730,7 +745,19 @@ function createTagSightingPort() {
730
745
  }
731
746
  function record(entries) {
732
747
  for (const entry of entries) {
733
- remember(matchTagRequest(entry.name), instantOfEntry(entry.startTime).getTime());
748
+ if (entry.startTime < startedAt)
749
+ buffered += 1;
750
+ const at = instantOfEntry(entry.startTime).getTime();
751
+ const match = matchTagRequest(entry.name);
752
+ remember(match, at);
753
+ const meta = match !== null &&
754
+ ("unread" in match ? match.unread : match.sighting.kind) === "meta";
755
+ if (meta) {
756
+ metaFrom = Math.min(metaFrom, at);
757
+ }
758
+ else if (isMetaConfiguration(entry.name)) {
759
+ metaFrom = Math.min(metaFrom, instantOfEntry(entry.startTime + entry.duration).getTime());
760
+ }
734
761
  }
735
762
  }
736
763
  function watchBody() {
@@ -797,6 +824,7 @@ function createTagSightingPort() {
797
824
  return;
798
825
  }
799
826
  const created = new Observer((list) => record(list.getEntries()));
827
+ startedAt = performance.now();
800
828
  created.observe({ type: "resource", buffered: true });
801
829
  observer = created;
802
830
  }
@@ -812,6 +840,8 @@ function createTagSightingPort() {
812
840
  bodyObserver?.disconnect();
813
841
  bodyObserver = undefined;
814
842
  watchedFrom = undefined;
843
+ metaFrom = Number.POSITIVE_INFINITY;
844
+ buffered = 0;
815
845
  matches = [];
816
846
  },
817
847
  observing() {
@@ -837,11 +867,12 @@ function createTagSightingPort() {
837
867
  },
838
868
  unreadAround(at) {
839
869
  const found = within(at);
840
- if (found === null ||
841
- watchedFrom === undefined ||
842
- watchedFrom > at.getTime() - TAG_SIGHTING_BEFORE_MS) {
870
+ if (found === null || watchedFrom === undefined)
871
+ return null;
872
+ const missedNone = watchedFrom <= at.getTime() - TAG_SIGHTING_BEFORE_MS ||
873
+ (watchedFrom <= metaFrom && buffered < RESOURCE_TIMING_BUFFER);
874
+ if (!missedNone)
843
875
  return null;
844
- }
845
876
  return tagSightingKinds.filter((kind) => found.some((match) => "unread" in match && match.unread === kind));
846
877
  },
847
878
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tracelog/capture-web",
3
- "version": "2.3.0",
3
+ "version": "2.4.0",
4
4
  "description": "The TraceLog browser capture runtime: consent-first, pinned per version.",
5
5
  "keywords": [
6
6
  "conversion",
@@ -46,8 +46,8 @@
46
46
  },
47
47
  "devDependencies": {
48
48
  "typescript": "5.9.3",
49
- "@tracelog/capture-core": "2.3.0",
50
- "@tracelog/event-contract": "2.3.0"
49
+ "@tracelog/capture-core": "2.4.0",
50
+ "@tracelog/event-contract": "2.4.0"
51
51
  },
52
52
  "scripts": {
53
53
  "build": "tsc -p tsconfig.build.json && node build.mjs",