@servicetitan/journey 1.0.0

package/dist/integrations/request-key.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Timing metadata stamped onto a request config so the response handler can attribute
+ * and measure the round trip. Intersect with your transport's config type.
+ *
+ * `journeyStep` is a JourneyStepTag (from `step.tag()` or ambient instrumentation)
+ * or, historically, a raw StepRecord. Adapters unwrap via `resolveJourneyStep`.
+ */
+export interface JourneyTimedMeta {
+    journeyStart?: number;
+    journeyStep?: unknown;
+}
+/**
+ * Endpoint key for timeout / ignore lookup: PATH for same-origin (vs instance baseURL),
+ * or "host/path" for cross-domain.
+ */
+export declare function requestKey(url: string | undefined, configBaseURL: string | undefined, instanceBaseURL: string | undefined): string;
+//# sourceMappingURL=request-key.d.ts.map

package/dist/integrations/request-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-key.d.ts","sourceRoot":"","sources":["../../src/integrations/request-key.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;CACzB;AAUD;;;GAGG;AACH,wBAAgB,UAAU,CACtB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,eAAe,EAAE,MAAM,GAAG,SAAS,GACpC,MAAM,CAiBR"}

package/dist/integrations/request-key.js

@@ -0,0 +1,39 @@
+/**
+ * Timing metadata stamped onto a request config so the response handler can attribute
+ * and measure the round trip. Intersect with your transport's config type.
+ *
+ * `journeyStep` is a JourneyStepTag (from `step.tag()` or ambient instrumentation)
+ * or, historically, a raw StepRecord. Adapters unwrap via `resolveJourneyStep`.
+ */ function pageOrigin() {
+    try {
+        var _ref;
+        var _globalThis_location;
+        return (_ref = (_globalThis_location = globalThis.location) === null || _globalThis_location === void 0 ? void 0 : _globalThis_location.origin) !== null && _ref !== void 0 ? _ref : '';
+    } catch (unused) {
+        return '';
+    }
+}
+/**
+ * Endpoint key for timeout / ignore lookup: PATH for same-origin (vs instance baseURL),
+ * or "host/path" for cross-domain.
+ */ export function requestKey(url, configBaseURL, instanceBaseURL) {
+    var _ref;
+    const origin = pageOrigin();
+    const base = (_ref = configBaseURL !== null && configBaseURL !== void 0 ? configBaseURL : instanceBaseURL) !== null && _ref !== void 0 ? _ref : origin;
+    let abs;
+    try {
+        abs = new URL(url !== null && url !== void 0 ? url : '', base || undefined);
+    } catch (unused) {
+        return url !== null && url !== void 0 ? url : '';
+    }
+    let homeOrigin;
+    try {
+        const homeBase = instanceBaseURL !== null && instanceBaseURL !== void 0 ? instanceBaseURL : origin;
+        homeOrigin = new URL(homeBase || 'http://localhost').origin;
+    } catch (unused) {
+        homeOrigin = origin;
+    }
+    return abs.origin === homeOrigin ? abs.pathname : abs.host + abs.pathname;
+}
+
+//# sourceMappingURL=request-key.js.map

