@servicetitan/journey 2.0.0 → 3.0.0

package/src/__tests__/integrations/scope.test.tsx

@@ -0,0 +1,286 @@
+/** @jest-environment jsdom */
+import { render, screen } from '@testing-library/react';
+import { useContext, useEffect } from 'react';
+
+import { useJourneyTestRuntime } from '../../__test-utils__/test-runtime';
+import { completeJourney, failJourney, journeyStep } from '../../core';
+import { onHttpComplete } from '../../integrations/http-report';
+import { JourneyNameContext } from '../../integrations/react/context';
+import { JourneyScope } from '../../integrations/react/scope';
+
+const emitMock = jest.fn();
+
+const def = {
+    name: 'scope-journey',
+    team: 'platform',
+    group: 'test',
+    service: 'journey',
+    timeoutMs: 0,
+};
+
+function NameProbe() {
+    const name = useContext(JourneyNameContext);
+    return <span data-testid="journey-name">{name}</span>;
+}
+
+describe('[journey] JourneyScope', () => {
+    useJourneyTestRuntime(emitMock);
+
+    beforeEach(() => {
+        jest.useFakeTimers();
+    });
+
+    afterEach(() => {
+        jest.useRealTimers();
+    });
+
+    test('opens a journey on mount and publishes the name via context', () => {
+        render(
+            <JourneyScope {...def}>
+                <NameProbe />
+            </JourneyScope>
+        );
+
+        expect(screen.getByTestId('journey-name').textContent).toBe(def.name);
+        completeJourney(def.name);
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.outcome).toBe('good');
+    });
+
+    test('applies tags from props', () => {
+        render(
+            <JourneyScope {...def} tags={{ plan: 'pro' }}>
+                <NameProbe />
+            </JourneyScope>
+        );
+
+        completeJourney(def.name);
+        expect(emitMock.mock.calls[0][0].journey.tags).toEqual({ plan: 'pro' });
+    });
+
+    test('excludes the journey on unmount', () => {
+        const { unmount } = render(
+            <JourneyScope {...def}>
+                <NameProbe />
+            </JourneyScope>
+        );
+
+        unmount();
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.outcome).toBe('excluded');
+    });
+
+    describe('when the journey already completed before unmount', () => {
+        test('unmount does not emit again', () => {
+            const { unmount } = render(
+                <JourneyScope {...def}>
+                    <NameProbe />
+                </JourneyScope>
+            );
+
+            completeJourney(def.name);
+            expect(emitMock).toHaveBeenCalledTimes(1);
+            expect(emitMock.mock.calls[0][0].journey.outcome).toBe('good');
+
+            emitMock.mockClear();
+            unmount();
+
+            expect(emitMock).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('when the name prop changes', () => {
+        const next = { ...def, name: 'scope-journey-next' };
+
+        test('excludes the prior journey and opens the new one', () => {
+            const { rerender } = render(
+                <JourneyScope {...def}>
+                    <NameProbe />
+                </JourneyScope>
+            );
+
+            rerender(
+                <JourneyScope {...next}>
+                    <NameProbe />
+                </JourneyScope>
+            );
+
+            expect(screen.getByTestId('journey-name').textContent).toBe(next.name);
+            expect(emitMock).toHaveBeenCalledTimes(1);
+            expect(emitMock.mock.calls[0][0].journey.name).toBe(def.name);
+            expect(emitMock.mock.calls[0][0].journey.outcome).toBe('excluded');
+
+            completeJourney(next.name);
+            expect(emitMock.mock.calls[1][0].journey.name).toBe(next.name);
+            expect(emitMock.mock.calls[1][0].journey.outcome).toBe('good');
+        });
+    });
+
+    describe('when a breach already occurred before unmount', () => {
+        test('unmount stays bad (breach-anchored)', () => {
+            const { unmount } = render(
+                <JourneyScope {...def}>
+                    <NameProbe />
+                </JourneyScope>
+            );
+
+            failJourney(def.name, 'validation');
+            expect(emitMock.mock.calls[0][0].journey.outcome).toBe('bad');
+
+            emitMock.mockClear();
+            unmount();
+
+            expect(emitMock).not.toHaveBeenCalled();
+        });
+    });
+
+    test('applies updated tags without restarting', () => {
+        const { rerender } = render(
+            <JourneyScope {...def} tags={{ plan: 'a' }}>
+                <NameProbe />
+            </JourneyScope>
+        );
+
+        rerender(
+            <JourneyScope {...def} tags={{ plan: 'b' }}>
+                <NameProbe />
+            </JourneyScope>
+        );
+
+        completeJourney(def.name);
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.tags).toEqual({ plan: 'b' });
+        expect(emitMock.mock.calls[0][0].journey.outcome).toBe('good');
+    });
+
+    test('child abort cleanup then unmount is excluded not request-aborted', async () => {
+        let stamp: Parameters<typeof onHttpComplete>[0]['stamp'];
+        let release!: () => void;
+        const hang = new Promise<void>(resolve => {
+            release = resolve;
+        });
+
+        function Child() {
+            useEffect(
+                () => () => {
+                    if (stamp) {
+                        onHttpComplete({
+                            stamp,
+                            aborted: true,
+                            requestKey: '/x',
+                            durationMs: 5,
+                        });
+                    }
+                },
+                []
+            );
+            return null;
+        }
+
+        const { unmount } = render(
+            <JourneyScope {...def}>
+                <Child />
+            </JourneyScope>
+        );
+
+        const stepPromise = journeyStep(def.name, 'load', async step => {
+            stamp = step.stamp();
+            await hang;
+        });
+        await Promise.resolve();
+        unmount();
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.outcome).toBe('excluded');
+
+        release();
+        await stepPromise;
+    });
+
+    test('rerendering with equal endpoint values does not re-arm timeout', async () => {
+        const timeoutDef = {
+            ...def,
+            name: 'scope-timer-stable',
+            timeoutMs: 30,
+            endpoints: [{ match: '/api/jobs', slowRequestMs: 100 }],
+        };
+
+        const { rerender } = render(
+            <JourneyScope {...timeoutDef}>
+                <NameProbe />
+            </JourneyScope>
+        );
+
+        await jest.advanceTimersByTimeAsync(20);
+
+        rerender(
+            <JourneyScope {...timeoutDef} endpoints={[{ match: '/api/jobs', slowRequestMs: 100 }]}>
+                <NameProbe />
+            </JourneyScope>
+        );
+
+        await jest.advanceTimersByTimeAsync(15);
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.outcome).toBe('bad');
+        expect(emitMock.mock.calls[0][0].journey.reason).toBe('journey-timeout');
+    });
+
+    test('live config updates keep original timeout budget', async () => {
+        const timeoutDef = {
+            ...def,
+            name: 'scope-timeout-updates',
+            timeoutMs: 30,
+            team: 'team-a',
+        };
+
+        const { rerender } = render(
+            <JourneyScope {...timeoutDef}>
+                <NameProbe />
+            </JourneyScope>
+        );
+
+        await jest.advanceTimersByTimeAsync(20);
+
+        rerender(
+            <JourneyScope {...timeoutDef} team="team-b">
+                <NameProbe />
+            </JourneyScope>
+        );
+
+        await jest.advanceTimersByTimeAsync(15);
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.name).toBe(timeoutDef.name);
+        expect(emitMock.mock.calls[0][0].journey.reason).toBe('journey-timeout');
+    });
+
+    test('live maxSteps updates apply without restarting', async () => {
+        const maxStepsDef = {
+            ...def,
+            name: 'scope-max-steps',
+            maxSteps: 1,
+        };
+
+        const { rerender } = render(
+            <JourneyScope {...maxStepsDef}>
+                <NameProbe />
+            </JourneyScope>
+        );
+
+        await journeyStep(maxStepsDef.name, 'first', async () => {});
+
+        rerender(
+            <JourneyScope {...maxStepsDef} maxSteps={2}>
+                <NameProbe />
+            </JourneyScope>
+        );
+
+        await journeyStep(maxStepsDef.name, 'second', async () => {});
+
+        completeJourney(maxStepsDef.name);
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.steps).toHaveLength(2);
+    });
+});

