@tracelog/lib 3.2.0 → 3.3.0-rc.124.4

package/dist/public-api.d.mts

@@ -393,6 +393,20 @@ 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
@@ -1474,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.
@@ -1505,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.
+     * Generates a deterministic navigation identifier for deduplication.
      *
-     * **ID Format**: `{timestamp}_{pathname}` or `{timestamp}_{pathname}_{counter}`
+     * **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).
      *
-     * **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
+     * **ID Format**: `{startTime}_{pathname}` or `{startTime}_{pathname}_{counter}`
      *
-     * **Why Deterministic**:
-     * - Previous implementation used random string → duplicate metrics on page reload
-     * - Now: Same navigation = same ID = proper deduplication via reportedByNav Map
+     * **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
      *
@@ -1607,6 +1625,15 @@ declare class ErrorHandler extends StateManager {
     private readonly handleRejection;
     private extractRejectionMessage;
     private sanitize;
+    /**
+     * Sanitizes an error message and guarantees a non-empty result.
+     *
+     * An empty `error_data.message` (from a `Promise.reject('')`, `new Error('')`,
+     * or `{ message: '' }` reason — all of which stringify to '') is rejected by
+     * the ingestion DTO, which 400s the whole batch and drops the co-traveling
+     * events. Every error path must fall back to a non-empty placeholder.
+     */
+    private sanitizeMessage;
     private shouldSuppressError;
     private static readonly TRUNCATION_SUFFIX;
     private truncateStack;

package/dist/public-api.d.ts

@@ -393,6 +393,20 @@ 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
@@ -1474,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.
@@ -1505,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.
+     * Generates a deterministic navigation identifier for deduplication.
      *
-     * **ID Format**: `{timestamp}_{pathname}` or `{timestamp}_{pathname}_{counter}`
+     * **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).
      *
-     * **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
+     * **ID Format**: `{startTime}_{pathname}` or `{startTime}_{pathname}_{counter}`
      *
-     * **Why Deterministic**:
-     * - Previous implementation used random string → duplicate metrics on page reload
-     * - Now: Same navigation = same ID = proper deduplication via reportedByNav Map
+     * **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
      *
@@ -1607,6 +1625,15 @@ declare class ErrorHandler extends StateManager {
     private readonly handleRejection;
     private extractRejectionMessage;
     private sanitize;
+    /**
+     * Sanitizes an error message and guarantees a non-empty result.
+     *
+     * An empty `error_data.message` (from a `Promise.reject('')`, `new Error('')`,
+     * or `{ message: '' }` reason — all of which stringify to '') is rejected by
+     * the ingestion DTO, which 400s the whole batch and drops the co-traveling
+     * events. Every error path must fall back to a non-empty placeholder.
+     */
+    private sanitizeMessage;
     private shouldSuppressError;
     private static readonly TRUNCATION_SUFFIX;
     private truncateStack;