package/dist/integrations/request-key.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/integrations/request-key.ts"],"sourcesContent":["/**\n * Timing metadata stamped onto a request config so the response handler can attribute\n * and measure the round trip. Intersect with your transport's config type.\n *\n * `journeyStep` is a JourneyStepTag (from `step.tag()` or ambient instrumentation)\n * or, historically, a raw StepRecord. Adapters unwrap via `resolveJourneyStep`.\n */\nexport interface JourneyTimedMeta {\n    journeyStart?: number;\n    journeyStep?: unknown;\n}\n\nfunction pageOrigin(): string {\n    try {\n        return globalThis.location?.origin ?? '';\n    } catch {\n        return '';\n    }\n}\n\n/**\n * Endpoint key for timeout / ignore lookup: PATH for same-origin (vs instance baseURL),\n * or \"host/path\" for cross-domain.\n */\nexport function requestKey(\n    url: string | undefined,\n    configBaseURL: string | undefined,\n    instanceBaseURL: string | undefined\n): string {\n    const origin = pageOrigin();\n    const base = configBaseURL ?? instanceBaseURL ?? origin;\n    let abs: URL;\n    try {\n        abs = new URL(url ?? '', base || undefined);\n    } catch {\n        return url ?? '';\n    }\n    let homeOrigin: string;\n    try {\n        const homeBase = instanceBaseURL ?? origin;\n        homeOrigin = new URL(homeBase || 'http://localhost').origin;\n    } catch {\n        homeOrigin = origin;\n    }\n    return abs.origin === homeOrigin ? abs.pathname : abs.host + abs.pathname;\n}\n"],"names":["pageOrigin","globalThis","location","origin","requestKey","url","configBaseURL","instanceBaseURL","base","abs","URL","undefined","homeOrigin","homeBase","pathname","host"],"mappings":"AAAA;;;;;;CAMC,GAMD,SAASA;IACL,IAAI;;YACOC;QAAP,gBAAOA,uBAAAA,WAAWC,QAAQ,cAAnBD,2CAAAA,qBAAqBE,MAAM,uCAAI;IAC1C,EAAE,eAAM;QACJ,OAAO;IACX;AACJ;AAEA;;;CAGC,GACD,OAAO,SAASC,WACZC,GAAuB,EACvBC,aAAiC,EACjCC,eAAmC;QAGtBD;IADb,MAAMH,SAASH;IACf,MAAMQ,QAAOF,OAAAA,0BAAAA,2BAAAA,gBAAiBC,6BAAjBD,kBAAAA,OAAoCH;IACjD,IAAIM;IACJ,IAAI;QACAA,MAAM,IAAIC,IAAIL,gBAAAA,iBAAAA,MAAO,IAAIG,QAAQG;IACrC,EAAE,eAAM;QACJ,OAAON,gBAAAA,iBAAAA,MAAO;IAClB;IACA,IAAIO;IACJ,IAAI;QACA,MAAMC,WAAWN,4BAAAA,6BAAAA,kBAAmBJ;QACpCS,aAAa,IAAIF,IAAIG,YAAY,oBAAoBV,MAAM;IAC/D,EAAE,eAAM;QACJS,aAAaT;IACjB;IACA,OAAOM,IAAIN,MAAM,KAAKS,aAAaH,IAAIK,QAAQ,GAAGL,IAAIM,IAAI,GAAGN,IAAIK,QAAQ;AAC7E"}

package/dist/sinks/datadog.d.ts

@@ -0,0 +1,6 @@
+import type { JourneyEvent } from '../core/types';
+/** Host-only: publish the initialized RUM instance so MFE bundles share the same session. */
+export declare function setJourneyRum(rum: unknown): void;
+/** Ship one terminal journey as a RUM custom action (`user_journey`). */
+export declare function sendToDatadog(payload: JourneyEvent): void;
+//# sourceMappingURL=datadog.d.ts.map

package/dist/sinks/datadog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datadog.d.ts","sourceRoot":"","sources":["../../src/sinks/datadog.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAA8B,MAAM,eAAe,CAAC;AAM9E,6FAA6F;AAC7F,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAEhD;AAwCD,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAkBzD"}

package/dist/sinks/datadog.js

