@duffcloudservices/telemetry 0.2.0 → 0.3.0

package/README.md

@@ -29,6 +29,38 @@ pnpm add @duffcloudservices/telemetry
 pnpm add @microsoft/applicationinsights-web vue
 ```
 
+## The SDK loads lazily — adoption does not move it onto your entry chunk
+
+Importing `useTelemetry` costs your **entry chunk** nothing but this package's own
+code (~6–7KB raw / ~2KB gzip minified). The ~192KB raw / ~78KB gzip App Insights
+web SDK is reached through a dynamic `import()` inside `initialize()`, so your
+bundler emits it as its **own async chunk**, fetched only when `initialize()` runs.
+
+This is not a micro-optimisation, it is the reason the package is adoptable. Before
+`0.3.0` the composable imported the SDK statically. Measured on a live customer site
+(bryans-handyman-solutions, 2026-08-11), adopting `0.2.1` in place of the site's
+hand-rolled lazy composable moved the whole SDK onto the entry chunk:
+
+| | entry chunk raw | entry chunk gzip | SDK on critical path? |
+| --- | --- | --- | --- |
+| site's own lazy composable | 213,172 B | 76,398 B | no — separate async chunk |
+| adopting `0.2.1` (static SDK) | 405,817 B **(+90.4%)** | 153,493 B **(+101.2%)** | **yes** |
+| adopting `0.3.0` (lazy SDK) | 219,842 B **(+3.1%)** | 78,582 B **(+2.9%)** | no — separate async chunk, byte-identical to the site's own |
+
+Total transferred JS barely moved in the middle row — the SDK simply relocated onto
+the critical path and defeated the site's deliberate `requestIdleCallback` deferral.
+
+Laziness costs you no telemetry:
+
+- **Calls made during the load are buffered**, with their call-time properties, and
+  replayed in order once the SDK lands (bounded at 100 calls). A landing pageView or
+  a boot-time `trackException` is not lost.
+- **`initialize()` is still synchronous** and still returns `boolean` — "telemetry is
+  enabled and the SDK load has started". Nothing about the call site changes.
+- **Concurrent `initialize()` callers share one load** and one SDK instance.
+- `whenReady(): Promise<boolean>` is available for the rare caller that must
+  sequence work after the SDK exists. You should not need it to avoid losing events.
+
 ## Usage — composable (SPA / eager)
 
 The connection string, cloud role, environment and app version are supplied by
@@ -48,15 +80,27 @@ const telemetry = useTelemetry({
 })
 
 telemetry.initialize() // synchronous; no-op (with a loud one-shot warn) when unconfigured
-telemetry.trackCtaClick('hero-cta', '/contact')
+telemetry.trackCtaClick('hero-cta', '/contact') // buffered if the SDK is still loading
+
+// Only when you must sequence work after the SDK itself exists:
+void telemetry.whenReady().then(() => telemetry.trackPageView())
 ```
 
-`initialize()` is **synchronous** because the SDK is statically imported.
+`initialize()` returns `boolean` **synchronously** — the SDK loads in the background
+(see above). Events fired before it lands are buffered, not dropped, so the common
+case needs no `await` at all.
+
+> **Migrating from a site-local composable?** The site versions were
+> `async initialize(): Promise<boolean>`, so `void initialize().then(…)` must become
+> `initialize(); void whenReady().then(…)`. TypeScript flags the old form
+> (`Property 'then' does not exist on type 'boolean'`), so this cannot slip through a
+> site's `type-check`.
 
 ## Usage — config only (lazy / inert loaders)
 
