@servicetitan/journey 2.0.0 → 3.0.0

package/src/core/request-policy.ts

@@ -0,0 +1,66 @@
+/** Verdict for attributed HTTP (abort / 4xx / similar). */
+export type JourneyRequestPolicy = 'continue' | 'bad' | 'exclude';
+
+/** Normalized facts adapters pass into policy resolvers (not axios/jqXHR). */
+export interface JourneyHttpPolicyContext {
+    requestKey: string;
+    /** Present when an HTTP response exists; omitted on abort / hard network failure. */
+    status?: number;
+    aborted: boolean;
+    url?: string;
+    method?: string;
+    journeyName?: string;
+    stepName?: string;
+}
+
+/**
+ * Per-stamp HTTP scorer from {@link StepHandle.stamp}. Must be synchronous.
+ * Return a policy to set the journey verdict; omit / void to keep default scoring.
+ * Do not consume a fetch body (clone first if you need to read it).
+ */
+export type JourneyHttpScore = (
+    ctx: JourneyHttpScoreContext
+) => JourneyRequestPolicy | void | undefined;
+
+/** Context for {@link JourneyHttpScore} — policy facts plus the transport req/res. */
+export interface JourneyHttpScoreContext extends JourneyHttpPolicyContext {
+    durationMs: number;
+    /** Transport request (axios config, fetch input/init, jQuery ajax settings). */
+    request?: unknown;
+    /** Transport response (axios response, fetch Response, jqXHR). */
+    response?: unknown;
+    /** Rejection reason when the transport failed. */
+    error?: unknown;
+}
+
+/** Options for {@link StepHandle.stamp}. */
+export interface JourneyStampOptions {
+    score?: JourneyHttpScore;
+    /** Skip scoring for this stamped request. Ignore wins over `score`. */
+    ignore?: boolean;
+}
+
+export type RequestPolicyConfig =
+    JourneyRequestPolicy | ((ctx: JourneyHttpPolicyContext) => JourneyRequestPolicy);
+
+export function resolveRequestPolicy(
+    config: RequestPolicyConfig | undefined,
+    fallback: JourneyRequestPolicy,
+    ctx: JourneyHttpPolicyContext
+): JourneyRequestPolicy {
+    if (config === undefined) {
+        return fallback;
+    }
+    if (typeof config === 'function') {
+        try {
+            return config(ctx);
+        } catch {
+            return fallback;
+        }
+    }
+    return config;
+}
+
+export function isJourneyRequestPolicy(value: unknown): value is JourneyRequestPolicy {
+    return value === 'continue' || value === 'bad' || value === 'exclude';
+}