@servicetitan/journey 2.1.0 → 3.0.0

package/src/global.ts

@@ -1,3 +1,5 @@
+import type { SlowRequestConfig } from './core/endpoint-policy';
+import { type RequestPolicyConfig } from './core/request-policy';
 import type { JourneyRuntime, JourneyRuntimeDebugSnapshot } from './core/runtime';
 
 /** Force-enable journey host wiring outside go* hosts (`__stJourney.enable()`). */
@@ -9,21 +11,45 @@ export const JOURNEY_DEBUG_STORAGE_KEY = 'st:journey:debug';
 /** @internal Shared cross-bundle bag on globalThis (`rum` fallback + DevTools helpers). */
 export const ST_JOURNEY_GLOBAL_KEY = '__stJourney';
 
-export interface JourneyDebugRuntimeEntry extends JourneyRuntimeDebugSnapshot {
-    id: string;
-}
+/** Bump when shared bag shape / policy semantics change incompatibly. */
+export const ST_JOURNEY_SCHEMA_VERSION = 2;
 
 export interface JourneyDebugState {
-    /** Force-enable flag (`st:journey:enabled`). */
+    /** Host default or force-enable (`isJourneyEnabled()`). */
     enabled: boolean;
     /** Console-logging flag (`st:journey:debug`). */
     debug: boolean;
     hasRum: boolean;
-    runtimes: JourneyDebugRuntimeEntry[];
+    runtimes: JourneyRuntimeDebugSnapshot[];
+}
+
+/** Shared host policies visible to every package copy on the page. */
+export interface JourneySharedPolicies {
+    slowRequests?: SlowRequestConfig;
+    /** Whether shared slowRequests were explicitly set via configureJourney. */
+    slowRequestsConfigured: boolean;
+    httpAbortedRequests: RequestPolicyConfig;
+    httpClientErrorRequests: RequestPolicyConfig;
+    autoAttributeRequests: boolean;
+    /** True after the first configureJourney that set any shared policy knob. */
+    locked: boolean;
+}
+
+/** DevTools registration — `{ id, getSnapshot }` so older package copies can still list runtimes. */
+export interface RuntimeRegistration {
+    id: string;
+    getSnapshot: () => JourneyRuntimeDebugSnapshot;
+    teardown?: () => void;
+}
+
+/** @internal Restore/dispose record for HTTP instrumentation. */
+export interface InstrumentRecord {
+    disposed: boolean;
+    restore?: () => void;
 }
 
 /**
- * @internal Cross-bundle surface on `globalThis.__stJourney`.
+ * Cross-bundle surface on `globalThis.__stJourney`.
  * Prefer importing `isJourneyEnabled` / `isJourneyDebugEnabled` from the package in app code.
  */
 export interface StJourneyGlobal {
@@ -32,6 +58,24 @@ export interface StJourneyGlobal {
      * Prefer `DD_RUM` (ST host: `datadogGuard`).
      */
     rum?: unknown;
+    /** Shared bag schema; mismatched copies warn but continue. */
+    schemaVersion?: number;
+    /** Host default enable (e.g. RUM active). Set via `setJourneyDefaultEnabled`. */
+    defaultEnabled?: boolean;
+    /** Shared configureJourney policies. */
+    policies: JourneySharedPolicies;
+    /**
+     * Bundle runtimes registered for DevTools `getDebugState()`.
+     * `{ id, getSnapshot }` so mixed package copies can list each other.
+     */
+    runtimeRegistrations: RuntimeRegistration[];
+    /** @internal Cross-bundle instrumented axios/fetch/jquery targets. */
+    instrumentedAxios: WeakSet<object>;
+    instrumentedFetch: WeakSet<object>;
+    instrumentedJquery: WeakSet<object>;
+    /** @internal Active instrument records for teardown. */
+    instrumentRecords: InstrumentRecord[];
+    fetchRestore?: () => void;
     enable(): void;
     disable(): void;
     isEnabled(): boolean;
@@ -45,21 +89,17 @@ export interface StJourneyGlobal {
     getDebugState(): JourneyDebugState;
 }
 
-interface RuntimeRegistration {
-    id: string;
-    getSnapshot: () => JourneyRuntimeDebugSnapshot;
-}
+let warnedMissingSlowRequests = false;
+let debugEnabledCache: boolean | undefined;
+const MAX_INSTRUMENT_RECORDS = 32;
 
-interface StJourneyGlobalInternal extends StJourneyGlobal {
-    /** @internal */
-    runtimeRegistrations: RuntimeRegistration[];
+function storageFor(key: string): Storage | undefined {
+    return key === JOURNEY_DEBUG_STORAGE_KEY ? globalThis.sessionStorage : globalThis.localStorage;
 }
 
-let runtimeSeq = 0;
-
 function readFlag(key: string): boolean {
     try {
-        return globalThis.localStorage?.getItem(key) === 'true';
+        return storageFor(key)?.getItem(key) === 'true';
     } catch {
         return false;
     }
@@ -67,19 +107,31 @@ function readFlag(key: string): boolean {
 
 function writeFlag(key: string, on: boolean): void {
     try {
+        const storage = storageFor(key);
         if (on) {
-            globalThis.localStorage?.setItem(key, 'true');
+            storage?.setItem(key, 'true');
         } else {
-            globalThis.localStorage?.removeItem(key);
+            storage?.removeItem(key);
         }
     } catch {
         // ignore storage failures (privacy mode, non-browser)
     }
 }
 
-/** True when `localStorage['st:journey:enabled'] === 'true'` (force-on outside go*). */
+/**
+ * Host default for journey wiring (e.g. RUM initialized). Stored on `__stJourney` so
+ * MFEs see the same value without importing Datadog. Call once after RUM init.
+ */
+export function setJourneyDefaultEnabled(enabled: boolean): void {
+    ensureGlobal().defaultEnabled = enabled === true;
+}
+
+/**
+ * True when the host default is on or force-enable is set
+ * (`st:journey:enabled` / `__stJourney.enable()`).
+ */
 export function isJourneyEnabled(): boolean {
-    return readFlag(JOURNEY_ENABLED_STORAGE_KEY);
+    return ensureGlobal().defaultEnabled === true || readFlag(JOURNEY_ENABLED_STORAGE_KEY);
 }
 
 /** Set the force-enable flag. Reload after calling from DevTools. */
@@ -92,19 +144,25 @@ export function disableJourney(): void {
     writeFlag(JOURNEY_ENABLED_STORAGE_KEY, false);
 }
 
-/** True when `localStorage['st:journey:debug'] === 'true'`. */
+/** True when `sessionStorage['st:journey:debug'] === 'true'`. */
 export function isJourneyDebugEnabled(): boolean {
-    return readFlag(JOURNEY_DEBUG_STORAGE_KEY);
+    const next = readFlag(JOURNEY_DEBUG_STORAGE_KEY);
+    if (debugEnabledCache !== next) {
+        debugEnabledCache = next;
+    }
+    return debugEnabledCache;
 }
 
 /** Set the console-debug flag. Reload after calling from DevTools. */
 export function enableJourneyDebugging(): void {
     writeFlag(JOURNEY_DEBUG_STORAGE_KEY, true);
+    debugEnabledCache = true;
 }
 
 /** Clear the console-debug flag. Reload after calling from DevTools. */
 export function disableJourneyDebugging(): void {
     writeFlag(JOURNEY_DEBUG_STORAGE_KEY, false);
+    debugEnabledCache = false;
 }
 
 function hasRum(): boolean {
@@ -113,7 +171,39 @@ function hasRum(): boolean {
     );
 }
 
-function buildDebugState(runtimes: RuntimeRegistration[]): JourneyDebugState {
+function snapshotOf(entry: unknown): JourneyRuntimeDebugSnapshot | undefined {
+    if (entry == null || typeof entry !== 'object') {
+        return undefined;
+    }
+    const rec = entry as {
+        id?: string;
+        getSnapshot?: () => JourneyRuntimeDebugSnapshot;
+        getDebugSnapshot?: () => JourneyRuntimeDebugSnapshot;
+    };
+    try {
+        if (typeof rec.getSnapshot === 'function') {
+            const snap = rec.getSnapshot();
+            const withId = snap.id ? snap : { ...snap, id: rec.id ?? '' };
+            return {
+                ...withId,
+                policyOverlay: withId.policyOverlay ?? {
+                    slowRequests: false,
+                    httpAbortedRequests: false,
+                    httpClientErrorRequests: false,
+                    autoAttributeRequests: false,
+                },
+            };
+        }
+        if (typeof rec.getDebugSnapshot === 'function') {
+            return rec.getDebugSnapshot();
+        }
+    } catch {
+        return undefined;
+    }
+    return undefined;
+}
+
+function buildDebugState(runtimes: readonly unknown[]): JourneyDebugState {
     if (!isJourneyDebugEnabled()) {
         return {
             enabled: isJourneyEnabled(),
@@ -127,26 +217,61 @@ function buildDebugState(runtimes: RuntimeRegistration[]): JourneyDebugState {
         enabled: isJourneyEnabled(),
         debug: true,
         hasRum: hasRum(),
-        runtimes: runtimes.map(entry => ({
-            id: entry.id,
-            ...entry.getSnapshot(),
-        })),
+        runtimes: runtimes
+            .map(snapshotOf)
+            .filter((snap): snap is JourneyRuntimeDebugSnapshot => snap != null),
+    };
+}
+
+function createEmptyPolicies(): JourneySharedPolicies {
+    return {
+        slowRequestsConfigured: false,
+        httpAbortedRequests: 'continue',
+        httpClientErrorRequests: 'continue',
+        autoAttributeRequests: true,
+        locked: false,
     };
 }
 
-function ensureGlobal(): StJourneyGlobalInternal {
+function ensureGlobal(): StJourneyGlobal {
     const g = globalThis as Record<string, unknown>;
-    const existing = g[ST_JOURNEY_GLOBAL_KEY] as StJourneyGlobalInternal | undefined;
+    const existing = g[ST_JOURNEY_GLOBAL_KEY] as StJourneyGlobal | undefined;
     // Reuse when a prior load already installed the full surface (incl. enable).
     if (existing?.runtimeRegistrations && typeof existing.enable === 'function') {
+        if (
+            existing.schemaVersion != null &&
+            existing.schemaVersion !== ST_JOURNEY_SCHEMA_VERSION
+        ) {
+            // eslint-disable-next-line no-console -- cross-bundle version skew
+            console.warn(
+                `[journey] __stJourney.schemaVersion mismatch: bag=${existing.schemaVersion}, package=${ST_JOURNEY_SCHEMA_VERSION}`
+            );
+        } else {
+            existing.schemaVersion ??= ST_JOURNEY_SCHEMA_VERSION;
+        }
+        existing.policies ??= createEmptyPolicies();
+        if (existing.policies.locked !== true && existing.policies.locked !== false) {
+            existing.policies.locked = false;
+        }
+        existing.instrumentedAxios ??= new WeakSet();
+        existing.instrumentedFetch ??= new WeakSet();
+        existing.instrumentedJquery ??= new WeakSet();
+        existing.instrumentRecords ??= [];
         return existing;
     }
 
     const runtimes: RuntimeRegistration[] = existing?.runtimeRegistrations ?? [];
 
-    const api: StJourneyGlobalInternal = {
+    const api: StJourneyGlobal = {
         rum: existing?.rum,
+        schemaVersion: ST_JOURNEY_SCHEMA_VERSION,
+        defaultEnabled: existing?.defaultEnabled === true,
         runtimeRegistrations: runtimes,
+        policies: createEmptyPolicies(),
+        instrumentedAxios: new WeakSet(),
+        instrumentedFetch: new WeakSet(),
+        instrumentedJquery: new WeakSet(),
+        instrumentRecords: [],
         enable: enableJourney,
         disable: disableJourney,
         isEnabled: isJourneyEnabled,
@@ -162,22 +287,129 @@ function ensureGlobal(): StJourneyGlobalInternal {
     return api;
 }
 
+/** @internal Shared policies bag. */
+export function getSharedPolicies(): JourneySharedPolicies {
+    return ensureGlobal().policies;
+}
+
+export function areSharedPoliciesLocked(): boolean {
+    return ensureGlobal().policies.locked === true;
+}
+
+function freezePolicies(policies: JourneySharedPolicies): JourneySharedPolicies {
+    const next: JourneySharedPolicies = { ...policies, locked: true };
+    if (next.slowRequests) {
+        const endpoints = next.slowRequests.endpoints
+            ? Object.freeze([...next.slowRequests.endpoints])
+            : next.slowRequests.endpoints;
+        next.slowRequests = Object.freeze({ ...next.slowRequests, endpoints });
+    }
+    return Object.freeze(next);
+}
+
 /**
- * @internal Register this bundle's module runtime on `__stJourney` so DevTools can
- * list every host/MFE engine copy on the page.
+ * First writer: merge `patch` into the shared bag and freeze it.
+ * Returns false when already locked (caller should overlay locally instead).
  */
-export function registerJourneyRuntime(runtime: JourneyRuntime): void {
-    const globalApi = ensureGlobal();
-    const id = `runtime-${++runtimeSeq}`;
-    globalApi.runtimeRegistrations.push({
-        id,
-        getSnapshot: () => runtime.getDebugSnapshot(),
-    });
+export function seedSharedPolicies(patch: Partial<Omit<JourneySharedPolicies, 'locked'>>): boolean {
+    const api = ensureGlobal();
+    if (api.policies.locked) {
+        return false;
+    }
+    api.policies = freezePolicies({ ...api.policies, ...patch });
+    return true;
+}
+
+export function getAutoAttributeRequests(): boolean {
+    return ensureGlobal().policies.autoAttributeRequests !== false;
+}
+
+export function getHttpAbortedRequestsPolicy(): RequestPolicyConfig {
+    return ensureGlobal().policies.httpAbortedRequests;
+}
+
+export function getHttpClientErrorRequestsPolicy(): RequestPolicyConfig {
+    return ensureGlobal().policies.httpClientErrorRequests;
+}
+
+export function getSharedSlowRequests(): SlowRequestConfig | undefined {
+    return ensureGlobal().policies.slowRequests;
+}
+
+export function areSharedSlowRequestsConfigured(): boolean {
+    return ensureGlobal().policies.slowRequestsConfigured === true;
+}
+
+/** One-time warn when transports are wired without explicit slowRequests. */
+export function warnIfSlowRequestsUnset(): void {
+    if (warnedMissingSlowRequests || areSharedSlowRequestsConfigured()) {
+        return;
+    }
+    warnedMissingSlowRequests = true;
+    // eslint-disable-next-line no-console -- host config guidance
+    console.warn(
+        '[journey] using default slowRequests.defaultMs=4000 — set configureJourney({ slowRequests }) to tune'
+    );
+}
+
+/** @internal Reset shared policies (tests / teardown). */
+export function resetSharedPolicies(): void {
+    const api = ensureGlobal();
+    api.policies = createEmptyPolicies();
+    warnedMissingSlowRequests = false;
+    debugEnabledCache = undefined;
+}
+
+export function getInstrumentedAxiosSet(): WeakSet<object> {
+    return ensureGlobal().instrumentedAxios;
+}
+
+export function getInstrumentedFetchSet(): WeakSet<object> {
+    return ensureGlobal().instrumentedFetch;
+}
+
+export function getInstrumentedJquerySet(): WeakSet<object> {
+    return ensureGlobal().instrumentedJquery;
+}
+
+export function registerInstrumentRecord(record: InstrumentRecord): void {
+    const api = ensureGlobal();
+    if (api.instrumentRecords.length >= MAX_INSTRUMENT_RECORDS) {
+        // eslint-disable-next-line no-console -- defensive cap for repeated instrumentation
+        console.warn('[journey] instrumentRecords cap reached — call teardownJourney()');
+        return;
+    }
+    api.instrumentRecords.push(record);
+}
+
+export function setFetchRestore(restore: (() => void) | undefined): void {
+    ensureGlobal().fetchRestore = restore;
 }
 
-/** @internal Ensure `__stJourney` exists (idempotent). */
-export function installJourneyGlobal(): void {
-    ensureGlobal();
+/**
+ * @internal Register this bundle's engine on `__stJourney` so DevTools can list
+ * every host/MFE copy on the page. Auto-assigns `runtime-N` when `runtime.id` is empty.
+ * Replaces an existing registration with the same id (HMR / test re-register).
+ */
+export function registerJourneyRuntime(
+    runtime: JourneyRuntime,
+    options?: { teardown?: () => void }
+): void {
+    const bag = ensureGlobal();
+    if (runtime.id === '') {
+        (runtime as { id: string }).id = `runtime-${bag.runtimeRegistrations.length + 1}`;
+    }
+    const entry: RuntimeRegistration = {
+        id: runtime.id,
+        getSnapshot: () => runtime.getDebugSnapshot(),
+        teardown: options?.teardown,
+    };
+    const existing = bag.runtimeRegistrations.findIndex(reg => reg.id === runtime.id);
+    if (existing >= 0) {
+        bag.runtimeRegistrations[existing] = entry;
+    } else {
+        bag.runtimeRegistrations.push(entry);
+    }
 }
 
 /**
@@ -194,3 +426,41 @@ export function getJourneyRumFallback(): unknown {
         StJourneyGlobal | undefined;
     return existing?.rum;
 }
+
+/**
+ * Dispose HTTP instrumentation hooks and reset registered engines that supplied a
+ * teardown callback. Intended for tests (e.g. afterEach). Prefer `resetJourney`
+ * when you only need this bundle's engine state.
+ */
+export function teardownJourney(): void {
+    const api = ensureGlobal();
+    for (const record of api.instrumentRecords) {
+        record.disposed = true;
+        try {
+            record.restore?.();
+        } catch {
+            // ignore restore failures
+        }
+    }
+    api.instrumentRecords = [];
+    try {
+        api.fetchRestore?.();
+    } catch {
+        // ignore
+    }
+    api.fetchRestore = undefined;
+
+    const kept: RuntimeRegistration[] = [];
+    for (const entry of api.runtimeRegistrations) {
+        if (entry.teardown) {
+            try {
+                entry.teardown();
+            } catch {
+                // ignore
+            }
+            continue;
+        }
+        kept.push(entry);
+    }
+    api.runtimeRegistrations = kept;
+}

package/src/index.ts

@@ -15,38 +15,35 @@ export {
     journeyStep,
     setJourneyTags,
     // Custom transport adapters / request attribution.
-    activeJourneyStep,
-    reportBackendRequest,
-    resolveJourneyStep,
-    JourneyStepTag,
+    singleInFlightJourneyStep,
+    resolveStamp,
+    JourneyStepStamp,
     type JourneyDef,
     type JourneyHandle,
     type JourneyNameLike,
     type JourneyStepOptions,
-    type JourneyStepRef,
     type JourneyStepTarget,
     type StepHandle,
 } from './core';
 
-export {
-    configureJourney,
-    type AppRequestTimeouts,
-    type EndpointPolicy,
-    type JourneyConfig,
-} from './config';
+export { configureJourney, type JourneyConfig } from './config';
+export type { EndpointPolicy, SlowRequestConfig } from './core/endpoint-policy';
+export type {
+    JourneyHttpPolicyContext,
+    JourneyHttpScore,
+    JourneyHttpScoreContext,
+    JourneyRequestPolicy,
+    JourneyStampOptions,
+    RequestPolicyConfig,
+} from './core/request-policy';
 
 export type { JourneySink } from './core';
 
-/**
- * @internal Accidentally exported — removing it is a breaking change, so it stays
- * for compatibility. Not part of the supported public API. Test helper only.
- */
-export { resetJourney } from './core';
-
 export { instrumentAxios } from './integrations/axios';
 export { instrumentFetch } from './integrations/fetch';
 export { exposeAppJourney, instrumentJquery } from './integrations/jquery';
 export { requestKey, type JourneyTimedMeta } from './integrations/request-key';
+export { onHttpComplete, type HttpCompleteReport } from './integrations/http-report';
 export {
     disableJourney,
     disableJourneyDebugging,
@@ -54,6 +51,8 @@ export {
     enableJourneyDebugging,
     isJourneyDebugEnabled,
     isJourneyEnabled,
+    setJourneyDefaultEnabled,
+    teardownJourney,
 } from './global';
 export { sendToConsole } from './sinks/console';
 export { normalizeTagValue, sendToDatadog, setJourneyRum } from './sinks/datadog';
@@ -62,3 +61,4 @@ export type { JourneyEvent, JourneyStepEvent, TagValue } from './core';
 
 export { useJourneyName, useOptionalJourneyName } from './integrations/react/context';
 export { JourneyScope } from './integrations/react/scope';
+export { useJourneyStep } from './integrations/react/use-journey-step';