@@ -0,0 +1,64 @@
+import { datadogRum } from '@datadog/browser-rum';
+const JOURNEY_ACTION = 'user_journey';
+const RUM_GLOBAL_KEY = '__stJourneyRum';
+/** Host-only: publish the initialized RUM instance so MFE bundles share the same session. */ export function setJourneyRum(rum) {
+    globalThis[RUM_GLOBAL_KEY] = rum;
+}
+function resolveRum() {
+    const shared = globalThis[RUM_GLOBAL_KEY];
+    return shared !== null && shared !== void 0 ? shared : datadogRum;
+}
+// Match Datadog metric-tag value rules so RUM attributes join derived SLO tags.
+const MAX_TAG_VALUE_LEN = 200;
+function normalizeTagValue(value) {
+    return value.toLowerCase().replace(/[^a-z0-9_\-:./]/g, '_').replace(/_+/g, '_').slice(0, MAX_TAG_VALUE_LEN).replace(/_+$/, '');
+}
+function normalizeTags(tags) {
+    const out = {};
+    for (const [key, value] of Object.entries(tags)){
+        out[key] = typeof value === 'string' ? normalizeTagValue(value) : value;
+    }
+    return out;
+}
+function toDatadogStep(step) {
+    /* eslint-disable @typescript-eslint/naming-convention -- Datadog RUM wire format (snake_case) */ return {
+        name: step.name,
+        start_ms: step.startMs,
+        duration_ms: step.durationMs,
+        outcome: step.outcome,
+        ...step.reason ? {
+            reason: step.reason
+        } : {},
+        ...step.httpStatus !== undefined ? {
+            http_status: step.httpStatus
+        } : {},
+        ...step.attributes ? {
+            attributes: step.attributes
+        } : {}
+    };
+/* eslint-enable @typescript-eslint/naming-convention */ }
+/** Ship one terminal journey as a RUM custom action (`user_journey`). */ export function sendToDatadog(payload) {
+    const j = payload.journey;
+    /* eslint-disable @typescript-eslint/naming-convention -- Datadog RUM wire format (snake_case) */ resolveRum().addAction(JOURNEY_ACTION, {
+        journey: {
+            name: normalizeTagValue(j.name),
+            team: normalizeTagValue(j.team),
+            group: normalizeTagValue(j.group),
+            service: normalizeTagValue(j.service),
+            outcome: j.outcome,
+            ...j.reason ? {
+                reason: normalizeTagValue(j.reason)
+            } : {},
+            duration_ms: j.durationMs,
+            steps: j.steps.map(toDatadogStep),
+            ...j.expected ? {
+                expected: j.expected
+            } : {},
+            ...j.tags ? {
+                tags: normalizeTags(j.tags)
+            } : {}
+        }
+    });
+/* eslint-enable @typescript-eslint/naming-convention */ }
+
+//# sourceMappingURL=datadog.js.map

