@servicetitan/journey 2.0.0 → 2.1.0

package/src/__tests__/{axios.test.ts → integrations/axios.test.ts}

@@ -1,7 +1,8 @@
 /** @jest-environment jsdom */
-import { useJourneyTestRuntime } from '../__mocks__/test-runtime';
-import { completeJourney, JourneyStepTag, journeyStep, startJourney } from '../core';
-import { instrumentAxios, type AxiosLikeInstance } from '../integrations/axios';
+import { useJourneyTestRuntime } from '../../__test-utils__/test-runtime';
+import { completeJourney, JourneyStepTag, journeyStep } from '../../core';
+import { moduleRuntime } from '../../core/runtime';
+import { instrumentAxios, type AxiosLikeInstance } from '../../integrations/axios';
 
 const emitMock = jest.fn();
 
@@ -77,7 +78,7 @@ describe('[journey] instrumentAxios', () => {
         const axios = createAxiosMock();
         instrumentAxios(axios);
 
-        startJourney(def);
+        moduleRuntime.startJourney(def);
         await journeyStep(def.name, 'book-job', () => {
             const config = axios.requestHandlers[0]({ url: '/CallScreen/BookJob' });
             expect(config.journeyStep).toBeInstanceOf(JourneyStepTag);
@@ -93,11 +94,41 @@ describe('[journey] instrumentAxios', () => {
         expect(emitMock.mock.calls[0][0].journey.outcome).toBe('good');
     });
 
+    test('stamped journeyStep is JSON-safe (AxiosError.toJSON includes config)', async () => {
+        const axios = createAxiosMock();
+        instrumentAxios(axios);
+
+        moduleRuntime.startJourney(def);
+        await journeyStep(def.name, 'book-job', step => {
+            // Ambient stamp — AxiosError.toJSON() embeds config by reference.
+            const ambient = axios.requestHandlers[0]({ url: '/CallScreen/BookJob' });
+            expect(ambient.journeyStep).toBeInstanceOf(JourneyStepTag);
+            const ambientSerialized = JSON.stringify({
+                message: 'Request failed',
+                name: 'AxiosError',
+                config: ambient,
+                status: 500,
+            });
+            expect(JSON.parse(ambientSerialized).config.journeyStep).toBe('[JourneyStepTag]');
+
+            // Explicit step.tag() spread into config — same circular risk.
+            const tagged = step.tag() as { journeyStep: unknown };
+            const explicit = axios.requestHandlers[0]({
+                url: '/CallScreen/BookJob',
+                journeyStep: tagged.journeyStep,
+            });
+            expect(explicit.journeyStep).toBe(tagged.journeyStep);
+            expect(explicit.journeyStep).toBeInstanceOf(JourneyStepTag);
+            expect(JSON.parse(JSON.stringify(explicit)).journeyStep).toBe('[JourneyStepTag]');
+        });
+        completeJourney(def.name);
+    });
+
     test('marks journey bad on 5xx via the rejection interceptor', async () => {
         const axios = createAxiosMock();
         instrumentAxios(axios);
 
-        startJourney(def);
+        moduleRuntime.startJourney(def);
         await expect(
             journeyStep(def.name, 'book-job', async () => {
                 const config = axios.requestHandlers[0]({ url: '/CallScreen/BookJob' });
@@ -118,7 +149,7 @@ describe('[journey] instrumentAxios', () => {
         const axios = createAxiosMock();
         instrumentAxios(axios);
 
-        startJourney(def);
+        moduleRuntime.startJourney(def);
         await journeyStep(def.name, 'book-job', async step => {
             const tagged = step.tag() as { journeyStep: unknown };
             const config = axios.requestHandlers[0]({
@@ -144,8 +175,8 @@ describe('[journey] instrumentAxios', () => {
         const axios = createAxiosMock();
         instrumentAxios(axios);
 
-        startJourney(def);
-        startJourney(other);
+        moduleRuntime.startJourney(def);
+        moduleRuntime.startJourney(other);
 
         let releaseA!: () => void;
         const gateA = new Promise<void>(r => {
@@ -184,8 +215,8 @@ describe('[journey] instrumentAxios', () => {
         const axios = createAxiosMock();
         instrumentAxios(axios);
 
-        startJourney(def);
-        startJourney(other);
+        moduleRuntime.startJourney(def);
+        moduleRuntime.startJourney(other);
 
         let releaseA!: () => void;
         const gateA = new Promise<void>(r => {
@@ -248,7 +279,7 @@ describe('[journey] instrumentAxios', () => {
         const axios = createAxiosMock();
         instrumentAxios(axios);
 
-        startJourney(def);
+        moduleRuntime.startJourney(def);
         await journeyStep(def.name, 'book-job', step => {
             const tagged = step.tag() as { journeyStep: unknown };
             const config = {
@@ -268,7 +299,7 @@ describe('[journey] instrumentAxios', () => {
         const axios = createAxiosMock();
         instrumentAxios(axios);
 
-        startJourney({ ...def, requestTimeoutMs: 50 });
+        moduleRuntime.startJourney({ ...def, requestTimeoutMs: 50 });
         await journeyStep(def.name, 'book-job', () => {
             const config = axios.requestHandlers[0]({ url: '/CallScreen/BookJob' });
             (globalThis.performance.now as jest.Mock).mockReturnValue(1_200);
@@ -284,7 +315,7 @@ describe('[journey] instrumentAxios', () => {
         const axios = createAxiosMock();
         instrumentAxios(axios);
 
-        startJourney(def);
+        moduleRuntime.startJourney(def);
         await journeyStep(def.name, 'book-job', async () => {
             const config = axios.requestHandlers[0]({ url: '/CallScreen/BookJob' });
             (globalThis.performance.now as jest.Mock).mockReturnValue(1_020);
@@ -305,7 +336,7 @@ describe('[journey] instrumentAxios', () => {
         const axios = createAxiosMock();
         instrumentAxios(axios);
 
-        startJourney(def);
+        moduleRuntime.startJourney(def);
         await expect(
             journeyStep(def.name, 'book-job', async () => {
                 const config = axios.requestHandlers[0]({ url: '/CallScreen/BookJob' });
@@ -340,7 +371,7 @@ describe('[journey] instrumentAxios', () => {
         const axios = createAxiosMock();
         instrumentAxios(axios);
 
-        startJourney({
+        moduleRuntime.startJourney({
             ...def,
             endpoints: [{ match: 'api.example.com/invoices', ignore: true }],
         });

package/src/__tests__/{context.test.tsx → integrations/context.test.tsx}

@@ -5,7 +5,7 @@ import {
     JourneyNameContext,
     useJourneyName,
     useOptionalJourneyName,
-} from '../integrations/react/context';
+} from '../../integrations/react/context';
 
 function OptionalProbe() {
     const name = useOptionalJourneyName();

package/src/__tests__/{expose-app-journey.test.ts → integrations/expose-app-journey.test.ts}

@@ -1,6 +1,6 @@
 /** @jest-environment jsdom */
-import { useJourneyTestRuntime } from '../__mocks__/test-runtime';
-import { exposeAppJourney, type WindowWithAppJourney } from '../integrations/jquery';
+import { useJourneyTestRuntime } from '../../__test-utils__/test-runtime';
+import { exposeAppJourney, type WindowWithAppJourney } from '../../integrations/jquery';
 
 const emitMock = jest.fn();
 

package/src/__tests__/{fetch.test.ts → integrations/fetch.test.ts}

@@ -1,14 +1,14 @@
 /** @jest-environment jsdom */
-import { activeJourneyStep, reportBackendRequest, type JourneyStepRef } from '../core';
-import { instrumentFetch, type InstrumentFetchOptions } from '../integrations/fetch';
-import { requestKey } from '../integrations/request-key';
+import { activeJourneyStep, reportBackendRequest, type JourneyStepRef } from '../../core';
+import { instrumentFetch, type InstrumentFetchOptions } from '../../integrations/fetch';
+import { requestKey } from '../../integrations/request-key';
 
-jest.mock('../core', () => ({
-    ...jest.requireActual('../core'),
+jest.mock('../../core', () => ({
+    ...jest.requireActual('../../core'),
     activeJourneyStep: jest.fn(),
     reportBackendRequest: jest.fn(),
 }));
-jest.mock('../integrations/request-key');
+jest.mock('../../integrations/request-key');
 
 describe('[journey] instrumentFetch', () => {
     const KEY = 'resolved-endpoint-key';

package/src/__tests__/{jquery.test.ts → integrations/jquery.test.ts}

@@ -1,7 +1,8 @@
 /** @jest-environment jsdom */
-import { useJourneyTestRuntime } from '../__mocks__/test-runtime';
-import { completeJourney, journeyStep, startJourney } from '../core';
-import { instrumentJquery } from '../integrations/jquery/instrument';
+import { useJourneyTestRuntime } from '../../__test-utils__/test-runtime';
+import { completeJourney, JourneyStepTag, journeyStep } from '../../core';
+import { moduleRuntime } from '../../core/runtime';
+import { instrumentJquery } from '../../integrations/jquery/instrument';
 
 const emitMock = jest.fn();
 
@@ -63,7 +64,7 @@ describe('[journey] instrumentJquery', () => {
         const $ = createJqueryMock();
         instrumentJquery($);
 
-        startJourney({
+        moduleRuntime.startJourney({
             name: 'jq-idle',
             team: 'test',
             group: 'test',
@@ -79,11 +80,47 @@ describe('[journey] instrumentJquery', () => {
         expect(emitMock.mock.calls[0][0].journey.outcome).toBe('good');
     });
 
+    test('stamped journeyStep is JSON-safe on jqXHR and ajax settings', async () => {
+        const $ = createJqueryMock();
+        instrumentJquery($);
+
+        moduleRuntime.startJourney({
+            name: 'jq-json-safe',
+            team: 'test',
+            group: 'test',
+            service: 'test',
+            timeoutMs: 0,
+            requestTimeoutMs: 5_000,
+        });
+
+        await journeyStep('jq-json-safe', 'book-job', step => {
+            // Ambient stamp lands on jqXHR — common to serialize for logging.
+            const ambientXhr: {
+                status: number;
+                journeyStep?: unknown;
+                journeyStart?: number;
+            } = { status: 200 };
+            const ambientSettings = { url: '/CallScreen/BookJob' };
+            for (const prefilter of $.__prefilters) {
+                prefilter(ambientSettings, ambientSettings, ambientXhr);
+            }
+            expect(ambientXhr.journeyStep).toBeInstanceOf(JourneyStepTag);
+            expect(JSON.parse(JSON.stringify(ambientXhr)).journeyStep).toBe('[JourneyStepTag]');
+
+            // Explicit step.tag() spread into ajax settings — same circular risk.
+            const tagged = step.tag() as { journeyStep: unknown };
+            const settings = { url: '/CallScreen/BookJob', ...tagged };
+            expect(settings.journeyStep).toBeInstanceOf(JourneyStepTag);
+            expect(JSON.parse(JSON.stringify(settings)).journeyStep).toBe('[JourneyStepTag]');
+        });
+        completeJourney('jq-json-safe');
+    });
+
     test('marks journey bad on 5xx inside a journey step', async () => {
         const $ = createJqueryMock();
         instrumentJquery($);
 
-        startJourney({
+        moduleRuntime.startJourney({
             name: 'jq-5xx',
             team: 'test',
             group: 'test',
@@ -106,7 +143,7 @@ describe('[journey] instrumentJquery', () => {
         const $ = createJqueryMock();
         instrumentJquery($);
 
-        startJourney({
+        moduleRuntime.startJourney({
             name: 'jq-slow',
             team: 'test',
             group: 'test',
@@ -129,7 +166,7 @@ describe('[journey] instrumentJquery', () => {
         const $ = createJqueryMock();
         instrumentJquery($);
 
-        startJourney({
+        moduleRuntime.startJourney({
             name: 'jq-network',
             team: 'test',
             group: 'test',
@@ -151,7 +188,7 @@ describe('[journey] instrumentJquery', () => {
         const $ = createJqueryMock();
         instrumentJquery($);
 
-        startJourney({
+        moduleRuntime.startJourney({
             name: 'jq-4xx',
             team: 'test',
             group: 'test',
@@ -173,7 +210,7 @@ describe('[journey] instrumentJquery', () => {
         const $ = createJqueryMock();
         instrumentJquery($);
 
-        startJourney({
+        moduleRuntime.startJourney({
             name: 'jq-explicit',
             team: 'test',
             group: 'test',
@@ -212,7 +249,7 @@ describe('[journey] instrumentJquery', () => {
         const $ = createJqueryMock();
         instrumentJquery($);
 
-        startJourney({
+        moduleRuntime.startJourney({
             name: 'jq-no-start',
             team: 'test',
             group: 'test',
@@ -269,7 +306,7 @@ describe('[journey] instrumentJquery', () => {
             return target;
         }
 
-        startJourney({
+        moduleRuntime.startJourney({
             name: 'jq-settings-tag',
             team: 'test',
             group: 'test',
@@ -305,7 +342,7 @@ describe('[journey] instrumentJquery', () => {
         const $ = createJqueryMock();
         instrumentJquery($);
 
-        startJourney({
+        moduleRuntime.startJourney({
             name: 'jq-cross',
             team: 'test',
             group: 'test',

package/src/__tests__/{request-key.test.ts → integrations/request-key.test.ts}

@@ -1,5 +1,5 @@
 /** @jest-environment jsdom */
-import { requestKey } from '../integrations/request-key';
+import { requestKey } from '../../integrations/request-key';
 
 describe('[journey] requestKey', () => {
     // Do not redefine window.location — jsdom's property is non-configurable.

package/src/__tests__/{scope.test.tsx → integrations/scope.test.tsx}

@@ -2,10 +2,10 @@
 import { render, screen } from '@testing-library/react';
 import { useContext } from 'react';
 
-import { useJourneyTestRuntime } from '../__mocks__/test-runtime';
-import { completeJourney, failJourney } from '../core';
-import { JourneyNameContext } from '../integrations/react/context';
-import { JourneyScope } from '../integrations/react/scope';
+import { useJourneyTestRuntime } from '../../__test-utils__/test-runtime';
+import { completeJourney, failJourney } from '../../core';
+import { JourneyNameContext } from '../../integrations/react/context';
+import { JourneyScope } from '../../integrations/react/scope';
 
 const emitMock = jest.fn();
 

package/src/__tests__/sinks/console.test.ts

@@ -0,0 +1,98 @@
+/** @jest-environment jsdom */
+import type { JourneyEvent } from '../../core/types';
+import { JOURNEY_DEBUG_STORAGE_KEY, isJourneyDebugEnabled } from '../../global';
+import { sendToConsole } from '../../sinks/console';
+
+function sampleEvent(overrides: Partial<JourneyEvent['journey']> = {}): JourneyEvent {
+    return {
+        journey: {
+            name: 'Book Job',
+            team: 'jbce',
+            group: 'call-booking',
+            service: 'call-screen',
+            outcome: 'good',
+            durationMs: 120,
+            steps: [],
+            ...overrides,
+        },
+    };
+}
+
+describe('[journey] sendToConsole / isJourneyDebugEnabled', () => {
+    let debugSpy: jest.SpyInstance;
+
+    beforeEach(() => {
+        localStorage.clear();
+        debugSpy = jest.spyOn(console, 'debug').mockImplementation(() => undefined);
+    });
+
+    afterEach(() => {
+        debugSpy.mockRestore();
+        localStorage.clear();
+    });
+
+    describe('when st:journey:debug is not set', () => {
+        test('isJourneyDebugEnabled is false', () => {
+            expect(isJourneyDebugEnabled()).toBe(false);
+        });
+
+        test('does not log', () => {
+            sendToConsole(sampleEvent());
+
+            expect(debugSpy).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('when st:journey:debug is a non-true value', () => {
+        beforeEach(() => {
+            localStorage.setItem(JOURNEY_DEBUG_STORAGE_KEY, '1');
+        });
+
+        test('isJourneyDebugEnabled is false', () => {
+            expect(isJourneyDebugEnabled()).toBe(false);
+        });
+
+        test('does not log', () => {
+            sendToConsole(sampleEvent());
+
+            expect(debugSpy).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('when st:journey:debug is true', () => {
+        beforeEach(() => {
+            localStorage.setItem(JOURNEY_DEBUG_STORAGE_KEY, 'true');
+        });
+
+        test('isJourneyDebugEnabled is true', () => {
+            expect(isJourneyDebugEnabled()).toBe(true);
+        });
+
+        test('logs the journey name, outcome, and payload', () => {
+            const event = sampleEvent({ outcome: 'bad', reason: 'request-error' });
+
+            sendToConsole(event);
+
+            expect(debugSpy).toHaveBeenCalledTimes(1);
+            expect(debugSpy).toHaveBeenCalledWith('[journey] Book Job → bad', event.journey);
+        });
+    });
+
+    describe('when localStorage throws', () => {
+        beforeEach(() => {
+            jest.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+                throw new Error('denied');
+            });
+        });
+
+        afterEach(() => {
+            jest.restoreAllMocks();
+        });
+
+        test('treats debug as disabled and does not throw', () => {
+            expect(isJourneyDebugEnabled()).toBe(false);
+            expect(() => sendToConsole(sampleEvent())).not.toThrow();
+            expect(debugSpy).not.toHaveBeenCalled();
+        });
+    });
+});

package/src/__tests__/{datadog.test.ts → sinks/datadog.test.ts}

@@ -1,6 +1,7 @@
 /** @jest-environment jsdom */
 const addAction = jest.fn();
 const importedAddAction = jest.fn();
+const ddRumAddAction = jest.fn();
 
 jest.mock('@datadog/browser-rum', () => ({
     datadogRum: {
@@ -8,10 +9,19 @@ jest.mock('@datadog/browser-rum', () => ({
     },
 }));
 
-import type { JourneyEvent } from '../core/types';
-import { sendToDatadog, setJourneyRum } from '../sinks/datadog';
+import type { JourneyEvent } from '../../core/types';
+import { ST_JOURNEY_GLOBAL_KEY, type StJourneyGlobal } from '../../global';
+import { normalizeTagValue, sendToDatadog, setJourneyRum } from '../../sinks/datadog';
 
-const RUM_GLOBAL_KEY = '__stJourneyRum';
+const DD_RUM_KEY = 'DD_RUM';
+
+function clearJourneyRumFallback(): void {
+    const st = (globalThis as Record<string, unknown>)[ST_JOURNEY_GLOBAL_KEY] as
+        StJourneyGlobal | undefined;
+    if (st) {
+        delete st.rum;
+    }
+}
 
 function sampleEvent(overrides: Partial<JourneyEvent['journey']> = {}): JourneyEvent {
     return {
@@ -29,10 +39,21 @@ function sampleEvent(overrides: Partial<JourneyEvent['journey']> = {}): JourneyE
 }
 
 describe('[journey] setJourneyRum / sendToDatadog', () => {
+    let warnSpy: jest.SpyInstance;
+
     beforeEach(() => {
         addAction.mockClear();
         importedAddAction.mockClear();
-        delete (globalThis as Record<string, unknown>)[RUM_GLOBAL_KEY];
+        ddRumAddAction.mockClear();
+        clearJourneyRumFallback();
+        delete (globalThis as Record<string, unknown>)[DD_RUM_KEY];
+        warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined);
+    });
+
+    afterEach(() => {
+        warnSpy.mockRestore();
+        clearJourneyRumFallback();
+        delete (globalThis as Record<string, unknown>)[DD_RUM_KEY];
     });
 
     describe('without a shared RUM instance', () => {
@@ -47,7 +68,37 @@ describe('[journey] setJourneyRum / sendToDatadog', () => {
         });
     });
 
-    describe('with setJourneyRum', () => {
+    describe('with globalThis.DD_RUM', () => {
+        beforeEach(() => {
+            (globalThis as Record<string, unknown>)[DD_RUM_KEY] = { addAction: ddRumAddAction };
+        });
+
+        test('prefers DD_RUM over setJourneyRum and the import', () => {
+            setJourneyRum({ addAction });
+            warnSpy.mockClear();
+            sendToDatadog(sampleEvent());
+
+            expect(ddRumAddAction).toHaveBeenCalledTimes(1);
+            expect(addAction).not.toHaveBeenCalled();
+            expect(importedAddAction).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('when setJourneyRum is called while globalThis.DD_RUM is set', () => {
+        test('logs a redundancy warning', () => {
+            (globalThis as Record<string, unknown>)[DD_RUM_KEY] = { addAction: ddRumAddAction };
+
+            setJourneyRum({ addAction });
+
+            expect(warnSpy).toHaveBeenCalledWith(
+                expect.stringContaining(
+                    'setJourneyRum() is unnecessary when globalThis.DD_RUM is set'
+                )
+            );
+        });
+    });
+
+    describe('with setJourneyRum (no DD_RUM)', () => {
         beforeEach(() => {
             setJourneyRum({ addAction });
         });
@@ -60,6 +111,7 @@ describe('[journey] setJourneyRum / sendToDatadog', () => {
 
             expect(addAction).toHaveBeenCalledTimes(1);
             expect(importedAddAction).not.toHaveBeenCalled();
+            expect(warnSpy).not.toHaveBeenCalled();
         });
 
         test('normalizes identity fields', () => {
@@ -127,6 +179,11 @@ describe('[journey] setJourneyRum / sendToDatadog', () => {
         expect(addAction.mock.calls[0][1].journey.reason).toBe('step_error');
     });
 
+    test('normalizeTagValue matches Datadog metric-tag rules', () => {
+        expect(normalizeTagValue('Tenant A!')).toBe('tenant_a');
+        expect(normalizeTagValue('Foo@@@Bar___')).toBe('foo_bar');
+    });
+
     test('maps camelCase fields to Datadog snake_case wire keys', () => {
         setJourneyRum({ addAction });
         sendToDatadog(

package/src/__tests__/{sinks.test.ts → sinks/sinks.test.ts}

@@ -1,14 +1,15 @@
 /** @jest-environment jsdom */
-jest.mock('../sinks/datadog', () => ({
+jest.mock('../../sinks/datadog', () => ({
     sendToDatadog: jest.fn(),
 }));
 
-import { resetJourney } from '../core';
-import { addJourneySink, emitJourneyEvent, setJourneySinks } from '../core/registry';
-import type { JourneyEvent } from '../core/types';
-import { sendToDatadog } from '../sinks/datadog';
+import { resetJourney } from '../../core';
+import { moduleRuntime } from '../../core/runtime';
+import type { JourneyEvent } from '../../core/types';
+import { sendToConsole } from '../../sinks/console';
+import { sendToDatadog } from '../../sinks/datadog';
 
-describe('[journey] emitJourneyEvent', () => {
+describe('[journey] moduleRuntime sinks', () => {
     let payload: JourneyEvent;
 
     beforeEach(() => {
@@ -28,10 +29,10 @@ describe('[journey] emitJourneyEvent', () => {
     });
 
     afterEach(() => {
-        resetJourney({ sinks: [sendToDatadog] });
+        resetJourney({ sinks: [sendToDatadog, sendToConsole] });
     });
 
-    const subject = () => emitJourneyEvent(payload);
+    const subject = () => moduleRuntime.emit(payload);
 
     test('forwards the payload to each configured sink', () => {
         subject();
@@ -44,7 +45,7 @@ describe('[journey] emitJourneyEvent', () => {
 
         beforeEach(() => {
             extra = jest.fn();
-            addJourneySink(extra);
+            moduleRuntime.addSink(extra);
         });
 
         test('invokes every configured sink', () => {
@@ -55,7 +56,7 @@ describe('[journey] emitJourneyEvent', () => {
         });
 
         test('continues to later sinks when one throws', () => {
-            setJourneySinks([
+            moduleRuntime.setSinks([
                 () => {
                     throw new Error('boom');
                 },
@@ -74,7 +75,7 @@ describe('[journey] emitJourneyEvent', () => {
 
         beforeEach(() => {
             only = jest.fn();
-            setJourneySinks([only]);
+            moduleRuntime.setSinks([only]);
         });
 
         test('does not call the previous sinks', () => {
@@ -87,7 +88,7 @@ describe('[journey] emitJourneyEvent', () => {
 
     describe('with an empty sink list', () => {
         beforeEach(() => {
-            setJourneySinks([]);
+            moduleRuntime.setSinks([]);
         });
 
         test('emits nowhere', () => {