@duffcloudservices/telemetry 0.1.0 → 0.2.1

package/package.json

@@ -1,9 +1,29 @@
 {
   "name": "@duffcloudservices/telemetry",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Shared Azure Application Insights telemetry for DCS Vue sites — one App Insights config (with the bfcache-safe unload fix) and a useTelemetry composable.",
   "type": "module",
   "sideEffects": false,
+  "//exports": [
+    "WORKSPACE consumers resolve SOURCE; PUBLISHED consumers resolve dist (see publishConfig",
+    "below, which pnpm substitutes into the packed package.json at publish time).",
+    "",
+    "WHY. dist/ is git-ignored build output, so on any clean checkout it does not exist until",
+    "`pnpm run bootstrap` has run. An exports map that points only at ./dist/* therefore makes",
+    "every subpath UNRESOLVABLE on a fresh tree -- the failure is not a type error, it is vite",
+    "refusing the import outright: 'Failed to resolve import",
+    "\"@duffcloudservices/telemetry/journey\" from \"src/composables/useTelemetry.ts\"'. That is",
+    "what put `Portal / Admin vitest` red on main (board C-470): the Test Gate job builds the",
+    "contracts package but not this one, so 8 portal spec files died at import. Pointing the",
+    "workspace at src/ removes the ordering requirement instead of adding one more build step",
+    "for a future job to forget. It also matches what web/ already did unilaterally via a vite",
+    "alias + tsconfig path to packages/telemetry/src -- this generalises that to every consumer.",
+    "",
+    "SAFE because every consumer of the workspace copy (portal, web) is a vite/vitest app that",
+    "compiles TS anyway, and the SDK + vue stay peer deps resolved from the consumer either way.",
+    "The npm tarball is unaffected: publishConfig restores the dist-only map, which is verified",
+    "by `pnpm pack` inspection, and prepublishOnly still builds dist first."
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -12,6 +32,10 @@
     "./config": {
       "types": "./dist/config.d.ts",
       "import": "./dist/config.js"
+    },
+    "./journey": {
+      "types": "./dist/journey.d.ts",
+      "import": "./dist/journey.js"
     }
   },
   "main": "./dist/index.js",
@@ -21,15 +45,6 @@
     "dist",
     "src"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "type-check": "tsc --noEmit",
-    "lint": "eslint src --ext .ts",
-    "prepublishOnly": "pnpm run build"
-  },
   "peerDependencies": {
     "@microsoft/applicationinsights-web": "^3.3.0",
     "vue": "^3.4.0"
@@ -37,9 +52,13 @@
   "devDependencies": {
     "@microsoft/applicationinsights-web": "^3.3.10",
     "@types/node": "^22.0.0",
+    "@vitest/eslint-plugin": "^1.3.4",
+    "eslint": "^9.31.0",
+    "jiti": "^2.4.2",
     "jsdom": "^26.0.0",
     "tsup": "^8.0.0",
     "typescript": "~5.8.0",
+    "typescript-eslint": "^8.48.1",
     "vitest": "^3.2.3",
     "vue": "^3.5.18"
   },
@@ -66,5 +85,14 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
   }
-}
+}

package/src/composable.test.ts

@@ -1,7 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 // Mock the App Insights web SDK so we can assert what the composable passes to
-// it (config + track* calls) without loading the real SDK or sending telemetry.
+// the SDK (config + track* calls) without loading the real SDK or sending telemetry.
 //
 // NOTE: the `ApplicationInsights` mock implementation must PERSIST across the
 // per-test `vi.resetModules()` — the composable's module-level singleton is
@@ -11,6 +11,8 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 // ApplicationInsights()` would yield a bare object). Mirrors web/'s test.
 const trackEventMock = vi.fn()
 const trackPageViewMock = vi.fn()
+const startTrackPageMock = vi.fn()
+const stopTrackPageMock = vi.fn()
 const loadAppInsightsMock = vi.fn()
 const addTelemetryInitializerMock = vi.fn()
 const constructorConfigs: unknown[] = []
