@servicetitan/journey 1.0.0

package/src/core/types.ts

@@ -0,0 +1,160 @@
+import type { EndpointPolicy } from '../endpoint-policy';
+
+/** Arbitrary tag values a developer can attach. */
+export type TagValue = string | number | boolean;
+
+/** Config for one journey — supplied by the caller (typically `<JourneyScope>` props). */
+export interface JourneyDef {
+    /** Journey name — lifecycle key, event field, and concurrency map key. */
+    name: string;
+    /** Owner team (required tag). */
+    team: string;
+    /** Functional area, e.g. "sales" (required tag). */
+    group: string;
+    /** Business component label, e.g. "checkout" — not the Datadog RUM service. */
+    service: string;
+    /** Whole-journey budget in ms; omit / 0 to disable. */
+    timeoutMs?: number;
+    /** Default per-step timeout in ms; per-call option overrides. Omit / 0 to disable. */
+    stepTimeoutMs?: number;
+    /** Slow-request threshold for this journey; falls back to app-wide default. */
+    requestTimeoutMs?: number;
+    /** Per-endpoint overrides for this journey (longest prefix wins over app-wide). */
+    endpoints?: readonly EndpointPolicy[];
+    /** Optional expected step names (rides as `expected` on the event). */
+    steps?: readonly string[];
+    /** Custom tags on every event of this journey. */
+    tags?: Record<string, TagValue>;
+}
+
+export type Outcome = 'good' | 'bad' | 'excluded';
+
+/** Handle passed to each step function. */
+export interface StepHandle {
+    /** Resolved journey name for this step, or null if untraced. */
+    readonly name: string | null;
+    setAttribute(key: string, value: string | number | boolean): void;
+    /** Journey-level tags without closing. */
+    setTags(tags: Record<string, TagValue>): void;
+    /** Apply optional tags then completeJourney. No-op if name is null. */
+    complete(tags?: Record<string, TagValue>): void;
+    /** Soft business Bad without throw. No-op if name is null. */
+    fail(reason: string): void;
+    /**
+     * Bind this step to a request explicitly (spread into axios config / fetch init /
+     * jQuery ajax settings). Needed when requests fire after an await or while steps
+     * overlap — see docs soft ambient. Untraced (noop) steps omit `journeyStep`.
+     *
+     * The value is a non-plain {@link JourneyStepTag} so jQuery/axios deep-merge will
+     * not recurse into the circular StepRecord graph.
+     */
+    tag(): { journeyStep?: unknown };
+}
+
+/** A journey name, or anything with a `name` (e.g. a JourneyHandle / JourneyDef). */
+export type JourneyNameLike = string | { readonly name: string };
+
+/** First argument to journeyStep / journeyMountStep. */
+export type JourneyStepTarget = JourneyNameLike | null | readonly JourneyNameLike[];
+
+/** Per-call options for journeyStep. */
+export interface JourneyStepOptions {
+    /** Timeout for this step in ms; overrides journey stepTimeoutMs. Omit / 0 to disable. */
+    timeoutMs?: number;
+}
+
+export interface JourneyState {
+    name: string;
+    team: string;
+    group: string;
+    service: string;
+    verdict: Outcome;
+    startedAt: number;
+    timeoutMs: number;
+    stepTimeoutMs?: number;
+    /**
+     * Why the journey closed as bad, else null.
+     * Engine: request-error | request-latency | journey-timeout | step-timeout | step-error.
+     * Also any custom business reason (e.g. call-not-associated).
+     */
+    reason: string | null;
+    steps: StepRecord[];
+    expected: string[] | null;
+    tags: Record<string, TagValue>;
+    requestTimeoutMs?: number;
+    endpoints?: readonly EndpointPolicy[];
+    timer: ReturnType<typeof setTimeout> | null;
+    closed: boolean;
+}
+
+export interface StepRecord {
+    name: string;
+    startedAt: number;
+    durationMs: number;
+    outcome: 'good' | 'bad';
+    reason?: string;
+    httpStatus?: number;
+    attributes: Record<string, string | number | boolean>;
+    journey: JourneyState;
+}
+
+/** Opaque handle to a step, captured at request initiation for response attribution. */
+export type JourneyStepRef = StepRecord;
+
+export interface JourneyStepEvent {
+    name: string;
+    /** Offset from the journey start, ms. */
+    startMs: number;
+    durationMs: number;
+    outcome: 'good' | 'bad';
+    reason?: string;
+    httpStatus?: number;
+    attributes?: Record<string, TagValue>;
+}
+
+/** Neutral journey event payload (journey-specific fields only; session context is host RUM globals). */
+export interface JourneyEvent {
+    journey: {
+        name: string;
+        team: string;
+        group: string;
+        service: string;
+        outcome: Outcome;
+        reason?: string;
+        durationMs: number;
+        steps: JourneyStepEvent[];
+        expected?: string[];
+        tags?: Record<string, TagValue>;
+    };
+}
+
+/** Destination for a terminal journey event. */
+export type JourneySink = (event: JourneyEvent) => void;
+
+/** Callable journey — config plus lifecycle helpers bound to `name`. Prefer this over free helpers. */
+export interface JourneyHandle extends JourneyDef {
+    /** Open this journey (restarts if already open). */
+    start(tags?: Record<string, TagValue>): void;
+    /**
+     * Record a step. Opens the journey first when it isn't already open
+     * (one-shot store actions); no-op start when a `<JourneyScope>` already opened it.
+     */
+    step<T>(
+        stepName: string,
+        fn: (step: StepHandle) => T | Promise<T>,
+        opts?: JourneyStepOptions
+    ): Promise<T>;
+    /**
+     * Like `step`, deferred one microtask for mount-effect use under `<JourneyScope>`
+     * (React runs child effects before parent). Also auto-starts if not already open.
+     */
+    mountStep<T>(
+        stepName: string,
+        fn: (step: StepHandle) => T | Promise<T>,
+        opts?: JourneyStepOptions
+    ): Promise<T>;
+    complete(tags?: Record<string, TagValue>): void;
+    fail(reason: string): void;
+    exclude(): void;
+    setTags(tags: Record<string, TagValue>): void;
+}

