@servicetitan/journey 1.0.0

package/src/__tests__/step.test.ts

@@ -0,0 +1,305 @@
+/** @jest-environment jsdom */
+import { baseJourneyDef, lastJourney, useJourneyTestRuntime } from '../__mocks__/test-runtime';
+import {
+    completeJourney,
+    failJourney,
+    journeyMountStep,
+    journeyStep,
+    resolveJourneyStep,
+    startJourney,
+} from '../core';
+
+const emitMock = jest.fn();
+const baseDef = { ...baseJourneyDef, name: 'step-api' };
+const otherDef = { ...baseJourneyDef, name: 'step-other' };
+
+describe('[journey] journeyStep', () => {
+    useJourneyTestRuntime(emitMock);
+
+    describe('with a candidate list', () => {
+        beforeEach(() => {
+            startJourney(baseDef);
+        });
+
+        const subject = () => journeyStep(['missing', baseDef.name], 'do-work', step => step.name);
+
+        test('resolves the first open name', async () => {
+            await expect(subject()).resolves.toBe(baseDef.name);
+        });
+    });
+
+    describe('with multiple open candidates', () => {
+        beforeEach(() => {
+            startJourney(otherDef);
+            startJourney(baseDef);
+        });
+
+        const subject = () =>
+            journeyStep([baseDef.name, otherDef.name], 'do-work', step => step.name);
+
+        test('prefers the first name in order', async () => {
+            await expect(subject()).resolves.toBe(baseDef.name);
+        });
+    });
+
+    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;
+            });
+
+        test('runs untraced', async () => {
+            await expect(subject()).resolves.toBeNull();
+            expect(emitMock).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('with a null target', () => {
+        const subject = () =>
+            journeyStep(null, 'untraced', step => step.tag() as Record<string, unknown>);
+
+        test('returns an empty tag object', async () => {
+            await expect(subject()).resolves.toEqual({});
+        });
+    });
+
+    describe('with an open journey', () => {
+        beforeEach(() => {
+            startJourney(baseDef);
+        });
+
+        describe('when the step completes with tags', () => {
+            const subject = () =>
+                journeyStep(baseDef.name, 'do-work', step => {
+                    step.setAttribute('x', 1);
+                    step.complete({ 'payment.id': 42 });
+                });
+
+            test('emits good with tags and attributes', async () => {
+                await subject();
+
+                expect(lastJourney(emitMock).outcome).toBe('good');
+                expect(lastJourney(emitMock).tags['payment.id']).toBe(42);
+                expect(lastJourney(emitMock).steps[0].attributes).toEqual({ x: 1 });
+            });
+        });
+
+        describe('when setTags is called without completing', () => {
+            const subject = () =>
+                journeyStep(baseDef.name, 'load', step => {
+                    step.setTags({ 'customer.id': 9 });
+                    step.setTags({ 'location.id': 3 });
+                });
+
+            test('merges tags without closing', async () => {
+                await subject();
+
+                expect(emitMock).not.toHaveBeenCalled();
+                completeJourney(baseDef.name);
+                expect(lastJourney(emitMock).tags).toEqual({
+                    'customer.id': 9,
+                    'location.id': 3,
+                });
+            });
+        });
+
+        describe('when step.tag is called', () => {
+            let tagged: Record<string, unknown> | null;
+
+            beforeEach(() => {
+                tagged = null;
+            });
+
+            const subject = () =>
+                journeyStep(baseDef.name, 'do-work', step => {
+                    tagged = step.tag() as Record<string, unknown>;
+                });
+
+            test('binds journeyStep', async () => {
+                await subject();
+
+                expect(tagged).toHaveProperty('journeyStep');
+            });
+        });
+
+        describe('when step.fail is called', () => {
+            const subject = () =>
+                journeyStep(baseDef.name, 'do-work', step => {
+                    step.fail('empty-catalog');
+                });
+
+            test('marks bad without throwing', async () => {
+                await subject();
+
+                expect(lastJourney(emitMock).outcome).toBe('bad');
+                expect(lastJourney(emitMock).reason).toBe('empty-catalog');
+            });
+        });
+
+        describe('when the step function throws an Error', () => {
+            const subject = () =>
+                journeyStep(baseDef.name, 'do-work', () => {
+                    throw new Error('boom');
+                });
+
+            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' });
+            });
+        });
+
+        describe('when the step function throws a non-Error', () => {
+            const subject = () =>
+                journeyStep(baseDef.name, 'do-work', () => {
+                    // eslint-disable-next-line @typescript-eslint/only-throw-error -- intentional non-Error throw
+                    throw 'string-boom';
+                });
+
+            test('stringifies the error attribute', async () => {
+                await expect(subject()).rejects.toBe('string-boom');
+                expect(lastJourney(emitMock).steps[0].attributes).toEqual({
+                    error: 'string-boom',
+                });
+            });
+        });
+
+        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';
+                    throw new Error('boom');
+                });
+
+            test('preserves the first error attribute', async () => {
+                await expect(subject()).rejects.toThrow('boom');
+                expect(lastJourney(emitMock).steps[0].attributes).toEqual({ error: 'already' });
+            });
+        });
+
+        describe('with multiple steps', () => {
+            beforeEach(() => {
+                // Parent already opened baseDef; restart with expected steps.
+                emitMock.mockClear();
+                startJourney({ ...baseDef, steps: ['load', 'save'] });
+                emitMock.mockClear();
+            });
+
+            test('only the final complete closes once', async () => {
+                await journeyStep(baseDef.name, 'load', step => {
+                    step.setAttribute('phase', 'load');
+                });
+                expect(emitMock).not.toHaveBeenCalled();
+
+                await journeyStep(baseDef.name, 'save', step => {
+                    step.complete({ done: true });
+                });
+
+                expect(emitMock).toHaveBeenCalledTimes(1);
+                expect(lastJourney(emitMock).expected).toEqual(['load', 'save']);
+                expect(lastJourney(emitMock).steps.map((s: { name: string }) => s.name)).toEqual([
+                    'load',
+                    'save',
+                ]);
+            });
+        });
+
+        describe('with a JourneyDef-like object target', () => {
+            const subject = () =>
+                journeyStep(baseDef, 'via-def', step => {
+                    step.complete();
+                    return step.name;
+                });
+
+            test('resolves the def name', async () => {
+                await expect(subject()).resolves.toBe(baseDef.name);
+            });
+        });
+
+        describe('when completing without attributes', () => {
+            const subject = () =>
+                journeyStep(baseDef.name, 'load', () => {}).then(() =>
+                    completeJourney(baseDef.name)
+                );
+
+            test('omits empty step attributes from the event', async () => {
+                await subject();
+
+                expect(lastJourney(emitMock).steps[0].attributes).toBeUndefined();
+            });
+        });
+    });
+
+    describe('journeyMountStep', () => {
+        describe('with candidates', () => {
+            beforeEach(() => {
+                startJourney(baseDef);
+            });
+
+            const subject = () =>
+                journeyMountStep(['missing', baseDef.name], 'mount-load', step => {
+                    step.complete();
+                    return step.name;
+                });
+
+            test('resolves the open candidate', async () => {
+                await expect(subject()).resolves.toBe(baseDef.name);
+            });
+        });
+
+        describe('when started after scheduling', () => {
+            const order: string[] = [];
+
+            beforeEach(() => {
+                order.length = 0;
+            });
+
+            test('defers until after a sync startJourney', async () => {
+                const mount = journeyMountStep(baseDef.name, 'boot', () => {
+                    order.push('mount-step');
+                });
+                startJourney(baseDef);
+                order.push('started');
+                await mount;
+                completeJourney(baseDef.name);
+
+                expect(order).toEqual(['started', 'mount-step']);
+            });
+        });
+    });
+
+    describe('when fail-fast happens mid-step', () => {
+        beforeEach(() => {
+            jest.spyOn(globalThis.performance, 'now').mockReturnValue(1_000);
+            startJourney(baseDef);
+        });
+
+        afterEach(() => {
+            jest.restoreAllMocks();
+        });
+
+        test('finalizes in-flight step duration', async () => {
+            let resolveWork!: () => void;
+            const hang = new Promise<void>(resolve => {
+                resolveWork = resolve;
+            });
+
+            const stepPromise = journeyStep(baseDef.name, 'slow', async () => {
+                (globalThis.performance.now as jest.Mock).mockReturnValue(1_150);
+                failJourney(baseDef.name, 'aborted');
+                await hang;
+            });
+
+            await Promise.resolve();
+            expect(lastJourney(emitMock).steps[0].durationMs).toBe(150);
+
+            resolveWork();
+            await stepPromise;
+        });
+    });
+});

