@duffcloudservices/telemetry 0.1.0

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@duffcloudservices/telemetry",
+  "version": "0.1.0",
+  "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": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "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"
+  },
+  "devDependencies": {
+    "@microsoft/applicationinsights-web": "^3.3.10",
+    "@types/node": "^22.0.0",
+    "jsdom": "^26.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "~5.8.0",
+    "vitest": "^3.2.3",
+    "vue": "^3.5.18"
+  },
+  "keywords": [
+    "vue",
+    "telemetry",
+    "application-insights",
+    "azure-monitor",
+    "dcs",
+    "duff-cloud-services"
+  ],
+  "author": "Duff Cloud Services",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NateDuff/dcs"
+  },
+  "homepage": "https://portal.duffcloudservices.com",
+  "bugs": {
+    "url": "https://github.com/NateDuff/dcs/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/composable.test.ts

@@ -0,0 +1,134 @@
+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.
+//
+// NOTE: the `ApplicationInsights` mock implementation must PERSIST across the
+// per-test `vi.resetModules()` — the composable's module-level singleton is
+// re-imported each test, but it re-imports this same mocked module. So we only
+// ever `mockReset()`/`mockClear()` the *leaf* mocks below; we never restore the
+// constructor mock (that would strip its implementation and every `new
+// ApplicationInsights()` would yield a bare object). Mirrors web/'s test.
+const trackEventMock = vi.fn()
+const trackPageViewMock = vi.fn()
+const loadAppInsightsMock = vi.fn()
+const addTelemetryInitializerMock = vi.fn()
+const constructorConfigs: unknown[] = []
+
+vi.mock('@microsoft/applicationinsights-web', () => {
+  return {
+    ApplicationInsights: vi.fn().mockImplementation((arg: { config: unknown }) => {
+      constructorConfigs.push(arg.config)
+      return {
+        loadAppInsights: loadAppInsightsMock,
+        addTelemetryInitializer: addTelemetryInitializerMock,
+        trackEvent: trackEventMock,
+        trackPageView: trackPageViewMock,
+        trackException: vi.fn(),
+        trackDependencyData: vi.fn(),
+        trackMetric: vi.fn(),
+        flush: vi.fn(),
+        startTrackPage: vi.fn(),
+        stopTrackPage: vi.fn(),
+      }
+    }),
+  }
+})
+
+// Silence (and let us assert on) console noise without touching the SDK mock.
+// Installed once, cleared per-test — never `restoreAllMocks`.
+const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+vi.spyOn(console, 'log').mockImplementation(() => {})
+vi.spyOn(console, 'error').mockImplementation(() => {})
+
+const CONNECTION_STRING =
+  'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://example.in.applicationinsights.azure.com/'
+
+describe('useTelemetry', () => {
+  beforeEach(() => {
+    trackEventMock.mockReset()
+    trackPageViewMock.mockReset()
+    loadAppInsightsMock.mockReset()
+    addTelemetryInitializerMock.mockReset()
+    warnSpy.mockClear()
+    constructorConfigs.length = 0
+    // Reset modules so the singleton state inside composable.ts is recreated.
+    vi.resetModules()
+  })
+
+  it('warns loudly and no-ops when no connection string / key is provided', async () => {
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry()
+
+    expect(t.isEnabled.value).toBe(false)
+    expect(t.initialize()).toBe(false)
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Application Insights DISABLED'),
+    )
+
+    // Must not reach the SDK.
+    t.trackCtaClick('hero-cta', '/contact')
+    expect(trackEventMock).not.toHaveBeenCalled()
+  })
+
+  it('initializes synchronously and passes the BP-54 unload fix into the SDK config', async () => {
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({ connectionString: CONNECTION_STRING, cloudRole: 'dcs-web' })
+
+    expect(t.initialize()).toBe(true)
+    expect(t.isInitialized.value).toBe(true)
+    expect(loadAppInsightsMock).toHaveBeenCalledTimes(1)
+
+    // The config actually handed to `new ApplicationInsights({ config })` must
+    // disable the deprecated `unload` event — this is the whole point of the
+    // package (the fix reaches the runtime SDK, not just a helper's return).
+    expect(constructorConfigs).toHaveLength(1)
+    const config = constructorConfigs[0] as { disablePageUnloadEvents?: string[] }
+    expect(config.disablePageUnloadEvents).toEqual(['unload'])
+  })
+
+  it('flows consumer options through to event properties (cloudRole → app_name)', async () => {
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({
+      connectionString: CONNECTION_STRING,
+      cloudRole: 'dcs-web',
+      environment: 'production',
+      appVersion: '9.9.9',
+    })
+    t.initialize()
+
+    t.trackCtaClick('hero-cta', '/contact')
+
+    expect(trackEventMock).toHaveBeenCalledTimes(1)
+    const call = trackEventMock.mock.calls[0][0]
+    expect(call.name).toBe('cta_click')
+    expect(call.properties).toMatchObject({
+      label: 'hero-cta',
+      page: '/contact',
+      app_name: 'dcs-web',
+      app_version: '9.9.9',
+      environment: 'production',
+    })
+  })
+
+  it('trackCtaClick falls back to window.location.pathname when page omitted', async () => {
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({ connectionString: CONNECTION_STRING })
+    t.initialize()
+
+    t.trackCtaClick('footer-cta')
+
+    expect(trackEventMock).toHaveBeenCalledTimes(1)
+    expect(trackEventMock.mock.calls[0][0].properties.page).toBe(
+      window.location.pathname,
+    )
+  })
+
+  it('defaults cloudRole to dcs-site when unspecified', async () => {
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({ connectionString: CONNECTION_STRING })
+    t.initialize()
+    t.trackEvent({ name: 'ping' })
+    expect(trackEventMock.mock.calls[0][0].properties.app_name).toBe('dcs-site')
+  })
+})