package/src/__tests__/integrations/use-journey-step.test.tsx

@@ -0,0 +1,43 @@
+/** @jest-environment jsdom */
+import { renderHook } from '@testing-library/react';
+import { type ReactNode } from 'react';
+
+import {
+    useJourneyTestRuntime,
+    baseJourneyDef,
+    lastJourney,
+} from '../../__test-utils__/test-runtime';
+import { completeJourney, defineJourney } from '../../core';
+import { JourneyScope } from '../../integrations/react/scope';
+import { useJourneyStep } from '../../integrations/react/use-journey-step';
+
+const emitMock = jest.fn();
+
+describe('[journey] useJourneyStep', () => {
+    useJourneyTestRuntime(emitMock);
+
+    test('runs a step on the JourneyScope journey', async () => {
+        const wrapper = ({ children }: { children: ReactNode }) => (
+            <JourneyScope {...baseJourneyDef} name="hook-journey">
+                {children}
+            </JourneyScope>
+        );
+
+        const { result } = renderHook(() => useJourneyStep(), { wrapper });
+        await result.current('load', () => 'ok');
+        completeJourney('hook-journey');
+
+        expect(lastJourney(emitMock).steps[0].name).toBe('load');
+        expect(lastJourney(emitMock).outcome).toBe('good');
+    });
+
+    test('auto-starts when given a handle', async () => {
+        const handle = defineJourney({ ...baseJourneyDef, name: 'hook-handle' });
+        const { result } = renderHook(() => useJourneyStep(handle));
+        await result.current('load', () => 'ok');
+        handle.complete();
+
+        expect(lastJourney(emitMock).steps[0].name).toBe('load');
+        expect(lastJourney(emitMock).outcome).toBe('good');
+    });
+});

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

