@servicetitan/journey 3.0.1 → 4.0.0

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';