@servicetitan/journey 2.1.0 → 3.0.0

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

@@ -4,7 +4,7 @@ import {
     lastJourney,
     useJourneyTestRuntime,
 } from '../../__test-utils__/test-runtime';
-import { completeJourney, failJourney, journeyStep, resolveJourneyStep } from '../../core';
+import { completeJourney, failJourney, JourneyStepStamp, journeyStep } from '../../core';
 import { moduleRuntime } from '../../core/runtime';
 
 const emitMock = jest.fn();
@@ -19,7 +19,8 @@ describe('[journey] journeyStep', () => {
             moduleRuntime.startJourney(baseDef);
         });
 
-        const subject = () => journeyStep(['missing', baseDef.name], 'do-work', step => step.name);
+        const subject = () =>
+            journeyStep(['missing', baseDef.name], 'do-work', step => step.journeyName);
 
         test('resolves the first open name', async () => {
             await expect(subject()).resolves.toBe(baseDef.name);
@@ -33,7 +34,7 @@ describe('[journey] journeyStep', () => {
         });
 
         const subject = () =>
-            journeyStep([baseDef.name, otherDef.name], 'do-work', step => step.name);
+            journeyStep([baseDef.name, otherDef.name], 'do-work', step => step.journeyName);
 
         test('prefers the first name in order', async () => {
             await expect(subject()).resolves.toBe(baseDef.name);
@@ -43,9 +44,9 @@ describe('[journey] journeyStep', () => {
     describe('with no matching open journey', () => {
         const subject = () =>
             journeyStep(['missing-a', 'missing-b'], 'do-work', step => {
-                step.complete({ a: 1 });
-                step.fail('noop');
-                return step.name;
+                step.completeJourney({ a: 1 });
+                step.failJourney('noop');
+                return step.journeyName;
             });
 
         test('runs untraced', async () => {
@@ -54,12 +55,21 @@ describe('[journey] journeyStep', () => {
         });
     });
 
+    describe('with a bare name and nothing open', () => {
+        test('does not auto-start', async () => {
+            await journeyStep(baseDef.name, 'do-work', step => {
+                expect(step.journeyName).toBeNull();
+                expect(step.stamp()).toBeUndefined();
+            });
+            expect(emitMock).not.toHaveBeenCalled();
+        });
+    });
+
     describe('with a null target', () => {
-        const subject = () =>
-            journeyStep(null, 'untraced', step => step.tag() as Record<string, unknown>);
+        const subject = () => journeyStep(null, 'untraced', step => step.stamp());
 
-        test('returns an empty tag object', async () => {
-            await expect(subject()).resolves.toEqual({});
+        test('returns undefined', async () => {
+            await expect(subject()).resolves.toBeUndefined();
         });
     });
 
@@ -72,7 +82,7 @@ describe('[journey] journeyStep', () => {
             const subject = () =>
                 journeyStep(baseDef.name, 'do-work', step => {
                     step.setAttribute('x', 1);
-                    step.complete({ 'payment.id': 42 });
+                    step.completeJourney({ 'payment.id': 42 });
                 });
 
             test('emits good with tags and attributes', async () => {
@@ -103,29 +113,63 @@ describe('[journey] journeyStep', () => {
             });
         });
 
-        describe('when step.tag is called', () => {
-            let tagged: Record<string, unknown> | null;
+        describe('when setAttribute uses unsafe or overflowing keys', () => {
+            test('skips prototype keys and caps the map', async () => {
+                await journeyStep(baseDef.name, 'attrs', step => {
+                    step.setAttribute('__proto__', 'nope');
+                    step.setAttribute('token', 'secret');
+                    step.setAttribute('ok', 1);
+                    for (let i = 0; i < 70; i += 1) {
+                        step.setAttribute(`k${i}`, i);
+                    }
+                });
+                completeJourney(baseDef.name);
+
+                const attributes = lastJourney(emitMock).steps[0].attributes as Record<
+                    string,
+                    unknown
+                >;
+                expect(Object.prototype.hasOwnProperty.call(attributes, '__proto__')).toBe(false);
+                expect(attributes.token).toBeUndefined();
+                expect(attributes.ok).toBe(1);
+                expect(Object.keys(attributes).length).toBe(64);
+                expect(({} as { polluted?: boolean }).polluted).toBeUndefined();
+            });
+        });
+
+        describe('when step.stamp is called', () => {
+            let tagged: JourneyStepStamp | undefined;
 
             beforeEach(() => {
-                tagged = null;
+                tagged = undefined;
             });
 
             const subject = () =>
                 journeyStep(baseDef.name, 'do-work', step => {
-                    tagged = step.tag() as Record<string, unknown>;
+                    tagged = step.stamp();
                 });
 
-            test('binds journeyStep', async () => {
+            test('binds stamp', async () => {
                 await subject();
 
-                expect(tagged).toHaveProperty('journeyStep');
+                expect(tagged).toBeInstanceOf(JourneyStepStamp);
+            });
+        });
+
+        describe('when step.stamp is called with a score function', () => {
+            test('stores score on the stamp', async () => {
+                await journeyStep(baseDef.name, 'do-work', step => {
+                    const score = () => 'exclude' as const;
+                    const stamp = step.stamp(score);
+                    expect(stamp?.score).toBe(score);
+                });
             });
         });
 
-        describe('when step.fail is called', () => {
+        describe('when step.failJourney is called', () => {
             const subject = () =>
                 journeyStep(baseDef.name, 'do-work', step => {
-                    step.fail('empty-catalog');
+                    step.failJourney('empty-catalog');
                 });
 
             test('marks bad without throwing', async () => {
@@ -145,7 +189,7 @@ describe('[journey] journeyStep', () => {
             test('marks step-error and rethrows', async () => {
                 await expect(subject()).rejects.toThrow('boom');
                 expect(lastJourney(emitMock).reason).toBe('step-error');
-                expect(lastJourney(emitMock).steps[0].attributes).toEqual({ error: 'boom' });
+                expect(lastJourney(emitMock).steps[0].attributes).toBeUndefined();
             });
         });
 
@@ -156,27 +200,22 @@ describe('[journey] journeyStep', () => {
                     throw 'string-boom';
                 });
 
-            test('stringifies the error attribute', async () => {
+            test('does not stringify the throw onto attributes', async () => {
                 await expect(subject()).rejects.toBe('string-boom');
-                expect(lastJourney(emitMock).steps[0].attributes).toEqual({
-                    error: 'string-boom',
-                });
+                expect(lastJourney(emitMock).steps[0].attributes).toBeUndefined();
             });
         });
 
         describe('when error is pre-set on the step', () => {
             const subject = () =>
                 journeyStep(baseDef.name, 'do-work', step => {
-                    const ref = resolveJourneyStep(
-                        (step.tag() as { journeyStep: unknown }).journeyStep
-                    )!;
-                    ref.attributes.error = 'already';
+                    step.setAttribute('phase', 'load');
                     throw new Error('boom');
                 });
 
-            test('preserves the first error attribute', async () => {
+            test('keeps developer attributes', async () => {
                 await expect(subject()).rejects.toThrow('boom');
-                expect(lastJourney(emitMock).steps[0].attributes).toEqual({ error: 'already' });
+                expect(lastJourney(emitMock).steps[0].attributes).toEqual({ phase: 'load' });
             });
         });
 
@@ -184,7 +223,7 @@ describe('[journey] journeyStep', () => {
             beforeEach(() => {
                 // Parent already opened baseDef; restart with expected steps.
                 emitMock.mockClear();
-                moduleRuntime.startJourney({ ...baseDef, steps: ['load', 'save'] });
+                moduleRuntime.startJourney({ ...baseDef, expected: ['load', 'save'] });
                 emitMock.mockClear();
             });
 
@@ -195,7 +234,7 @@ describe('[journey] journeyStep', () => {
                 expect(emitMock).not.toHaveBeenCalled();
 
                 await journeyStep(baseDef.name, 'save', step => {
-                    step.complete({ done: true });
+                    step.completeJourney({ done: true });
                 });
 
                 expect(emitMock).toHaveBeenCalledTimes(1);
@@ -210,8 +249,8 @@ describe('[journey] journeyStep', () => {
         describe('with a JourneyDef-like object target', () => {
             const subject = () =>
                 journeyStep(baseDef, 'via-def', step => {
-                    step.complete();
-                    return step.name;
+                    step.completeJourney();
+                    return step.journeyName;
                 });
 
             test('resolves the def name', async () => {
@@ -241,8 +280,8 @@ describe('[journey] journeyStep', () => {
 
             const subject = () =>
                 moduleRuntime.journeyMountStep(['missing', baseDef.name], 'mount-load', step => {
-                    step.complete();
-                    return step.name;
+                    step.completeJourney();
+                    return step.journeyName;
                 });
 
             test('resolves the open candidate', async () => {
@@ -300,4 +339,61 @@ describe('[journey] journeyStep', () => {
             await stepPromise;
         });
     });
+
+    describe('when the same name is restarted while a step is in flight', () => {
+        test('completeJourney on the old step does not close the new instance', async () => {
+            moduleRuntime.startJourney(baseDef);
+            let resolveWork!: () => void;
+            const hang = new Promise<void>(resolve => {
+                resolveWork = resolve;
+            });
+            const stepPromise = journeyStep(baseDef.name, 'slow', async step => {
+                await hang;
+                step.completeJourney();
+            });
+            await Promise.resolve();
+            moduleRuntime.startJourney(baseDef);
+            expect(lastJourney(emitMock).outcome).toBe('excluded');
+            emitMock.mockClear();
+
+            resolveWork();
+            await stepPromise;
+            expect(emitMock).not.toHaveBeenCalled();
+
+            completeJourney(baseDef.name);
+            expect(lastJourney(emitMock).outcome).toBe('good');
+            expect(lastJourney(emitMock).steps).toHaveLength(0);
+        });
+    });
+
+    describe('when maxSteps is exceeded', () => {
+        test('stops recording steps and sets steps_truncated', async () => {
+            moduleRuntime.startJourney({ ...baseDef, maxSteps: 2 });
+            await journeyStep(baseDef.name, 'a', () => {});
+            await journeyStep(baseDef.name, 'b', () => {});
+            await journeyStep(baseDef.name, 'c', () => {});
+            completeJourney(baseDef.name);
+
+            expect(lastJourney(emitMock).steps.map((s: { name: string }) => s.name)).toEqual([
+                'a',
+                'b',
+            ]);
+            expect(lastJourney(emitMock).tags?.steps_truncated).toBe(true);
+        });
+    });
+
+    describe('when the started config is frozen', () => {
+        test('rejects mutation of the snapshot', () => {
+            const config = { ...baseDef, name: 'frozen-def' };
+            moduleRuntime.startJourney(config);
+            const snapshot = moduleRuntime.getOpenJourney('frozen-def')!.config;
+            expect(Object.isFrozen(snapshot)).toBe(true);
+            expect(snapshot).not.toBe(config);
+            expect(() => {
+                (snapshot as { name: string }).name = 'hacked';
+            }).toThrow();
+            expect(snapshot.name).toBe('frozen-def');
+            completeJourney('frozen-def');
+        });
+    });
 });

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

@@ -4,7 +4,8 @@ import {
     lastJourney,
     useJourneyTestRuntime,
 } from '../../__test-utils__/test-runtime';
-import { completeJourney, journeyStep, resolveJourneyStep } from '../../core';
+import type { JourneyStepStamp } from '../../core';
+import { completeJourney, journeyStep } from '../../core';
 import { moduleRuntime } from '../../core/runtime';
 
 const emitMock = jest.fn();
@@ -52,6 +53,24 @@ describe('[journey] timeouts', () => {
         });
     });
 
+    describe('without timeoutMs', () => {
+        beforeEach(() => {
+            moduleRuntime.startJourney({
+                name: 'timeout-idle',
+                team: baseDef.team,
+                group: baseDef.group,
+                service: baseDef.service,
+            });
+        });
+
+        test('closes excluded with journey-idle-timeout after default idle window', async () => {
+            await jest.advanceTimersByTimeAsync(15 * 60 * 1_000);
+
+            expect(lastJourney(emitMock).outcome).toBe('excluded');
+            expect(lastJourney(emitMock).reason).toBe('journey-idle-timeout');
+        });
+    });
+
     describe('with a step timeoutMs', () => {
         let resolveWork!: () => void;
         let stepPromise: Promise<unknown>;
@@ -154,9 +173,7 @@ describe('[journey] timeouts', () => {
                 resolveWork = resolve;
             });
             stepPromise = journeyStep(baseDef.name, 'slow', async step => {
-                const ref = resolveJourneyStep(
-                    (step.tag() as { journeyStep: unknown }).journeyStep
-                )!;
+                const ref = (step.stamp() as JourneyStepStamp).step;
                 ref.reason = 'pre-existing';
                 ref.attributes.timeout_ms = 999;
                 await hang;
@@ -199,6 +216,34 @@ describe('[journey] timeouts', () => {
         });
     });
 
+    describe('when a journey timeout closes a hung step', () => {
+        let releaseWork!: () => void;
+        let stepPromise: Promise<unknown>;
+
+        beforeEach(() => {
+            moduleRuntime.startJourney({ ...baseDef, timeoutMs: 50 });
+            const hang = new Promise<void>(resolve => {
+                releaseWork = resolve;
+            });
+            stepPromise = journeyStep(baseDef.name, 'slow', async () => {
+                await hang;
+            });
+        });
+
+        afterEach(async () => {
+            releaseWork();
+            await stepPromise;
+        });
+
+        test('releases inFlight state before the step settles', async () => {
+            await jest.advanceTimersByTimeAsync(50);
+
+            expect(moduleRuntime.activeJourneyStep()).toBeNull();
+            expect(lastJourney(emitMock).outcome).toBe('bad');
+            expect(lastJourney(emitMock).reason).toBe('journey-timeout');
+        });
+    });
+
     describe('with stepTimeoutMs 0', () => {
         let resolveWork!: () => void;
         let stepPromise: Promise<unknown>;
@@ -228,4 +273,24 @@ describe('[journey] timeouts', () => {
             expect(lastJourney(emitMock).outcome).toBe('good');
         });
     });
+
+    describe('with non-finite timeoutMs', () => {
+        test('Infinity disables the countdown', async () => {
+            moduleRuntime.startJourney({ ...baseDef, timeoutMs: Infinity });
+            await jest.advanceTimersByTimeAsync(60_000);
+
+            expect(emitMock).not.toHaveBeenCalled();
+            completeJourney(baseDef.name);
+            expect(lastJourney(emitMock).outcome).toBe('good');
+        });
+
+        test('NaN disables the countdown', async () => {
+            moduleRuntime.startJourney({ ...baseDef, timeoutMs: Number.NaN });
+            await jest.advanceTimersByTimeAsync(60_000);
+
+            expect(emitMock).not.toHaveBeenCalled();
+            completeJourney(baseDef.name);
+            expect(lastJourney(emitMock).outcome).toBe('good');
+        });
+    });
 });

package/src/__tests__/global.test.ts

@@ -1,13 +1,16 @@
 /** @jest-environment jsdom */
 import '../config';
 import { defineJourney, resetJourney } from '../core';
+import { moduleRuntime } from '../core/runtime';
 import {
     JOURNEY_DEBUG_STORAGE_KEY,
     JOURNEY_ENABLED_STORAGE_KEY,
     ST_JOURNEY_GLOBAL_KEY,
+    ST_JOURNEY_SCHEMA_VERSION,
     disableJourney,
     enableJourney,
     isJourneyEnabled,
+    setJourneyDefaultEnabled,
     type StJourneyGlobal,
 } from '../global';
 import { setJourneyRum } from '../sinks/datadog';
@@ -19,6 +22,8 @@ function getStJourney(): StJourneyGlobal {
 describe('[journey] __stJourney global', () => {
     beforeEach(() => {
         localStorage.clear();
+        sessionStorage.clear();
+        setJourneyDefaultEnabled(false);
         delete getStJourney().rum;
         delete (globalThis as Record<string, unknown>).DD_RUM;
         resetJourney({ sinks: [] });
@@ -26,6 +31,8 @@ describe('[journey] __stJourney global', () => {
 
     afterEach(() => {
         localStorage.clear();
+        sessionStorage.clear();
+        setJourneyDefaultEnabled(false);
         delete getStJourney().rum;
         delete (globalThis as Record<string, unknown>).DD_RUM;
         resetJourney({ sinks: [] });
@@ -34,6 +41,7 @@ describe('[journey] __stJourney global', () => {
     test('installs __stJourney on package load', () => {
         expect(getStJourney()).toEqual(
             expect.objectContaining({
+                schemaVersion: ST_JOURNEY_SCHEMA_VERSION,
                 enable: expect.any(Function),
                 disable: expect.any(Function),
                 isEnabled: expect.any(Function),
@@ -58,15 +66,47 @@ describe('[journey] __stJourney global', () => {
         expect(isJourneyEnabled()).toBe(false);
     });
 
-    test('enableDebugging / disableDebugging toggle console-debug localStorage', () => {
+    test('isJourneyEnabled is true when host default is on', () => {
+        expect(isJourneyEnabled()).toBe(false);
+
+        setJourneyDefaultEnabled(true);
+        expect(isJourneyEnabled()).toBe(true);
+        expect(getStJourney().isEnabled()).toBe(true);
+
+        setJourneyDefaultEnabled(false);
+        expect(isJourneyEnabled()).toBe(false);
+    });
+
+    test('isJourneyEnabled is true when either host default or force flag is on', () => {
+        setJourneyDefaultEnabled(true);
+        enableJourney();
+        expect(isJourneyEnabled()).toBe(true);
+
+        setJourneyDefaultEnabled(false);
+        expect(isJourneyEnabled()).toBe(true);
+
+        disableJourney();
+        expect(isJourneyEnabled()).toBe(false);
+
+        setJourneyDefaultEnabled(true);
+        expect(isJourneyEnabled()).toBe(true);
+    });
+
+    test('host default is shared on __stJourney for cross-bundle reads', () => {
+        setJourneyDefaultEnabled(true);
+        expect(getStJourney().defaultEnabled).toBe(true);
+        expect(isJourneyEnabled()).toBe(true);
+    });
+
+    test('enableDebugging / disableDebugging toggle console-debug sessionStorage', () => {
         const st = getStJourney();
 
         st.enableDebugging();
-        expect(localStorage.getItem(JOURNEY_DEBUG_STORAGE_KEY)).toBe('true');
+        expect(sessionStorage.getItem(JOURNEY_DEBUG_STORAGE_KEY)).toBe('true');
         expect(st.isDebugEnabled()).toBe(true);
 
         st.disableDebugging();
-        expect(localStorage.getItem(JOURNEY_DEBUG_STORAGE_KEY)).toBeNull();
+        expect(sessionStorage.getItem(JOURNEY_DEBUG_STORAGE_KEY)).toBeNull();
         expect(st.isDebugEnabled()).toBe(false);
     });
 
@@ -91,6 +131,7 @@ describe('[journey] __stJourney global', () => {
         getStJourney().enableDebugging();
         const on = getStJourney().getDebugState();
         expect(on.debug).toBe(true);
+        expect(on.runtimes.some(r => r.id === moduleRuntime.id)).toBe(true);
         expect(on.runtimes.some(r => r.openJourneys.some(j => j.name === 'Book Job'))).toBe(true);
 
         getStJourney().disableDebugging();