@@ -0,0 +1,103 @@
+/** @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();
+        sessionStorage.clear();
+        debugSpy = jest.spyOn(console, 'debug').mockImplementation(() => undefined);
+    });
+
+    afterEach(() => {
+        debugSpy.mockRestore();
+        localStorage.clear();
+        sessionStorage.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(() => {
+            sessionStorage.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(() => {
+            sessionStorage.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',
+                expect.objectContaining({ name: 'book_job', outcome: 'bad' })
+            );
+        });
+    });
+
+    describe('when sessionStorage 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,47 @@ 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 the resolved RUM stub has no addAction', () => {
+        test('is a no-op', () => {
+            (globalThis as Record<string, unknown>)[DD_RUM_KEY] = {};
+
+            expect(() => sendToDatadog(sampleEvent())).not.toThrow();
+            expect(importedAddAction).not.toHaveBeenCalled();
+            expect(addAction).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 +121,7 @@ describe('[journey] setJourneyRum / sendToDatadog', () => {
 
             expect(addAction).toHaveBeenCalledTimes(1);
             expect(importedAddAction).not.toHaveBeenCalled();
+            expect(warnSpy).not.toHaveBeenCalled();
         });
 
         test('normalizes identity fields', () => {
@@ -127,6 +189,48 @@ 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('drops denied tag keys and normalizes tag keys on the wire', () => {
+        setJourneyRum({ addAction });
+        sendToDatadog(
+            sampleEvent({
+                tags: {
+                    'token': 'secret',
+                    'User Email': 'Pat!',
+                },
+                steps: [
+                    {
+                        name: 'Load Draft!!',
+                        startMs: 0,
+                        durationMs: 3,
+                        outcome: 'good',
+                        attributes: { token: 'nope', phase: 'Load' },
+                    },
+                ],
+            })
+        );
+
+        const ctx = addAction.mock.calls[0][1];
+        expect(ctx.journey.tags.token).toBeUndefined();
+        expect(ctx.journey.tags.user_email).toBe('pat');
+        expect(ctx.journey.steps[0].name).toBe('load_draft');
+        expect(ctx.journey.steps[0].attributes.token).toBeUndefined();
+        expect(ctx.journey.steps[0].attributes.phase).toBe('load');
+    });
+
+    test('truncates long tag values on the wire', () => {
+        setJourneyRum({ addAction });
+        const long = `x${'a'.repeat(250)}`;
+        sendToDatadog(sampleEvent({ tags: { note: long } }));
+
+        const ctx = addAction.mock.calls[0][1];
+        expect(ctx.journey.tags.note.length).toBeLessThanOrEqual(200);
+    });
+
     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', () => {