@servicetitan/journey 2.0.0 → 3.0.0

package/src/integrations/axios.ts

@@ -1,10 +1,13 @@
+import { resolveStamp } from '../core';
+import { adoptJourneyStepStamp, type JourneyStepStamp } from '../core/step-tag';
 import {
-    activeJourneyStep,
-    JourneyStepTag,
-    reportBackendRequest,
-    resolveJourneyStep,
-} from '../core';
+    getInstrumentedAxiosSet,
+    registerInstrumentRecord,
+    type InstrumentRecord,
+} from '../global';
+import { isCanceledError, onHttpComplete } from './http-report';
 import { requestKey, type JourneyTimedMeta } from './request-key';
+import { acceptInstrumentTarget } from './soft-skip';
 
 /**
  * Minimal structural axios surface. No axios dependency — works across 0.31 and 1.x.
@@ -12,74 +15,209 @@ import { requestKey, type JourneyTimedMeta } from './request-key';
 export interface AxiosLikeInstance {
     defaults: { baseURL?: string };
     interceptors: {
-        request: { use(onFulfilled: (config: any) => any): unknown };
+        request: {
+            use(onFulfilled: (config: any) => any): unknown;
+            eject?(id: unknown): void;
+        };
         response: {
             use(onFulfilled: (response: any) => any, onRejected?: (error: any) => any): unknown;
+            eject?(id: unknown): void;
         };
     };
 }
 
-type TimedConfig = JourneyTimedMeta & { url?: string; baseURL?: string };
+type TimedConfig = JourneyTimedMeta & { url?: string; baseURL?: string; method?: string };
+
+const axiosStamps = new WeakMap<object, JourneyStepStamp>();
+
+function stampFromConfig(config: TimedConfig | undefined): JourneyStepStamp | undefined {
+    if (!config) {
+        return undefined;
+    }
+    return axiosStamps.get(config) ?? adoptJourneyStepStamp(config.stamp);
+}
 
 function reportTiming(
     instance: AxiosLikeInstance,
     config: TimedConfig | undefined,
-    status: number | undefined
+    status: number | undefined,
+    aborted: boolean,
+    extras?: { request?: unknown; response?: unknown; error?: unknown }
 ): void {
-    const step = resolveJourneyStep(config?.journeyStep);
-    if (!step || !config) {
+    if (!config || config.ignore === true) {
+        return;
+    }
+    const stamp = stampFromConfig(config);
+    if (!stamp || stamp.ignore) {
         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);
+    onHttpComplete({
+        stamp,
+        status,
+        durationMs: globalThis.performance.now() - start,
+        requestKey: key,
+        aborted,
+        url: config.url,
+        method: config.method,
+        meta: config,
+        request: extras?.request ?? config,
+        response: extras?.response,
+        error: extras?.error,
+    });
 }
 
-const instrumented = new WeakSet<object>();
+function isAxiosLikeInstance(value: unknown): value is AxiosLikeInstance {
+    if (value == null || (typeof value !== 'object' && typeof value !== 'function')) {
+        return false;
+    }
+    const instance = value as AxiosLikeInstance;
+    return (
+        instance.defaults != null &&
+        typeof instance.defaults === 'object' &&
+        typeof instance.interceptors?.request?.use === 'function' &&
+        typeof instance.interceptors?.response?.use === 'function'
+    );
+}
+
+function ejectInterceptor(
+    interceptors: { eject?: (id: unknown) => void } | undefined,
+    id: unknown
+): boolean {
+    if (id === undefined || typeof interceptors?.eject !== 'function') {
+        return false;
+    }
+    try {
+        interceptors.eject(id);
+        return true;
+    } catch {
+        return false;
+    }
+}
 
 /**
  * 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.
+ * Soft-skips when `instance` is missing or not axios-like — hosts can pass axios as-is.
+ * Returns a restore function that disposes handlers (they no-op after restore).
  */
