@servicetitan/journey 3.0.0 → 4.0.0

package/src/core/persist.ts

@@ -0,0 +1,131 @@
+import {
+    clampMaxSteps,
+    finiteSlowRequestMs,
+    finiteTimeoutMs,
+    MAX_ATTRIBUTE_KEYS,
+    MAX_TAG_KEYS,
+    resolveJourneyTimeoutMs,
+} from './limits';
+import { assignRecord, emptyRecord } from './sanitize';
+import { bindJourneyEngine, freezeJourneyDef, type JourneyRuntime } from './runtime';
+import {
+    JOURNEY_ENGINE,
+    type JourneyDef,
+    type JourneyState,
+    type SerializedJourneyState,
+    type StepRecord,
+} from './types';
+
+/**
+ * @internal Project an open {@link JourneyState} into a plain, JSON-safe
+ * {@link SerializedJourneyState} that can ride a cookie across page navigations.
+ * The step projection mirrors `finish()`; `startedAt` (a `performance.now()`
+ * monotonic stamp) is bridged to a wall-clock epoch so it survives the page
+ * load where `performance.now()` resets.
+ */
+export function projectJourneyState(journey: JourneyState): SerializedJourneyState {
+    const steps = journey.steps.map(s => ({
+        name: s.name,
+        startMs: Math.round(s.startedAt - journey.startedAt),
+        durationMs: s.durationMs || Math.round(globalThis.performance.now() - s.startedAt),
+        outcome: s.outcome,
+        ...(s.reason ? { reason: s.reason } : {}),
+        ...(s.httpStatus !== undefined ? { httpStatus: s.httpStatus } : {}),
+        // Attributes are raw here — final emission sanitization happens in finish().
+        ...(Object.keys(s.attributes).length ? { attributes: { ...s.attributes } } : {}),
+    }));
+
+    const startedAtEpoch = Date.now() - (globalThis.performance.now() - journey.startedAt);
+    // Coerce any non-null st_journey_id tag to a string so a numeric/boolean id survives the round-trip.
+    const stJourneyId =
+        journey.tags.st_journey_id != null ? String(journey.tags.st_journey_id) : '';
+
+    return {
+        stJourneyId,
+        startedAtEpoch,
+        // Open journeys are never 'excluded' — that verdict is only set inside finish().
+        verdict: journey.verdict === 'bad' ? 'bad' : 'good',
+        reason: journey.reason,
+        steps,
+        tags: { ...journey.tags },
+    };
+}
+
+/**
+ * @internal Rehydrate a {@link SerializedJourneyState} into a live
+ * {@link JourneyState} bound to the supplied runtime. `startedAt` is rebased
+ * from the wall-clock epoch back to a `performance.now()` monotonic stamp,
+ * `StepRecord[]` is rebuilt with re-linked circular references, and the
+ * `JOURNEY_ENGINE` hook is re-bound so HTTP attribution works on the new page.
+ */
+export function deserializeJourneyState(
+    serialized: SerializedJourneyState,
+    config: JourneyDef,
+    api: JourneyRuntime,
+    defaultJourneyIdleMs: number
+): JourneyState {
+    const tags = emptyRecord();
+    // Caller config tags win; serialized tags fill the rest (incl. st_journey_id).
+    assignRecord(tags, serialized.tags, MAX_TAG_KEYS);
+    assignRecord(tags, config.tags, MAX_TAG_KEYS);
+    if (serialized.stJourneyId && tags.st_journey_id === undefined) {
+        tags.st_journey_id = serialized.stJourneyId;
+    }
+
+    const snapshot = freezeJourneyDef(config, tags);
+    const timeout = resolveJourneyTimeoutMs(snapshot.timeoutMs, defaultJourneyIdleMs);
+
+    const startedAt = globalThis.performance.now() - (Date.now() - serialized.startedAtEpoch);
+
+    const journey: JourneyState = {
+        config: snapshot,
+        name: snapshot.name,
+        team: snapshot.team,
+        group: snapshot.group,
+        service: snapshot.service,
+        verdict: serialized.verdict === 'bad' ? 'bad' : 'good',
+        startedAt,
+        timeoutMs: timeout.ms,
+        timeoutExplicit: timeout.explicit,
+        stepTimeoutMs:
+            snapshot.stepTimeoutMs !== undefined
+                ? finiteTimeoutMs(snapshot.stepTimeoutMs)
+                : undefined,
+        reason: serialized.reason,
+        steps: [],
+        expected: snapshot.expected ? [...snapshot.expected] : null,
+        tags,
+        slowRequestMs: finiteSlowRequestMs(snapshot.slowRequestMs),
+        endpoints: snapshot.endpoints,
+        timer: null,
+        closed: false,
+        maxSteps: snapshot.maxSteps !== undefined ? clampMaxSteps(snapshot.maxSteps) : undefined,
+    };
+
+    // Rebuild StepRecord[] — re-link the circular `step.journey` reference and rebase `startedAt` from the offset.
+    for (const s of serialized.steps) {
+        const step: StepRecord = {
+            name: s.name,
+            startedAt: journey.startedAt + s.startMs,
+            durationMs: s.durationMs,
+            outcome: s.outcome,
+            attributes: emptyRecord(),
+            journey,
+        };
+        if (s.reason !== undefined) {
+            step.reason = s.reason;
+        }
+        if (s.httpStatus !== undefined) {
+            step.httpStatus = s.httpStatus;
+        }
+        if (s.attributes) {
+            assignRecord(step.attributes, s.attributes, MAX_ATTRIBUTE_KEYS);
+        }
+        journey.steps.push(step);
+    }
+
+    // Re-bind the engine so HTTP attribution / fail-fast works on this page.
+    journey[JOURNEY_ENGINE] = bindJourneyEngine(api, journey, api.shouldIgnoreRequest);
+
+    return journey;
+}