package/dist/sinks/datadog.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sinks/datadog.ts"],"sourcesContent":["import { datadogRum } from '@datadog/browser-rum';\n\nimport type { JourneyEvent, JourneyStepEvent, TagValue } from '../core/types';\n\nconst JOURNEY_ACTION = 'user_journey';\n\nconst RUM_GLOBAL_KEY = '__stJourneyRum';\n\n/** Host-only: publish the initialized RUM instance so MFE bundles share the same session. */\nexport function setJourneyRum(rum: unknown): void {\n    (globalThis as Record<string, unknown>)[RUM_GLOBAL_KEY] = rum;\n}\n\nfunction resolveRum(): typeof datadogRum {\n    const shared = (globalThis as Record<string, unknown>)[RUM_GLOBAL_KEY];\n    return (shared as typeof datadogRum | undefined) ?? datadogRum;\n}\n\n// Match Datadog metric-tag value rules so RUM attributes join derived SLO tags.\nconst MAX_TAG_VALUE_LEN = 200;\nfunction normalizeTagValue(value: string): string {\n    return value\n        .toLowerCase()\n        .replace(/[^a-z0-9_\\-:./]/g, '_')\n        .replace(/_+/g, '_')\n        .slice(0, MAX_TAG_VALUE_LEN)\n        .replace(/_+$/, '');\n}\n\nfunction normalizeTags(tags: Record<string, TagValue>): Record<string, TagValue> {\n    const out: Record<string, TagValue> = {};\n    for (const [key, value] of Object.entries(tags)) {\n        out[key] = typeof value === 'string' ? normalizeTagValue(value) : value;\n    }\n    return out;\n}\n\nfunction toDatadogStep(step: JourneyStepEvent) {\n    /* eslint-disable @typescript-eslint/naming-convention -- Datadog RUM wire format (snake_case) */\n    return {\n        name: step.name,\n        start_ms: step.startMs,\n        duration_ms: step.durationMs,\n        outcome: step.outcome,\n        ...(step.reason ? { reason: step.reason } : {}),\n        ...(step.httpStatus !== undefined ? { http_status: step.httpStatus } : {}),\n        ...(step.attributes ? { attributes: step.attributes } : {}),\n    };\n    /* eslint-enable @typescript-eslint/naming-convention */\n}\n\n/** Ship one terminal journey as a RUM custom action (`user_journey`). */\nexport function sendToDatadog(payload: JourneyEvent): void {\n    const j = payload.journey;\n    /* eslint-disable @typescript-eslint/naming-convention -- Datadog RUM wire format (snake_case) */\n    resolveRum().addAction(JOURNEY_ACTION, {\n        journey: {\n            name: normalizeTagValue(j.name),\n            team: normalizeTagValue(j.team),\n            group: normalizeTagValue(j.group),\n            service: normalizeTagValue(j.service),\n            outcome: j.outcome,\n            ...(j.reason ? { reason: normalizeTagValue(j.reason) } : {}),\n            duration_ms: j.durationMs,\n            steps: j.steps.map(toDatadogStep),\n            ...(j.expected ? { expected: j.expected } : {}),\n            ...(j.tags ? { tags: normalizeTags(j.tags) } : {}),\n        },\n    });\n    /* eslint-enable @typescript-eslint/naming-convention */\n}\n"],"names":["datadogRum","JOURNEY_ACTION","RUM_GLOBAL_KEY","setJourneyRum","rum","globalThis","resolveRum","shared","MAX_TAG_VALUE_LEN","normalizeTagValue","value","toLowerCase","replace","slice","normalizeTags","tags","out","key","Object","entries","toDatadogStep","step","name","start_ms","startMs","duration_ms","durationMs","outcome","reason","httpStatus","undefined","http_status","attributes","sendToDatadog","payload","j","journey","addAction","team","group","service","steps","map","expected"],"mappings":"AAAA,SAASA,UAAU,QAAQ,uBAAuB;AAIlD,MAAMC,iBAAiB;AAEvB,MAAMC,iBAAiB;AAEvB,2FAA2F,GAC3F,OAAO,SAASC,cAAcC,GAAY;IACrCC,UAAsC,CAACH,eAAe,GAAGE;AAC9D;AAEA,SAASE;IACL,MAAMC,SAAS,AAACF,UAAsC,CAACH,eAAe;IACtE,OAAQK,mBAAAA,oBAAAA,SAA4CP;AACxD;AAEA,gFAAgF;AAChF,MAAMQ,oBAAoB;AAC1B,SAASC,kBAAkBC,KAAa;IACpC,OAAOA,MACFC,WAAW,GACXC,OAAO,CAAC,oBAAoB,KAC5BA,OAAO,CAAC,OAAO,KACfC,KAAK,CAAC,GAAGL,mBACTI,OAAO,CAAC,OAAO;AACxB;AAEA,SAASE,cAAcC,IAA8B;IACjD,MAAMC,MAAgC,CAAC;IACvC,KAAK,MAAM,CAACC,KAAKP,MAAM,IAAIQ,OAAOC,OAAO,CAACJ,MAAO;QAC7CC,GAAG,CAACC,IAAI,GAAG,OAAOP,UAAU,WAAWD,kBAAkBC,SAASA;IACtE;IACA,OAAOM;AACX;AAEA,SAASI,cAAcC,IAAsB;IACzC,+FAA+F,GAC/F,OAAO;QACHC,MAAMD,KAAKC,IAAI;QACfC,UAAUF,KAAKG,OAAO;QACtBC,aAAaJ,KAAKK,UAAU;QAC5BC,SAASN,KAAKM,OAAO;QACrB,GAAIN,KAAKO,MAAM,GAAG;YAAEA,QAAQP,KAAKO,MAAM;QAAC,IAAI,CAAC,CAAC;QAC9C,GAAIP,KAAKQ,UAAU,KAAKC,YAAY;YAAEC,aAAaV,KAAKQ,UAAU;QAAC,IAAI,CAAC,CAAC;QACzE,GAAIR,KAAKW,UAAU,GAAG;YAAEA,YAAYX,KAAKW,UAAU;QAAC,IAAI,CAAC,CAAC;IAC9D;AACA,sDAAsD,GAC1D;AAEA,uEAAuE,GACvE,OAAO,SAASC,cAAcC,OAAqB;IAC/C,MAAMC,IAAID,QAAQE,OAAO;IACzB,+FAA+F,GAC/F9B,aAAa+B,SAAS,CAACpC,gBAAgB;QACnCmC,SAAS;YACLd,MAAMb,kBAAkB0B,EAAEb,IAAI;YAC9BgB,MAAM7B,kBAAkB0B,EAAEG,IAAI;YAC9BC,OAAO9B,kBAAkB0B,EAAEI,KAAK;YAChCC,SAAS/B,kBAAkB0B,EAAEK,OAAO;YACpCb,SAASQ,EAAER,OAAO;YAClB,GAAIQ,EAAEP,MAAM,GAAG;gBAAEA,QAAQnB,kBAAkB0B,EAAEP,MAAM;YAAE,IAAI,CAAC,CAAC;YAC3DH,aAAaU,EAAET,UAAU;YACzBe,OAAON,EAAEM,KAAK,CAACC,GAAG,CAACtB;YACnB,GAAIe,EAAEQ,QAAQ,GAAG;gBAAEA,UAAUR,EAAEQ,QAAQ;YAAC,IAAI,CAAC,CAAC;YAC9C,GAAIR,EAAEpB,IAAI,GAAG;gBAAEA,MAAMD,cAAcqB,EAAEpB,IAAI;YAAE,IAAI,CAAC,CAAC;QACrD;IACJ;AACA,sDAAsD,GAC1D"}

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "@servicetitan/journey",
+    "version": "1.0.0",
+    "description": "Critical user journey monitoring — reports good/bad/excluded verdicts to Datadog RUM as a custom action",
+    "homepage": "https://docs.st.dev/docs/frontend/journey",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/servicetitan/anvil-uikit-contrib.git",
+        "directory": "packages/journey"
+    },
+    "sideEffects": [
+        "./dist/config.js",
+        "./src/config.ts"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        }
+    },
+    "main": "./dist/index.js",
+    "typings": "./dist/index.d.ts",
+    "files": [
+        "dist",
+        "src"
+    ],
+    "devDependencies": {
+        "@datadog/browser-rum": "^7.5.0",
+        "@testing-library/jest-dom": "^6.4.2",
+        "@testing-library/react": "^14.2.1",
+        "@types/react": "~18.2.55",
+        "react": "^18.2.0"
+    },
+    "peerDependencies": {
+        "@datadog/browser-rum": ">=6.19.0",
+        "react": ">=17.0.2"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "cli": {
+        "webpack": false
+    }
+}

