@servicetitan/journey 2.1.0 → 3.0.0

package/src/integrations/jquery/index.ts

@@ -11,17 +11,21 @@ import { moduleRuntime } from '../../core/runtime';
 
 /**
  * Knockout / desktop-legacy bridge on `window.App.Journey`.
- * Prefer `defineJourney` handles; `journeyStep` / `firstOpenJourney` cover multi-journey steps.
+ * Prefer `defineJourney` handles; `journeyStep` / `firstOpenJourneyName` cover multi-journey steps.
+ * Use `getJourneyHandle(name)` when you need the handle from another module.
  */
 interface AppJourneyApi {
-    defineJourney(def: JourneyDef): JourneyHandle;
+    defineJourney(config: JourneyDef): JourneyHandle;
     journeyStep<T>(
         journey: JourneyStepTarget,
         stepName: string,
         fn: (step: StepHandle) => T | Promise<T>,
         opts?: JourneyStepOptions
     ): Promise<T>;
-    firstOpenJourney(names: readonly string[]): string | null;
+    /** First open journey **name** among candidates, or null. */
+    firstOpenJourneyName(names: readonly string[]): string | null;
+    /** `defineJourney` handle for an open name, or null. */
+    getJourneyHandle(name: string): JourneyHandle | null;
 }
 
 export type WindowWithAppJourney = Window & {
@@ -31,9 +35,17 @@ export type WindowWithAppJourney = Window & {
 let journeyExposed = false;
 let windowJourneyApi: AppJourneyApi | undefined;
 
+function handleForOpenJourney(name: string): JourneyHandle | null {
+    const open = moduleRuntime.getOpenJourney(name);
+    if (!open) {
+        return null;
+    }
+    return defineJourney(open.config);
+}
+
 /**
  * Publish the Knockout bridge on window.App.Journey. Idempotent for the real window.
- * Optional `target` is for tests.
+ * Optional `target` is for tests. Never throws — logs and returns a usable API if publish fails.
  */
 export function exposeAppJourney(target: WindowWithAppJourney = window): AppJourneyApi {
     if (journeyExposed && target === window && windowJourneyApi) {
@@ -43,13 +55,25 @@ export function exposeAppJourney(target: WindowWithAppJourney = window): AppJour
     const api: AppJourneyApi = {
         defineJourney,
         journeyStep,
-        firstOpenJourney: names => moduleRuntime.firstOpenJourney(names),
+        firstOpenJourneyName: names => moduleRuntime.firstOpenJourneyName(names),
+        getJourneyHandle: handleForOpenJourney,
     };
-    target.App = target.App ?? {};
-    target.App.Journey = api;
-    if (target === window) {
-        journeyExposed = true;
-        windowJourneyApi = api;
+
+    try {
+        if (target == null || (typeof target !== 'object' && typeof target !== 'function')) {
+            // eslint-disable-next-line no-console -- soft-skip missing host window
+            console.warn('[journey] exposeAppJourney: skipped — missing');
+            return api;
+        }
+        target.App = target.App ?? {};
+        target.App.Journey = Object.freeze(api);
+        if (target === window) {
+            journeyExposed = true;
+            windowJourneyApi = api;
+        }
+    } catch (err) {
+        // eslint-disable-next-line no-console -- soft-fail host wiring
+        console.error('[journey] exposeAppJourney failed', err);
     }
     return api;
 }

package/src/integrations/jquery/instrument.ts

@@ -1,22 +1,29 @@
+import { resolveStamp } from '../../core';
+import { adoptJourneyStepStamp, type JourneyStepStamp } from '../../core/step-tag';
 import {
-    activeJourneyStep,
-    JourneyStepTag,
-    reportBackendRequest,
-    resolveJourneyStep,
-} from '../../core';
-import { requestKey } from '../request-key';
+    getInstrumentedJquerySet,
+    registerInstrumentRecord,
+    type InstrumentRecord,
+} from '../../global';
+import { onHttpComplete } from '../http-report';
+import { requestKey, type JourneyTimedMeta } from '../request-key';
+import { acceptInstrumentTarget } from '../soft-skip';
 
 export interface JqueryXHR {
     status: number;
-    journeyStep?: unknown;
+    statusText?: string;
+    stamp?: unknown;
     journeyStart?: number;
 }
 
-export interface JqueryAjaxSettings {
+export interface JqueryAjaxSettings extends JourneyTimedMeta {
     url?: string;
-    journeyStep?: unknown;
+    type?: string;
+    method?: string;
 }
 
+const jqueryStamps = new WeakMap<object, JourneyStepStamp>();
+
 export interface JqueryStatic {
     ajaxPrefilter(
         handler: (
@@ -32,53 +39,130 @@ export interface JqueryStatic {
     };
 }
 
-const instrumented = new WeakSet<object>();
-
 function reportTiming(jqXHR: JqueryXHR, settings: JqueryAjaxSettings): void {
-    const step = resolveJourneyStep(jqXHR.journeyStep);
-    if (!step) {
+    const stamp = jqueryStamps.get(jqXHR) ?? adoptJourneyStepStamp(jqXHR.stamp);
+    if (!stamp || stamp.ignore || settings.ignore === true) {
         return;
     }
     const start = jqXHR.journeyStart ?? globalThis.performance.now();
+    const aborted = jqXHR.statusText === 'abort';
     // jQuery uses status 0 for network / abort failures — treat like a missing status.
-    const status = jqXHR.status === 0 ? undefined : jqXHR.status;
-    reportBackendRequest(
-        step,
+    const status = aborted || jqXHR.status === 0 ? undefined : jqXHR.status;
+    onHttpComplete({
+        stamp,
         status,
-        globalThis.performance.now() - start,
-        requestKey(settings.url, undefined, undefined)
+        durationMs: globalThis.performance.now() - start,
+        requestKey: requestKey(settings.url, undefined, undefined),
+        aborted,
+        url: settings.url,
+        method: settings.type ?? settings.method,
+        meta: settings,
+        request: settings,
+        response: jqXHR,
+    });
+}
+
+function isJqueryStatic(value: unknown): value is JqueryStatic {
+    return (
+        typeof value === 'function' && typeof (value as JqueryStatic).ajaxPrefilter === 'function'
     );
 }
 
-/** Wire a jQuery static into the journey engine. Call once per $ (idempotent). Observation-only. */
-export function instrumentJquery($: JqueryStatic): void {
-    if (instrumented.has($ as object)) {
+/** Resolve `globalThis.$`, then `globalThis.jQuery`. */
+export function resolveGlobalJquery(): JqueryStatic | null | undefined {
+    const g = globalThis as typeof globalThis & { $?: unknown; jQuery?: unknown };
+    return (g.$ ?? g.jQuery) as JqueryStatic | null | undefined;
+}
+
+/** Live record per $ — handlers look this up so restore+rewire does not stack prefilters. */
+const jqueryLiveRecords = new WeakMap<object, InstrumentRecord>();
+/** jQuery cannot unregister these; track each so a partial-wire retry does not stack. */
+const jqueryPrefiltersInstalled = new WeakSet<object>();
+const jqueryCompletesInstalled = new WeakSet<object>();
+
+function stampAjax(jqXHR: JqueryXHR, options: JqueryAjaxSettings): void {
+    if (options.ignore === true) {
         return;
     }
-    instrumented.add($ as object);
+    const stamp = resolveStamp(jqXHR.stamp ?? options.stamp);
+    if (stamp) {
+        jqueryStamps.set(jqXHR, stamp);
+        delete jqXHR.stamp;
+        delete options.stamp;
+    }
+    if (stamp && !stamp.ignore) {
+        jqXHR.journeyStart = globalThis.performance.now();
+    }
+}
 
-    $.ajaxPrefilter((options, _originalOptions, jqXHR) => {
-        /*
-         * Prefer explicit step.tag() (settings or XHR); else soft ambient.
-         * Box ambient steps in JourneyStepTag — raw StepRecord is circular and blows jQuery deep-merge.
-         */
-        if (!jqXHR.journeyStep) {
-            const fromSettings = options.journeyStep;
-            if (fromSettings) {
-                jqXHR.journeyStep = fromSettings;
-            } else {
-                const step = activeJourneyStep();
-                if (step) {
-                    jqXHR.journeyStep = new JourneyStepTag(step);
+/**
+ * Wire a jQuery static into the journey engine. Call once per $ (idempotent). Observation-only.
+ * Soft-skips when `$` is missing or not a real jQuery (no `ajaxPrefilter`) so hosts can pass `$` as-is.
+ * Returns a restore that disposes handlers (they no-op after restore).
+ */
+export function instrumentJquery($: JqueryStatic | null | undefined): () => void {
+    const jquery = acceptInstrumentTarget('Jquery', $, isJqueryStatic);
+    const instrumented = getInstrumentedJquerySet();
+    if (!jquery || instrumented.has(jquery as object)) {
+        return () => {};
+    }
+
+    const key = jquery as object;
+    const record: InstrumentRecord = { disposed: false };
+
+    try {
+        if (!jqueryPrefiltersInstalled.has(key)) {
+            jquery.ajaxPrefilter((options, _originalOptions, jqXHR) => {
+                const current = jqueryLiveRecords.get(key);
+                if (!current || current.disposed) {
+                    return;
                 }
-            }
+                stampAjax(jqXHR, options);
+            });
+            jqueryPrefiltersInstalled.add(key);
         }
-        if (resolveJourneyStep(jqXHR.journeyStep)) {
-            jqXHR.journeyStart = globalThis.performance.now();
+        if (!jqueryCompletesInstalled.has(key)) {
+            jquery(document).ajaxComplete((_event, jqXHR, settings) => {
+                const current = jqueryLiveRecords.get(key);
+                if (!current || current.disposed) {
+                    return;
+                }
+                reportTiming(jqXHR, settings);
+            });
+            jqueryCompletesInstalled.add(key);
         }
-    });
+        jqueryLiveRecords.set(key, record);
+        instrumented.add(key);
+    } catch (err) {
+        /*
+         * Keep per-handler installed flags so a retry cannot double-register
+         * prefilters. Restore deletes the shared instrumented slot so teardown /
+         * retry can finish whichever handler never succeeded.
+         */
+        record.disposed = true;
+        instrumented.add(key);
+        const restore = () => {
+            record.disposed = true;
+            if (jqueryLiveRecords.get(key) === record) {
+                jqueryLiveRecords.delete(key);
+            }
+            instrumented.delete(key);
+        };
+        record.restore = restore;
+        registerInstrumentRecord(record);
+        // eslint-disable-next-line no-console -- soft-fail host wiring
+        console.error('[journey] instrumentJquery failed', err);
+        return restore;
+    }
 
-    $(document).ajaxComplete((_event, jqXHR, settings) => {
-        reportTiming(jqXHR, settings);
-    });
+    const restore = () => {
+        record.disposed = true;
+        if (jqueryLiveRecords.get(key) === record) {
+            jqueryLiveRecords.delete(key);
+        }
+        instrumented.delete(key);
+    };
+    record.restore = restore;
+    registerInstrumentRecord(record);
+    return restore;
 }

package/src/integrations/react/context.ts

@@ -7,7 +7,10 @@ export function useOptionalJourneyName(): string | null {
     return useContext(JourneyNameContext);
 }
 
-/** Active journey name; throws outside a `<JourneyScope>`. */
+/**
+ * Active journey name; throws outside a `<JourneyScope>`.
+ * Prefer {@link useOptionalJourneyName} when the shell may omit a scope.
+ */
 export function useJourneyName(): string {
     const name = useContext(JourneyNameContext);
     if (!name) {

package/src/integrations/react/scope.tsx

@@ -1,33 +1,83 @@
 import { useEffect, type ReactNode } from 'react';
 
-import { excludeJourney, setJourneyTags, type JourneyDef } from '../../core';
+import { setJourneyTags, type JourneyDef } from '../../core';
 import { moduleRuntime } from '../../core/runtime';
 import type { TagValue } from '../../core/types';
 import { JourneyNameContext } from './context';
+import { stableEndpointKey, stableExpectedKey, stableTagsKey } from './stable-config-keys';
+
+type JourneyScopeDef = JourneyDef | { config: JourneyDef };
 
 /**
  * Opens a journey while the subtree is mounted; Excludes on unmount.
- * Config (timeouts, endpoints, tags, …) is captured when the journey opens;
- * only a `name` change re-opens.
+ * `name` is the lifecycle key — changing it excludes the previous instance
+ * and opens a new one. Other config fields and `tags` update the open instance
+ * in place (timeouts re-arm; they do not restart).
+ *
+ * Pass a {@link JourneyDef} (`<JourneyScope {...def}>`) or spread a handle
+ * (`<JourneyScope {...makeASaleJourney}>` reads `handle.config`).
+ *
+ * React 18 Strict Mode (development) remounts once: expect an `excluded` emission
+ * then a fresh open. Production single-mount does not.
  */
 export function JourneyScope({
     tags,
     children,
-    ...def
-}: JourneyDef & {
+    ...rest
+}: JourneyScopeDef & {
     tags?: Record<string, TagValue>;
     children: ReactNode;
 }) {
-    const { name } = def;
+    const def: JourneyDef = 'config' in rest ? rest.config : rest;
+    const {
+        name,
+        timeoutMs,
+        stepTimeoutMs,
+        slowRequestMs,
+        endpoints,
+        expected,
+        service,
+        team,
+        group,
+        maxSteps,
+    } = def;
+    const endpointKey = stableEndpointKey(endpoints);
+    const expectedKey = stableExpectedKey(expected);
+    const configTagsKey = stableTagsKey(def.tags);
 
     useEffect(() => {
         moduleRuntime.startJourney(def);
+        const opened = moduleRuntime.getOpenJourney(name);
+        return () => {
+            if (opened) {
+                moduleRuntime.excludeJourney(opened);
+            }
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- name is the lifecycle key
+    }, [name]);
+
+    useEffect(() => {
         if (tags) {
             setJourneyTags(name, tags);
         }
-        return () => excludeJourney(name);
-        // eslint-disable-next-line react-hooks/exhaustive-deps -- freeze-on-mount; name is the lifecycle key
-    }, [name]);
+    }, [name, tags]);
+
+    useEffect(() => {
+        moduleRuntime.updateOpenJourney(def);
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- field-level live updates; name-change is the other effect
+    }, [
+        name,
+        timeoutMs,
+        stepTimeoutMs,
+        slowRequestMs,
+        endpointKey,
+        expectedKey,
+        service,
+        team,
+        group,
+        maxSteps,
+        configTagsKey,
+    ]);
 
     return <JourneyNameContext.Provider value={name}>{children}</JourneyNameContext.Provider>;
 }

package/src/integrations/react/stable-config-keys.ts

@@ -0,0 +1,28 @@
+import type { EndpointPolicy } from '../../core/endpoint-policy';
+import type { TagValue } from '../../core/types';
+
+export function stableEndpointKey(endpoints?: readonly EndpointPolicy[]): string {
+    if (!endpoints?.length) {
+        return '';
+    }
+    return endpoints
+        .map(
+            endpoint =>
+                `${endpoint.match}\0${endpoint.slowRequestMs ?? ''}\0${endpoint.ignore === true}`
+        )
+        .join('\n');
+}
+
+export function stableExpectedKey(expected?: readonly string[]): string {
+    return expected?.join('\0') ?? '';
+}
+
+export function stableTagsKey(tags?: Record<string, TagValue>): string {
+    if (!tags) {
+        return '';
+    }
+    return Object.keys(tags)
+        .sort()
+        .map(key => `${key}\0${String(tags[key])}`)
+        .join('\n');
+}

package/src/integrations/react/use-journey-step.ts

@@ -0,0 +1,31 @@
+import { useCallback } from 'react';
+
+import {
+    journeyStep,
+    type JourneyHandle,
+    type JourneyStepOptions,
+    type StepHandle,
+} from '../../core';
+import { useOptionalJourneyName } from './context';
+
+/**
+ * Run a step on the active `<JourneyScope>` journey, an explicit name, or a handle.
+ * A handle auto-starts when the journey is not open; a bare name does not.
+ *
+ * @example
+ * const runStep = useJourneyStep();
+ * await runStep('load', async step => { await api.get('/x', { stamp: step.stamp() }); });
+ */
+export function useJourneyStep(journey?: string | JourneyHandle | null) {
+    const fromScope = useOptionalJourneyName();
+    const resolved = journey !== undefined ? journey : fromScope;
+
+    return useCallback(
+        <T>(
+            stepName: string,
+            fn: (step: StepHandle) => T | Promise<T>,
+            opts?: JourneyStepOptions
+        ): Promise<T> => journeyStep(resolved, stepName, fn, opts),
+        [resolved]
+    );
+}

package/src/integrations/request-key.ts

@@ -2,12 +2,17 @@
  * Timing metadata stamped onto a request config so the response handler can attribute
  * and measure the round trip. Intersect with your transport's config type.
  *
- * `journeyStep` is a JourneyStepTag (from `step.tag()` or ambient instrumentation)
- * or, historically, a raw StepRecord. Adapters unwrap via `resolveJourneyStep`.
+ * `stamp` is a JourneyStepStamp from `step.stamp()` or ambient instrumentation.
  */
 export interface JourneyTimedMeta {
     journeyStart?: number;
-    journeyStep?: unknown;
+    stamp?: unknown;
+    /** Skip attribution for this request (no ambient stamp, no scoring). */
+    ignore?: boolean;
+    /** Per-request override for aborted/cancelled HTTP policy. */
+    httpAbortedRequests?: 'continue' | 'bad' | 'exclude';
+    /** Per-request override for 4xx HTTP policy. */
+    httpClientErrorRequests?: 'continue' | 'bad' | 'exclude';
 }
 
 function pageOrigin(): string {
@@ -18,6 +23,15 @@ function pageOrigin(): string {
     }
 }
 
+function resolveHomeOrigin(instanceBaseURL: string | undefined, origin: string): string {
+    try {
+        const homeBase = instanceBaseURL ?? origin;
+        return new URL(homeBase || 'http://localhost').origin;
+    } catch {
+        return origin;
+    }
+}
+
 /**
  * Endpoint key for timeout / ignore lookup: PATH for same-origin (vs instance baseURL),
  * or "host/path" for cross-domain.
@@ -35,12 +49,6 @@ export function requestKey(
     } catch {
         return url ?? '';
     }
-    let homeOrigin: string;
-    try {
-        const homeBase = instanceBaseURL ?? origin;
-        homeOrigin = new URL(homeBase || 'http://localhost').origin;
-    } catch {
-        homeOrigin = origin;
-    }
+    const homeOrigin = resolveHomeOrigin(instanceBaseURL, origin);
     return abs.origin === homeOrigin ? abs.pathname : abs.host + abs.pathname;
 }

package/src/integrations/soft-skip.ts

@@ -0,0 +1,35 @@
+/**
+ * Soft-accept an instrumentation target. Never throws.
+ * - `null` / `undefined` → `console.warn` and return `undefined`
+ * - fails `isValid` → `console.error` and return `undefined`
+ */
+export function acceptInstrumentTarget<T>(
+    kind: string,
+    value: unknown,
+    isValid: (value: unknown) => value is T
+): T | undefined {
+    if (value == null) {
+        // eslint-disable-next-line no-console -- soft-skip missing host wiring
+        console.warn(`[journey] instrument${kind}: skipped — missing`);
+        return undefined;
+    }
+    if (!isValid(value)) {
+        // eslint-disable-next-line no-console -- soft-skip invalid host wiring
+        console.error(
+            `[journey] instrument${kind}: skipped — invalid shape (${describeTarget(value)})`
+        );
+        return undefined;
+    }
+    return value;
+}
+
+function describeTarget(value: unknown): string {
+    const kind = typeof value;
+    if (value != null && (kind === 'object' || kind === 'function')) {
+        const name = (value as { constructor?: { name?: string } }).constructor?.name;
+        if (typeof name === 'string' && name !== '' && name !== 'Object') {
+            return `${kind} ${name}`;
+        }
+    }
+    return kind;
+}

package/src/sinks/console.ts

@@ -1,3 +1,4 @@
+import { isSanitizedJourneyEvent, sanitizeJourneyEvent } from '../core/sanitize';
 import { isJourneyDebugEnabled } from '../global';
 import type { JourneyEvent } from '../core/types';
 
@@ -14,7 +15,7 @@ export function sendToConsole(event: JourneyEvent): void {
         return;
     }
 
-    const j = event.journey;
+    const j = isSanitizedJourneyEvent(event) ? event.journey : sanitizeJourneyEvent(event).journey;
     // eslint-disable-next-line no-console -- intentional debug sink
     console.debug(`[journey] ${j.name} → ${j.outcome}`, j);
 }

package/src/sinks/datadog.ts

@@ -1,7 +1,10 @@
 import { datadogRum } from '@datadog/browser-rum';
 
+import { isSanitizedJourneyEvent, sanitizeJourneyEvent } from '../core/sanitize';
 import { getJourneyRumFallback, setJourneyRumFallback } from '../global';
-import type { JourneyEvent, JourneyStepEvent, TagValue } from '../core/types';
+import type { JourneyEvent, JourneyStepEvent } from '../core/types';
+
+export { normalizeTagValue } from '../core/sanitize';
 
 const JOURNEY_ACTION = 'user_journey';
 
@@ -41,25 +44,6 @@ function resolveRum(): typeof datadogRum {
     return (shared as typeof datadogRum | undefined) ?? datadogRum;
 }
 
-/** Match Datadog metric-tag value rules so RUM attributes / globals join derived SLO tags. */
-const MAX_TAG_VALUE_LEN = 200;
-export function normalizeTagValue(value: string): string {
-    return value
-        .toLowerCase()
-        .replace(/[^a-z0-9_\-:./]/g, '_')
-        .replace(/_+/g, '_')
-        .slice(0, MAX_TAG_VALUE_LEN)
-        .replace(/_+$/, '');
-}
-
-function normalizeTags(tags: Record<string, TagValue>): Record<string, TagValue> {
-    const out: Record<string, TagValue> = {};
-    for (const [key, value] of Object.entries(tags)) {
-        out[key] = typeof value === 'string' ? normalizeTagValue(value) : value;
-    }
-    return out;
-}
-
 function toDatadogStep(step: JourneyStepEvent) {
     /* eslint-disable @typescript-eslint/naming-convention -- Datadog RUM wire format (snake_case) */
     return {
@@ -69,27 +53,37 @@ function toDatadogStep(step: JourneyStepEvent) {
         outcome: step.outcome,
         ...(step.reason ? { reason: step.reason } : {}),
         ...(step.httpStatus !== undefined ? { http_status: step.httpStatus } : {}),
-        ...(step.attributes ? { attributes: step.attributes } : {}),
+        ...(step.attributes && Object.keys(step.attributes).length
+            ? { attributes: step.attributes }
+            : {}),
     };
     /* eslint-enable @typescript-eslint/naming-convention */
 }
 
 /** Ship one terminal journey as a RUM custom action (`user_journey`). */
 export function sendToDatadog(payload: JourneyEvent): void {
-    const j = payload.journey;
+    const rum = resolveRum();
+    // Skip bad/missing host stubs — uninit RUM still buffers addAction safely.
+    if (typeof rum.addAction !== 'function') {
+        return;
+    }
+
+    const j = isSanitizedJourneyEvent(payload)
+        ? payload.journey
+        : sanitizeJourneyEvent(payload).journey;
     /* eslint-disable @typescript-eslint/naming-convention -- Datadog RUM wire format (snake_case) */
-    resolveRum().addAction(JOURNEY_ACTION, {
+    rum.addAction(JOURNEY_ACTION, {
         journey: {
-            name: normalizeTagValue(j.name),
-            team: normalizeTagValue(j.team),
-            group: normalizeTagValue(j.group),
-            service: normalizeTagValue(j.service),
+            name: j.name,
+            team: j.team,
+            group: j.group,
+            service: j.service,
             outcome: j.outcome,
-            ...(j.reason ? { reason: normalizeTagValue(j.reason) } : {}),
+            ...(j.reason ? { reason: j.reason } : {}),
             duration_ms: j.durationMs,
             steps: j.steps.map(toDatadogStep),
             ...(j.expected ? { expected: j.expected } : {}),
-            ...(j.tags ? { tags: normalizeTags(j.tags) } : {}),
+            ...(j.tags ? { tags: j.tags } : {}),
         },
     });
     /* eslint-enable @typescript-eslint/naming-convention */