@tracelog/lib 3.1.1 → 3.2.0-rc.123.9

package/dist/public-api.d.mts

@@ -393,6 +393,27 @@ interface Config {
             projectId: string;
             /** Enable Shopify cart attribute linking for webhook revenue attribution. */
             shopify?: boolean;
+            /**
+             * Opt into "Accuracy mode": send events through the merchant's own first-party
+             * subdomain (`https://{projectId}.{rootDomain}/collect`, a CNAME → middleware)
+             * instead of the default hosted endpoint (`https://ingest.tracelog.io/p/{projectId}/collect`).
+             *
+             * Leave unset (the default) and events post to the hosted endpoint with zero DNS
+             * setup — the snippet works the moment it is pasted. Only enable this once the
+             * CNAME (and the domain-ownership TXT record) are verified; the dashboard surfaces
+             * this flag in the snippet only after verification, so the lib never points at an
+             * unresolved subdomain. First-party transport recovers ~10–30% of visits that
+             * ad-blockers strip from third-party hosts.
+             * @default false
+             */
+            firstParty?: boolean;
+            /**
+             * Emit a low-frequency diagnostic "health beacon" when ingest is rejected at the domain
+             * gate (HTTP 403) so the dashboard can tell the merchant their snippet is alive but their
+             * events are blocked. Diagnostic only — it never carries analytics data. Set `false` to opt out.
+             * @default true
+             */
+            healthBeacon?: boolean;
         };
     };
 }
@@ -1467,6 +1488,8 @@ declare class PerformanceHandler extends StateManager {
     private readonly observers;
     private vitalThresholds;
     private navigationCounter;
+    private currentNavBase;
+    private currentNavId;
     constructor(eventManager: EventManager);
     /**
      * Starts tracking Web Vitals and performance metrics.
@@ -1498,21 +1521,23 @@ declare class PerformanceHandler extends StateManager {
     private sendVital;
     private trackWebVital;
     /**
-     * Generates a unique navigation identifier for deduplication.
-     *
-     * **Purpose**: Creates deterministic IDs to prevent duplicate Web Vitals reporting
-     * across multiple metrics for the same navigation event.
-     *
-     * **ID Format**: `{timestamp}_{pathname}` or `{timestamp}_{pathname}_{counter}`
-     *
-     * **Edge Case Handling**:
-     * - If multiple navigations occur to the same pathname in the same millisecond,
-     *   a counter suffix is appended (e.g., `1234.56_/home_2`)
-     * - Counter only added when > 1 to minimize ID length for common case
-     *
-     * **Why Deterministic**:
-     * - Previous implementation used random string → duplicate metrics on page reload
-     * - Now: Same navigation = same ID = proper deduplication via reportedByNav Map
+     * Generates a deterministic navigation identifier for deduplication.
+     *
+     * **Purpose**: Every call within the same navigation must return the SAME id,
+     * so `reportedByNav` can collapse duplicate Web Vitals (one emission per
+     * metric type per navigation — critical for the fallback observers, which
+     * fire per entry batch).
+     *
+     * **ID Format**: `{startTime}_{pathname}` or `{startTime}_{pathname}_{counter}`
+     *
+     * **Determinism**:
+     * - Base id is derived only from the navigation entry's `startTime` (0 by spec
+     *   for the document navigation — no `performance.now()` fallback, which made
+     *   every call unique) and the current pathname.
+     * - The id is cached per navigation; the counter suffix is appended ONLY on a
+     *   real collision: a new navigation whose base id was already reported
+     *   (SPA revisit to the same path, e.g. A→B→A), so the revisit's vitals are
+     *   not suppressed by the first visit's dedup entries.
      *
      * @returns Navigation ID string or null if navigation timing unavailable
      *

package/dist/public-api.d.ts

@@ -393,6 +393,27 @@ interface Config {
             projectId: string;
             /** Enable Shopify cart attribute linking for webhook revenue attribution. */
             shopify?: boolean;
+            /**
+             * Opt into "Accuracy mode": send events through the merchant's own first-party
+             * subdomain (`https://{projectId}.{rootDomain}/collect`, a CNAME → middleware)
+             * instead of the default hosted endpoint (`https://ingest.tracelog.io/p/{projectId}/collect`).
+             *
+             * Leave unset (the default) and events post to the hosted endpoint with zero DNS
+             * setup — the snippet works the moment it is pasted. Only enable this once the
+             * CNAME (and the domain-ownership TXT record) are verified; the dashboard surfaces
+             * this flag in the snippet only after verification, so the lib never points at an
+             * unresolved subdomain. First-party transport recovers ~10–30% of visits that
+             * ad-blockers strip from third-party hosts.
+             * @default false
+             */
+            firstParty?: boolean;
+            /**
+             * Emit a low-frequency diagnostic "health beacon" when ingest is rejected at the domain
+             * gate (HTTP 403) so the dashboard can tell the merchant their snippet is alive but their
+             * events are blocked. Diagnostic only — it never carries analytics data. Set `false` to opt out.
+             * @default true
+             */
+            healthBeacon?: boolean;
         };
     };
 }
@@ -1467,6 +1488,8 @@ declare class PerformanceHandler extends StateManager {
     private readonly observers;
     private vitalThresholds;
     private navigationCounter;
+    private currentNavBase;
+    private currentNavId;
     constructor(eventManager: EventManager);
     /**
      * Starts tracking Web Vitals and performance metrics.
@@ -1498,21 +1521,23 @@ declare class PerformanceHandler extends StateManager {
     private sendVital;
     private trackWebVital;
     /**
-     * Generates a unique navigation identifier for deduplication.
-     *
-     * **Purpose**: Creates deterministic IDs to prevent duplicate Web Vitals reporting
-     * across multiple metrics for the same navigation event.
-     *
-     * **ID Format**: `{timestamp}_{pathname}` or `{timestamp}_{pathname}_{counter}`
-     *
-     * **Edge Case Handling**:
-     * - If multiple navigations occur to the same pathname in the same millisecond,
-     *   a counter suffix is appended (e.g., `1234.56_/home_2`)
-     * - Counter only added when > 1 to minimize ID length for common case
-     *
-     * **Why Deterministic**:
-     * - Previous implementation used random string → duplicate metrics on page reload
-     * - Now: Same navigation = same ID = proper deduplication via reportedByNav Map
+     * Generates a deterministic navigation identifier for deduplication.
+     *
+     * **Purpose**: Every call within the same navigation must return the SAME id,
+     * so `reportedByNav` can collapse duplicate Web Vitals (one emission per
+     * metric type per navigation — critical for the fallback observers, which
+     * fire per entry batch).
+     *
+     * **ID Format**: `{startTime}_{pathname}` or `{startTime}_{pathname}_{counter}`
+     *
+     * **Determinism**:
+     * - Base id is derived only from the navigation entry's `startTime` (0 by spec
+     *   for the document navigation — no `performance.now()` fallback, which made
+     *   every call unique) and the current pathname.
+     * - The id is cached per navigation; the counter suffix is appended ONLY on a
+     *   real collision: a new navigation whose base id was already reported
+     *   (SPA revisit to the same path, e.g. A→B→A), so the revisit's vitals are
+     *   not suppressed by the first visit's dedup entries.
      *
      * @returns Navigation ID string or null if navigation timing unavailable
      *