package/src/composable.ts

@@ -0,0 +1,356 @@
+import { ApplicationInsights } from '@microsoft/applicationinsights-web'
+import { computed, ref } from 'vue'
+
+import { DEFAULT_CLOUD_ROLE, createTelemetryConfig } from './config'
+import type {
+  TelemetryDependency,
+  TelemetryEvent,
+  TelemetryException,
+  TelemetryMetric,
+  TelemetryOptions,
+  TelemetryPageView,
+} from './types'
+
+interface TelemetryEnvelope {
+  data?: {
+    baseData?: {
+      properties?: Record<string, string>
+    }
+  }
+  tags?: Record<string, string>
+}
+
+// Module-level singleton state: one App Insights instance per app bundle,
+// shared across every `useTelemetry()` call (matches the original per-app
+// composable). The reactive refs let views observe init state.
+let appInsights: ApplicationInsights | null = null
+const isInitialized = ref(false)
+const initializationError = ref<string | null>(null)
+
+// One-shot guards so we surface "App Insights is not configured" loudly in
+// DevTools the FIRST time the app tries to use it, but don't spam the console
+// for every subsequent trackEvent / trackPageView call. See web/ site-audit F2
+// — `customEvents = 0` for 7d was a missing connection string silently
+// no-op'ing every telemetry call; the loud warning makes that mode visible.
+let warnedDisabled = false
+let warnedNotInitialized = false
+
+function resolveAppVersion(explicit?: string): string {
+  if (explicit) return explicit
+  const w =
+    typeof window !== 'undefined'
+      ? (window as Window & { __APP_VERSION__?: string })
+      : undefined
+  return w?.__APP_VERSION__ ?? 'unknown'
+}
+
+/**
+ * Azure Application Insights composable for DCS Vue apps.
+ *
+ * The connection string, cloud role, environment and app version are supplied
+ * by the consumer (they read their own `import.meta.env` / build defines and
+ * pass plain values in) so this package stays portable and build-tool agnostic.
+ * The shared App Insights config — including the `disablePageUnloadEvents:
+ * ['unload']` bfcache/Lighthouse fix — comes from {@link createTelemetryConfig}.
+ */
+export function useTelemetry(options: TelemetryOptions = {}) {
+  const cloudRole = options.cloudRole ?? DEFAULT_CLOUD_ROLE
+  const environment = options.environment ?? 'unknown'
+
+  const isEnabled = computed(() => {
+    return !!(options.connectionString || options.instrumentationKey)
+  })
+
+  function buildSharedProperties(): Record<string, string> {
+    const appVersion = resolveAppVersion(options.appVersion)
+    const referrerHost =
+      typeof document !== 'undefined' && document.referrer
+        ? (() => {
+            try {
+              return new URL(document.referrer).hostname
+            } catch {
+              return 'unknown'
+            }
+          })()
+        : 'direct'
+
+    return {
+      app_version: appVersion,
+      app_name: cloudRole,
+      app_host: typeof window !== 'undefined' ? window.location.hostname : '',
+      page_path: typeof window !== 'undefined' ? window.location.pathname : '',
+      referrer_host: referrerHost,
+    }
+  }
+
+  function buildEventProperties(
+    additional?: Record<string, string>,
+  ): Record<string, string> {
+    return {
+      timestamp: new Date().toISOString(),
+      environment,
+      ...buildSharedProperties(),
+      ...additional,
+    }
+  }
+
+  function enrichTelemetryEnvelope(envelope: TelemetryEnvelope) {
+    if (!envelope.data) {
+      envelope.data = {}
+    }
+
+    envelope.data.baseData = envelope.data.baseData || {}
+    envelope.data.baseData.properties = envelope.data.baseData.properties || {}
+    Object.assign(envelope.data.baseData.properties, buildSharedProperties())
+
+    const appVersion = resolveAppVersion(options.appVersion)
+    envelope.tags = envelope.tags || {}
+    envelope.tags['ai.application.ver'] = appVersion
+    envelope.tags['ai.cloud.role'] = cloudRole
+    envelope.tags['ai.cloud.roleInstance'] =
+      typeof window !== 'undefined' ? window.location.hostname : ''
+  }
+
+  const initialize = (): boolean => {
+    try {
+      if (isInitialized.value && appInsights) {
+        return true
+      }
+
+      if (!isEnabled.value) {
+        if (!warnedDisabled) {
+          warnedDisabled = true
+          // Loud, one-shot warning so this is obvious in DevTools. If you see
+          // this in production, the build pipeline is not injecting the App
+          // Insights connection string — every track* call below silently
+          // no-ops. See web/ site-audit F2.
+          console.warn(
+            '[telemetry] Application Insights DISABLED: no connection string ' +
+              'or instrumentation key was provided at build time. ' +
+              'All telemetry calls will silently no-op.',
+          )
+        }
+        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,
+        }),
+      })
+
+      appInsights.loadAppInsights()
+      appInsights.addTelemetryInitializer((envelope) => {
+        try {
+          enrichTelemetryEnvelope(envelope as TelemetryEnvelope)
+        } catch (error) {
+          console.warn('Failed to add web telemetry context:', error)
+        }
+
+        return true
+      })
+
+      isInitialized.value = true
+      initializationError.value = null
+      console.log('Application Insights initialized successfully')
+      return true
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : 'Unknown initialization error'
+      initializationError.value = errorMessage
+      console.error('Failed to initialize Application Insights:', error)
+      return false
+    }
+  }
+
+  const trackEvent = (event: TelemetryEvent) => {
+    if (!appInsights || !isInitialized.value) {
+      if (!warnedNotInitialized) {
+        warnedNotInitialized = true
+        console.warn(
+          `[telemetry] Application Insights not initialized — dropping event "${event.name}" ` +
+            '(and silencing further "not initialized" warnings for this session).',
+        )
+      }
+      return
+    }
+
+    try {
+      appInsights.trackEvent({
+        name: event.name,
+        properties: buildEventProperties(event.properties),
+        measurements: event.measurements,
+      })
+    } catch (error) {
+      console.error('Failed to track event:', error)
+    }
+  }
+
+  const trackPageView = (pageView?: TelemetryPageView) => {
+    if (!appInsights || !isInitialized.value) {
+      console.warn('Application Insights not initialized, skipping page view tracking')
+      return
+    }
+
+    try {
+      // Attach the full document.referrer (not just hostname) so we can
+      // attribute traffic sources in App Insights pageViews.
+      const referrer =
+        typeof document !== 'undefined' ? (document.referrer ?? '') : ''
+      appInsights.trackPageView({
+        name:
+          pageView?.name ||
+          (typeof document !== 'undefined' ? document.title : undefined),
+        uri:
+          pageView?.uri ||
+          (typeof window !== 'undefined' ? window.location.href : undefined),
+        properties: buildEventProperties({
+          referrer,
+          ...pageView?.properties,
+        }),
+        measurements: pageView?.measurements,
+      })
+    } catch (error) {
+      console.error('Failed to track page view:', error)
+    }
+  }
+
+  /**
+   * Convenience helper for primary CTA conversion measurement. Fires a
+   * `cta_click` custom event so conversion rate per landing page can be
+   * computed in App Insights / KQL.
+   */
+  const trackCtaClick = (label: string, page?: string) => {
+    trackEvent({
+      name: 'cta_click',
+      properties: {
+        label,
+        page:
+          page ??
+          (typeof window !== 'undefined' ? window.location.pathname : ''),
+      },
+    })
+  }
+
+  const trackException = (exception: TelemetryException) => {
+    if (!appInsights || !isInitialized.value) {
+      console.warn('Application Insights not initialized, skipping exception tracking')
+      return
+    }
+
+    try {
+      appInsights.trackException({
+        exception: exception.exception,
+        properties: buildEventProperties({
+          url: typeof window !== 'undefined' ? window.location.href : '',
+          userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : '',
+          ...exception.properties,
+        }),
+        measurements: exception.measurements,
+      })
+    } catch (error) {
+      console.error('Failed to track exception:', error)
+    }
+  }
+
+  const trackDependency = (dependency: TelemetryDependency) => {
+    if (!appInsights || !isInitialized.value) {
+      console.warn('Application Insights not initialized, skipping dependency tracking')
+      return
+    }
+
+    try {
+      appInsights.trackDependencyData({
+        id: `dep-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`,
+        name: dependency.name,
+        data: dependency.data,
+        duration: dependency.duration,
+        success: dependency.success,
+        responseCode: dependency.resultCode || 0,
+        properties: buildEventProperties(dependency.properties),
+        measurements: dependency.measurements,
+      })
+    } catch (error) {
+      console.error('Failed to track dependency:', error)
+    }
+  }
+
+  const trackMetric = (metric: TelemetryMetric) => {
+    if (!appInsights || !isInitialized.value) {
+      console.warn('Application Insights not initialized, skipping metric tracking')
+      return
+    }
+
+    try {
+      appInsights.trackMetric({
+        name: metric.name,
+        average: metric.average,
+        sampleCount: metric.sampleCount,
+        min: metric.min,
+        max: metric.max,
+        properties: buildEventProperties(metric.properties),
+      })
+    } catch (error) {
+      console.error('Failed to track metric:', error)
+    }
+  }
+
+  const flush = () => {
+    if (!appInsights || !isInitialized.value) return
+
+    try {
+      appInsights.flush()
+    } catch (error) {
+      console.error('Failed to flush telemetry:', error)
+    }
+  }
+
+  const startTrackPage = (name?: string) => {
+    if (!appInsights || !isInitialized.value) return
+
+    try {
+      appInsights.startTrackPage(name)
+    } catch (error) {
+      console.error('Failed to start track page:', error)
+    }
+  }
+
+  const stopTrackPage = (
+    name?: string,
+    url?: string,
+    properties?: Record<string, string>,
+    measurements?: Record<string, number>,
+  ) => {
+    if (!appInsights || !isInitialized.value) return
+
+    try {
+      appInsights.stopTrackPage(name, url, buildEventProperties(properties), measurements)
+    } catch (error) {
+      console.error('Failed to stop track page:', error)
+    }
+  }
+
+  return {
+    isEnabled,
+    isInitialized,
+    initializationError,
+    initialize,
+    flush,
+    startTrackPage,
+    stopTrackPage,
+    trackDependency,
+    trackEvent,
+    trackException,
+    trackMetric,
+    trackPageView,
+    trackCtaClick,
+  }
+}
+
+/** The full public API returned by {@link useTelemetry}. */
+export type TelemetryApi = ReturnType<typeof useTelemetry>

