@servicetitan/journey 2.1.0 → 3.0.0

package/src/__tests__/config.test.ts

@@ -16,11 +16,12 @@ jest.mock('../integrations/jquery', () => ({
     exposeAppJourney: jest.fn(),
 }));
 
-import { configureJourney, getRequestTimeouts } from '../config';
+import { configureJourney, getSlowRequests } from '../config';
 import { resetJourney } from '../core';
 import { moduleRuntime } from '../core/runtime';
 import type { JourneyEvent } from '../core/types';
 import { longestEndpointMatch, sortEndpointsByLongestMatch } from '../core/endpoint-policy';
+import { resetSharedPolicies, setJourneyDefaultEnabled } from '../global';
 import { instrumentAxios } from '../integrations/axios';
 import { instrumentFetch } from '../integrations/fetch';
 import {
@@ -36,11 +37,18 @@ const instrumentFetchMock = jest.mocked(instrumentFetch);
 const instrumentJqueryMock = jest.mocked(instrumentJquery);
 const exposeAppJourneyMock = jest.mocked(exposeAppJourney);
 
-describe('[journey] configureJourney / getRequestTimeouts', () => {
+describe('[journey] configureJourney / getSlowRequests', () => {
+    beforeEach(() => {
+        setJourneyDefaultEnabled(true);
+    });
+
     afterEach(() => {
+        setJourneyDefaultEnabled(false);
+        localStorage.clear();
+        resetSharedPolicies();
         resetJourney({
             sinks: [sendToDatadog, sendToConsole],
-            requestTimeouts: { defaultMs: 4_000, endpoints: [] },
+            slowRequests: { defaultMs: 4_000, endpoints: [] },
         });
         instrumentAxiosMock.mockClear();
         instrumentFetchMock.mockClear();
@@ -49,27 +57,36 @@ describe('[journey] configureJourney / getRequestTimeouts', () => {
     });
 
     test('defaults to 4s with empty endpoints', () => {
-        expect(getRequestTimeouts()).toEqual({ defaultMs: 4_000, endpoints: [] });
+        expect(getSlowRequests()).toEqual({ defaultMs: 4_000, endpoints: [] });
     });
 
     test('overrides the app-wide request timeout tier', () => {
         configureJourney({
-            requestTimeouts: {
+            slowRequests: {
                 defaultMs: 2_000,
-                endpoints: [{ match: '/slow', timeoutMs: 8_000 }],
+                endpoints: [{ match: '/slow', slowRequestMs: 8_000 }],
             },
         });
 
-        expect(getRequestTimeouts()).toEqual({
+        expect(getSlowRequests()).toEqual({
             defaultMs: 2_000,
-            endpoints: [{ match: '/slow', timeoutMs: 8_000 }],
+            endpoints: [{ match: '/slow', slowRequestMs: 8_000 }],
         });
     });
 
-    test('ignores configureJourney when requestTimeouts is omitted', () => {
-        configureJourney({ requestTimeouts: { defaultMs: 1_000, endpoints: [] } });
+    test('ignores configureJourney when slowRequests is omitted', () => {
+        configureJourney({ slowRequests: { defaultMs: 1_000, endpoints: [] } });
         configureJourney({});
-        expect(getRequestTimeouts().defaultMs).toBe(1_000);
+        expect(getSlowRequests().defaultMs).toBe(1_000);
+    });
+
+    test('clamps maxSteps to 1..200', () => {
+        configureJourney({ maxSteps: Infinity });
+        expect(moduleRuntime.getMaxSteps()).toBe(50);
+        configureJourney({ maxSteps: 0 });
+        expect(moduleRuntime.getMaxSteps()).toBe(50);
+        configureJourney({ maxSteps: 500 });
+        expect(moduleRuntime.getMaxSteps()).toBe(200);
     });
 
     describe('with sinks', () => {
@@ -102,11 +119,25 @@ describe('[journey] configureJourney / getRequestTimeouts', () => {
 
         test('leaves sinks unchanged when sinks is omitted', () => {
             configureJourney({ sinks: [custom] });
-            configureJourney({ requestTimeouts: { defaultMs: 2_000, endpoints: [] } });
+            configureJourney({ slowRequests: { defaultMs: 2_000, endpoints: [] } });
+            moduleRuntime.emit(payload);
+
+            expect(custom).toHaveBeenCalledWith(payload);
+            expect(sendToDatadog).not.toHaveBeenCalled();
+        });
+
+        test('ignores a later sinks replacement on this runtime', () => {
+            const warn = jest.spyOn(console, 'warn').mockImplementation(() => undefined);
+            configureJourney({ sinks: [custom] });
+            configureJourney({ sinks: [sendToDatadog] });
             moduleRuntime.emit(payload);
 
             expect(custom).toHaveBeenCalledWith(payload);
             expect(sendToDatadog).not.toHaveBeenCalled();
+            expect(warn).toHaveBeenCalledWith(
+                expect.stringContaining('sinks already set on this runtime')
+            );
+            warn.mockRestore();
         });
 
         test('disables emission when sinks is empty', () => {
@@ -125,6 +156,15 @@ describe('[journey] configureJourney / getRequestTimeouts', () => {
         };
         const jquery = { ajaxPrefilter: jest.fn(), bind: jest.fn() } as never;
         const fetchTarget = { fetch: jest.fn() };
+        let warnSpy: jest.SpyInstance;
+
+        beforeEach(() => {
+            warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+        });
+
+        afterEach(() => {
+            warnSpy.mockRestore();
+        });
 
         test('instruments axios when provided', () => {
             configureJourney({ axios: axios as never });
@@ -155,6 +195,38 @@ describe('[journey] configureJourney / getRequestTimeouts', () => {
             expect(instrumentJqueryMock).toHaveBeenCalledWith(jquery);
         });
 
+        test('instruments global $ when jquery is true', () => {
+            const $ = Object.assign(jest.fn(), { ajaxPrefilter: jest.fn() });
+            (globalThis as { $?: unknown }).$ = $;
+
+            try {
+                configureJourney({ jquery: true });
+
+                expect(instrumentJqueryMock).toHaveBeenCalledWith($);
+            } finally {
+                delete (globalThis as { $?: unknown }).$;
+            }
+        });
+
+        test('falls back to global jQuery when jquery is true and $ is absent', () => {
+            const jQuery = Object.assign(jest.fn(), { ajaxPrefilter: jest.fn() });
+            (globalThis as { jQuery?: unknown }).jQuery = jQuery;
+
+            try {
+                configureJourney({ jquery: true });
+
+                expect(instrumentJqueryMock).toHaveBeenCalledWith(jQuery);
+            } finally {
+                delete (globalThis as { jQuery?: unknown }).jQuery;
+            }
+        });
+
+        test('skips jquery wiring when jquery is false', () => {
+            configureJourney({ jquery: false });
+
+            expect(instrumentJqueryMock).not.toHaveBeenCalled();
+        });
+
         test('exposes App.Journey when exposeAppJourney is true', () => {
             configureJourney({ exposeAppJourney: true });
 
@@ -169,21 +241,64 @@ describe('[journey] configureJourney / getRequestTimeouts', () => {
         });
 
         test('skips transport helpers when omitted', () => {
-            configureJourney({ requestTimeouts: { defaultMs: 1_000, endpoints: [] } });
+            configureJourney({ slowRequests: { defaultMs: 1_000, endpoints: [] } });
 
             expect(instrumentAxiosMock).not.toHaveBeenCalled();
             expect(instrumentFetchMock).not.toHaveBeenCalled();
             expect(instrumentJqueryMock).not.toHaveBeenCalled();
             expect(exposeAppJourneyMock).not.toHaveBeenCalled();
         });
+
+        test('never throws on missing config', () => {
+            const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+            expect(() => configureJourney(null as never)).not.toThrow();
+            expect(() => configureJourney(undefined as never)).not.toThrow();
+            expect(warn).toHaveBeenCalledWith(
+                expect.stringContaining('[journey] configureJourney: skipped — missing')
+            );
+        });
+
+        test('skips when journey is disabled', () => {
+            setJourneyDefaultEnabled(false);
+            const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+            configureJourney({ axios: axios as never, fetch: true });
+
+            expect(warn).toHaveBeenCalledWith(
+                expect.stringContaining('[journey] configureJourney: skipped — disabled')
+            );
+            expect(instrumentAxiosMock).not.toHaveBeenCalled();
+            expect(instrumentFetchMock).not.toHaveBeenCalled();
+        });
+
+        test('never throws when a transport step fails', () => {
+            const error = jest.spyOn(console, 'error').mockImplementation(() => {});
+            instrumentAxiosMock.mockImplementationOnce(() => {
+                throw new Error('axios boom');
+            });
+
+            expect(() =>
+                configureJourney({
+                    axios: axios as never,
+                    jquery,
+                    exposeAppJourney: true,
+                })
+            ).not.toThrow();
+
+            expect(error).toHaveBeenCalledWith(
+                '[journey] configureJourney failed',
+                expect.any(Error)
+            );
+        });
     });
 });
 
 describe('longestEndpointMatch', () => {
     // Lookup expects longest-match-first (configureJourney / startJourney sort for you).
     const endpoints = [
-        { match: '/api/invoices', timeoutMs: 2_000 },
-        { match: '/api', timeoutMs: 1_000 },
+        { match: '/api/invoices', slowRequestMs: 2_000 },
+        { match: '/api', slowRequestMs: 1_000 },
         { match: '/other', ignore: true },
     ];
 
@@ -193,8 +308,8 @@ describe('longestEndpointMatch', () => {
     });
 
     test('picks the longest matching prefix (first hit when sorted)', () => {
-        expect(longestEndpointMatch(endpoints, '/api/invoices/42')?.timeoutMs).toBe(2_000);
-        expect(longestEndpointMatch(endpoints, '/api/jobs')?.timeoutMs).toBe(1_000);
+        expect(longestEndpointMatch(endpoints, '/api/invoices/42')?.slowRequestMs).toBe(2_000);
+        expect(longestEndpointMatch(endpoints, '/api/jobs')?.slowRequestMs).toBe(1_000);
     });
 
     test('returns undefined when nothing matches', () => {
@@ -202,40 +317,44 @@ describe('longestEndpointMatch', () => {
     });
 
     test('requires a path boundary after the prefix', () => {
-        const user = [{ match: '/api/user', timeoutMs: 1_000 }];
-        expect(longestEndpointMatch(user, '/api/user')?.timeoutMs).toBe(1_000);
-        expect(longestEndpointMatch(user, '/api/user/42')?.timeoutMs).toBe(1_000);
+        const user = [{ match: '/api/user', slowRequestMs: 1_000 }];
+        expect(longestEndpointMatch(user, '/api/user')?.slowRequestMs).toBe(1_000);
+        expect(longestEndpointMatch(user, '/api/user/42')?.slowRequestMs).toBe(1_000);
         expect(longestEndpointMatch(user, '/api/user-preferences')).toBeUndefined();
         expect(longestEndpointMatch(user, '/api/users')).toBeUndefined();
 
-        const trailed = [{ match: '/api/user/', timeoutMs: 2_000 }];
-        expect(longestEndpointMatch(trailed, '/api/user/42')?.timeoutMs).toBe(2_000);
+        const trailed = [{ match: '/api/user/', slowRequestMs: 2_000 }];
+        expect(longestEndpointMatch(trailed, '/api/user/42')?.slowRequestMs).toBe(2_000);
     });
 });
 
 describe('configureJourney endpoint ordering', () => {
+    beforeEach(() => {
+        setJourneyDefaultEnabled(true);
+    });
+
     afterEach(() => {
+        setJourneyDefaultEnabled(false);
+        localStorage.clear();
+        resetSharedPolicies();
         resetJourney({
             sinks: [sendToDatadog, sendToConsole],
-            requestTimeouts: { defaultMs: 4_000, endpoints: [] },
+            slowRequests: { defaultMs: 4_000, endpoints: [] },
         });
     });
 
     test('stores endpoints longest-match-first', () => {
         configureJourney({
-            requestTimeouts: {
+            slowRequests: {
                 defaultMs: 4_000,
                 endpoints: [
-                    { match: '/api', timeoutMs: 1_000 },
-                    { match: '/api/invoices', timeoutMs: 2_000 },
+                    { match: '/api', slowRequestMs: 1_000 },
+                    { match: '/api/invoices', slowRequestMs: 2_000 },
                 ],
             },
         });
 
-        expect(getRequestTimeouts().endpoints?.map(e => e.match)).toEqual([
-            '/api/invoices',
-            '/api',
-        ]);
+        expect(getSlowRequests().endpoints?.map(e => e.match)).toEqual(['/api/invoices', '/api']);
     });
 });
 
@@ -245,7 +364,7 @@ describe('[journey] sortEndpointsByLongestMatch', () => {
     });
 
     test('returns a copy for a single endpoint', () => {
-        const only = [{ match: '/api', timeoutMs: 1_000 }];
+        const only = [{ match: '/api', slowRequestMs: 1_000 }];
         const sorted = sortEndpointsByLongestMatch(only);
 
         expect(sorted).toEqual(only);

package/src/__tests__/core/ambient.test.ts

@@ -1,13 +1,18 @@
 /** @jest-environment jsdom */
 import { baseJourneyDef, useJourneyTestRuntime } from '../../__test-utils__/test-runtime';
-import { activeJourneyStep, completeJourney, journeyStep } from '../../core';
+import {
+    singleInFlightJourneyStep,
+    completeJourney,
+    journeyStep,
+    JourneyStepStamp,
+} from '../../core';
 import { moduleRuntime } from '../../core/runtime';
 
 const emitMock = jest.fn();
 const baseDef = { ...baseJourneyDef, name: 'ambient-a' };
 const otherDef = { ...baseJourneyDef, name: 'ambient-b' };
 
-describe('[journey] activeJourneyStep', () => {
+describe('[journey] singleInFlightJourneyStep', () => {
     useJourneyTestRuntime(emitMock);
 
     describe('around a single step', () => {
@@ -16,13 +21,13 @@ describe('[journey] activeJourneyStep', () => {
         });
 
         test('is set only while the step is running', async () => {
-            expect(activeJourneyStep()).toBeNull();
+            expect(singleInFlightJourneyStep()).toBeNull();
 
             await journeyStep(baseDef.name, 'do-work', () => {
-                expect(activeJourneyStep()).not.toBeNull();
+                expect(singleInFlightJourneyStep()).toBeInstanceOf(JourneyStepStamp);
             });
 
-            expect(activeJourneyStep()).toBeNull();
+            expect(singleInFlightJourneyStep()).toBeNull();
             completeJourney(baseDef.name);
         });
     });
@@ -50,7 +55,7 @@ describe('[journey] activeJourneyStep', () => {
             completeJourney(otherDef.name);
         });
 
-        const subject = () => journeyStep(otherDef.name, 'book', () => activeJourneyStep());
+        const subject = () => journeyStep(otherDef.name, 'book', () => singleInFlightJourneyStep());
 
         test('returns null', async () => {
             await expect(subject()).resolves.toBeNull();
@@ -60,7 +65,7 @@ describe('[journey] activeJourneyStep', () => {
     describe('when the first-finishing sibling ends first', () => {
         let releaseB!: () => void;
         let stepB: Promise<unknown>;
-        let ambientWhileBAlone: ReturnType<typeof activeJourneyStep> | 'unset';
+        let ambientWhileBAlone: ReturnType<typeof singleInFlightJourneyStep> | 'unset';
 
         beforeEach(() => {
             moduleRuntime.startJourney(baseDef);
@@ -72,7 +77,7 @@ describe('[journey] activeJourneyStep', () => {
             });
             stepB = journeyStep(otherDef.name, 'book', async () => {
                 await gateB;
-                ambientWhileBAlone = activeJourneyStep();
+                ambientWhileBAlone = singleInFlightJourneyStep();
             });
         });
 
@@ -85,7 +90,7 @@ describe('[journey] activeJourneyStep', () => {
 
         test('keeps ambient on the remaining step', async () => {
             await journeyStep(baseDef.name, 'load', () => {
-                expect(activeJourneyStep()).toBeNull();
+                expect(singleInFlightJourneyStep()).toBeNull();
             });
 
             releaseB();
@@ -96,7 +101,8 @@ describe('[journey] activeJourneyStep', () => {
             if (ambientWhileBAlone === 'unset' || ambientWhileBAlone == null) {
                 throw new Error('expected ambient step');
             }
-            expect(ambientWhileBAlone.name).toBe('book');
+            expect(ambientWhileBAlone).toBeInstanceOf(JourneyStepStamp);
+            expect(ambientWhileBAlone.step.name).toBe('book');
         });
     });
 });

package/src/__tests__/core/api.test.ts

@@ -20,10 +20,10 @@ const otherDef = { ...baseJourneyDef, name: 'api-other' };
 describe('[journey] api', () => {
     useJourneyTestRuntime(emitMock);
 
-    describe('firstOpenJourney', () => {
+    describe('firstOpenJourneyName', () => {
         const names = [baseDef.name, otherDef.name];
 
-        const subject = () => moduleRuntime.firstOpenJourney(names);
+        const subject = () => moduleRuntime.firstOpenJourneyName(names);
 
         describe('when none are open', () => {
             test('returns null', () => {
@@ -49,7 +49,7 @@ describe('[journey] api', () => {
 
             test('returns the first match in order', () => {
                 expect(subject()).toBe(baseDef.name);
-                expect(moduleRuntime.firstOpenJourney([otherDef.name, baseDef.name])).toBe(
+                expect(moduleRuntime.firstOpenJourneyName([otherDef.name, baseDef.name])).toBe(
                     otherDef.name
                 );
             });
@@ -85,7 +85,7 @@ describe('[journey] api', () => {
             beforeEach(async () => {
                 moduleRuntime.startJourney(baseDef);
                 await journeyStep(baseDef.name, 'do-work', step => {
-                    step.complete();
+                    step.completeJourney();
                 });
             });
 
@@ -102,7 +102,7 @@ describe('[journey] api', () => {
             beforeEach(async () => {
                 moduleRuntime.startJourney(baseDef);
                 await journeyStep(baseDef.name, 'do-work', step => {
-                    step.fail('validation');
+                    step.failJourney('validation');
                 });
             });
 
@@ -136,7 +136,7 @@ describe('[journey] api', () => {
             beforeEach(async () => {
                 moduleRuntime.startJourney(baseDef);
                 await journeyStep(baseDef.name, 'do-work', step => {
-                    step.fail('validation');
+                    step.failJourney('validation');
                 });
             });
 
@@ -209,7 +209,7 @@ describe('[journey] api', () => {
             beforeEach(async () => {
                 moduleRuntime.startJourney(baseDef);
                 await journeyStep(baseDef.name, 'do-work', step => {
-                    step.fail('validation');
+                    step.failJourney('validation');
                 });
                 emitMock.mockClear();
             });

package/src/__tests__/core/define-journey.test.ts

@@ -26,7 +26,7 @@ describe('[journey] defineJourney', () => {
         const subject = () =>
             journey.step('do-work', step => {
                 step.setAttribute('x', 1);
-                step.complete({ 'payment.id': 42 });
+                step.completeJourney({ 'payment.id': 42 });
             });
 
         test('opens, records the step, and completes good', async () => {
@@ -41,7 +41,7 @@ describe('[journey] defineJourney', () => {
 
         test('mountStep also opens the journey', async () => {
             await journey.mountStep('boot', step => {
-                step.complete();
+                step.completeJourney();
             });
 
             expect(emitMock).toHaveBeenCalledTimes(1);
@@ -57,7 +57,7 @@ describe('[journey] defineJourney', () => {
 
         const subject = () =>
             journey.step('do-work', step => {
-                step.complete();
+                step.completeJourney();
             });
 
         test('does not restart the open journey', async () => {
@@ -76,7 +76,7 @@ describe('[journey] defineJourney', () => {
 
         const subject = () =>
             journeyStep(journey, 'via-free', step => {
-                step.complete();
+                step.completeJourney();
             });
 
         test('resolves the handle name', async () => {
@@ -153,7 +153,7 @@ describe('[journey] defineJourney', () => {
 
         const subject = () =>
             journey.mountStep('boot', step => {
-                step.complete();
+                step.completeJourney();
             });
 
         test('does not restart the open journey', async () => {
@@ -166,12 +166,29 @@ describe('[journey] defineJourney', () => {
         });
     });
 
-    describe('when copying def fields onto the handle', () => {
-        test('exposes the journey config properties', () => {
-            expect(journey.name).toBe(base.name);
-            expect(journey.team).toBe(base.team);
-            expect(journey.group).toBe(base.group);
-            expect(journey.service).toBe(base.service);
+    describe('when keeping the original config on the handle', () => {
+        test('exposes the same config object', () => {
+            expect(journey.config).toBe(base);
+            expect(journey.config.name).toBe(base.name);
+            expect(journey.config.name).toBe(base.name);
+            expect(journey.config.team).toBe(base.team);
+            expect(journey.config.group).toBe(base.group);
+            expect(journey.config.service).toBe(base.service);
+        });
+    });
+
+    describe('when stepping via free journeyStep with a handle and nothing open', () => {
+        const subject = () =>
+            journeyStep(journey, 'via-handle', step => {
+                step.completeJourney();
+            });
+
+        test('auto-starts from the handle config', async () => {
+            await subject();
+
+            expect(emitMock).toHaveBeenCalledTimes(1);
+            expect(lastJourney(emitMock).outcome).toBe('good');
+            expect(lastJourney(emitMock).steps[0].name).toBe('via-handle');
         });
     });
 });