package/src/__mocks__/test-runtime.ts

@@ -0,0 +1,37 @@
+import { resetJourney } from '../core';
+import { sendToDatadog } from '../sinks/datadog';
+
+/** Standard journey def used across engine suites. */
+export const baseJourneyDef = {
+    name: 'journey-under-test',
+    team: 'platform',
+    group: 'test',
+    service: 'journey',
+    timeoutMs: 0,
+} as const;
+
+/** Last emitted journey payload from a sink mock. */
+export function lastJourney(emitMock: jest.Mock) {
+    return emitMock.mock.calls[emitMock.mock.calls.length - 1][0].journey;
+}
+
+/**
+ * Wire `emitMock` as the only sink and restore package defaults after each test.
+ * Call once at the top of a `describe` block.
+ */
+export function useJourneyTestRuntime(emitMock: jest.Mock) {
+    beforeEach(() => {
+        resetJourney({
+            sinks: [emitMock],
+            requestTimeouts: { defaultMs: 4_000, endpoints: [] },
+        });
+        emitMock.mockClear();
+    });
+
+    afterEach(() => {
+        resetJourney({
+            sinks: [sendToDatadog],
+            requestTimeouts: { defaultMs: 4_000, endpoints: [] },
+        });
+    });
+}

package/src/__tests__/ambient.test.ts

