@servicetitan/journey 2.1.0 → 3.0.0

package/src/core/limits.ts

@@ -0,0 +1,73 @@
+/** Payload / timer bounds shared by the engine and default sinks. */
+
+export const DEFAULT_MAX_STEPS = 50;
+export const MAX_STEPS_CAP = 200;
+export const MAX_TAG_KEYS = 32;
+export const MAX_ATTRIBUTE_KEYS = 64;
+export const MAX_ATTRIBUTED_REQUEST_KEYS = 50;
+export const MAX_TAG_VALUE_LEN = 200;
+export const DEFAULT_JOURNEY_IDLE_MS = 15 * 60 * 1_000;
+
+const DENIED_KEYS = new Set([
+    '__proto__',
+    'constructor',
+    'prototype',
+    'authorization',
+    'cookie',
+    'set-cookie',
+    'password',
+    'token',
+    'secret',
+    'ssn',
+]);
+
+/** True for prototype-polluting keys and a small secret-name deny-list (case-insensitive). */
+export function isUnsafeKey(key: string): boolean {
+    return DENIED_KEYS.has(key.toLowerCase());
+}
+
+/**
+ * Finite integer ≥ 1, else `fallback`. Used for maxSteps-like caps.
+ * Non-finite / ≤ 0 / non-numbers return `fallback`.
+ */
+export function finitePositiveInt(n: unknown, fallback: number): number {
+    if (typeof n !== 'number' || !Number.isFinite(n) || n <= 0) {
+        return fallback;
+    }
+    return Math.floor(n);
+}
+
+/**
+ * Journey/step timeout: finite ≥ 0 keeps the value (floored); anything else is 0 (disabled).
+ */
+export function finiteTimeoutMs(n: unknown): number {
+    if (typeof n !== 'number' || !Number.isFinite(n) || n < 0) {
+        return 0;
+    }
+    return Math.floor(n);
+}
+
+/** Clamp recorded-step cap to 1..MAX_STEPS_CAP; invalid → DEFAULT_MAX_STEPS. */
+export function clampMaxSteps(n: unknown): number {
+    const value = finitePositiveInt(n, DEFAULT_MAX_STEPS);
+    return Math.min(value, MAX_STEPS_CAP);
+}
+
+/** Finite ≥ 0 slow-request threshold, or undefined to fall through. */
+export function finiteSlowRequestMs(n: unknown): number | undefined {
+    if (typeof n !== 'number' || !Number.isFinite(n) || n < 0) {
+        return undefined;
+    }
+    return Math.floor(n);
+}
+
+/** Explicit 0 disables; omitted uses idle default; finite N keeps caller timeout. */
+export function resolveJourneyTimeoutMs(
+    timeoutMs: number | undefined,
+    idleDefaultMs: number = DEFAULT_JOURNEY_IDLE_MS
+): { ms: number; explicit: boolean } {
+    if (timeoutMs === undefined) {
+        return { ms: finiteTimeoutMs(idleDefaultMs), explicit: false };
+    }
+    return { ms: finiteTimeoutMs(timeoutMs), explicit: true };
+}

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