package/src/endpoint-policy.ts

@@ -0,0 +1,66 @@
+/** Per-endpoint request policy (app-wide or per-journey). Longest matching prefix wins. */
+export interface EndpointPolicy {
+    /**
+     * Path/host prefix against the request key (`"/path"` same-origin, `"host/path"` cross-domain).
+     * Match requires an exact hit or a `/` boundary after the prefix — `/api/user` matches
+     * `/api/user` and `/api/user/42`, but not `/api/user-preferences`. A trailing `/` on
+     * `match` already supplies the boundary.
+     */
+    match: string;
+    /** Custom slow-request threshold in ms; omit / 0 falls through. */
+    timeoutMs?: number;
+    /** When true, errors and slow responses never mark the journey Bad. */
+    ignore?: boolean;
+}
+
+/** App-wide slow-request threshold fallback (not an axios abort). */
+export interface AppRequestTimeouts {
+    /** Fallback threshold when no endpoint or journey override applies. */
+    defaultMs: number;
+    /** App-wide endpoint overrides; journey-specific ones belong on JourneyDef.endpoints. */
+    endpoints?: readonly EndpointPolicy[];
+}
+
+/** Copy sorted longest-match-first so lookup can return on the first hit. */
+export function sortEndpointsByLongestMatch(
+    endpoints: readonly EndpointPolicy[] | undefined
+): EndpointPolicy[] | undefined {
+    if (endpoints == null) {
+        return undefined;
+    }
+    if (endpoints.length <= 1) {
+        return endpoints.length === 0 ? [] : [...endpoints];
+    }
+    return [...endpoints].sort((a, b) => b.match.length - a.match.length);
+}
+
+/**
+ * True when `key` equals `match` or continues past a path boundary.
+ * `/api/user` matches `/api/user` and `/api/user/42`, not `/api/user-preferences`.
+ */
+function matchesEndpoint(key: string, match: string): boolean {
+    if (!key.startsWith(match)) {
+        return false;
+    }
+    if (match.endsWith('/')) {
+        return true;
+    }
+    const next = key[match.length];
+    return next === undefined || next === '/';
+}
+
+/**
+ * Longest-prefix match of an endpoint list against a request key.
+ * Expects `endpoints` sorted longest-match-first (see `sortEndpointsByLongestMatch`).
+ */
+export function longestEndpointMatch(
+    endpoints: readonly EndpointPolicy[] | undefined,
+    key: string
+): EndpointPolicy | undefined {
+    for (const e of endpoints ?? []) {
+        if (matchesEndpoint(key, e.match)) {
+            return e;
+        }
+    }
+    return undefined;
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+/*
+ * Force-evaluate config so the default Datadog sink registers even when consumers only
+ * import core APIs (defineJourney, etc.). Paired with package.json "sideEffects" for
+ * config — otherwise bundlers with sideEffects:false would drop an unused re-export.
+ */
+import './config';
+
+export {
+    // Custom transport adapters only.
+    activeJourneyStep,
+    // Prefer defineJourney(...).complete/fail/… — free helpers for name-from-context call sites.
+    completeJourney,
+    defineJourney,
+    excludeJourney,
+    failJourney,
+    journeyStep,
+    reportBackendRequest,
+    resolveJourneyStep,
+    setJourneyTags,
+    JourneyStepTag,
+    type JourneyDef,
+    type JourneyHandle,
+    type JourneyNameLike,
+    type JourneyStepOptions,
+    type JourneyStepRef,
+    type JourneyStepTarget,
+    type StepHandle,
+} from './core';
+
+export {
+    configureJourney,
+    type AppRequestTimeouts,
+    type EndpointPolicy,
+    type JourneyConfig,
+} from './config';
+
+export type { JourneySink } from './core';
+
+/** Test helper — clears open journeys / ambient steps on the default engine. */
+export { resetJourney } from './core';
+
+export { instrumentAxios } from './integrations/axios';
+export { instrumentFetch } from './integrations/fetch';
+export { exposeAppJourney, instrumentJquery } from './integrations/jquery';
+export { requestKey, type JourneyTimedMeta } from './integrations/request-key';
+export { sendToDatadog, setJourneyRum } from './sinks/datadog';
+
+export type { JourneyEvent, JourneyStepEvent, TagValue } from './core';
+
+export { useJourneyName, useOptionalJourneyName } from './integrations/react/context';
+export { JourneyScope } from './integrations/react/scope';

package/src/integrations/axios.ts

@@ -0,0 +1,85 @@
+import {
+    activeJourneyStep,
+    JourneyStepTag,
+    reportBackendRequest,
+    resolveJourneyStep,
+} from '../core';
+import { requestKey, type JourneyTimedMeta } from './request-key';
+
+/**
+ * Minimal structural axios surface. No axios dependency — works across 0.31 and 1.x.
+ */
+export interface AxiosLikeInstance {
+    defaults: { baseURL?: string };
+    interceptors: {
+        request: { use(onFulfilled: (config: any) => any): unknown };
+        response: {
+            use(onFulfilled: (response: any) => any, onRejected?: (error: any) => any): unknown;
+        };
+    };
+}
+
+type TimedConfig = JourneyTimedMeta & { url?: string; baseURL?: string };
+
+function reportTiming(
+    instance: AxiosLikeInstance,
+    config: TimedConfig | undefined,
+    status: number | undefined
+): void {
+    const step = resolveJourneyStep(config?.journeyStep);
+    if (!step || !config) {
+        return;
+    }
+    const start = config.journeyStart ?? globalThis.performance.now();
+    const key = requestKey(config.url, config.baseURL, instance.defaults.baseURL);
+    reportBackendRequest(step, status, globalThis.performance.now() - start, key);
+}
+
+const instrumented = new WeakSet<object>();
+
+/**
+ * Wire an axios instance into the journey engine (observation-only).
+ * Call once per instance (idempotent). Register any async request interceptors
+ * (e.g. auth) before this call so this one runs first.
+ */
+export function instrumentAxios(instance: AxiosLikeInstance): void {
+    if (instrumented.has(instance as object)) {
+        return;
+    }
+    instrumented.add(instance as object);
+
+    instance.interceptors.request.use(config => {
+        const timed = config as TimedConfig;
+        /*
+         * Prefer explicit step.tag(); else soft ambient (null when 0 or 2+ steps in flight).
+         * Box ambient steps in JourneyStepTag — raw StepRecord is circular and blows axios mergeConfig.
+         */
+        if (!resolveJourneyStep(timed.journeyStep)) {
+            const step = activeJourneyStep();
+            if (step) {
+                timed.journeyStep = new JourneyStepTag(step);
+            }
+        }
+        timed.journeyStart = globalThis.performance.now();
+        return config;
+    });
+
+    instance.interceptors.response.use(
+        response => {
+            reportTiming(instance, response?.config as TimedConfig | undefined, response?.status);
+            return response;
+        },
+        (error: unknown) => {
+            const axiosError = error as {
+                config?: TimedConfig;
+                response?: { status?: number };
+            };
+            reportTiming(instance, axiosError?.config, axiosError?.response?.status);
+            /*
+             * Passthrough original reason (AxiosError or test doubles). Do not wrap —
+             * callers match on .response / AxiosError identity.
+             */
+            return Promise.reject(error as Error);
+        }
+    );
+}

package/src/integrations/fetch.ts

@@ -0,0 +1,97 @@
+import { activeJourneyStep, reportBackendRequest, resolveJourneyStep } from '../core';
+import { requestKey, type JourneyTimedMeta } from './request-key';
+
+/** Minimal structural fetch shape. */
+export type FetchLike = (input: any, init?: any) => Promise<{ status: number }>;
+
+/** Holder of a `fetch` property — globalThis by default, or a scoped object. */
+export interface FetchTarget {
+    fetch: FetchLike;
+}
+
+export interface InstrumentFetchOptions {
+    /** Object whose `fetch` is wrapped. Defaults to globalThis. */
+    target?: FetchTarget;
+    /** Home API base URL for request-key origin resolution. */
+    baseURL?: string;
+}
+
+const instrumented = new WeakSet<object>();
+const originals = new WeakMap<object, FetchLike>();
+
+function resolveUrl(input: any): string | undefined {
+    if (typeof input === 'string') {
+        return input;
+    }
+    if (input && typeof input.url === 'string') {
+        return input.url;
+    }
+    if (input && typeof input.href === 'string') {
+        return input.href;
+    }
+    return undefined;
+}
+
+/**
+ * Wrap a target's fetch so requests inside a journeyStep are attributed and timed.
+ * Call once per target (idempotent — second call is a no-op). Returns a restore
+ * function that puts the original fetch back. Observation-only.
+ */
+export function instrumentFetch(options: InstrumentFetchOptions = {}): () => void {
+    const target = options.target ?? (globalThis as unknown as FetchTarget);
+    const key = target as object;
+
+    if (instrumented.has(key)) {
+        return () => {};
+    }
+
+    const original = target.fetch;
+    originals.set(key, original);
+    instrumented.add(key);
+
+    // Call through `target` — native fetch throws "Illegal invocation" with the wrong receiver.
+    const wrapped: FetchLike = (input, init) => {
+        // Prefer explicit step.tag(); else soft ambient.
+        const explicit = resolveJourneyStep((init as JourneyTimedMeta | undefined)?.journeyStep);
+        const step = explicit ?? activeJourneyStep();
+        if (!step) {
+            return original.call(target, input, init);
+        }
+
+        const start = globalThis.performance.now();
+        const endpointKey = requestKey(resolveUrl(input), undefined, options.baseURL);
+        const promise = original.call(target, input, init);
+        return promise.then(
+            response => {
+                reportBackendRequest(
+                    step,
+                    response.status,
+                    globalThis.performance.now() - start,
+                    endpointKey
+                );
+                return response;
+            },
+            (error: unknown) => {
+                reportBackendRequest(
+                    step,
+                    undefined,
+                    globalThis.performance.now() - start,
+                    endpointKey
+                );
+                // Passthrough original rejection reason; do not wrap (identity / AbortError).
+                return Promise.reject(error as Error);
+            }
+        );
+    };
+
+    target.fetch = wrapped;
+
+    return () => {
+        if (!instrumented.has(key)) {
+            return;
+        }
+        target.fetch = originals.get(key) ?? original;
+        instrumented.delete(key);
+        originals.delete(key);
+    };
+}

package/src/integrations/jquery/index.ts

@@ -0,0 +1,62 @@
+import {
+    defineJourney,
+    firstOpenJourney,
+    journeyStep,
+    type JourneyDef,
+    type JourneyHandle,
+    type JourneyStepOptions,
+    type JourneyStepTarget,
+    type StepHandle,
+} from '../../core';
+
+/**
+ * Knockout / desktop-legacy bridge on `window.App.Journey`.
+ * Prefer `defineJourney` handles; `journeyStep` / `firstOpenJourney` cover multi-journey steps.
+ */
+export interface AppJourneyApi {
+    defineJourney(def: JourneyDef): JourneyHandle;
+    journeyStep<T>(
+        journey: JourneyStepTarget,
+        stepName: string,
+        fn: (step: StepHandle) => T | Promise<T>,
+        opts?: JourneyStepOptions
+    ): Promise<T>;
+    firstOpenJourney(names: readonly string[]): string | null;
+}
+
+export type WindowWithAppJourney = Window & {
+    App?: { Journey?: AppJourneyApi } & Record<string, unknown>;
+};
+
+let journeyExposed = false;
+let windowJourneyApi: AppJourneyApi | undefined;
+
+/**
+ * Publish the Knockout bridge on window.App.Journey. Idempotent for the real window.
+ * Optional `target` is for tests.
+ */
+export function exposeAppJourney(target: WindowWithAppJourney = window): AppJourneyApi {
+    if (journeyExposed && target === window && windowJourneyApi) {
+        return windowJourneyApi;
+    }
+
+    const api: AppJourneyApi = {
+        defineJourney,
+        journeyStep,
+        firstOpenJourney,
+    };
+    target.App = target.App ?? {};
+    target.App.Journey = api;
+    if (target === window) {
+        journeyExposed = true;
+        windowJourneyApi = api;
+    }
+    return api;
+}
+
+export {
+    instrumentJquery,
+    type JqueryAjaxSettings,
+    type JqueryStatic,
+    type JqueryXHR,
+} from './instrument';

package/src/integrations/jquery/instrument.ts

@@ -0,0 +1,84 @@
+import {
+    activeJourneyStep,
+    JourneyStepTag,
+    reportBackendRequest,
+    resolveJourneyStep,
+} from '../../core';
+import { requestKey } from '../request-key';
+
+export interface JqueryXHR {
+    status: number;
+    journeyStep?: unknown;
+    journeyStart?: number;
+}
+
+export interface JqueryAjaxSettings {
+    url?: string;
+    journeyStep?: unknown;
+}
+
+export interface JqueryStatic {
+    ajaxPrefilter(
+        handler: (
+            options: JqueryAjaxSettings,
+            originalOptions: JqueryAjaxSettings,
+            jqXHR: JqueryXHR
+        ) => void
+    ): void;
+    (selector: Document): {
+        ajaxComplete(
+            handler: (event: unknown, jqXHR: JqueryXHR, settings: JqueryAjaxSettings) => void
+        ): void;
+    };
+}
+
+const instrumented = new WeakSet<object>();
+
+function reportTiming(jqXHR: JqueryXHR, settings: JqueryAjaxSettings): void {
+    const step = resolveJourneyStep(jqXHR.journeyStep);
+    if (!step) {
+        return;
+    }
+    const start = jqXHR.journeyStart ?? globalThis.performance.now();
+    // jQuery uses status 0 for network / abort failures — treat like a missing status.
+    const status = jqXHR.status === 0 ? undefined : jqXHR.status;
+    reportBackendRequest(
+        step,
+        status,
+        globalThis.performance.now() - start,
+        requestKey(settings.url, undefined, undefined)
+    );
+}
+
+/** Wire a jQuery static into the journey engine. Call once per $ (idempotent). Observation-only. */
+export function instrumentJquery($: JqueryStatic): void {
+    if (instrumented.has($ as object)) {
+        return;
+    }
+    instrumented.add($ as object);
+
+    $.ajaxPrefilter((options, _originalOptions, jqXHR) => {
+        /*
+         * Prefer explicit step.tag() (settings or XHR); else soft ambient.
+         * Box ambient steps in JourneyStepTag — raw StepRecord is circular and blows jQuery deep-merge.
+         */
+        if (!jqXHR.journeyStep) {
+            const fromSettings = options.journeyStep;
+            if (fromSettings) {
+                jqXHR.journeyStep = fromSettings;
+            } else {
+                const step = activeJourneyStep();
+                if (step) {
+                    jqXHR.journeyStep = new JourneyStepTag(step);
+                }
+            }
+        }
+        if (resolveJourneyStep(jqXHR.journeyStep)) {
+            jqXHR.journeyStart = globalThis.performance.now();
+        }
+    });
+
+    $(document).ajaxComplete((_event, jqXHR, settings) => {
+        reportTiming(jqXHR, settings);
+    });
+}

package/src/integrations/react/context.ts

@@ -0,0 +1,17 @@
+import { createContext, useContext } from 'react';
+
+export const JourneyNameContext = createContext<string | null>(null);
+
+/** Active journey name, or null outside a `<JourneyScope>` (steps run untraced). */
+export function useOptionalJourneyName(): string | null {
+    return useContext(JourneyNameContext);
+}
+
+/** Active journey name; throws outside a `<JourneyScope>`. */
+export function useJourneyName(): string {
+    const name = useContext(JourneyNameContext);
+    if (!name) {
+        throw new Error('useJourneyName must be used within a <JourneyScope>');
+    }
+    return name;
+}

package/src/integrations/react/scope.tsx

@@ -0,0 +1,32 @@
+import { useEffect, type ReactNode } from 'react';
+
+import { excludeJourney, setJourneyTags, startJourney, type JourneyDef } from '../../core';
+import type { TagValue } from '../../core/types';
+import { JourneyNameContext } from './context';
+
+/**
+ * Opens a journey while the subtree is mounted; Excludes on unmount.
+ * Config (timeouts, endpoints, tags, …) is captured when the journey opens;
+ * only a `name` change re-opens.
+ */
+export function JourneyScope({
+    tags,
+    children,
+    ...def
+}: JourneyDef & {
+    tags?: Record<string, TagValue>;
+    children: ReactNode;
+}) {
+    const { name } = def;
+
+    useEffect(() => {
+        startJourney(def);
+        if (tags) {
+            setJourneyTags(name, tags);
+        }
+        return () => excludeJourney(name);
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- freeze-on-mount; name is the lifecycle key
+    }, [name]);
+
+    return <JourneyNameContext.Provider value={name}>{children}</JourneyNameContext.Provider>;
+}