package/src/core/runtime.ts

@@ -11,6 +11,7 @@ import {
     sortEndpointsByLongestMatch,
     type SlowRequestConfig,
 } from './endpoint-policy';
+import { deserializeJourneyState, projectJourneyState } from './persist';
 import {
     clampMaxSteps,
     DEFAULT_MAX_STEPS,
@@ -36,6 +37,7 @@ import {
     type JourneyStepOptions,
     type JourneyStepTarget,
     type Outcome,
+    type SerializedJourneyState,
     type StepHandle,
     type StepRecord,
     type TagValue,
@@ -106,7 +108,8 @@ export interface JourneyRuntimeDebugSnapshot {
     };
 }
 
-function freezeJourneyDef(config: JourneyDef, tags: Record<string, TagValue>): JourneyDef {
+/** @internal Freeze a caller-supplied journey def + tags snapshot. */
+export function freezeJourneyDef(config: JourneyDef, tags: Record<string, TagValue>): JourneyDef {
     const endpoints = sortEndpointsByLongestMatch(config.endpoints);
     return Object.freeze({
         ...config,
@@ -164,6 +167,17 @@ export interface JourneyRuntime {
     completeJourneyState(journey: JourneyState, tags?: Record<string, TagValue>): void;
     excludeJourney(journey: JourneyState): void;
     updateOpenJourney(config: JourneyDef): void;
+    /**
+     * @internal Snapshot an open journey for cross-page transfer. Does NOT
+     * close the journey. Returns `null` when no journey is open under `name`.
+     */
+    serializeJourneyState(name: string): SerializedJourneyState | null;
+    /**
+     * @internal Rehydrate a serialized journey onto this runtime. Returns
+     * `null` (after emitting a `bad` `journey-timeout` event) when the journey
+     * already exhausted its budget in transit.
+     */
+    restoreJourney(serialized: SerializedJourneyState, config: JourneyDef): JourneyState | null;
 
     activeJourneyStep(): StepRecord | null;
     journeyStep<T>(
@@ -192,7 +206,8 @@ export interface JourneyRuntime {
     reset(options?: JourneyRuntimeOptions): void;
 }
 
-function bindJourneyEngine(
+/** @internal Bind the fail/exclude/report hooks for a journey's creating engine. */
+export function bindJourneyEngine(
     api: JourneyRuntime,
     journey: JourneyState,
     shouldIgnoreRequest: (target: JourneyState, key: string) => boolean
@@ -685,6 +700,51 @@ export function createJourneyRuntime(options: JourneyRuntimeOptions = {}): Journ
             armCountdown(journey, remainingMs);
         },
 
+        serializeJourneyState(name) {
+            const journey = journeys.get(name);
+            if (!journey || journey.closed) {
+                return null;
+            }
+            return projectJourneyState(journey);
+        },
+
+        restoreJourney(serialized, config) {
+            // Refuse double-registration: leave an existing journey under this name in place.
+            if (journeys.has(config.name)) {
+                return null;
+            }
+
+            const journey = deserializeJourneyState(serialized, config, api, defaultJourneyIdleMs);
+
+            if (journey.timeoutMs > 0) {
+                const elapsedMs = globalThis.performance.now() - journey.startedAt;
+                if (elapsedMs >= journey.timeoutMs) {
+                    // journey not yet in journeys Map — finish() handles unregistered journeys gracefully.
+                    if (journey.timeoutExplicit) {
+                        finish(journey, 'bad', 'journey-timeout');
+                    } else {
+                        finish(
+                            journey,
+                            journey.verdict === 'bad' ? 'bad' : 'excluded',
+                            'journey-idle-timeout'
+                        );
+                    }
+                    return null;
+                }
+
+                journeys.set(config.name, journey);
+
+                const remainingMs = journey.timeoutMs - elapsedMs;
+                if (remainingMs > 0) {
+                    armCountdown(journey, remainingMs);
+                }
+            } else {
+                journeys.set(config.name, journey);
+            }
+
+            return journey;
+        },
+
         activeJourneyStep() {
             if (!api.getAutoAttributeRequests()) {
                 return null;

package/src/core/types.ts

@@ -163,6 +163,32 @@ export interface JourneyStepEvent {
     attributes?: Record<string, TagValue>;
 }
 
+/**
+ * Snapshot of an open journey that can survive a page navigation. Produced by
+ * `serializeJourneyState` and rehydrated by `restoreJourney`. Mirrors the
+ * `JourneyStepEvent` projection emitted by `finish()`, plus the wall-clock
+ * start time, verdict, reason, and tags needed to re-arm the countdown.
+ */
+export interface SerializedJourneyState {
+    /** `st_journey_id` tag — cross-page correlation key. Empty string when unset. */
+    stJourneyId: string;
+    /** Wall-clock epoch (Date.now()) when the journey started. */
+    startedAtEpoch: number;
+    verdict: 'good' | 'bad';
+    reason: string | null;
+    steps: {
+        name: string;
+        /** Offset from the journey start, ms. */
+        startMs: number;
+        durationMs: number;
+        outcome: 'good' | 'bad';
+        reason?: string;
+        httpStatus?: number;
+        attributes?: Record<string, TagValue>;
+    }[];
+    tags: Record<string, TagValue>;
+}
+
 /** Neutral journey event payload (journey-specific fields only; session context is host RUM globals). */
 export interface JourneyEvent {
     journey: {

package/src/index.ts

@@ -13,6 +13,8 @@ export {
     excludeJourney,
     failJourney,
     journeyStep,
+    restoreJourney,
+    serializeJourneyState,
     setJourneyTags,
     // Custom transport adapters / request attribution.
     singleInFlightJourneyStep,
@@ -23,6 +25,7 @@ export {
     type JourneyNameLike,
     type JourneyStepOptions,
     type JourneyStepTarget,
+    type SerializedJourneyState,
     type StepHandle,
 } from './core';
 

package/src/sinks/datadog.ts

@@ -1,5 +1,3 @@
-import { datadogRum } from '@datadog/browser-rum';
-
 import { isSanitizedJourneyEvent, sanitizeJourneyEvent } from '../core/sanitize';
 import { getJourneyRumFallback, setJourneyRumFallback } from '../global';
 import type { JourneyEvent, JourneyStepEvent } from '../core/types';
@@ -10,8 +8,16 @@ const JOURNEY_ACTION = 'user_journey';
 
 const DD_RUM_KEY = 'DD_RUM';
 
-function getDdRum(): typeof datadogRum | undefined {
-    return (globalThis as Record<string, unknown>)[DD_RUM_KEY] as typeof datadogRum | undefined;
+/**
+ * Not imported from @datadog/browser-rum on purpose: importing it sets globalThis.DD_RUM at
+ * module load, which lets an MFE bundle replace the host's initialized RUM instance.
+ */
+interface RumLike {
+    addAction(name: string, context?: object): void;
+}
+
+function getDdRum(): RumLike | undefined {
+    return (globalThis as Record<string, unknown>)[DD_RUM_KEY] as RumLike | undefined;
 }
 
 /**
@@ -20,7 +26,7 @@ function getDdRum(): typeof datadogRum | undefined {
  *
  * Prefer exposing the initialized instance as `globalThis.DD_RUM` (ST host:
  * `datadogGuard`). `sendToDatadog` resolves `DD_RUM` first, then `__stJourney.rum`
- * (this fallback), then the bundle's imported `datadogRum`.
+ * (this fallback); with neither present the event is dropped.
  *
  * Calling `setJourneyRum` while `globalThis.DD_RUM` is already set logs a warning —
  * the call is redundant because `sendToDatadog` prefers `DD_RUM`.
@@ -35,13 +41,8 @@ export function setJourneyRum(rum: unknown): void {
     setJourneyRumFallback(rum);
 }
 
-function resolveRum(): typeof datadogRum {
-    const ddRum = getDdRum();
-    if (ddRum) {
-        return ddRum;
-    }
-    const shared = getJourneyRumFallback();
-    return (shared as typeof datadogRum | undefined) ?? datadogRum;
+function resolveRum(): RumLike | undefined {
+    return getDdRum() ?? (getJourneyRumFallback() as RumLike | undefined);
 }
 
 function toDatadogStep(step: JourneyStepEvent) {
@@ -63,8 +64,7 @@ function toDatadogStep(step: JourneyStepEvent) {
 /** Ship one terminal journey as a RUM custom action (`user_journey`). */
 export function sendToDatadog(payload: JourneyEvent): void {
     const rum = resolveRum();
-    // Skip bad/missing host stubs — uninit RUM still buffers addAction safely.
-    if (typeof rum.addAction !== 'function') {
+    if (!rum || typeof rum.addAction !== 'function') {
         return;
     }