@servicetitan/journey 1.0.0

package/src/__tests__/context.test.tsx

@@ -0,0 +1,84 @@
+/** @jest-environment jsdom */
+import { render, screen } from '@testing-library/react';
+
+import {
+    JourneyNameContext,
+    useJourneyName,
+    useOptionalJourneyName,
+} from '../integrations/react/context';
+
+function OptionalProbe() {
+    const name = useOptionalJourneyName();
+    return <span data-testid="optional">{name ?? 'null'}</span>;
+}
+
+function RequiredProbe() {
+    const name = useJourneyName();
+    return <span data-testid="required">{name}</span>;
+}
+
+describe('[journey] context hooks', () => {
+    describe('useOptionalJourneyName', () => {
+        describe('without a provider', () => {
+            const subject = () => render(<OptionalProbe />);
+
+            test('returns null', () => {
+                subject();
+
+                expect(screen.getByTestId('optional').textContent).toBe('null');
+            });
+        });
+
+        describe('with a provider', () => {
+            const subject = () =>
+                render(
+                    <JourneyNameContext.Provider value="scoped">
+                        <OptionalProbe />
+                    </JourneyNameContext.Provider>
+                );
+
+            test('reads the provided name', () => {
+                subject();
+
+                expect(screen.getByTestId('optional').textContent).toBe('scoped');
+            });
+        });
+    });
+
+    describe('useJourneyName', () => {
+        describe('with a provider', () => {
+            const subject = () =>
+                render(
+                    <JourneyNameContext.Provider value="scoped">
+                        <RequiredProbe />
+                    </JourneyNameContext.Provider>
+                );
+
+            test('returns the provided name', () => {
+                subject();
+
+                expect(screen.getByTestId('required').textContent).toBe('scoped');
+            });
+        });
+
+        describe('without a provider', () => {
+            let spy: jest.SpyInstance;
+
+            beforeEach(() => {
+                spy = jest.spyOn(console, 'error').mockImplementation(() => {});
+            });
+
+            afterEach(() => {
+                spy.mockRestore();
+            });
+
+            const subject = () => render(<RequiredProbe />);
+
+            test('throws', () => {
+                expect(() => subject()).toThrow(
+                    'useJourneyName must be used within a <JourneyScope>'
+                );
+            });
+        });
+    });
+});

package/src/__tests__/datadog.test.ts

