@duffcloudservices/telemetry 0.1.0

package/src/config.ts

@@ -0,0 +1,94 @@
+import type { ApplicationInsightsConfig, TelemetryConfigOptions } from './types'
+
+/**
+ * The page-unload events the DCS default config tells the App Insights web SDK
+ * to leave un-hooked. Only the deprecated `unload` event is disabled — the SDK
+ * still hooks `pagehide` / `visibilitychange` (the supported flush path), so no
+ * telemetry is lost, back/forward-cache eligibility is restored, and the
+ * Lighthouse "avoid `unload` event listeners" audit passes.
+ */
+export const DEFAULT_DISABLE_PAGE_UNLOAD_EVENTS: readonly string[] = ['unload']
+
+/** Cloud-role default when a consumer does not name itself. */
+export const DEFAULT_CLOUD_ROLE = 'dcs-site'
+
+/** Correlation is added to first-party requests to these domains. */
+const DEFAULT_CORRELATION_HEADER_DOMAINS: readonly string[] = [
+  'localhost',
+  '127.0.0.1',
+  '*.duffcloudservices.com',
+]
+
+/** Correlation headers are never attached to these third-party domains. */
+const DEFAULT_CORRELATION_HEADER_EXCLUDED_DOMAINS: readonly string[] = [
+  '*.googleapis.com',
+  '*.stripe.com',
+  '*.auth0.com',
+  '*.linkedin.com',
+  '*.github.com',
+  '*.microsoft.com',
+  '*.microsoftonline.com',
+]
+
+/**
+ * Build the App Insights web SDK config with DCS's shared defaults.
+ *
+ * The DEFAULT always includes {@link DEFAULT_DISABLE_PAGE_UNLOAD_EVENTS}
+ * (`disablePageUnloadEvents: ['unload']`) — the fleet-wide bfcache / Lighthouse
+ * best-practices fix. Callers only need to supply their connection string; every
+ * field is overridable via the typed options (and the escape-hatch `overrides`).
+ *
+ * This function performs no SDK import and reads no `import.meta.env` — it is
+ * pure, so it is safe to call from lazy/inert telemetry loaders (the SDK is only
+ * pulled in when the composable, or the consumer, actually constructs
+ * `ApplicationInsights`).
+ */
+export function createTelemetryConfig(
+  options: TelemetryConfigOptions = {},
+): ApplicationInsightsConfig {
+  const {
+    connectionString,
+    instrumentationKey,
+    enableAutoRouteTracking = true,
+    dev = false,
+    disablePageUnloadEvents = [...DEFAULT_DISABLE_PAGE_UNLOAD_EVENTS],
+    overrides,
+  } = options
+
+  const config: ApplicationInsightsConfig = {
+    connectionString,
+    instrumentationKey,
+    // ── BP-54 fleet fix ──────────────────────────────────────────────────
+    // Never register a listener on the deprecated `unload` event. Keeping it
+    // out restores back/forward-cache eligibility and clears the Lighthouse
+    // "avoid unload event listeners" audit (~19 best-practices points). The
+    // SDK still flushes on pagehide/visibilitychange, so telemetry is intact.
+    disablePageUnloadEvents: [...disablePageUnloadEvents],
+    enableAutoRouteTracking,
+    enableCorsCorrelation: true,
+    enableRequestHeaderTracking: true,
+    enableResponseHeaderTracking: true,
+    autoTrackPageVisitTime: true,
+    enableAjaxErrorStatusText: true,
+    enableAjaxPerfTracking: true,
+    disableExceptionTracking: false,
+    disableTelemetry: false,
+    loggingLevelConsole: dev ? 1 : 2,
+    loggingLevelTelemetry: dev ? 1 : 2,
+    samplingPercentage: 100,
+    isCookieUseDisabled: false,
+    distributedTracingMode: 2,
+    correlationHeaderDomains: [...DEFAULT_CORRELATION_HEADER_DOMAINS],
+    correlationHeaderExcludedDomains: [...DEFAULT_CORRELATION_HEADER_EXCLUDED_DOMAINS],
+    ...overrides,
+  }
+
+  // Re-assert the unload fix AFTER the overrides spread so a caller that passes
+  // `overrides` can never accidentally re-enable the deprecated `unload` listener
+  // and regress the fleet-wide BP-54 / bfcache fix. A caller that genuinely needs
+  // a different unload policy sets `disablePageUnloadEvents` via the dedicated
+  // option (applied above), not through `overrides`.
+  config.disablePageUnloadEvents = [...disablePageUnloadEvents]
+
+  return config
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+/**
+ * `@duffcloudservices/telemetry` — shared Azure Application Insights telemetry
+ * for DCS Vue sites.
+ *
+ * - {@link useTelemetry} — the full composable (init + track* API). Statically
+ *   imports the App Insights web SDK, so `initialize()` is synchronous.
+ * - {@link createTelemetryConfig} — the shared App Insights config, with the
+ *   `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.
+ */
+export { useTelemetry, type TelemetryApi } from './composable'
+export {
+  createTelemetryConfig,
+  DEFAULT_CLOUD_ROLE,
+  DEFAULT_DISABLE_PAGE_UNLOAD_EVENTS,
+} from './config'
+export type {
+  ApplicationInsightsConfig,
+  TelemetryConfigOptions,
+  TelemetryDependency,
+  TelemetryEvent,
+  TelemetryException,
+  TelemetryMetric,
+  TelemetryOptions,
+  TelemetryPageView,
+} from './types'

package/src/types.ts

@@ -0,0 +1,103 @@
+import type { IConfig, IConfiguration } from '@microsoft/applicationinsights-web'
+
+/**
+ * The concrete config shape accepted by the App Insights web SDK's
+ * `ApplicationInsights` constructor (`{ config }`). The SDK types the field as
+ * `IConfiguration & IConfig`; `disablePageUnloadEvents` lives on `IConfiguration`.
+ */
+export type ApplicationInsightsConfig = IConfiguration & IConfig
+
+export interface TelemetryEvent {
+  name: string
+  properties?: Record<string, string>
+  measurements?: Record<string, number>
+}
+
+export interface TelemetryPageView {
+  name?: string
+  uri?: string
+  properties?: Record<string, string>
+  measurements?: Record<string, number>
+}
+
+export interface TelemetryException {
+  exception: Error
+  properties?: Record<string, string>
+  measurements?: Record<string, number>
+}
+
+export interface TelemetryDependency {
+  name: string
+  data: string
+  duration: number
+  success: boolean
+  resultCode?: number
+  properties?: Record<string, string>
+  measurements?: Record<string, number>
+}
+
+export interface TelemetryMetric {
+  name: string
+  average: number
+  sampleCount?: number
+  min?: number
+  max?: number
+  properties?: Record<string, string>
+}
+
+/**
+ * Options that shape the App Insights *config object* — everything
+ * {@link createTelemetryConfig} needs. All fields are per-consumer variance;
+ * the package supplies the shared DCS defaults (including the unload fix).
+ */
+export interface TelemetryConfigOptions {
+  /** App Insights connection string (preferred). Sourced from the consumer's env. */
+  connectionString?: string
+  /** Legacy instrumentation key, if a connection string is not available. */
+  instrumentationKey?: string
+  /** Enable the SDK's built-in SPA route tracking. Default `true`. */
+  enableAutoRouteTracking?: boolean
+  /**
+   * Dev mode — routes internal SDK logs more verbosely to the console
+   * (`loggingLevel* = 1` vs `2`). The consumer passes `import.meta.env.DEV`.
+   * Default `false`.
+   */
+  dev?: boolean
+  /**
+   * Page-unload events the SDK must NOT hook. Defaults to `['unload']`.
+   *
+   * This is the fleet-wide "BP-54" fix: the App Insights web SDK otherwise
+   * registers a listener on the deprecated `unload` event, which (a) blocks
+   * back/forward-cache eligibility and (b) trips the Lighthouse
+   * "avoid `unload` event listeners" best-practices audit (~19 points).
+   * The SDK keeps flushing telemetry on `pagehide` / `visibilitychange`
+   * (the supported path), so nothing is lost. See the SDK's own
+   * `IConfiguration.disablePageUnloadEvents` docs.
+   */
+  disablePageUnloadEvents?: string[]
+  /**
+   * Deep overrides spread over the DCS defaults *last*, so a consumer can
+   * change any App Insights config field (correlation domains, sampling, …).
+   */
+  overrides?: Partial<ApplicationInsightsConfig>
+}
+
+/**
+ * Options for the {@link useTelemetry} composable — the config options plus the
+ * per-app enrichment values that the SDK config itself does not carry.
+ */
+export interface TelemetryOptions extends TelemetryConfigOptions {
+  /** `ai.cloud.role` for this app, e.g. `'dcs-web'`. Default `'dcs-site'`. */
+  cloudRole?: string
+  /**
+   * App version stamped onto every event (`app_version` property +
+   * `ai.application.ver` tag). The consumer passes its build-time version
+   * define; falls back to `window.__APP_VERSION__` then `'unknown'`.
+   */
+  appVersion?: string
+  /**
+   * Environment label added as the `environment` property, e.g. the consumer's
+   * `import.meta.env.MODE`. Falls back to `'unknown'`.
+   */
+  environment?: string
+}