-export function instrumentAxios(instance: AxiosLikeInstance): void {
-    if (instrumented.has(instance as object)) {
-        return;
+export function instrumentAxios(instance: AxiosLikeInstance | null | undefined): () => void {
+    const axios = acceptInstrumentTarget('Axios', instance, isAxiosLikeInstance);
+    const instrumented = getInstrumentedAxiosSet();
+    if (!axios || instrumented.has(axios 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);
+    const record: InstrumentRecord = { disposed: false };
+    let requestId: unknown;
+    let responseId: unknown;
+    let requestAdded = false;
+    let responseAdded = false;
+
+    try {
+        requestId = axios.interceptors.request.use(config => {
+            if (record.disposed) {
+                return config;
             }
-        }
-        timed.journeyStart = globalThis.performance.now();
-        return config;
-    });
+            const timed = config as TimedConfig;
+            if (timed.ignore === true) {
+                return config;
+            }
+            const stamp = resolveStamp(timed.stamp);
+            if (stamp) {
+                axiosStamps.set(timed, stamp);
+                /*
+                 * Keep config.stamp so later interceptors that clone/spread config
+                 * still carry attribution. JourneyStepStamp.toJSON keeps this safe
+                 * for AxiosError serialization.
+                 */
+            }
+            if (stamp?.ignore === true) {
+                return config;
+            }
+            if (stamp) {
+                timed.journeyStart = globalThis.performance.now();
+            }
+            return config;
+        });
+        requestAdded = true;
 
-    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);
+        responseId = axios.interceptors.response.use(
+            response => {
+                if (!record.disposed) {
+                    reportTiming(
+                        axios,
+                        response?.config as TimedConfig | undefined,
+                        response?.status,
+                        false,
+                        { request: response?.config, response }
+                    );
+                }
+                return response;
+            },
+            (error: unknown) => {
+                if (!record.disposed) {
+                    const axiosError = error as {
+                        config?: TimedConfig;
+                        response?: { status?: number };
+                    };
+                    reportTiming(
+                        axios,
+                        axiosError?.config,
+                        axiosError?.response?.status,
+                        isCanceledError(error),
+                        {
+                            request: axiosError?.config,
+                            response: axiosError?.response,
+                            error,
+                        }
+                    );
+                }
+                /*
+                 * Passthrough original reason (AxiosError or test doubles). Do not wrap —
+                 * callers match on .response / AxiosError identity.
+                 */
+                return Promise.reject(error as Error);
+            }
+        );
+        responseAdded = true;
+        instrumented.add(axios as object);
+    } catch (err) {
+        const unwound =
+            (!responseAdded || ejectInterceptor(axios.interceptors.response, responseId)) &&
+            (!requestAdded || ejectInterceptor(axios.interceptors.request, requestId));
+        if (!unwound) {
             /*
-             * Passthrough original reason (AxiosError or test doubles). Do not wrap —
-             * callers match on .response / AxiosError identity.
+             * Interceptors may still be registered and cannot be ejected. Mark disposed
+             * and keep the WeakSet slot, but register a restore so teardownJourney can
+             * unmark and a later retry can proceed.
              */
-            return Promise.reject(error as Error);
+            record.disposed = true;
+            instrumented.add(axios as object);
+            const restore = () => {
+                record.disposed = true;
+                instrumented.delete(axios as object);
+            };
+            record.restore = restore;
+            registerInstrumentRecord(record);
+            // eslint-disable-next-line no-console -- soft-fail host wiring
+            console.error('[journey] instrumentAxios failed', err);
+            return restore;
         }
-    );
+        // eslint-disable-next-line no-console -- soft-fail host wiring
+        console.error('[journey] instrumentAxios failed', err);
+        return () => {};
+    }
+
+    const restore = () => {
+        record.disposed = true;
+        ejectInterceptor(axios.interceptors.request, requestId);
+        ejectInterceptor(axios.interceptors.response, responseId);
+        instrumented.delete(axios as object);
+    };
+    record.restore = restore;
+    registerInstrumentRecord(record);
+    return restore;
 }

package/src/integrations/fetch.ts

@@ -1,22 +1,29 @@
-import { activeJourneyStep, reportBackendRequest, resolveJourneyStep } from '../core';
+import { resolveStamp } from '../core';
+import {
+    getInstrumentedFetchSet,
+    registerInstrumentRecord,
+    setFetchRestore,
+    type InstrumentRecord,
+} from '../global';
+import { isAbortError, onHttpComplete } from './http-report';
 import { requestKey, type JourneyTimedMeta } from './request-key';
+import { acceptInstrumentTarget } from './soft-skip';
 
 /** Minimal structural fetch shape. */
-export type FetchLike = (input: any, init?: any) => Promise<{ status: number }>;
+type FetchLike = (input: any, init?: any) => Promise<{ status: number }>;
 
 /** Holder of a `fetch` property — globalThis by default, or a scoped object. */