package/src/config.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  DEFAULT_DISABLE_PAGE_UNLOAD_EVENTS,
+  createTelemetryConfig,
+} from './config'
+
+describe('createTelemetryConfig — BP-54 unload fix', () => {
+  it('the DEFAULT config disables the deprecated `unload` event', () => {
+    const config = createTelemetryConfig()
+    expect(config.disablePageUnloadEvents).toEqual(['unload'])
+  })
+
+  it('keeps pagehide / visibilitychange hooked (only `unload` is disabled)', () => {
+    const config = createTelemetryConfig({
+      connectionString: 'InstrumentationKey=abc',
+    })
+    const disabled = config.disablePageUnloadEvents ?? []
+    expect(disabled).toContain('unload')
+    // The supported flush events must NOT be in the disabled list.
+    expect(disabled).not.toContain('pagehide')
+    expect(disabled).not.toContain('visibilitychange')
+    expect(disabled).not.toContain('beforeunload')
+  })
+
+  it('exposes the default as a stable constant', () => {
+    expect(DEFAULT_DISABLE_PAGE_UNLOAD_EVENTS).toEqual(['unload'])
+  })
+
+  it('the default array is copied, not shared by reference (no cross-config mutation)', () => {
+    const a = createTelemetryConfig()
+    const b = createTelemetryConfig()
+    expect(a.disablePageUnloadEvents).not.toBe(b.disablePageUnloadEvents)
+    expect(a.disablePageUnloadEvents).not.toBe(DEFAULT_DISABLE_PAGE_UNLOAD_EVENTS)
+  })
+})
+
+describe('createTelemetryConfig — consumer options flow through', () => {
+  it('passes the connection string and instrumentation key through', () => {
+    const config = createTelemetryConfig({
+      connectionString: 'InstrumentationKey=00000000-0000-0000-0000-000000000000',
+      instrumentationKey: '00000000-0000-0000-0000-000000000000',
+    })
+    expect(config.connectionString).toBe(
+      'InstrumentationKey=00000000-0000-0000-0000-000000000000',
+    )
+    expect(config.instrumentationKey).toBe(
+      '00000000-0000-0000-0000-000000000000',
+    )
+  })
+
+  it('defaults enableAutoRouteTracking to true but honors an explicit false', () => {
+    expect(createTelemetryConfig().enableAutoRouteTracking).toBe(true)
+    expect(
+      createTelemetryConfig({ enableAutoRouteTracking: false })
+        .enableAutoRouteTracking,
+    ).toBe(false)
+  })
+
+  it('dev mode lowers the SDK logging levels (1 vs 2)', () => {
+    const prod = createTelemetryConfig({ dev: false })
+    const dev = createTelemetryConfig({ dev: true })
+    expect(prod.loggingLevelConsole).toBe(2)
+    expect(prod.loggingLevelTelemetry).toBe(2)
+    expect(dev.loggingLevelConsole).toBe(1)
+    expect(dev.loggingLevelTelemetry).toBe(1)
+  })
+
+  it('lets a consumer override the disabled unload events', () => {
+    const config = createTelemetryConfig({
+      disablePageUnloadEvents: ['unload', 'beforeunload'],
+    })
+    expect(config.disablePageUnloadEvents).toEqual(['unload', 'beforeunload'])
+  })
+
+  it('applies `overrides` last, over the DCS defaults', () => {
+    const config = createTelemetryConfig({
+      overrides: {
+        samplingPercentage: 25,
+        correlationHeaderDomains: ['example.com'],
+      },
+    })
+    expect(config.samplingPercentage).toBe(25)
+    expect(config.correlationHeaderDomains).toEqual(['example.com'])
+    // Untouched defaults survive.
+    expect(config.disablePageUnloadEvents).toEqual(['unload'])
+    expect(config.distributedTracingMode).toBe(2)
+  })
+
+  it('overrides can NEVER re-enable the deprecated `unload` listener (BP-54 guard)', () => {
+    // A caller fat-fingering the unload policy via `overrides` must not regress the
+    // fleet-wide bfcache / Lighthouse fix — the fix is re-asserted after the spread.
+    const config = createTelemetryConfig({
+      overrides: { disablePageUnloadEvents: [] },
+    })
+    expect(config.disablePageUnloadEvents).toEqual(['unload'])
+  })
+
+  it('ships the DCS first-party correlation defaults', () => {
+    const config = createTelemetryConfig()
+    expect(config.correlationHeaderDomains).toContain('*.duffcloudservices.com')
+    expect(config.correlationHeaderExcludedDomains).toContain('*.stripe.com')
+    expect(config.samplingPercentage).toBe(100)
+  })
+})