@@ -0,0 +1,160 @@
+/** @jest-environment jsdom */
+const addAction = jest.fn();
+const importedAddAction = jest.fn();
+
+jest.mock('@datadog/browser-rum', () => ({
+    datadogRum: {
+        addAction: (...args: unknown[]) => importedAddAction(...args),
+    },
+}));
+
+import type { JourneyEvent } from '../core/types';
+import { sendToDatadog, setJourneyRum } from '../sinks/datadog';
+
+const RUM_GLOBAL_KEY = '__stJourneyRum';
+
+function sampleEvent(overrides: Partial<JourneyEvent['journey']> = {}): JourneyEvent {
+    return {
+        journey: {
+            name: 'Call Screen Book!',
+            team: 'JBCE',
+            group: 'call-booking',
+            service: 'call-screen',
+            outcome: 'good',
+            durationMs: 120,
+            steps: [],
+            ...overrides,
+        },
+    };
+}
+
+describe('[journey] setJourneyRum / sendToDatadog', () => {
+    beforeEach(() => {
+        addAction.mockClear();
+        importedAddAction.mockClear();
+        delete (globalThis as Record<string, unknown>)[RUM_GLOBAL_KEY];
+    });
+
+    describe('without a shared RUM instance', () => {
+        const subject = () => sendToDatadog(sampleEvent());
+
+        test('falls back to the imported datadogRum', () => {
+            subject();
+
+            expect(importedAddAction).toHaveBeenCalledTimes(1);
+            expect(importedAddAction.mock.calls[0][0]).toBe('user_journey');
+            expect(addAction).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('with setJourneyRum', () => {
+        beforeEach(() => {
+            setJourneyRum({ addAction });
+        });
+
+        const subject = () =>
+            sendToDatadog(sampleEvent({ reason: 'request-error', outcome: 'bad' }));
+
+        test('uses the shared RUM instance', () => {
+            subject();
+
+            expect(addAction).toHaveBeenCalledTimes(1);
+            expect(importedAddAction).not.toHaveBeenCalled();
+        });
+
+        test('normalizes identity fields', () => {
+            subject();
+
+            const ctx = addAction.mock.calls[0][1];
+            expect(ctx.journey.name).toBe('call_screen_book');
+            expect(ctx.journey.team).toBe('jbce');
+        });
+    });
+
+    test('normalizes string tags and passes numbers/booleans through', () => {
+        setJourneyRum({ addAction });
+        sendToDatadog(
+            sampleEvent({
+                tags: {
+                    'plan': 'Pro Plan!!',
+                    'job.id': 42,
+                    'inbound': true,
+                },
+                expected: ['book-job'],
+            })
+        );
+
+        const ctx = addAction.mock.calls[0][1];
+        expect(ctx.journey.tags).toEqual({
+            'plan': 'pro_plan',
+            'job.id': 42,
+            'inbound': true,
+        });
+        expect(ctx.journey.expected).toEqual(['book-job']);
+    });
+
+    test('omits reason and tags when absent', () => {
+        setJourneyRum({ addAction });
+        sendToDatadog(sampleEvent());
+
+        const ctx = addAction.mock.calls[0][1];
+        expect(ctx.journey.reason).toBeUndefined();
+        expect(ctx.journey.tags).toBeUndefined();
+        expect(ctx.journey.expected).toBeUndefined();
+    });
+
+    test('collapses runs of underscores and drops trailing ones', () => {
+        setJourneyRum({ addAction });
+        sendToDatadog(sampleEvent({ name: 'Foo@@@Bar___' }));
+
+        expect(addAction.mock.calls[0][1].journey.name).toBe('foo_bar');
+    });
+
+    test('truncates long string tag values to 200 characters', () => {
+        setJourneyRum({ addAction });
+        const long = `A${'b'.repeat(250)}`;
+        sendToDatadog(sampleEvent({ tags: { note: long } }));
+
+        const note = addAction.mock.calls[0][1].journey.tags.note as string;
+        expect(note.length).toBeLessThanOrEqual(200);
+        expect(note.endsWith('_')).toBe(false);
+    });
+
+    test('normalizes the failure reason string', () => {
+        setJourneyRum({ addAction });
+        sendToDatadog(sampleEvent({ outcome: 'bad', reason: 'Step Error!!' }));
+
+        expect(addAction.mock.calls[0][1].journey.reason).toBe('step_error');
+    });
+
+    test('maps camelCase fields to Datadog snake_case wire keys', () => {
+        setJourneyRum({ addAction });
+        sendToDatadog(
+            sampleEvent({
+                steps: [
+                    {
+                        name: 'load',
+                        startMs: 0,
+                        durationMs: 12,
+                        outcome: 'good',
+                        httpStatus: 502,
+                    },
+                ],
+            })
+        );
+
+        const ctx = addAction.mock.calls[0][1];
+        expect(ctx.journey.duration_ms).toBe(120);
+        /* eslint-disable @typescript-eslint/naming-convention -- assert Datadog RUM wire format */
+        expect(ctx.journey.steps).toEqual([
+            {
+                name: 'load',
+                start_ms: 0,
+                duration_ms: 12,
+                outcome: 'good',
+                http_status: 502,
+            },
+        ]);
+        /* eslint-enable @typescript-eslint/naming-convention */
+    });
+});

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

@@ -0,0 +1,176 @@
+/** @jest-environment jsdom */
+import { lastJourney, useJourneyTestRuntime } from '../__mocks__/test-runtime';
+import { defineJourney, journeyStep, startJourney } from '../core';
+
+const emitMock = jest.fn();
+
+const base = {
+    name: 'handle-api',
+    team: 'platform',
+    group: 'test',
+    service: 'journey',
+    timeoutMs: 0,
+};
+
+describe('[journey] defineJourney', () => {
+    let journey = defineJourney(base);
+
+    useJourneyTestRuntime(emitMock);
+
+    beforeEach(() => {
+        journey = defineJourney(base);
+    });
+
+    describe('when no journey is open', () => {
+        const subject = () =>
+            journey.step('do-work', step => {
+                step.setAttribute('x', 1);
+                step.complete({ 'payment.id': 42 });
+            });
+
+        test('opens, records the step, and completes good', async () => {
+            await subject();
+
+            expect(emitMock).toHaveBeenCalledTimes(1);
+            const event = lastJourney(emitMock);
+            expect(event.outcome).toBe('good');
+            expect(event.tags?.['payment.id']).toBe(42);
+            expect(event.steps[0].attributes).toEqual({ x: 1 });
+        });
+
+        test('mountStep also opens the journey', async () => {
+            await journey.mountStep('boot', step => {
+                step.complete();
+            });
+
+            expect(emitMock).toHaveBeenCalledTimes(1);
+            expect(lastJourney(emitMock).outcome).toBe('good');
+            expect(lastJourney(emitMock).steps[0].name).toBe('boot');
+        });
+    });
+
+    describe('when a JourneyScope already opened the journey', () => {
+        beforeEach(() => {
+            startJourney(base);
+        });
+
+        const subject = () =>
+            journey.step('do-work', step => {
+                step.complete();
+            });
+
+        test('does not restart the open journey', async () => {
+            await subject();
+
+            expect(emitMock).toHaveBeenCalledTimes(1);
+            expect(lastJourney(emitMock).outcome).toBe('good');
+            expect(lastJourney(emitMock).steps).toHaveLength(1);
+        });
+    });
+
+    describe('when stepping via free journeyStep with a handle', () => {
+        beforeEach(() => {
+            journey.start();
+        });
+
+        const subject = () =>
+            journeyStep(journey, 'via-free', step => {
+                step.complete();
+            });
+
+        test('resolves the handle name', async () => {
+            await subject();
+
+            expect(lastJourney(emitMock).steps[0].name).toBe('via-free');
+        });
+    });
+
+    describe('when using bound lifecycle helpers', () => {
+        test('fail marks bad', () => {
+            journey.start();
+            journey.fail('no-inventory');
+
+            expect(lastJourney(emitMock).outcome).toBe('bad');
+            expect(lastJourney(emitMock).reason).toBe('no-inventory');
+        });
+
+        test('exclude marks excluded', () => {
+            journey.start();
+            journey.exclude();
+
+            expect(lastJourney(emitMock).outcome).toBe('excluded');
+        });
+
+        test('setTags merges onto the open journey', () => {
+            journey.start();
+            journey.setTags({ plan: 'pro' });
+            journey.complete();
+
+            expect(lastJourney(emitMock).tags?.plan).toBe('pro');
+        });
+
+        test('start with tags applies them', () => {
+            journey.start({ cohort: 'a' });
+            journey.complete();
+
+            expect(lastJourney(emitMock).tags?.cohort).toBe('a');
+        });
+
+        test('complete with tags applies them', () => {
+            journey.start();
+            journey.complete({ done: true });
+
+            expect(lastJourney(emitMock).tags?.done).toBe(true);
+        });
+
+        test('start restarts an already-open journey', () => {
+            journey.start();
+            journey.start();
+
+            expect(emitMock).toHaveBeenCalledTimes(1);
+            expect(lastJourney(emitMock).outcome).toBe('excluded');
+
+            journey.complete();
+            expect(lastJourney(emitMock).outcome).toBe('good');
+        });
+
+        test('complete after fail does not flip the outcome', () => {
+            journey.start();
+            journey.fail('validation');
+            journey.complete({ ignored: true });
+
+            expect(emitMock).toHaveBeenCalledTimes(1);
+            expect(lastJourney(emitMock).outcome).toBe('bad');
+            expect(lastJourney(emitMock).reason).toBe('validation');
+        });
+    });
+
+    describe('when mountStep runs under an already-open journey', () => {
+        beforeEach(() => {
+            startJourney(base);
+        });
+
+        const subject = () =>
+            journey.mountStep('boot', step => {
+                step.complete();
+            });
+
+        test('does not restart the open journey', async () => {
+            await subject();
+
+            expect(emitMock).toHaveBeenCalledTimes(1);
+            expect(lastJourney(emitMock).outcome).toBe('good');
+            expect(lastJourney(emitMock).steps).toHaveLength(1);
+            expect(lastJourney(emitMock).steps[0].name).toBe('boot');
+        });
+    });
+
+    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);
+        });
+    });
+});

