@duffcloudservices/telemetry 0.1.0 → 0.2.0

package/src/journey.test.ts

@@ -0,0 +1,135 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import {
+  captureJourneyFirstTouch,
+  getJourneyContext,
+  JOURNEY_FIELD_MAX_LENGTH,
+  JOURNEY_FIRST_TOUCH_KEY,
+  setJourneyIdentityResolver,
+  toJourneyTelemetryPayload,
+} from './journey'
+
+function clearCookies(): void {
+  for (const part of document.cookie.split(';')) {
+    const name = part.split('=')[0]?.trim()
+    if (name) document.cookie = `${name}=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/`
+  }
+}
+
+function navigateTo(url: string): void {
+  window.history.replaceState({}, '', url)
+}
+
+describe('journey', () => {
+  beforeEach(() => {
+    sessionStorage.clear()
+    clearCookies()
+    setJourneyIdentityResolver(null)
+    navigateTo('/')
+  })
+
+  afterEach(() => {
+    setJourneyIdentityResolver(null)
+  })
+
+  it('captures referrer, landing path and utm once per session', () => {
+    Object.defineProperty(document, 'referrer', {
+      value: 'https://www.google.com/',
+      configurable: true,
+    })
+    navigateTo('/compare/booksy-alternative?utm_source=google&utm_medium=organic')
+
+    captureJourneyFirstTouch()
+
+    const snapshot = JSON.parse(sessionStorage.getItem(JOURNEY_FIRST_TOUCH_KEY) ?? '{}')
+    expect(snapshot.referrer).toBe('https://www.google.com/')
+    expect(snapshot.landingPath).toBe(
+      '/compare/booksy-alternative?utm_source=google&utm_medium=organic',
+    )
+    expect(snapshot.utm).toEqual({ source: 'google', medium: 'organic' })
+  })
+
+  it('never overwrites the first-touch snapshot on a later page', () => {
+    Object.defineProperty(document, 'referrer', {
+      value: 'https://www.google.com/',
+      configurable: true,
+    })
+    navigateTo('/compare/booksy-alternative')
+    captureJourneyFirstTouch()
+
+    // The SPA navigates; document.referrer is gone by the time the form renders.
+    Object.defineProperty(document, 'referrer', { value: '', configurable: true })
+    navigateTo('/contact?plan=Professional')
+    captureJourneyFirstTouch()
+
+    const context = getJourneyContext()
+    expect(context.referrer).toBe('https://www.google.com/')
+    expect(context.landingPath).toBe('/compare/booksy-alternative')
+    // ...while the submit-time page is the contact page, not the landing page.
+    expect(context.pagePath).toBe('/contact')
+  })
+
+  it('falls back to the ai_user / ai_session cookies for identity', () => {
+    document.cookie = 'ai_user=oA7p7yUdBDbu0bXCR6WACW|2026-07-30T12:54:01.000Z; path=/'
+    document.cookie = 'ai_session=Yb3kZ|2026-07-30T12:54:01.000Z|2026-07-30T12:55:47.000Z; path=/'
+
+    const context = getJourneyContext()
+    expect(context.visitorId).toBe('oA7p7yUdBDbu0bXCR6WACW')
+    expect(context.sessionId).toBe('Yb3kZ')
+  })
+
+  it('prefers the live SDK identity over the cookies', () => {
+    document.cookie = 'ai_user=cookie-user|2026-07-30T12:54:01.000Z; path=/'
+    setJourneyIdentityResolver(() => ({ visitorId: 'sdk-user', sessionId: 'sdk-session' }))
+
+    const context = getJourneyContext()
+    expect(context.visitorId).toBe('sdk-user')
+    expect(context.sessionId).toBe('sdk-session')
+  })
+
+  it('survives a throwing identity resolver', () => {
+    document.cookie = 'ai_user=cookie-user|2026-07-30T12:54:01.000Z; path=/'
+    setJourneyIdentityResolver(() => {
+      throw new Error('SDK context unavailable')
+    })
+
+    expect(() => getJourneyContext()).not.toThrow()
+    expect(getJourneyContext().visitorId).toBe('cookie-user')
+  })
+
+  it('clamps every field to the server-side maximum', () => {
+    const long = 'x'.repeat(JOURNEY_FIELD_MAX_LENGTH + 50)
+    document.cookie = `ai_user=${long}|2026-07-30T12:54:01.000Z; path=/`
+
+    const context = getJourneyContext()
+    expect(context.visitorId).toHaveLength(JOURNEY_FIELD_MAX_LENGTH)
+  })
+
+  it('omits the payload entirely when there is nothing to report', () => {
+    Object.defineProperty(document, 'referrer', { value: '', configurable: true })
+    navigateTo('/')
+    sessionStorage.clear()
+
+    // A bare "/" landing with no referrer, no utm and no cookies still reports
+    // the submit-time page, which is legitimately useful.
+    const payload = toJourneyTelemetryPayload()
+    expect(payload?.pagePath).toBe('/')
+    expect(payload?.visitorId).toBeUndefined()
+
+    // ...but an empty context flattens to undefined so the caller omits the field.
+    expect(toJourneyTelemetryPayload({})).toBeUndefined()
+  })
+
+  it('flattens utm into the contract shape', () => {
+    const payload = toJourneyTelemetryPayload({
+      visitorId: 'v1',
+      utm: { source: 'google', medium: 'cpc', campaign: 'summer' },
+    })
+    expect(payload).toEqual({
+      visitorId: 'v1',
+      utmSource: 'google',
+      utmMedium: 'cpc',
+      utmCampaign: 'summer',
+    })
+  })
+})