-export interface FetchTarget {
+interface FetchTarget {
     fetch: FetchLike;
 }
 
 export interface InstrumentFetchOptions {
     /** Object whose `fetch` is wrapped. Defaults to globalThis. */
-    target?: FetchTarget;
+    target?: FetchTarget | null;
     /** 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 {
@@ -32,14 +39,47 @@ function resolveUrl(input: any): string | undefined {
     return undefined;
 }
 
+/** Fetch defaults to GET; `init.method` overrides a Request's method. */
+function resolveMethod(input: any, init?: any): string {
+    if (typeof init?.method === 'string' && init.method !== '') {
+        return init.method;
+    }
+    if (typeof input?.method === 'string' && input.method !== '') {
+        return input.method;
+    }
+    return 'GET';
+}
+
+function isFetchTarget(value: unknown): value is FetchTarget {
+    return (
+        value != null &&
+        (typeof value === 'object' || typeof value === 'function') &&
+        typeof (value as FetchTarget).fetch === 'function'
+    );
+}
+
 /**
  * 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.
+ * Soft-skips when the resolved target is missing or has no callable `fetch`.
  */
-export function instrumentFetch(options: InstrumentFetchOptions = {}): () => void {
-    const target = options.target ?? (globalThis as unknown as FetchTarget);
+export function instrumentFetch(options?: InstrumentFetchOptions | null): () => void {
+    if (options === null) {
+        acceptInstrumentTarget('Fetch', null, isFetchTarget);
+        return () => {};
+    }
+
+    const opts = options ?? {};
+    const candidate =
+        opts.target !== undefined ? opts.target : (globalThis as unknown as FetchTarget);
+    const target = acceptInstrumentTarget('Fetch', candidate, isFetchTarget);
+    if (!target) {
+        return () => {};
+    }
+
     const key = target as object;
+    const instrumented = getInstrumentedFetchSet();
 
     if (instrumented.has(key)) {
         return () => {};
@@ -49,49 +89,95 @@ export function instrumentFetch(options: InstrumentFetchOptions = {}): () => voi
     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 record: InstrumentRecord = { disposed: false };
 
-        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);
+    try {
+        // Call through `target` — native fetch throws "Illegal invocation" with the wrong receiver.
+        const wrapped: FetchLike = (input, init) => {
+            if (record.disposed) {
+                return original.call(target, input, init);
+            }
+            // Prefer explicit step.stamp(); else auto-attribute when enabled.
+            const meta = init as JourneyTimedMeta | undefined;
+            if (meta?.ignore === true) {
+                return original.call(target, input, init);
+            }
+            const stamp = resolveStamp(meta?.stamp);
+            if (!stamp || stamp.ignore) {
+                return original.call(target, input, init);
             }
-        );
-    };
 
-    target.fetch = wrapped;
+            const start = globalThis.performance.now();
+            const url = resolveUrl(input);
+            const method = resolveMethod(input, init);
+            const endpointKey = requestKey(url, undefined, opts.baseURL);
+            const promise = original.call(target, input, init);
+            return promise.then(
+                response => {
+                    if (!record.disposed) {
+                        onHttpComplete({
+                            stamp,
+                            status: response.status,
+                            durationMs: globalThis.performance.now() - start,
+                            requestKey: endpointKey,
+                            url,
+                            method,
+                            meta,
+                            request: init ?? input,
+                            response,
+                        });
+                    }
+                    return response;
+                },
+                (error: unknown) => {
+                    if (!record.disposed) {
+                        onHttpComplete({
+                            stamp,
+                            status: undefined,
+                            durationMs: globalThis.performance.now() - start,
+                            requestKey: endpointKey,
+                            aborted: isAbortError(error),
+                            url,
+                            method,
+                            meta,
+                            request: init ?? input,
+                            error,
+                        });
+                    }
+                    // Passthrough original rejection reason; do not wrap (identity / AbortError).
+                    return Promise.reject(error as Error);
+                }
+            );
+        };
+
+        target.fetch = wrapped;
+    } catch (err) {
+        target.fetch = original;
+        instrumented.delete(key);
+        originals.delete(key);
+        // eslint-disable-next-line no-console -- soft-fail host wiring
+        console.error('[journey] instrumentFetch failed', err);
+        return () => {};
+    }
 
-    return () => {
+    const restore = () => {
         if (!instrumented.has(key)) {
             return;
         }
+        record.disposed = true;
         target.fetch = originals.get(key) ?? original;
         instrumented.delete(key);
         originals.delete(key);
+        if (target === (globalThis as unknown as FetchTarget)) {
+            setFetchRestore(undefined);
+        }
     };
+
+    record.restore = restore;
+    registerInstrumentRecord(record);
+    if (target === (globalThis as unknown as FetchTarget)) {
+        setFetchRestore(restore);
+    }
+
+    return restore;
 }

package/src/integrations/http-report.ts

@@ -0,0 +1,184 @@
+import { MAX_ATTRIBUTED_REQUEST_KEYS } from '../core/limits';
+import {
+    isJourneyRequestPolicy,
+    resolveRequestPolicy,
+    type JourneyHttpPolicyContext,
+    type JourneyRequestPolicy,
+} from '../core/request-policy';
+import { reportBackendRequest } from '../core/api';
+import { canRouteHttpToJourney, resolveJourneyEngine } from '../core/runtime';
+import type { JourneyStepStamp } from '../core/step-tag';
+import type { StepRecord } from '../core/types';
+import type { JourneyTimedMeta } from './request-key';
+
+export interface HttpCompleteReport {
+    stamp: JourneyStepStamp | undefined;
+    status?: number;
+    durationMs: number;
+    requestKey: string;
+    aborted?: boolean;
+    url?: string;
+    method?: string;
+    /** Per-request literal overrides from JourneyTimedMeta. */
+    meta?: JourneyTimedMeta;
+    /** Transport request (axios config, fetch input/init, jQuery settings). */
+    request?: unknown;
+    /** Transport response (axios response, fetch Response, jqXHR). */
+    response?: unknown;
+    /** Rejection reason when the transport failed. */
+    error?: unknown;
+}
+
+function applyPolicy(
+    policy: JourneyRequestPolicy,
+    step: StepRecord,
+    reason: string,
+    status?: number
+): void {
+    if (policy === 'continue') {
+        return;
+    }
+    const journey = step.journey;
+    if (!journey || journey.closed) {
+        return;
+    }
+    const engine = resolveJourneyEngine(journey);
+    if (policy === 'exclude') {
+        engine.exclude();
+        return;
+    }
+    // 'bad'
+    step.outcome = 'bad';
+    step.reason ??= reason;
+    if (status !== undefined) {
+        step.httpStatus = status;
+    }
+    engine.failJourney(reason);
+}
+
+function httpScoreReason(report: HttpCompleteReport): string {
+    if (report.aborted) {
+        return 'request-aborted';
+    }
+    const status = report.status;
+    if (status !== undefined && status >= 400 && status < 500) {
+        return 'request-client-error';
+    }
+    return 'request-error';
+}
+
+/**
+ * Attribute a finished HTTP call: abort / 4xx policies, else 5xx+latency via reportBackendRequest.
+ * Ignored endpoint prefixes never change the journey verdict.
+ * 4xx with policy `'continue'` (default) still scores latency.
+ */
+export function onHttpComplete(report: HttpCompleteReport): void {
+    const {
+        stamp,
+        status,
+        durationMs,
+        requestKey,
+        aborted,
+        url,
+        method,
+        meta,
+        request,
+        response,
+        error,
+    } = report;
+    if (!stamp) {
+        return;
+    }
+    const step = stamp.step;
+    if (!step?.journey) {
+        return;
+    }
+    /*
+     * Unstamped foreign journeys (older package copies) cannot be closed from
+     * this bundle — do not write onHttpAborted / step.outcome on them.
+     */
+    if (!canRouteHttpToJourney(step.journey)) {
+        return;
+    }
+    const engine = resolveJourneyEngine(step.journey);
+
+    if (meta?.ignore === true || stamp.ignore === true) {
+        return;
+    }
+
+    if (aborted) {
+        step.onHttpAborted = true;
+    }
+
+    if (requestKey) {
+        step.attributedRequestKeys ??= [];
+        if (
+            step.attributedRequestKeys.length < MAX_ATTRIBUTED_REQUEST_KEYS &&
+            !step.attributedRequestKeys.includes(requestKey)
+        ) {
+            step.attributedRequestKeys.push(requestKey);
+        }
+    }
+
+    if (requestKey && engine.shouldIgnoreRequest(requestKey)) {
+        return;
+    }
+
+    const ctx: JourneyHttpPolicyContext = {
+        requestKey,
+        status,
+        aborted: aborted === true,
+        url,
+        method,
+        journeyName: step.journey.name,
+        stepName: step.name,
+    };
+
+    const score = stamp.score;
+    if (score) {
+        let policy: JourneyRequestPolicy | undefined;
+        try {
+            const scored = score({
+                ...ctx,
+                durationMs,
+                request,
+                response,
+                error,
+            });
+            if (isJourneyRequestPolicy(scored)) {
+                policy = scored;
+            }
+        } catch {
+            policy = undefined;
+        }
+        if (policy !== undefined) {
+            applyPolicy(policy, step, httpScoreReason(report), status);
+            return;
+        }
+    }
+
+    if (aborted) {
+        const override = meta?.httpAbortedRequests;
+        const policy = isJourneyRequestPolicy(override)
+            ? override
+            : resolveRequestPolicy(engine.getHttpAbortedRequestsPolicy(), 'continue', ctx);
+        applyPolicy(policy, step, 'request-aborted');
+        return;
+    }
+
+    if (status !== undefined && status >= 400 && status < 500) {
+        const override = meta?.httpClientErrorRequests;
+        const policy = isJourneyRequestPolicy(override)
+            ? override
+            : resolveRequestPolicy(engine.getHttpClientErrorRequestsPolicy(), 'continue', ctx);
+        if (policy !== 'continue') {
+            applyPolicy(policy, step, 'request-client-error', status);
+            return;
+        }
+        // 'continue' does not count 4xx as an error; still score latency below.
+    }
+
+    reportBackendRequest(step, status, durationMs, requestKey);
+}
+
+export { isAbortError, isCanceledError } from '../core/abort-error';