package/src/__tests__/timeouts.test.ts

@@ -0,0 +1,226 @@
+/** @jest-environment jsdom */
+import { baseJourneyDef, lastJourney, useJourneyTestRuntime } from '../__mocks__/test-runtime';
+import { completeJourney, journeyStep, resolveJourneyStep, startJourney } from '../core';
+
+const emitMock = jest.fn();
+const baseDef = { ...baseJourneyDef, name: 'timeout-api' };
+
+describe('[journey] timeouts', () => {
+    useJourneyTestRuntime(emitMock);
+
+    beforeEach(() => {
+        jest.useFakeTimers();
+    });
+
+    afterEach(() => {
+        jest.useRealTimers();
+    });
+
+    describe('with a journey timeoutMs', () => {
+        beforeEach(() => {
+            startJourney({ ...baseDef, timeoutMs: 50 });
+        });
+
+        const subject = () => jest.advanceTimersByTimeAsync(50);
+
+        test('closes bad with journey-timeout', async () => {
+            await subject();
+
+            expect(lastJourney(emitMock).outcome).toBe('bad');
+            expect(lastJourney(emitMock).reason).toBe('journey-timeout');
+        });
+    });
+
+    describe('with timeoutMs 0', () => {
+        beforeEach(() => {
+            startJourney({ ...baseDef, timeoutMs: 0 });
+        });
+
+        const subject = () => jest.advanceTimersByTimeAsync(60_000);
+
+        test('does not arm a countdown', async () => {
+            await subject();
+
+            expect(emitMock).not.toHaveBeenCalled();
+            completeJourney(baseDef.name);
+            expect(lastJourney(emitMock).outcome).toBe('good');
+        });
+    });
+
+    describe('with a step timeoutMs', () => {
+        let resolveWork!: () => void;
+        let stepPromise: Promise<unknown>;
+
+        beforeEach(() => {
+            startJourney({ ...baseDef, stepTimeoutMs: 40 });
+            const hang = new Promise<void>(resolve => {
+                resolveWork = resolve;
+            });
+            stepPromise = journeyStep(baseDef.name, 'slow', async () => {
+                await hang;
+            });
+        });
+
+        afterEach(async () => {
+            resolveWork();
+            await stepPromise;
+        });
+
+        const subject = () => jest.advanceTimersByTimeAsync(40);
+
+        test('closes bad with step-timeout', async () => {
+            await subject();
+
+            expect(lastJourney(emitMock).reason).toBe('step-timeout');
+            expect(lastJourney(emitMock).steps[0].attributes.timeout_ms).toBe(40);
+        });
+    });
+
+    describe('with per-call step timeoutMs', () => {
+        let resolveWork!: () => void;
+        let stepPromise: Promise<unknown>;
+
+        beforeEach(() => {
+            startJourney({ ...baseDef, stepTimeoutMs: 5_000 });
+            const hang = new Promise<void>(resolve => {
+                resolveWork = resolve;
+            });
+            stepPromise = journeyStep(
+                baseDef.name,
+                'slow',
+                async () => {
+                    await hang;
+                },
+                { timeoutMs: 25 }
+            );
+        });
+
+        afterEach(async () => {
+            resolveWork();
+            await stepPromise;
+        });
+
+        const subject = () => jest.advanceTimersByTimeAsync(25);
+
+        test('overrides the journey default', async () => {
+            await subject();
+
+            expect(lastJourney(emitMock).steps[0].attributes.timeout_ms).toBe(25);
+        });
+    });
+
+    describe('when the journey closes before the step timeout', () => {
+        let resolveWork!: () => void;
+        let stepPromise: Promise<unknown>;
+
+        beforeEach(() => {
+            startJourney({ ...baseDef, stepTimeoutMs: 40 });
+            const hang = new Promise<void>(resolve => {
+                resolveWork = resolve;
+            });
+            stepPromise = journeyStep(baseDef.name, 'slow', async () => {
+                await hang;
+            });
+            completeJourney(baseDef.name);
+            emitMock.mockClear();
+        });
+
+        afterEach(async () => {
+            resolveWork();
+            await stepPromise;
+        });
+
+        const subject = () => jest.advanceTimersByTimeAsync(40);
+
+        test('the step timeout is a no-op', async () => {
+            await subject();
+
+            expect(emitMock).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('when step reason is pre-set before timeout', () => {
+        let resolveWork!: () => void;
+        let stepPromise: Promise<unknown>;
+
+        beforeEach(() => {
+            startJourney({ ...baseDef, stepTimeoutMs: 40 });
+            const hang = new Promise<void>(resolve => {
+                resolveWork = resolve;
+            });
+            stepPromise = journeyStep(baseDef.name, 'slow', async step => {
+                const ref = resolveJourneyStep(
+                    (step.tag() as { journeyStep: unknown }).journeyStep
+                )!;
+                ref.reason = 'pre-existing';
+                ref.attributes.timeout_ms = 999;
+                await hang;
+            });
+        });
+
+        afterEach(async () => {
+            resolveWork();
+            await stepPromise;
+        });
+
+        const subject = () => jest.advanceTimersByTimeAsync(40);
+
+        test('preserves the first step reason', async () => {
+            await subject();
+
+            expect(lastJourney(emitMock).steps[0].reason).toBe('pre-existing');
+            expect(lastJourney(emitMock).steps[0].attributes?.timeout_ms).toBe(999);
+        });
+    });
+
+    describe('when clearTimeout is bypassed after complete', () => {
+        beforeEach(() => {
+            jest.spyOn(globalThis, 'clearTimeout').mockImplementation(() => {});
+            startJourney({ ...baseDef, timeoutMs: 50 });
+            completeJourney(baseDef.name);
+            emitMock.mockClear();
+        });
+
+        afterEach(() => {
+            jest.mocked(globalThis.clearTimeout).mockRestore();
+        });
+
+        const subject = () => jest.advanceTimersByTimeAsync(50);
+
+        test('the late timer does not emit', async () => {
+            await subject();
+
+            expect(emitMock).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('with stepTimeoutMs 0', () => {
+        let resolveWork!: () => void;
+        let stepPromise: Promise<unknown>;
+
+        beforeEach(() => {
+            startJourney({ ...baseDef, stepTimeoutMs: 0 });
+            const hang = new Promise<void>(resolve => {
+                resolveWork = resolve;
+            });
+            stepPromise = journeyStep(baseDef.name, 'slow', async () => {
+                await hang;
+            });
+        });
+
+        afterEach(async () => {
+            resolveWork();
+            await stepPromise;
+        });
+
+        const subject = () => jest.advanceTimersByTimeAsync(60_000);
+
+        test('does not arm a step countdown', async () => {
+            await subject();
+
+            expect(emitMock).not.toHaveBeenCalled();
+            completeJourney(baseDef.name);
+            expect(lastJourney(emitMock).outcome).toBe('good');
+        });
+    });
+});

package/src/config.ts

@@ -0,0 +1,87 @@
+import { defaultRuntime } from './core/runtime';
+import { setJourneySinks, type JourneySink } from './core/registry';
+import {
+    sortEndpointsByLongestMatch,
+    type AppRequestTimeouts,
+    type EndpointPolicy,
+} from './endpoint-policy';
+import { instrumentAxios, type AxiosLikeInstance } from './integrations/axios';
+import { instrumentFetch, type InstrumentFetchOptions } from './integrations/fetch';
+import {
+    exposeAppJourney,
+    instrumentJquery,
+    type JqueryStatic,
+    type WindowWithAppJourney,
+} from './integrations/jquery';
+import { sendToDatadog } from './sinks/datadog';
+
+export { longestEndpointMatch, sortEndpointsByLongestMatch } from './endpoint-policy';
+export type { AppRequestTimeouts, EndpointPolicy };
+
+/** Optional app-wide / per-bundle configuration. */
+export interface JourneyConfig {
+    /** App-wide request-timeout fallback. Defaults to { defaultMs: 4000, endpoints: [] }. */
+    requestTimeouts?: AppRequestTimeouts;
+    /**
+     * Replace the sink list used when a journey finishes.
+     * Only applied when provided — omit to leave the current list unchanged.
+     * Package default is `[sendToDatadog]`; pass `[]` to disable emission.
+     */
+    sinks?: readonly JourneySink[];
+    /**
+     * Wire this bundle's axios instance (host or MFE). Same as `instrumentAxios(axios)`.
+     * Register any async request interceptors (e.g. auth) before `configureJourney`.
+     */
+    axios?: AxiosLikeInstance;
+    /**
+     * Wire fetch. `true` wraps `globalThis.fetch`; pass options for a scoped target / baseURL.
+     * Same as `instrumentFetch(...)`.
+     */
+    fetch?: true | InstrumentFetchOptions;
+    /** Wire this bundle's jQuery static. Same as `instrumentJquery($)`. */
+    jquery?: JqueryStatic;
+    /**
+     * Publish `window.App.Journey` for Knockout / legacy hosts.
+     * `true` uses the real window; pass a target object in tests.
+     */
+    exposeAppJourney?: boolean | WindowWithAppJourney;
+}
+
+/*
+ * Default emission target. Kept as a module side effect so any import of this file
+ * (see index.ts `import './config'`) installs Datadog. configureJourney only replaces
+ * sinks when `sinks` is passed explicitly.
+ */
+setJourneySinks([sendToDatadog]);
+
+/**
+ * Apply bundle options: request thresholds, sinks, and/or HTTP / legacy wiring.
+ * Optional — call once at startup. Pass this bundle's own axios / `$` / fetch target.
+ */
+export function configureJourney(config: JourneyConfig): void {
+    if (config.requestTimeouts !== undefined) {
+        defaultRuntime.setRequestTimeouts({
+            ...config.requestTimeouts,
+            endpoints: sortEndpointsByLongestMatch(config.requestTimeouts.endpoints),
+        });
+    }
+    if (config.sinks !== undefined) {
+        setJourneySinks(config.sinks);
+    }
+    if (config.axios !== undefined) {
+        instrumentAxios(config.axios);
+    }
+    if (config.fetch !== undefined) {
+        instrumentFetch(config.fetch === true ? {} : config.fetch);
+    }
+    if (config.jquery !== undefined) {
+        instrumentJquery(config.jquery);
+    }
+    if (config.exposeAppJourney) {
+        exposeAppJourney(config.exposeAppJourney === true ? undefined : config.exposeAppJourney);
+    }
+}
+
+export function getRequestTimeouts(): AppRequestTimeouts {
+    return defaultRuntime.getRequestTimeouts();
+}

package/src/core/index.ts

@@ -0,0 +1,39 @@
+/** Core engine barrel — free helpers over the default runtime, plus handles and types. */
+
+export {
+    activeJourneyStep,
+    addJourneySink,
+    completeJourney,
+    defineJourney,
+    emitJourneyEvent,
+    excludeJourney,
+    failJourney,
+    firstOpenJourney,
+    journeyMountStep,
+    journeyStep,
+    reportBackendRequest,
+    setJourneySinks,
+    setJourneyTags,
+    startJourney,
+    type JourneyHandle,
+    type JourneySink,
+} from './registry';
+export {
+    createJourneyRuntime,
+    defaultRuntime,
+    resetJourney,
+    type JourneyRuntime,
+    type JourneyRuntimeOptions,
+} from './runtime';
+export type {
+    JourneyDef,
+    JourneyEvent,
+    JourneyNameLike,
+    JourneyStepEvent,
+    JourneyStepOptions,
+    JourneyStepRef,
+    JourneyStepTarget,
+    StepHandle,
+    TagValue,
+} from './types';
+export { JourneyStepTag, resolveJourneyStep } from './step-tag';