@duffcloudservices/telemetry 0.2.0 → 0.3.0

package/src/syntheticCapture.test.ts

@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { SYNTHETIC_CAPTURE_PARAMS, syntheticCaptureDetected } from './syntheticCapture'
+
+/**
+ * C-614. Both directions matter and they are NOT symmetric:
+ *
+ *  - Under-detecting re-creates the measured defect (49 synthetic vs 14 organic
+ *    pageViews on coron8 over the 8 days to 2026-08-11).
+ *  - Over-detecting silently DELETES real visits, and a missing pageView leaves
+ *    nothing behind to notice it by. The "real visit" cases are therefore the
+ *    load-bearing half.
+ */
+
+const originalLocation = window.location
+
+function setSearch(search: string) {
+  Object.defineProperty(window, 'location', {
+    configurable: true,
+    value: { hostname: 'duffcloudservices.com', pathname: '/', search } as Location,
+  })
+}
+
+afterEach(() => {
+  Object.defineProperty(window, 'location', { configurable: true, value: originalLocation })
+})
+
+describe('syntheticCaptureDetected', () => {
+  it.each(SYNTHETIC_CAPTURE_PARAMS)('detects the valueless %s the capture pass emits', (param) => {
+    setSearch(`?${param}=`)
+    expect(syntheticCaptureDetected()).toBe(true)
+  })
+
+  it('detects a marker appended after existing parameters', () => {
+    setSearch('?utm_source=newsletter&dcs-no-telemetry=')
+    expect(syntheticCaptureDetected()).toBe(true)
+  })
+
+  it('counts a bare visit', () => {
+    setSearch('')
+    expect(syntheticCaptureDetected()).toBe(false)
+  })
+
+  it('counts a campaign visit', () => {
+    setSearch('?utm_source=google&utm_medium=cpc&gclid=abc123')
+    expect(syntheticCaptureDetected()).toBe(false)
+  })
+
+  it('does not match a lookalike value or a substring', () => {
+    setSearch('?ref=dcs-hide-ribbon&note=dcs-no-telemetry-please')
+    expect(syntheticCaptureDetected()).toBe(false)
+  })
+
+  it('re-reads the URL rather than caching the first verdict', () => {
+    setSearch('?dcs-no-telemetry=')
+    expect(syntheticCaptureDetected()).toBe(true)
+    setSearch('')
+    expect(syntheticCaptureDetected()).toBe(false)
+  })
+
+  it('fails OPEN when the query string cannot be read', () => {
+    Object.defineProperty(window, 'location', {
+      configurable: true,
+      value: {
+        hostname: 'duffcloudservices.com',
+        pathname: '/',
+        get search(): string {
+          throw new Error('unreadable location')
+        },
+      } as unknown as Location,
+    })
+    expect(syntheticCaptureDetected()).toBe(false)
+  })
+})

package/src/syntheticCapture.ts

@@ -0,0 +1,50 @@
+/**
+ * Synthetic-capture detection (C-614).
+ *
+ * The post-deploy "Capture page snapshots" CI step drives real Chromium against
+ * the LIVE production URL of the site it just deployed, so the site's telemetry
+ * boots exactly as it would for a visitor and every page the capture walked is
+ * recorded as a production pageView — during our own deploy run. Measured on
+ * coron8 over the 8 days to 2026-08-11: 49 synthetic pageViews against 14
+ * organic, 78% of the entire store, all 49 on 08-11 across 5 deploys versus 3
+ * real visits that day.
+ *
+ * The capture tooling marks every URL it loads (`packages/cli/src/commands/
+ * capture-snapshots.ts` and each site's own `scripts/capture-snapshots.*`).
+ * `initialize()` reads that mark and declines, so nothing is emitted at all.
+ * Suppressing here rather than tagging and filtering downstream keeps the
+ * denominator honest in every read path at once instead of obliging each of
+ * them to remember an exclusion — the C-430 preview/localhost blend is the
+ * recorded UNSOLVED residual that shape produces.
+ *
+ * DELIBERATE DUPLICATION. `@duffcloudservices/cms` carries the same predicate in
+ * its own `syntheticCapture.ts`. These two packages are intentionally decoupled
+ * — this one is the low-level telemetry package (peer deps: the App Insights SDK
+ * and vue, nothing else), cms is the site-content package — and a dependency
+ * edge between them to share ten lines of pure string matching would cost more
+ * than the duplication does. The parameter list is the contract; keep the two
+ * lists identical, and note that the CI drift guard in the canonical
+ * site-deploy workflow greps for these same names.
+ */
+
+/** Query parameters that mark a document as an automated capture, not a visit. */
+export const SYNTHETIC_CAPTURE_PARAMS = ['dcs-hide-ribbon', 'dcs-no-telemetry'] as const
+
+/**
+ * Whether this document is an automated capture rather than a visit worth counting.
+ *
+ * Reads `window.location.search` on every call rather than caching, so a
+ * client-side route change is judged on the CURRENT URL. Returns `false` on the
+ * server, and `false` when the query string cannot be read: over-suppression
+ * deletes real visits and leaves no trace to notice it by, so this fails OPEN.
+ */
+export function syntheticCaptureDetected(): boolean {
+  if (typeof window === 'undefined') return false
+
+  try {
+    const params = new URLSearchParams(window.location.search)
+    return SYNTHETIC_CAPTURE_PARAMS.some((param) => params.has(param))
+  } catch {
+    return false
+  }
+}