package/src/journey.ts

@@ -0,0 +1,280 @@
+/**
+ * Visitor-journey context for form submissions.
+ *
+ * A submitted form row and the site's Application Insights telemetry describe
+ * the same visit, but nothing joins them: the row knows the message, the
+ * telemetry knows the path that produced it. `getJourneyContext()` returns the
+ * join key — the ids the SDK is already stamping on every event, plus the
+ * first-touch attribution the SPA throws away.
+ *
+ * WHY FIRST-TOUCH IS CAPTURED AT SESSION START, NOT AT SUBMIT. `document.referrer`
+ * is only populated for the document the browser actually loaded. The moment a
+ * client-side router takes over, it is gone — so a visitor who lands from Google
+ * on a comparison page and clicks through to /contact submits with an empty
+ * referrer. Capture-at-submit is not "less accurate" here; it is structurally
+ * always empty for the multi-page journeys worth attributing. So
+ * `captureJourneyFirstTouch()` snapshots the referrer, landing path, and utm_*
+ * parameters once per session into `sessionStorage`, and every later read serves
+ * that snapshot.
+ *
+ * This module deliberately imports nothing. It must stay usable by a consumer
+ * that has no App Insights SDK loaded (the portal runs its own hand-rolled
+ * telemetry boot), and it must never be the reason a form submission fails —
+ * every entry point swallows its own errors and degrades to an empty result.
+ */
+
+/** First-touch UTM parameters parsed from the landing URL. */
+export interface JourneyUtm {
+  source?: string
+  medium?: string
+  campaign?: string
+  term?: string
+  content?: string
+}
+
+/** The join key attached to an outbound form submission. */
+export interface JourneyContext {
+  /** App Insights user id — the visitor, across sessions. */
+  visitorId?: string
+  /** App Insights session id — this visit. */
+  sessionId?: string
+  /** Route path the form was submitted from. */
+  pagePath?: string
+  /** Full URL the form was submitted from. */
+  pageUrl?: string
+  /** First-touch `document.referrer` for this session. */
+  referrer?: string
+  /** First-touch landing path (pathname + query) for this session. */
+  landingPath?: string
+  /** First-touch UTM parameters, when the landing URL carried any. */
+  utm?: JourneyUtm
+}
+
+/** Resolves visitor/session ids from a live telemetry SDK instance. */
+export type JourneyIdentityResolver = () =>
+  | { visitorId?: string; sessionId?: string }
+  | undefined
+
+/** sessionStorage key holding this session's first-touch snapshot. */
+export const JOURNEY_FIRST_TOUCH_KEY = 'dcs:journey:first-touch'
+
+/**
+ * Per-field clamp. Mirrors the server's `journey.FieldMaxLength` so a value that
+ * survives here is never silently truncated on the way into storage.
+ */
+export const JOURNEY_FIELD_MAX_LENGTH = 512
+
+interface FirstTouchSnapshot {
+  referrer?: string
+  landingPath?: string
+  utm?: JourneyUtm
+}
+
+let identityResolver: JourneyIdentityResolver | null = null
+
+/**
+ * Register the live-SDK source for visitor/session ids.
+ *
+ * The composable calls this after `loadAppInsights()`. Without it — or when the
+ * resolver returns nothing — {@link getJourneyContext} falls back to parsing the
+ * `ai_user` / `ai_session` cookies the SDK writes, which is why the portal (with
+ * its own SDK boot and no call to this function) still reports usable ids.
+ */
+export function setJourneyIdentityResolver(
+  resolver: JourneyIdentityResolver | null,
+): void {
+  identityResolver = resolver
+}
+
+function clamp(value: string | undefined | null): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const trimmed = value.trim()
+  if (!trimmed) return undefined
+  return trimmed.length > JOURNEY_FIELD_MAX_LENGTH
+    ? trimmed.slice(0, JOURNEY_FIELD_MAX_LENGTH)
+    : trimmed
+}
+
+/**
+ * Read a cookie value, URL-decoded. Returns undefined when absent.
+ */
+function readCookie(name: string): string | undefined {
+  if (typeof document === 'undefined' || typeof document.cookie !== 'string') {
+    return undefined
+  }
+  const prefix = `${name}=`
+  for (const part of document.cookie.split(';')) {
+    const entry = part.trim()
+    if (!entry.startsWith(prefix)) continue
+    const raw = entry.slice(prefix.length)
+    try {
+      return decodeURIComponent(raw)
+    } catch {
+      return raw
+    }
+  }
+  return undefined
+}
+
+/**
+ * The App Insights cookies are pipe-delimited composites:
+ * `ai_user=<userId>|<acquisitionDate>` and
+ * `ai_session=<sessionId>|<acquisitionDate>|<renewalDate>`. Only the leading
+ * segment is the id.
+ */
+function firstCookieSegment(name: string): string | undefined {
+  const value = readCookie(name)
+  if (!value) return undefined
+  return clamp(value.split('|')[0])
+}
+
+function parseUtm(params: URLSearchParams): JourneyUtm | undefined {
+  const utm: JourneyUtm = {}
+  const source = clamp(params.get('utm_source'))
+  const medium = clamp(params.get('utm_medium'))
+  const campaign = clamp(params.get('utm_campaign'))
+  const term = clamp(params.get('utm_term'))
+  const content = clamp(params.get('utm_content'))
+  if (source) utm.source = source
+  if (medium) utm.medium = medium
+  if (campaign) utm.campaign = campaign
+  if (term) utm.term = term
+  if (content) utm.content = content
+  return Object.keys(utm).length > 0 ? utm : undefined
+}
+
+function readFirstTouch(): FirstTouchSnapshot | undefined {
+  if (typeof sessionStorage === 'undefined') return undefined
+  try {
+    const raw = sessionStorage.getItem(JOURNEY_FIRST_TOUCH_KEY)
+    if (!raw) return undefined
+    const parsed = JSON.parse(raw) as FirstTouchSnapshot
+    return parsed && typeof parsed === 'object' ? parsed : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Snapshot this session's first-touch context, once.
+ *
+ * Idempotent and safe to call from anywhere: a snapshot already in
+ * sessionStorage always wins, so a later call on a deep page can never overwrite
+ * the real landing page with the current one. Called by the composable's
+ * `initialize()` (as early in the app's life as telemetry exists) and lazily by
+ * {@link getJourneyContext} so a consumer that never initializes the shared SDK
+ * still records *something* rather than nothing.
+ */
+export function captureJourneyFirstTouch(): void {
+  try {
+    if (typeof window === 'undefined' || typeof sessionStorage === 'undefined') {
+      return
+    }
+    if (sessionStorage.getItem(JOURNEY_FIRST_TOUCH_KEY)) return
+
+    const snapshot: FirstTouchSnapshot = {}
+    const referrer =
+      typeof document !== 'undefined' ? clamp(document.referrer) : undefined
+    if (referrer) snapshot.referrer = referrer
+
+    const landingPath = clamp(
+      `${window.location.pathname}${window.location.search}`,
+    )
+    if (landingPath) snapshot.landingPath = landingPath
+
+    const utm = parseUtm(new URLSearchParams(window.location.search))
+    if (utm) snapshot.utm = utm
+
+    sessionStorage.setItem(JOURNEY_FIRST_TOUCH_KEY, JSON.stringify(snapshot))
+  } catch {
+    // sessionStorage can throw under blocked-storage policies. Journey capture
+    // is an enrichment, never a requirement — stay silent and degrade.
+  }
+}
+
+/**
+ * Build the journey context to attach to an outbound form submission.
+ *
+ * NEVER THROWS. Returns `{}` when there is nothing to report (SSR, blocked
+ * storage, telemetry-dark site), and callers omit the field entirely in that
+ * case — a telemetry failure must not cost a lead.
+ */
+export function getJourneyContext(): JourneyContext {
+  try {
+    if (typeof window === 'undefined') return {}
+
+    captureJourneyFirstTouch()
+
+    const context: JourneyContext = {}
+
+    const identity = (() => {
+      try {
+        return identityResolver?.()
+      } catch {
+        return undefined
+      }
+    })()
+
+    const visitorId = clamp(identity?.visitorId) ?? firstCookieSegment('ai_user')
+    const sessionId =
+      clamp(identity?.sessionId) ?? firstCookieSegment('ai_session')
+    if (visitorId) context.visitorId = visitorId
+    if (sessionId) context.sessionId = sessionId
+
+    const pagePath = clamp(window.location.pathname)
+    const pageUrl = clamp(window.location.href)
+    if (pagePath) context.pagePath = pagePath
+    if (pageUrl) context.pageUrl = pageUrl
+
+    const firstTouch = readFirstTouch()
+    const referrer = clamp(firstTouch?.referrer)
+    const landingPath = clamp(firstTouch?.landingPath)
+    if (referrer) context.referrer = referrer
+    if (landingPath) context.landingPath = landingPath
+    if (firstTouch?.utm && Object.keys(firstTouch.utm).length > 0) {
+      context.utm = firstTouch.utm
+    }
+
+    return context
+  } catch {
+    return {}
+  }
+}
+
+/** The wire shape the DCS submission contracts accept (`SubmissionTelemetry`). */
+export interface JourneyTelemetryPayload {
+  visitorId?: string
+  sessionId?: string
+  pagePath?: string
+  pageUrl?: string
+  referrer?: string
+  landingPath?: string
+  utmSource?: string
+  utmMedium?: string
+  utmCampaign?: string
+  utmTerm?: string
+  utmContent?: string
+}
+
+/**
+ * Flatten a {@link JourneyContext} into the contract's `telemetry` object, or
+ * return `undefined` when there is nothing worth sending so the caller can omit
+ * the field rather than post an empty object.
+ */
+export function toJourneyTelemetryPayload(
+  context: JourneyContext = getJourneyContext(),
+): JourneyTelemetryPayload | undefined {
+  const payload: JourneyTelemetryPayload = {}
+  if (context.visitorId) payload.visitorId = context.visitorId
+  if (context.sessionId) payload.sessionId = context.sessionId
+  if (context.pagePath) payload.pagePath = context.pagePath
+  if (context.pageUrl) payload.pageUrl = context.pageUrl
+  if (context.referrer) payload.referrer = context.referrer
+  if (context.landingPath) payload.landingPath = context.landingPath
+  if (context.utm?.source) payload.utmSource = context.utm.source
+  if (context.utm?.medium) payload.utmMedium = context.utm.medium
+  if (context.utm?.campaign) payload.utmCampaign = context.utm.campaign
+  if (context.utm?.term) payload.utmTerm = context.utm.term
+  if (context.utm?.content) payload.utmContent = context.utm.content
+  return Object.keys(payload).length > 0 ? payload : undefined
+}

package/src/types.ts

@@ -18,6 +18,17 @@ export interface TelemetryPageView {
   uri?: string
   properties?: Record<string, string>
   measurements?: Record<string, number>
+  /**
+   * Send this page view even though the SDK's `enableAutoRouteTracking` is active.
+   *
+   * Off by default, and it should stay off: with auto-route tracking on, the SDK
+   * already emits one pageView per navigation, so a manual one double-counts the
+   * page. C-288 measured that exact configuration producing 52% duplicate page views
+   * on a live customer site, which the portal then reported to the owner. Set this
+   * only when you have verified auto-route tracking does not fire for your routing
+   * setup; prefer `useTelemetry({ enableAutoRouteTracking: false })` instead.
+   */
+  force?: boolean
 }
 
 export interface TelemetryException {