@@ -28,8 +30,8 @@ vi.mock('@microsoft/applicationinsights-web', () => {
         trackDependencyData: vi.fn(),
         trackMetric: vi.fn(),
         flush: vi.fn(),
-        startTrackPage: vi.fn(),
-        stopTrackPage: vi.fn(),
+        startTrackPage: startTrackPageMock,
+        stopTrackPage: stopTrackPageMock,
       }
     }),
   }
@@ -48,6 +50,8 @@ describe('useTelemetry', () => {
   beforeEach(() => {
     trackEventMock.mockReset()
     trackPageViewMock.mockReset()
+    startTrackPageMock.mockReset()
+    stopTrackPageMock.mockReset()
     loadAppInsightsMock.mockReset()
     addTelemetryInitializerMock.mockReset()
     warnSpy.mockClear()
@@ -131,4 +135,196 @@ describe('useTelemetry', () => {
     t.trackEvent({ name: 'ping' })
     expect(trackEventMock.mock.calls[0][0].properties.app_name).toBe('dcs-site')
   })
+  // ── C-288 / C-291: page-view double-count guard ──────────────────────────────
+  //
+  // The App Insights SDK's enableAutoRouteTracking already emits one pageView per
+  // navigation. A consumer that also calls trackPageView() on route change counts
+  // every page twice — measured on the live Just Posh site as 509 duplicates out of
+  // 971 human page views (52%), which the portal then reported to the owner.
+
+  it('skips trackPageView when the SDK is already auto-tracking routes', async () => {
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({
+      connectionString: CONNECTION_STRING,
+      enableAutoRouteTracking: true,
+    })
+    t.initialize()
+
+    t.trackPageView()
+    t.trackPageView({ name: 'Services' })
+
+    expect(trackPageViewMock).not.toHaveBeenCalled()
+    expect(
+      warnSpy.mock.calls.some((c) => String(c[0]).includes('double-counting')),
+    ).toBe(true)
+  })
+
+  it('warns about double-counting only once, not per navigation', async () => {
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({
+      connectionString: CONNECTION_STRING,
+      enableAutoRouteTracking: true,
+    })
+    t.initialize()
+
+    t.trackPageView()
+    t.trackPageView()
+    t.trackPageView()
+
+    expect(
+      warnSpy.mock.calls.filter((c) => String(c[0]).includes('double-counting')),
+    ).toHaveLength(1)
+  })
+
+  it('defaults to auto-route tracking, so an unconfigured consumer cannot double-count', async () => {
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({ connectionString: CONNECTION_STRING })
+    t.initialize()
+
+    t.trackPageView()
+
+    expect(trackPageViewMock).not.toHaveBeenCalled()
+  })
+
+  it('sends trackPageView when the consumer owns page views (auto-route off)', async () => {
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({
+      connectionString: CONNECTION_STRING,
+      enableAutoRouteTracking: false,
+    })
+    t.initialize()
+
+    t.trackPageView({ name: 'Services', uri: '/services' })
+
+    expect(trackPageViewMock).toHaveBeenCalledTimes(1)
+    expect(trackPageViewMock.mock.calls[0][0].name).toBe('Services')
+  })
+
+  it('honours an explicit force override for a verified routing edge case', async () => {
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({
+      connectionString: CONNECTION_STRING,
+      enableAutoRouteTracking: true,
+    })
+    t.initialize()
+
+    t.trackPageView({ name: 'Hash route', force: true })
+
+    expect(trackPageViewMock).toHaveBeenCalledTimes(1)
+  })
+
+  // ── The same guard on the OTHER door (lead-journey-telemetry Phase 4) ────────
+  //
+  // stopTrackPage() emits a page view exactly as trackPageView() does, so a guard
+  // that covered only trackPageView left the C-288 double-count fully reachable.
+  // web/ walked through it: manual router timing + the `true` default, which live
+  // KQL caught writing THREE AppPageViews rows for one /contact navigation.
+
+  it('skips the manual page-timing pair when the SDK is auto-tracking routes', async () => {
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({
+      connectionString: CONNECTION_STRING,
+      enableAutoRouteTracking: true,
+    })
+    t.initialize()
+
+    t.startTrackPage('/contact')
+    t.stopTrackPage('/contact', 'https://example.com/contact')
+
+    expect(startTrackPageMock).not.toHaveBeenCalled()
+    expect(stopTrackPageMock).not.toHaveBeenCalled()
+    expect(
+      warnSpy.mock.calls.some((c) => String(c[0]).includes('double-counting')),
+    ).toBe(true)
+  })
+
+  it('sends the manual page-timing pair when the consumer owns page views', async () => {
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({
+      connectionString: CONNECTION_STRING,
+      enableAutoRouteTracking: false,
+    })
+    t.initialize()
+
+    t.startTrackPage('/contact')
+    t.stopTrackPage('/contact', 'https://example.com/contact', { routeName: 'contact' })
+
+    expect(startTrackPageMock).toHaveBeenCalledTimes(1)
+    expect(startTrackPageMock.mock.calls[0][0]).toBe('/contact')
+    expect(stopTrackPageMock).toHaveBeenCalledTimes(1)
+    expect(stopTrackPageMock.mock.calls[0][0]).toBe('/contact')
+  })
+
+  it('skips both halves of the pair, never just the stop', async () => {
+    // Skipping only stopTrackPage would leave an unterminated page-timing entry
+    // inside the SDK for every navigation.
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({
+      connectionString: CONNECTION_STRING,
+      enableAutoRouteTracking: true,
+    })
+    t.initialize()
+
+    t.startTrackPage('/a')
+    t.stopTrackPage('/a')
+    t.startTrackPage('/b')
+    t.stopTrackPage('/b')
+
+    expect(startTrackPageMock).not.toHaveBeenCalled()
+    expect(stopTrackPageMock).not.toHaveBeenCalled()
+    // …and still only one warning for the whole session.
+    expect(
+      warnSpy.mock.calls.filter((c) => String(c[0]).includes('double-counting')),
+    ).toHaveLength(1)
+  })
+
+  // ---------------------------------------------------------------------
+  // C-326 — conversion capture handshake.
+  //
+  // The cms package auto-installs a delegated conversion listener that buffers
+  // clicks until a telemetry transport exists. This composable IS a transport,
+  // and it must say so on its own — the fleet's whole problem was that wiring
+  // this up was somebody's job and nobody did it.
+  // ---------------------------------------------------------------------
+  describe('conversion capture handshake', () => {
+    const conversionWindow = () =>
+      window as Window & { __dcsConversionAttach?: (sink: unknown) => number }
+
+    beforeEach(() => {
+      delete conversionWindow().__dcsConversionAttach
+    })
+
+    it('hands App Insights to the cms conversion tracker on initialize()', async () => {
+      const attach = vi.fn().mockReturnValue(1)
+      conversionWindow().__dcsConversionAttach = attach
+
+      const { useTelemetry } = await import('./composable')
+      useTelemetry({ connectionString: CONNECTION_STRING }).initialize()
+
+      expect(attach).toHaveBeenCalledTimes(1)
+
+      // And the thing handed over must actually reach the SDK.
+      const sink = attach.mock.calls[0][0] as (e: { name: string }) => void
+      sink({ name: 'site_interaction' })
+      expect(trackEventMock).toHaveBeenCalledTimes(1)
+      expect(trackEventMock.mock.calls[0][0].name).toBe('site_interaction')
+    })
+
+    it('is silent on a site with no cms conversion tracker', async () => {
+      const { useTelemetry } = await import('./composable')
+      const ok = useTelemetry({ connectionString: CONNECTION_STRING }).initialize()
+
+      expect(ok).toBe(true)
+      expect(warnSpy).not.toHaveBeenCalled()
+    })
+
+    it('a throwing handshake never fails initialization', async () => {
+      conversionWindow().__dcsConversionAttach = () => {
+        throw new Error('cms is on fire')
+      }
+
+      const { useTelemetry } = await import('./composable')
+      expect(useTelemetry({ connectionString: CONNECTION_STRING }).initialize()).toBe(true)
+    })
+  })
 })

package/src/composable.ts

@@ -2,6 +2,7 @@ import { ApplicationInsights } from '@microsoft/applicationinsights-web'
 import { computed, ref } from 'vue'
 
 import { DEFAULT_CLOUD_ROLE, createTelemetryConfig } from './config'
+import { captureJourneyFirstTouch, setJourneyIdentityResolver } from './journey'
 import type {
   TelemetryDependency,
   TelemetryEvent,
@@ -34,6 +35,97 @@ const initializationError = ref<string | null>(null)
 // no-op'ing every telemetry call; the loud warning makes that mode visible.
 let warnedDisabled = false
 let warnedNotInitialized = false
+let warnedDoubleCount = false
+
+// Whether the live instance was created with the SDK's own SPA route tracking on.
+// When it is, the SDK already emits one pageView per navigation, so a consumer that
+// ALSO calls trackPageView() on route change counts every page twice.
+//
+// This is not hypothetical (C-288, 2026-07-25): the Just Posh site ran both at once
+// and 509 of its 971 human page views last month — 52% — were duplicates. It was the
+// largest single correction in either owner report, and the portal dashboard was
+// showing the uncorrected number to the customer. See
+// .docs/analysis/owner-reports/2026-07-justposh.md §7.
+let autoRouteTrackingActive = false
+
+/**
+ * Hand this App Insights instance to the cms conversion tracker, if one is capturing.
+ *
+ * THE CONTRACT, AND WHY IT IS A GLOBAL. `@duffcloudservices/cms` auto-installs a delegated
+ * conversion listener (C-326) that starts capturing `tel:`/`sms:`/`mailto:`/booking/form
+ * interactions before any telemetry SDK exists, buffering them until a transport shows up.
+ * This package is a transport. Importing cms from here to say so would couple two packages
+ * that are versioned and published independently — and would break the one property the
+ * capture layer exists to have, which is that it never depends on a telemetry SDK.
+ *
+ * So the handshake is a single global function that cms publishes and anyone may call:
+ *
+ * ```js
+ * window.__dcsConversionAttach?.((event) => appInsights.trackEvent(event))
+ * ```
+ *
+ * A site with a bespoke telemetry boot (Bryan's is a hand-rolled copy of this composable)
+ * adds exactly that line. Consumers of this package get it for free, here.
+ *
+ * Failing silently is correct: on a site without cms, or an older cms, the global is simply
+ * absent and there is nothing to drain.
+ */
+function attachConversionCapture(sink: (event: TelemetryEvent) => void): void {
+  try {
+    const w =
+      typeof window !== 'undefined'
+        ? (window as Window & {
+            __dcsConversionAttach?: (s: (event: TelemetryEvent) => void) => number
+          })
+        : undefined
+    w?.__dcsConversionAttach?.(sink)
+  } catch (error) {
+    console.warn('Failed to attach conversion capture to App Insights:', error)
+  }
+}
+
+/**
+ * Read the visitor/session ids off a live App Insights instance.
+ *
+ * The SDK's `context` shape is internal-ish and has moved between major
+ * versions, so this reads it structurally and returns undefined on any
+ * mismatch — {@link getJourneyContext} then falls back to the `ai_user` /
+ * `ai_session` cookies. Never throws.
+ */
+function readSdkIdentity(
+  instance: ApplicationInsights | null,
+): { visitorId?: string; sessionId?: string } | undefined {
+  if (!instance) return undefined
+  try {
+    const context = (
+      instance as unknown as {
+        context?: {
+          user?: { id?: unknown }
+          getSessionId?: () => unknown
+          sessionManager?: { automaticSession?: { id?: unknown } }
+        }
+      }
+    ).context
+    if (!context) return undefined
+
+    const visitorId =
+      typeof context.user?.id === 'string' ? context.user.id : undefined
+
+    let sessionId: string | undefined
+    const fromGetter =
+      typeof context.getSessionId === 'function' ? context.getSessionId() : undefined
+    if (typeof fromGetter === 'string') {
+      sessionId = fromGetter
+    } else if (typeof context.sessionManager?.automaticSession?.id === 'string') {
+      sessionId = context.sessionManager.automaticSession.id
+    }
+
+    if (!visitorId && !sessionId) return undefined
+    return { visitorId, sessionId }
+  } catch {
+    return undefined
+  }
+}
 
 function resolveAppVersion(explicit?: string): string {
   if (explicit) return explicit
@@ -113,6 +205,14 @@ export function useTelemetry(options: TelemetryOptions = {}) {
 
   const initialize = (): boolean => {
     try {
+      // BEFORE the enabled check, and before anything can navigate. The SPA
+      // router destroys document.referrer on the first route change, so the
+      // landing referrer/utm has to be snapshotted here or it is gone. It is
+      // deliberately not conditional on telemetry being configured: a site with
+      // no connection string still benefits from first-touch attribution on its
+      // stored form submissions.
+      captureJourneyFirstTouch()
+
       if (isInitialized.value && appInsights) {
         return true
       }
@@ -133,16 +233,19 @@ export function useTelemetry(options: TelemetryOptions = {}) {
         return false
       }
 
-      appInsights = new ApplicationInsights({
-        config: createTelemetryConfig({
-          connectionString: options.connectionString,
-          instrumentationKey: options.instrumentationKey,
-          enableAutoRouteTracking: options.enableAutoRouteTracking,
-          dev: options.dev,
-          disablePageUnloadEvents: options.disablePageUnloadEvents,
-          overrides: options.overrides,
-        }),
+      const resolvedConfig = createTelemetryConfig({
+        connectionString: options.connectionString,
+        instrumentationKey: options.instrumentationKey,
+        enableAutoRouteTracking: options.enableAutoRouteTracking,
+        dev: options.dev,
+        disablePageUnloadEvents: options.disablePageUnloadEvents,
+        overrides: options.overrides,
       })
+      // Remember whether the SDK is counting page views for us, so trackPageView()
+      // can refuse to count them a second time.
+      autoRouteTrackingActive = resolvedConfig.enableAutoRouteTracking !== false
+
+      appInsights = new ApplicationInsights({ config: resolvedConfig })
 
       appInsights.loadAppInsights()
       appInsights.addTelemetryInitializer((envelope) => {
@@ -155,9 +258,19 @@ export function useTelemetry(options: TelemetryOptions = {}) {
         return true
       })
 
+      // Prefer the live SDK context over cookie parsing for the journey join
+      // key: the instance is authoritative, and it stays correct even if the
+      // cookies are blocked or renamed by a future SDK version.
+      setJourneyIdentityResolver(() => readSdkIdentity(appInsights))
+
       isInitialized.value = true
       initializationError.value = null
       console.log('Application Insights initialized successfully')
+
+      // Drain any conversion clicks captured before this transport existed, and stay
+      // attached for the rest of the session. See attachConversionCapture().
+      attachConversionCapture(trackEvent)
+
       return true
     } catch (error) {
       const errorMessage =
@@ -191,12 +304,39 @@ export function useTelemetry(options: TelemetryOptions = {}) {
     }
   }
 
+  /**
+   * Send a page view.
+   *
+   * REFUSES TO SEND when the SDK's own `enableAutoRouteTracking` is active, because
+   * the SDK has already emitted a pageView for this navigation and sending another
+   * double-counts the page. Pass `{ force: true }` only when you have verified that
+   * auto-route tracking genuinely does not fire for your routing setup — and expect
+   * to justify it, because a page-view count that is silently 2x is the defect this
+   * guard exists to prevent (C-288: 52% of one site's page views were duplicates).
+   *
+   * If you want manual page views, turn the SDK's tracking off:
+   * `useTelemetry({ enableAutoRouteTracking: false })`. One tracker, one count.
+   */
   const trackPageView = (pageView?: TelemetryPageView) => {
     if (!appInsights || !isInitialized.value) {
       console.warn('Application Insights not initialized, skipping page view tracking')
       return
     }
 
+    if (autoRouteTrackingActive && !pageView?.force) {
+      if (!warnedDoubleCount) {
+        warnedDoubleCount = true
+        console.warn(
+          '[telemetry] trackPageView() SKIPPED to prevent double-counting: this ' +
+            'instance was initialized with enableAutoRouteTracking, so the App ' +
+            'Insights SDK already reports one page view per navigation. Pass ' +
+            '{ enableAutoRouteTracking: false } to useTelemetry() if you want to ' +
+            'report page views manually instead.',
+        )
+      }
+      return
+    }
+
     try {
       // Attach the full document.referrer (not just hostname) so we can
       // attribute traffic sources in App Insights pageViews.
@@ -310,8 +450,36 @@ export function useTelemetry(options: TelemetryOptions = {}) {
     }
   }
 
+  /**
+   * The same guard `trackPageView` applies, on the other door into the page-view
+   * pipeline. `stopTrackPage` emits a page view just as surely as `trackPageView`
+   * does, so leaving it unguarded left the C-288 double-count fully reachable —
+   * and `web/` walked straight through it: the marketing site called the manual
+   * pair from its router while `enableAutoRouteTracking` kept its `true` default,
+   * and live KQL (2026-07-31) caught one /contact navigation writing THREE
+   * AppPageViews rows in 700ms. A guard on one entry point is not a guard.
+   *
+   * Both halves of the pair check this so they stay balanced: skipping only the
+   * stop would leave an unterminated page-timing entry inside the SDK.
+   */
+  const manualPageTrackingIsRedundant = (): boolean => {
+    if (!autoRouteTrackingActive) return false
+    if (!warnedDoubleCount) {
+      warnedDoubleCount = true
+      console.warn(
+        '[telemetry] startTrackPage()/stopTrackPage() SKIPPED to prevent ' +
+          'double-counting: this instance was initialized with ' +
+          'enableAutoRouteTracking, so the App Insights SDK already reports a ' +
+          'page view per navigation. Pass { enableAutoRouteTracking: false } to ' +
+          'useTelemetry() if you want to time and report page views manually.',
+      )
+    }
+    return true
+  }
+
   const startTrackPage = (name?: string) => {
     if (!appInsights || !isInitialized.value) return
+    if (manualPageTrackingIsRedundant()) return
 
     try {
       appInsights.startTrackPage(name)
@@ -327,6 +495,7 @@ export function useTelemetry(options: TelemetryOptions = {}) {
     measurements?: Record<string, number>,
   ) => {
     if (!appInsights || !isInitialized.value) return
+    if (manualPageTrackingIsRedundant()) return
 
     try {
       appInsights.stopTrackPage(name, url, buildEventProperties(properties), measurements)

package/src/index.ts

@@ -8,6 +8,10 @@
  *   `disablePageUnloadEvents: ['unload']` bfcache/Lighthouse fix baked into the
  *   default. Pure (no SDK import); also available SDK-free at
  *   `@duffcloudservices/telemetry/config` for lazy/inert telemetry loaders.
+ * - {@link getJourneyContext} — the visitor-journey join key attached to form
+ *   submissions. Pure (no SDK import); also available SDK-free at
+ *   `@duffcloudservices/telemetry/journey` for consumers with their own
+ *   telemetry boot.
  */
 export { useTelemetry, type TelemetryApi } from './composable'
 export {
@@ -15,6 +19,18 @@ export {
   DEFAULT_CLOUD_ROLE,
   DEFAULT_DISABLE_PAGE_UNLOAD_EVENTS,
 } from './config'
+export {
+  captureJourneyFirstTouch,
+  getJourneyContext,
+  setJourneyIdentityResolver,
+  toJourneyTelemetryPayload,
+  JOURNEY_FIELD_MAX_LENGTH,
+  JOURNEY_FIRST_TOUCH_KEY,
+  type JourneyContext,
+  type JourneyIdentityResolver,
+  type JourneyTelemetryPayload,
+  type JourneyUtm,
+} from './journey'
 export type {
   ApplicationInsightsConfig,
   TelemetryConfigOptions,