-Sites that lazy-load the SDK themselves (to stay inert when telemetry is
-unconfigured) can import just the config — no SDK is pulled in:
+`useTelemetry` already loads the SDK lazily, so most sites no longer need this. It
+remains for consumers that construct the SDK themselves — a bespoke boot, or a
+non-Vue surface — and want the shared config without the composable:
 
 ```ts
 import { createTelemetryConfig } from '@duffcloudservices/telemetry/config'
@@ -103,7 +147,7 @@ omit the field entirely rather than block a submission.
 
 | Export | Description |
 | --- | --- |
-| `useTelemetry(options?)` | Full composable: `initialize`, `trackEvent`, `trackPageView`, `trackCtaClick`, `trackException`, `trackMetric`, `trackDependency`, `flush`, `startTrackPage`, `stopTrackPage`, plus `isEnabled` / `isInitialized` / `initializationError` refs. |
+| `useTelemetry(options?)` | Full composable: `initialize`, `whenReady`, `trackEvent`, `trackPageView`, `trackCtaClick`, `trackException`, `trackMetric`, `trackDependency`, `flush`, `startTrackPage`, `stopTrackPage`, plus `isEnabled` / `isInitialized` / `initializationError` refs. Loads the App Insights SDK lazily. |
 | `createTelemetryConfig(options?)` | Builds the App Insights config with DCS defaults + the `disablePageUnloadEvents: ['unload']` fix. Pure, no SDK import. |
 | `getJourneyContext()` | Visitor-journey join key for a form submission. Never throws. Also at `@duffcloudservices/telemetry/journey` (no SDK import). |
 | `toJourneyTelemetryPayload(context?)` | Flattens a journey context into the DCS `SubmissionTelemetry` wire shape, or `undefined` when empty. |

package/dist/index.d.ts

@@ -12,12 +12,36 @@ import '@microsoft/applicationinsights-web';
  * 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}.
+ *
+ * ## The SDK loads LAZILY (C-601)
+ *
+ * `initialize()` still returns `boolean` synchronously — "telemetry is enabled and
+ * the SDK load has started" — but the App Insights web SDK itself arrives through
+ * a dynamic `import()`, so a bundler emits it as its own async chunk instead of
+ * folding ~192KB raw / ~78KB gzip into the consumer's entry chunk. Adopting this
+ * package therefore no longer moves the SDK onto the critical path.
+ *
+ * Three things make that safe:
+ *
+ * 1. **Buffered, not dropped.** track* calls made between `initialize()` and the
+ *    chunk landing are queued with their call-time properties and replayed in
+ *    order (bounded at {@link PENDING_CALL_LIMIT}). The site-local composables this
+ *    package replaces dropped them.
+ * 2. **One init.** Concurrent `initialize()` callers share one `import()` and one
+ *    `new ApplicationInsights(...)` via {@link initPromise}.
+ * 3. **Guards stay synchronous.** `enableAutoRouteTracking` is resolved before the
+ *    `await`, so the C-288 double-count guard is armed for calls made during the
+ *    load, not only after it.
+ *
+ * `whenReady()` is there for the rare caller that must sequence work after the SDK
+ * exists. You should not need it to avoid losing events.
  */
 declare function useTelemetry(options?: TelemetryOptions): {
     isEnabled: vue.ComputedRef<boolean>;
     isInitialized: vue.Ref<boolean, boolean>;
     initializationError: vue.Ref<string | null, string | null>;
     initialize: () => boolean;
+    whenReady: () => Promise<boolean>;
     flush: () => void;
     startTrackPage: (name?: string) => void;
     stopTrackPage: (name?: string, url?: string, properties?: Record<string, string>, measurements?: Record<string, number>) => void;
@@ -31,4 +55,44 @@ declare function useTelemetry(options?: TelemetryOptions): {
 /** The full public API returned by {@link useTelemetry}. */
 type TelemetryApi = ReturnType<typeof useTelemetry>;
 
-export { type TelemetryApi, TelemetryDependency, TelemetryEvent, TelemetryException, TelemetryMetric, TelemetryOptions, TelemetryPageView, useTelemetry };
+/**
+ * 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. */
+declare const SYNTHETIC_CAPTURE_PARAMS: readonly ["dcs-hide-ribbon", "dcs-no-telemetry"];
+/**
+ * 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.
+ */
+declare function syntheticCaptureDetected(): boolean;
+
+export { SYNTHETIC_CAPTURE_PARAMS, type TelemetryApi, TelemetryDependency, TelemetryEvent, TelemetryException, TelemetryMetric, TelemetryOptions, TelemetryPageView, syntheticCaptureDetected, useTelemetry };

package/dist/index.js

@@ -2,12 +2,67 @@ import { DEFAULT_CLOUD_ROLE, createTelemetryConfig } from './chunk-MX6WFWG4.js';
 export { DEFAULT_CLOUD_ROLE, DEFAULT_DISABLE_PAGE_UNLOAD_EVENTS, createTelemetryConfig } from './chunk-MX6WFWG4.js';
 import { captureJourneyFirstTouch, setJourneyIdentityResolver } from './chunk-DKX4AC2U.js';
 export { JOURNEY_FIELD_MAX_LENGTH, JOURNEY_FIRST_TOUCH_KEY, captureJourneyFirstTouch, getJourneyContext, setJourneyIdentityResolver, toJourneyTelemetryPayload } from './chunk-DKX4AC2U.js';
-import { ApplicationInsights } from '@microsoft/applicationinsights-web';
 import { ref, computed } from 'vue';
 
+// src/syntheticCapture.ts
+var SYNTHETIC_CAPTURE_PARAMS = ["dcs-hide-ribbon", "dcs-no-telemetry"];
+function syntheticCaptureDetected() {
+  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;
+  }
+}
+
+// src/composable.ts
 var appInsights = null;
 var isInitialized = ref(false);
 var initializationError = ref(null);
+var initPromise = null;
+var pendingSdkCalls = [];
+var PENDING_CALL_LIMIT = 100;
+var warnedBufferFull = false;
+function bufferWhileLoading(call) {
+  if (!initPromise) return false;
+  if (pendingSdkCalls.length >= PENDING_CALL_LIMIT) {
+    if (!warnedBufferFull) {
+      warnedBufferFull = true;
+      console.warn(
+        `[telemetry] pre-init buffer full (${PENDING_CALL_LIMIT} calls) \u2014 dropping telemetry until the Application Insights SDK chunk finishes loading. If you see this, the SDK chunk is failing to load, not merely slow.`
+      );
+    }
+    return true;
+  }
+  pendingSdkCalls.push(call);
+  return true;
+}
+function drainPendingSdkCalls(instance) {
+  const calls = pendingSdkCalls.splice(0, pendingSdkCalls.length);
+  for (const call of calls) {
+    try {
+      call(instance);
+    } catch (error) {
+      console.error("Failed to replay buffered telemetry:", error);
+    }
+  }
+}
+function discardPendingSdkCalls() {
+  pendingSdkCalls.length = 0;
+}
+async function loadSdk() {
+  const module = await import('@microsoft/applicationinsights-web');
+  return module.ApplicationInsights;
+}
+function nowMs() {
+  return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+}
+var preInitPageTimings = /* @__PURE__ */ new Map();
+function resolvePageName(name) {
+  if (typeof name === "string") return name;
+  return typeof document !== "undefined" ? document.title : "";
+}
 var warnedDisabled = false;
 var warnedNotInitialized = false;
 var warnedDoubleCount = false;
@@ -91,9 +146,15 @@ function useTelemetry(options = {}) {
   const initialize = () => {
     try {
       captureJourneyFirstTouch();
+      if (syntheticCaptureDetected()) {
+        return false;
+      }
       if (isInitialized.value && appInsights) {
         return true;
       }
+      if (initPromise) {
+        return true;
+      }
       if (!isEnabled.value) {
         if (!warnedDisabled) {
           warnedDisabled = true;
@@ -112,21 +173,37 @@ function useTelemetry(options = {}) {
         overrides: options.overrides
       });
       autoRouteTrackingActive = resolvedConfig.enableAutoRouteTracking !== false;
-      appInsights = new ApplicationInsights({ config: resolvedConfig });
-      appInsights.loadAppInsights();
-      appInsights.addTelemetryInitializer((envelope) => {
+      initPromise = (async () => {
         try {
-          enrichTelemetryEnvelope(envelope);
+          const ApplicationInsightsCtor = await loadSdk();
+          const instance = new ApplicationInsightsCtor({ config: resolvedConfig });
+          instance.loadAppInsights();
+          instance.addTelemetryInitializer((envelope) => {
+            try {
+              enrichTelemetryEnvelope(envelope);
+            } catch (error) {
+              console.warn("Failed to add web telemetry context:", error);
+            }
+            return true;
+          });
+          appInsights = instance;
+          setJourneyIdentityResolver(() => readSdkIdentity(appInsights));
+          isInitialized.value = true;
+          initializationError.value = null;
+          console.log("Application Insights initialized successfully");
+          drainPendingSdkCalls(instance);
+          attachConversionCapture(trackEvent);
+          return true;
         } catch (error) {
-          console.warn("Failed to add web telemetry context:", error);
+          const errorMessage = error instanceof Error ? error.message : "Unknown initialization error";
+          initializationError.value = errorMessage;
+          console.error("Failed to initialize Application Insights:", error);
+          discardPendingSdkCalls();
+          preInitPageTimings.clear();
+          initPromise = null;
+          return false;
         }
-        return true;
-      });
-      setJourneyIdentityResolver(() => readSdkIdentity(appInsights));
-      isInitialized.value = true;
-      initializationError.value = null;
-      console.log("Application Insights initialized successfully");
-      attachConversionCapture(trackEvent);
+      })();
       return true;
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : "Unknown initialization error";
@@ -135,8 +212,18 @@ function useTelemetry(options = {}) {
       return false;
     }
   };
+  const whenReady = () => {
+    if (isInitialized.value && appInsights) return Promise.resolve(true);
+    return initPromise ?? Promise.resolve(false);
+  };
   const trackEvent = (event) => {
     if (!appInsights || !isInitialized.value) {
+      const payload = {
+        name: event.name,
+        properties: buildEventProperties(event.properties),
+        measurements: event.measurements
+      };
+      if (bufferWhileLoading((instance) => instance.trackEvent(payload))) return;
       if (!warnedNotInitialized) {
         warnedNotInitialized = true;
         console.warn(
@@ -156,10 +243,6 @@ function useTelemetry(options = {}) {
     }
   };
   const trackPageView = (pageView) => {
-    if (!appInsights || !isInitialized.value) {
-      console.warn("Application Insights not initialized, skipping page view tracking");
-      return;
-    }
     if (autoRouteTrackingActive && !pageView?.force) {
       if (!warnedDoubleCount) {
         warnedDoubleCount = true;
@@ -169,17 +252,23 @@ function useTelemetry(options = {}) {
       }
       return;
     }
+    const referrer = typeof document !== "undefined" ? document.referrer ?? "" : "";
+    const payload = {
+      name: pageView?.name || (typeof document !== "undefined" ? document.title : void 0),
+      uri: pageView?.uri || (typeof window !== "undefined" ? window.location.href : void 0),
+      properties: buildEventProperties({
+        referrer,
+        ...pageView?.properties
+      }),
+      measurements: pageView?.measurements
+    };
+    if (!appInsights || !isInitialized.value) {
+      if (bufferWhileLoading((instance) => instance.trackPageView(payload))) return;
+      console.warn("Application Insights not initialized, skipping page view tracking");
+      return;
+    }
     try {
-      const referrer = typeof document !== "undefined" ? document.referrer ?? "" : "";
-      appInsights.trackPageView({
-        name: pageView?.name || (typeof document !== "undefined" ? document.title : void 0),
-        uri: pageView?.uri || (typeof window !== "undefined" ? window.location.href : void 0),
-        properties: buildEventProperties({
-          referrer,
-          ...pageView?.properties
-        }),
-        measurements: pageView?.measurements
-      });
+      appInsights.trackPageView(payload);
     } catch (error) {
       console.error("Failed to track page view:", error);
     }
@@ -194,58 +283,64 @@ function useTelemetry(options = {}) {
     });
   };
   const trackException = (exception) => {
+    const payload = {
+      exception: exception.exception,
+      properties: buildEventProperties({
+        url: typeof window !== "undefined" ? window.location.href : "",
+        userAgent: typeof navigator !== "undefined" ? navigator.userAgent : "",
+        ...exception.properties
+      }),
+      measurements: exception.measurements
+    };
     if (!appInsights || !isInitialized.value) {
+      if (bufferWhileLoading((instance) => instance.trackException(payload))) return;
       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
-      });
+      appInsights.trackException(payload);
     } catch (error) {
       console.error("Failed to track exception:", error);
     }
   };
   const trackDependency = (dependency) => {
+    const payload = {
+      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
+    };
     if (!appInsights || !isInitialized.value) {
+      if (bufferWhileLoading((instance) => instance.trackDependencyData(payload))) return;
       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
-      });
+      appInsights.trackDependencyData(payload);
     } catch (error) {
       console.error("Failed to track dependency:", error);
     }
   };
   const trackMetric = (metric) => {
+    const payload = {
+      name: metric.name,
+      average: metric.average,
+      sampleCount: metric.sampleCount,
+      min: metric.min,
+      max: metric.max,
+      properties: buildEventProperties(metric.properties)
+    };
     if (!appInsights || !isInitialized.value) {
+      if (bufferWhileLoading((instance) => instance.trackMetric(payload))) return;
       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)
-      });
+      appInsights.trackMetric(payload);
     } catch (error) {
       console.error("Failed to track metric:", error);
     }
@@ -269,28 +364,58 @@ function useTelemetry(options = {}) {
     return true;
   };
   const startTrackPage = (name) => {
-    if (!appInsights || !isInitialized.value) return;
     if (manualPageTrackingIsRedundant()) return;
-    try {
-      appInsights.startTrackPage(name);
-    } catch (error) {
-      console.error("Failed to start track page:", error);
+    if (appInsights && isInitialized.value) {
+      try {
+        appInsights.startTrackPage(name);
+      } catch (error) {
+        console.error("Failed to start track page:", error);
+      }
+      return;
+    }
+    if (initPromise) {
+      preInitPageTimings.set(resolvePageName(name), nowMs());
     }
   };
   const stopTrackPage = (name, url, properties, measurements) => {
-    if (!appInsights || !isInitialized.value) return;
     if (manualPageTrackingIsRedundant()) return;
-    try {
-      appInsights.stopTrackPage(name, url, buildEventProperties(properties), measurements);
-    } catch (error) {
-      console.error("Failed to stop track page:", error);
+    if (appInsights && isInitialized.value) {
+      try {
+        appInsights.stopTrackPage(name, url, buildEventProperties(properties), measurements);
+      } catch (error) {
+        console.error("Failed to stop track page:", error);
+      }
+      return;
     }
+    if (!initPromise) return;
+    const key = resolvePageName(name);
+    const startedAt = preInitPageTimings.get(key);
+    if (startedAt === void 0) return;
+    preInitPageTimings.delete(key);
+    const duration = Math.max(0, Math.round(nowMs() - startedAt));
+    const payload = {
+      name: key,
+      uri: url ?? (typeof window !== "undefined" ? window.location.href : void 0),
+      // `duration` as a STRING alongside the custom properties is the SDK's OWN
+      // encoding for a timed page view — `_pageTracking.action` does
+      // `properties.duration = duration.toString()` — and it is what
+      // `sendPageViewInternal` reads to back-date `startTime`.
+      //
+      // The cast is deliberate: `IPageViewTelemetry` declares `properties.duration`
+      // as `number`, which its own `stopTrackPage` path does not honour. Matching
+      // the runtime the collector actually parses beats matching a type that the
+      // emitting SDK contradicts.
+      properties: { ...buildEventProperties(properties), duration: String(duration) },
+      measurements
+    };
+    bufferWhileLoading((instance) => instance.trackPageView(payload));
   };
   return {
     isEnabled,
     isInitialized,
     initializationError,
     initialize,
+    whenReady,
     flush,
     startTrackPage,
     stopTrackPage,
@@ -303,6 +428,6 @@ function useTelemetry(options = {}) {
   };
 }
 
-export { useTelemetry };
+export { SYNTHETIC_CAPTURE_PARAMS, syntheticCaptureDetected, useTelemetry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map