@@ -0,0 +1,101 @@
+/** @jest-environment jsdom */
+import { baseJourneyDef, useJourneyTestRuntime } from '../__mocks__/test-runtime';
+import { activeJourneyStep, completeJourney, journeyStep, startJourney } from '../core';
+
+const emitMock = jest.fn();
+const baseDef = { ...baseJourneyDef, name: 'ambient-a' };
+const otherDef = { ...baseJourneyDef, name: 'ambient-b' };
+
+describe('[journey] activeJourneyStep', () => {
+    useJourneyTestRuntime(emitMock);
+
+    describe('around a single step', () => {
+        beforeEach(() => {
+            startJourney(baseDef);
+        });
+
+        test('is set only while the step is running', async () => {
+            expect(activeJourneyStep()).toBeNull();
+
+            await journeyStep(baseDef.name, 'do-work', () => {
+                expect(activeJourneyStep()).not.toBeNull();
+            });
+
+            expect(activeJourneyStep()).toBeNull();
+            completeJourney(baseDef.name);
+        });
+    });
+
+    describe('when two steps overlap', () => {
+        let releaseA!: () => void;
+        let stepA: Promise<unknown>;
+
+        beforeEach(() => {
+            startJourney(baseDef);
+            startJourney(otherDef);
+
+            const gateA = new Promise<void>(r => {
+                releaseA = r;
+            });
+            stepA = journeyStep(baseDef.name, 'load', async () => {
+                await gateA;
+            });
+        });
+
+        afterEach(async () => {
+            releaseA();
+            await stepA;
+            completeJourney(baseDef.name);
+            completeJourney(otherDef.name);
+        });
+
+        const subject = () => journeyStep(otherDef.name, 'book', () => activeJourneyStep());
+
+        test('returns null', async () => {
+            await expect(subject()).resolves.toBeNull();
+        });
+    });
+
+    describe('when the first-finishing sibling ends first', () => {
+        let releaseB!: () => void;
+        let stepB: Promise<unknown>;
+        let ambientWhileBAlone: ReturnType<typeof activeJourneyStep> | 'unset';
+
+        beforeEach(() => {
+            startJourney(baseDef);
+            startJourney(otherDef);
+            ambientWhileBAlone = 'unset';
+
+            const gateB = new Promise<void>(r => {
+                releaseB = r;
+            });
+            stepB = journeyStep(otherDef.name, 'book', async () => {
+                await gateB;
+                ambientWhileBAlone = activeJourneyStep();
+            });
+        });
+
+        afterEach(async () => {
+            releaseB();
+            await stepB;
+            completeJourney(baseDef.name);
+            completeJourney(otherDef.name);
+        });
+
+        test('keeps ambient on the remaining step', async () => {
+            await journeyStep(baseDef.name, 'load', () => {
+                expect(activeJourneyStep()).toBeNull();
+            });
+
+            releaseB();
+            await stepB;
+
+            expect(ambientWhileBAlone).not.toBeNull();
+            expect(ambientWhileBAlone).not.toBe('unset');
+            if (ambientWhileBAlone === 'unset' || ambientWhileBAlone == null) {
+                throw new Error('expected ambient step');
+            }
+            expect(ambientWhileBAlone.name).toBe('book');
+        });
+    });
+});