package/src/__tests__/expose-app-journey.test.ts

@@ -0,0 +1,149 @@
+/** @jest-environment jsdom */
+import { useJourneyTestRuntime } from '../__mocks__/test-runtime';
+import { exposeAppJourney, type WindowWithAppJourney } from '../integrations/jquery';
+
+const emitMock = jest.fn();
+
+function createTarget(existingApp?: Record<string, unknown>) {
+    return {
+        App: existingApp ? { ...existingApp } : undefined,
+    } as any;
+}
+
+describe('[journey] exposeAppJourney', () => {
+    useJourneyTestRuntime(emitMock);
+
+    test('creates window.App when missing and assigns Journey', () => {
+        const target = createTarget();
+
+        const api = exposeAppJourney(target);
+
+        expect(target.App).toBeDefined();
+        expect(target.App.Journey).toBe(api);
+        expect(typeof api.defineJourney).toBe('function');
+        expect(typeof api.journeyStep).toBe('function');
+        expect(typeof api.firstOpenJourney).toBe('function');
+    });
+
+    test('preserves existing window.App properties', () => {
+        const target = createTarget({ CallBoard: { Instance: {} } });
+
+        exposeAppJourney(target);
+
+        expect(target.App.CallBoard).toEqual({ Instance: {} });
+        expect(target.App.Journey).toBeDefined();
+    });
+
+    describe('with defineJourney', () => {
+        let j: ReturnType<typeof exposeAppJourney>;
+        let bookJob: ReturnType<typeof j.defineJourney>;
+
+        beforeEach(() => {
+            j = exposeAppJourney(createTarget());
+            bookJob = j.defineJourney({
+                name: 'ko-bridge-good',
+                team: 'test',
+                group: 'test',
+                service: 'test',
+                timeoutMs: 0,
+            });
+        });
+
+        test('emits a good outcome via handle lifecycle', async () => {
+            bookJob.start();
+            await bookJob.step('book-job', step => {
+                step.setAttribute('call.id', 42);
+                return 'ok';
+            });
+            bookJob.complete();
+
+            expect(emitMock).toHaveBeenCalledTimes(1);
+            const event = emitMock.mock.calls[0][0].journey;
+            expect(event.name).toBe('ko-bridge-good');
+            expect(event.outcome).toBe('good');
+            expect(event.steps).toHaveLength(1);
+            expect(event.steps[0].attributes).toEqual({ 'call.id': 42 });
+        });
+
+        test('emits a bad outcome via handle.fail', () => {
+            bookJob = j.defineJourney({
+                name: 'ko-bridge-fail',
+                team: 'test',
+                group: 'test',
+                service: 'test',
+                timeoutMs: 0,
+            });
+            bookJob.start();
+            bookJob.fail('book-rejected');
+
+            expect(emitMock).toHaveBeenCalledTimes(1);
+            const event = emitMock.mock.calls[0][0].journey;
+            expect(event.outcome).toBe('bad');
+            expect(event.reason).toBe('book-rejected');
+        });
+
+        test('emits excluded via handle.exclude', () => {
+            bookJob = j.defineJourney({
+                name: 'ko-bridge-exclude',
+                team: 'test',
+                group: 'test',
+                service: 'test',
+                timeoutMs: 0,
+            });
+            bookJob.start();
+            bookJob.exclude();
+
+            expect(emitMock).toHaveBeenCalledTimes(1);
+            expect(emitMock.mock.calls[0][0].journey.outcome).toBe('excluded');
+        });
+
+        test('applies setTags before complete', async () => {
+            bookJob = j.defineJourney({
+                name: 'ko-bridge-tags',
+                team: 'test',
+                group: 'test',
+                service: 'test',
+                timeoutMs: 0,
+                steps: ['load'],
+            });
+            bookJob.start();
+            expect(j.firstOpenJourney(['missing', 'ko-bridge-tags'])).toBe('ko-bridge-tags');
+
+            await bookJob.step('load', step => {
+                step.setAttribute('phase', 'load');
+            });
+            bookJob.setTags({ 'job.id': 9 });
+            bookJob.complete();
+
+            expect(emitMock).toHaveBeenCalledTimes(1);
+            const event = emitMock.mock.calls[0][0].journey;
+            expect(event.tags).toEqual({ 'job.id': 9 });
+            expect(event.steps[0].attributes).toEqual({ phase: 'load' });
+        });
+    });
+
+    test('journeyStep supports candidate lists without a handle', async () => {
+        const j = exposeAppJourney(createTarget());
+        const primary = j.defineJourney({
+            name: 'ko-candidates-a',
+            team: 'test',
+            group: 'test',
+            service: 'test',
+            timeoutMs: 0,
+        });
+        primary.start();
+
+        await j.journeyStep(['missing', 'ko-candidates-a'], 'shared-step', () => 'ok');
+        primary.complete();
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.steps[0].name).toBe('shared-step');
+    });
+
+    test('is idempotent when called repeatedly on window', () => {
+        const first = exposeAppJourney(window as WindowWithAppJourney);
+        const second = exposeAppJourney(window as WindowWithAppJourney);
+        expect(second).toBe(first);
+        expect((window as WindowWithAppJourney).App?.Journey).toBe(first);
+    });
+});