@active-reach/web-sdk 1.43.1 → 1.43.2

package/dist/triggers/TriggerEngine.d.ts

@@ -0,0 +1,296 @@
+/**
+ * TriggerEngine - Client-Side Trigger Evaluation
+ *
+ * Evaluates behavioral triggers that require real-time client state:
+ * - Scroll depth (e.g., user scrolled >= 50%)
+ * - Time on page (e.g., >= 30 seconds on current page)
+ * - Exit intent (mouse leaving viewport toward browser controls)
+ * - Inactivity (no user interaction for X seconds)
+ * - Scroll velocity (mobile exit intent - fast upward scroll)
+ * - Visibility change (tab/app switching)
+ * - Back button (history navigation)
+ *
+ * Architecture:
+ * - Server evaluates historical triggers (event counts, segments)
+ * - Client evaluates behavioral triggers (scroll, time, exit intent)
+ * - Zero latency - no server round trip needed
+ *
+ * Usage:
+ *   const trigger = new TriggerEngine();
+ *   trigger.on('scroll_depth_50', (data) => {
+ *     console.log('User scrolled to 50%', data);
+ *   });
+ *   trigger.start();
+ *
+ * Every `page_url` a trigger emits is credential-redacted (`redactUrl`): the
+ * payload is handed to listeners that track it. The two `history.pushState`
+ * calls read the raw URL on purpose — they re-push the page the visitor is
+ * on, and a redacted URL there would rewrite the address bar.
+ */
+export interface TriggerRule {
+    type: 'scroll_depth' | 'time_on_page' | 'exit_intent' | 'inactivity' | 'scroll_velocity' | 'visibility_change' | 'back_button';
+    config: ScrollDepthConfig | TimeOnPageConfig | ExitIntentConfig | InactivityConfig | ScrollVelocityConfig | VisibilityChangeConfig | BackButtonConfig;
+}
+export interface ScrollDepthConfig {
+    depth_percent: number;
+}
+export interface TimeOnPageConfig {
+    seconds: number;
+}
+export interface ExitIntentConfig {
+    enabled: boolean;
+}
+export interface InactivityConfig {
+    idle_seconds: number;
+}
+export interface ScrollVelocityConfig {
+    threshold: number;
+    minScrollPosition: number;
+    cooldown: number;
+}
+export interface VisibilityChangeConfig {
+    enabled: boolean;
+}
+export interface BackButtonConfig {
+    enabled: boolean;
+}
+/**
+ * Rage-click detection (Micro-Intent Engine P2 Task 1).
+ *
+ * Per-intent ring buffer: when ≥ `threshold` clicks land on the same
+ * intent inside `windowMs`, the engine emits `rage_click` with the
+ * intent name + current count + window. Frustration signal used by the
+ * Stuck-at-Checkout pattern (e.g., rage-clicking the coupon input four
+ * times in 800ms).
+ *
+ * Defaults match the plan:
+ *   threshold = 3 clicks
+ *   windowMs  = 1000 ms
+ *
+ * TriggerEngine does NOT attach its own pointerdown listener — the
+ * SelectorBinder (P1 Task 5) owns the global, delegated listener and
+ * dispatches per-intent click events. The IntentSnapshotCollector
+ * (P2 Task 5) wires `SelectorBinder.onIntent` to
+ * `TriggerEngine.noteClick(intent)` so TriggerEngine sees a clean
+ * intent-stamped stream instead of raw DOM events.
+ */
+export interface RageClickConfig {
+    threshold: number;
+    windowMs: number;
+}
+/** Payload emitted on the `rage_click` event. */
+export interface RageClickData {
+    intent: string;
+    count: number;
+    window_ms: number;
+}
+/**
+ * Hover-dwell tracking (Micro-Intent Engine P2 Task 2).
+ *
+ * Tracks per-intent hover duration in milliseconds. `getHoverMs(intent)`
+ * returns:
+ *   - if currently hovering the intent: ms since hover_start (live)
+ *   - else: ms duration of the most recent hover on that intent (sticky)
+ *   - if never hovered: 0
+ *
+ * The sticky behaviour is deliberate. The canonical use case
+ * (MICRO_INTENT_ENGINE.md Story 1):
+ *     "Priya hovers price for 1.8s, considers, moves cursor away.
+ *      Exit_intent fires. Rule checks price_hover_ms >= 1500 → true."
+ * The rule evaluator queries `price_hover_ms` AFTER the hover ends. If
+ * we reset to 0 on hover_end, the rule never matches the very pattern
+ * the engine exists to detect.
+ *
+ * Threshold-based emission: when a hover crosses one of the registered
+ * dwell targets (e.g. 1500ms), a `<intent>_hover_dwell_<ms>` event
+ * fires. Useful for journeys that want event-style hooks; the
+ * snapshot-style `getHoverMs` is the primary surface for the
+ * compound-rule evaluator.
+ */
+export interface HoverDwellConfig {
+    /** Dwell thresholds (ms) per intent. The engine fires
+     *  `<intent>_hover_dwell_<ms>` when an active hover crosses each
+     *  threshold. Defaults: price→[1500], cta→[1500]. */
+    thresholdsByIntent?: Partial<Record<string, ReadonlyArray<number>>>;
+}
+/**
+ * Mouse velocity toward the viewport top (Micro-Intent Engine P2 Task 3).
+ *
+ * Detects the early phase of exit-intent: the mouse moving rapidly
+ * upward before it actually crosses out of the viewport. The signal is
+ * a continuous px/ms value (positive = moving up), updated as samples
+ * arrive. When velocity crosses `threshold`, a `mouse_velocity_to_top`
+ * event fires (once per session-window cooldown to avoid spamming on a
+ * single gesture).
+ *
+ * Sampling: callers feed positions via `noteMousePosition(x, y, ts)`.
+ * The engine keeps a sliding `windowMs` ring buffer of samples and
+ * computes velocity as the average dy / dt over samples in the window.
+ * Per the plan: sampled at 100ms, 400ms window. That bound is
+ * configurable.
+ *
+ * Why "to top" specifically: exit-intent fires only when y crosses 0;
+ * we want the warning BEFORE that. A typical exit-intent gesture has
+ * upward velocity well above any normal browsing motion.
+ */
+export interface MouseVelocityConfig {
+    /** Threshold in px/ms (positive = moving up). Default 1.5 px/ms,
+     *  ≈ moving 600px in 400ms, which only happens during a deliberate
+     *  upward sweep. */
+    threshold: number;
+    /** Rolling-window length over which to compute velocity. */
+    windowMs: number;
+    /** Cooldown after a fire before the signal can fire again. */
+    cooldownMs: number;
+}
+export interface TriggerEvent {
+    type: string;
+    data: Record<string, any>;
+    timestamp: number;
+}
+type TriggerCallback = (event: TriggerEvent) => void;
+export declare class TriggerEngine {
+    private listeners;
+    private isStarted;
+    private scrollDepthTargets;
+    private scrollDepthReached;
+    private timeOnPageTargets;
+    private pageLoadTime?;
+    private exitIntentEnabled;
+    private exitIntentFired;
+    private inactivityTargets;
+    private lastActivityTime;
+    private inactivityCheckInterval?;
+    private scrollVelocityEnabled;
+    private scrollVelocityFired;
+    private scrollVelocityConfig;
+    private lastScrollY;
+    private lastScrollTime;
+    private scrollVelocityCooldownTimer?;
+    private visibilityChangeEnabled;
+    private backButtonEnabled;
+    private backButtonFired;
+    private rageClickEnabled;
+    private rageClickConfig;
+    private rageClickBuffer;
+    /** Tracks whether a rage_click event has already fired for an intent
+     *  in the current burst. Reset when the buffer empties below threshold.
+     *  Prevents the same burst from firing the event N-2 times as each
+     *  click after threshold pushes the count higher. */
+    private rageClickFiredInBurst;
+    private hoverEnabled;
+    private hoverStartAt;
+    private hoverLastMs;
+    private hoverThresholds;
+    /** Track which (intent, threshold) pairs have already fired in the
+     *  current hover so a single long hover doesn't double-fire as time
+     *  marches on. Reset on hover_start. */
+    private hoverThresholdsFired;
+    /** Pending threshold timers, keyed by intent. Cleared on hover_end. */
+    private hoverThresholdTimers;
+    private mouseVelEnabled;
+    private mouseVelConfig;
+    /** Ring buffer of (x, y, ts) samples within the rolling window. */
+    private mouseSamples;
+    /** Last computed velocity-to-top in px/ms (positive = moving up). */
+    private mouseVelLast;
+    /** Epoch ms when the velocity event last fired — gates cooldown. */
+    private mouseVelLastFiredAt;
+    constructor();
+    on(eventType: string, callback: TriggerCallback): void;
+    off(eventType: string, callback: TriggerCallback): void;
+    registerScrollDepth(depthPercent: number): void;
+    registerTimeOnPage(seconds: number): void;
+    registerExitIntent(): void;
+    registerInactivity(idleSeconds: number): void;
+    registerScrollVelocity(config?: Partial<ScrollVelocityConfig>): void;
+    registerVisibilityChange(): void;
+    registerBackButton(): void;
+    /**
+     * Enable rage-click detection (P2 Task 1).
+     *
+     * After calling this, feed click events via `noteClick(intent)`.
+     * SelectorBinder (P1 Task 5) is the upstream source; the wiring lives
+     * in IntentSnapshotCollector (P2 Task 5). Calling `noteClick` without
+     * a prior `registerRageClick()` is a no-op so legacy callers don't
+     * accidentally enable the feature.
+     */
+    registerRageClick(config?: Partial<RageClickConfig>): void;
+    /**
+     * Feed a click event for rage-click detection. Returns the current
+     * count within-window for the intent — useful for the snapshot
+     * collector (P2 Task 5) which updates IntentRuleEvaluator with
+     * `rage_click_count` continuously, not just at the burst threshold.
+     *
+     * Idempotent w.r.t. `registerRageClick` — when not enabled, this
+     * returns 0 without buffering.
+     */
+    noteClick(intent: string, timestamp?: number): number;
+    /** Snapshot the current rage_click count for an intent. The
+     *  IntentSnapshotCollector (P2 Task 5) calls this when building the
+     *  `rage_click_count` signal value for the IntentRuleEvaluator. */
+    getRageClickCount(intent: string): number;
+    /**
+     * Enable hover-dwell tracking (P2 Task 2). After registration, feed
+     * hover events via `noteHoverStart(intent, ts)` / `noteHoverEnd`.
+     * SelectorBinder (P1 Task 5) is the upstream source; wiring lands in
+     * P2 Task 5.
+     */
+    registerHoverDwell(config?: HoverDwellConfig): void;
+    /** Record the start of a hover on the named intent. Schedules
+     *  per-threshold timers that emit `<intent>_hover_dwell_<ms>` when
+     *  the active hover passes each registered threshold. */
+    noteHoverStart(intent: string, timestamp?: number): void;
+    /** Record the end of a hover on the named intent. Updates the sticky
+     *  `lastHoverMs` so `getHoverMs` keeps returning the last-known
+     *  duration until the next hover_start. */
+    noteHoverEnd(intent: string, timestamp?: number): void;
+    /**
+     * Enable mouse-velocity-to-top tracking (P2 Task 3). After
+     * registration, feed positions via `noteMousePosition(x, y, ts?)`.
+     * IntentSnapshotCollector (P2 Task 5) wires window 'mousemove' to
+     * this method, with throttling to ~100ms per the plan.
+     */
+    registerMouseVelocityToTop(config?: Partial<MouseVelocityConfig>): void;
+    /** Feed a mouse-position sample. Recomputes the rolling-window
+     *  velocity-to-top and fires `mouse_velocity_to_top` when the value
+     *  crosses the configured threshold (subject to cooldown). */
+    noteMousePosition(x: number, y: number, timestamp?: number): number;
+    /** Snapshot the current velocity-to-top in px/ms (positive = up).
+     *  Returns 0 when not enabled or insufficient samples. */
+    getMouseVelocityToTop(): number;
+    /**
+     * Snapshot the hover dwell for an intent.
+     * - Currently hovering: returns `Date.now() - hover_start_at`.
+     * - Hovered before, not currently: returns the most recent hover's
+     *   duration (sticky — the rule evaluator queries this AFTER
+     *   mouseleave to see "did Priya hover the price ≥ 1.5s?").
+     * - Never hovered: returns 0.
+     */
+    getHoverMs(intent: string): number;
+    start(): void;
+    stop(): void;
+    reset(): void;
+    private attachScrollListener;
+    private removeScrollListener;
+    private handleScroll;
+    private attachExitIntentListener;
+    private removeExitIntentListener;
+    private handleExitIntent;
+    private attachScrollVelocityListener;
+    private removeScrollVelocityListener;
+    private handleScrollVelocity;
+    private attachVisibilityChangeListener;
+    private removeVisibilityChangeListener;
+    private handleVisibilityChange;
+    private attachBackButtonListener;
+    private removeBackButtonListener;
+    private handleBackButton;
+    private attachActivityListeners;
+    private removeActivityListeners;
+    private handleActivity;
+    private startInactivityCheck;
+    private emit;
+}
+export {};
+//# sourceMappingURL=TriggerEngine.d.ts.map

package/dist/triggers/TriggerEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TriggerEngine.d.ts","sourceRoot":"","sources":["../../src/triggers/TriggerEngine.ts"],"names":[],"mappings":"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"}

package/dist/triggers/behaviouralTriggers.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Behavioural in-app triggers — the builder's "When" options
+ * (`display_rules.trigger_type`, served as `client_trigger`) that wait on a
+ * visitor behaviour the TriggerEngine detects.
+ *
+ * ONE table maps each trigger to the client event it fires on, so the in-app
+ * manager's matcher and the runtime's arming read the same names. Defaults
+ * match the builder's (when-panel.tsx): 50 % scroll, 30 s on page, 30 s idle.
+ *
+ * `micro_intent` is NOT here: it is a compound rule the IntentRuleEvaluator
+ * owns, not one engine event.
+ */
+import type { TriggerEngine } from './TriggerEngine';
+export interface ClientTrigger {
+    type: string;
+    config?: Record<string, unknown>;
+}
+export declare const BEHAVIOURAL_TRIGGER_TYPES: readonly ["exit_intent", "scroll_depth", "time_on_page", "inactivity"];
+export declare const DEFAULT_SCROLL_DEPTH_PERCENT = 50;
+export declare const DEFAULT_TIME_ON_PAGE_SECONDS = 30;
+export declare const DEFAULT_IDLE_SECONDS = 30;
+/**
+ * The client event a behavioural trigger fires on — the TriggerEngine's own
+ * event name — or null when the trigger is not behavioural.
+ */
+export declare function behaviouralTriggerEvent(trigger: ClientTrigger | null | undefined): string | null;
+/**
+ * The inverse of `behaviouralTriggerEvent`: reads an engine event name
+ * (`exit_intent`, `inactivity_60`, `time_on_page_30`, `scroll_depth_50`) back
+ * into its trigger, for hosts that configure triggers by event name (the chat
+ * launcher's `proactiveTriggers`). Null for any other name.
+ */
+export declare function triggerFromEngineEvent(eventName: string): ClientTrigger | null;
+/**
+ * Arms the TriggerEngine for the behavioural triggers of `triggers` and calls
+ * `fire(eventName)` when one happens. Returns the events it newly armed, so a
+ * caller re-arming after each campaign refresh subscribes each event once.
+ *
+ * Exit intent: mouse leaving the top of the window on desktop; on mobile (no
+ * mouse) a fast scroll back up, which the engine reports as
+ * `mobile_exit_intent` and this forwards as `exit_intent`.
+ */
+export declare function armBehaviouralTriggers(engine: TriggerEngine, triggers: ReadonlyArray<ClientTrigger | null | undefined>, armed: Set<string>, fire: (eventName: string) => void, isMobile: boolean): string[];
+//# sourceMappingURL=behaviouralTriggers.d.ts.map

package/dist/triggers/behaviouralTriggers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"behaviouralTriggers.d.ts","sourceRoot":"","sources":["../../src/triggers/behaviouralTriggers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,eAAO,MAAM,yBAAyB,wEAK5B,CAAC;AAEX,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAC/C,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAC/C,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAOvC;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAehG;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAQ9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,aAAa,CAAC,aAAa,GAAG,IAAI,GAAG,SAAS,CAAC,EACzD,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,EAClB,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,EACjC,QAAQ,EAAE,OAAO,GAChB,MAAM,EAAE,CA+BV"}

package/dist/triggers/index.d.ts

@@ -0,0 +1,11 @@
+export { TriggerEngine } from './TriggerEngine';
+export type { TriggerRule, ScrollDepthConfig, TimeOnPageConfig, ExitIntentConfig, InactivityConfig, TriggerEvent, RageClickConfig, RageClickData, HoverDwellConfig, MouseVelocityConfig, } from './TriggerEngine';
+export { IntentRuleEvaluator, evaluateLeaf, evaluateExpr, evaluateRule, isIntentLeaf, isIntentNode, MAX_RULE_DEPTH, } from './IntentRuleEvaluator';
+export type { IntentSignal, Comparator, IntentLeafValue, IntentLeaf, IntentNode, IntentExpr, IntentRule, IntentSnapshot, SignalValue, ArmedCampaign, EvaluationDecision, } from './IntentRuleEvaluator';
+export { SelectorBinder } from './SelectorBinder';
+export type { IntentElementName, IntentDomEventType, IntentDomEvent, IntentDomHandler, IntentSelectors, SelectorBinderConfig, } from './SelectorBinder';
+export { IntentSnapshotCollector } from './IntentSnapshotCollector';
+export type { IntentSnapshotCollectorConfig } from './IntentSnapshotCollector';
+export { ContactScoresFetcher, toIntentSnapshot } from './ContactScoresFetcher';
+export type { ContactScoresFetcherConfig, ContactScoresResponse } from './ContactScoresFetcher';
+//# sourceMappingURL=index.d.ts.map

package/dist/triggers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/triggers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EACV,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,YAAY,EACZ,UAAU,EACV,eAAe,EACf,UAAU,EACV,UAAU,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,WAAW,EACX,aAAa,EACb,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,YAAY,EAAE,6BAA6B,EAAE,MAAM,2BAA2B,CAAC;AAG/E,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAChF,YAAY,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/triggers/microIntentTriggers.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Smart trigger (`micro_intent`) arming — the production caller the
+ * IntentRuleEvaluator never had (Aman 2026-09-28, plan
+ * GAMIFICATION_ENGAGEMENT_TARGETING_PLAN §0d).
+ *
+ * A `micro_intent` campaign is served as `client_trigger: { type:
+ * 'micro_intent', config: <IntentRule> }`. Before this module nothing called
+ * `setArmed`, nothing turned a TriggerEngine event into an evaluator signal,
+ * and `converted_in_session` was never written — so `NOT(converted)` stayed
+ * null and every rule carrying it could never fire.
+ *
+ * This arms the evaluator on every campaign load, registers the engine
+ * thresholds the rules read (the `fire_on` signals and every numeric leaf of
+ * `time_on_page` / `scroll_depth` / `inactivity`), writes each engine event
+ * into the snapshot, and asks the evaluator for a decision.
+ *
+ * Signals owned elsewhere: Layer-1 scores (ContactScoresFetcher), `cart_value`
+ * (runtime updateContext). Hover / rage-click / SKU dwell need the
+ * IntentSnapshotCollector + SelectorBinder, which no host wires yet — rules on
+ * them stay unmet (null), never fire.
+ */
+import type { TriggerEngine } from './TriggerEngine';
+import type { ArmedCampaign, IntentRule, IntentRuleEvaluator } from './IntentRuleEvaluator';
+import { type ClientTrigger } from './behaviouralTriggers';
+export declare const MICRO_INTENT_TRIGGER_TYPE = "micro_intent";
+/** Signals whose value is a count the engine reports at registered thresholds. */
+declare const THRESHOLD_SIGNALS: {
+    readonly time_on_page: 30;
+    readonly scroll_depth: 50;
+    readonly inactivity: 30;
+};
+type ThresholdSignal = keyof typeof THRESHOLD_SIGNALS;
+/** The rule a `micro_intent` trigger carries, or null when it is not one or is malformed. */
+export declare function microIntentRule(trigger: ClientTrigger | null | undefined): IntentRule | null;
+/** Every loaded campaign whose client trigger is a well-formed smart trigger. */
+export declare function armedMicroIntentCampaigns(campaigns: ReadonlyArray<{
+    id: string;
+    client_trigger?: ClientTrigger | null;
+}>): ArmedCampaign[];
+/**
+ * The engine thresholds at which `signal` must be observed for `rules` to be
+ * decided truthfully: each numeric leaf's crossing point (`gte 8` → 8,
+ * `gt 8` → 9), plus the builder default when a rule fires on the signal but
+ * never names a value.
+ */
+export declare function signalThresholds(rules: ReadonlyArray<IntentRule>, signal: ThresholdSignal): number[];
+export interface MicroIntentArmingConfig {
+    engine: TriggerEngine;
+    evaluator: IntentRuleEvaluator;
+    /** Display the campaign; true only when it actually showed. */
+    show: (campaignId: string) => boolean;
+    /** Whether this session already converted (the in-app manager's record). */
+    hasConverted: () => boolean;
+    /** No hovering pointer: exit intent is the engine's fast scroll up. */
+    isMobile: boolean;
+}
+export declare class MicroIntentArming {
+    private readonly cfg;
+    private readonly registered;
+    private listening;
+    private readonly onEngineEvent;
+    constructor(cfg: MicroIntentArmingConfig);
+    /** Replace the armed rules with the smart triggers among `campaigns`. */
+    arm(campaigns: ReadonlyArray<{
+        id: string;
+        client_trigger?: ClientTrigger | null;
+    }>): void;
+    /** The host reported a conversion: rules gated on NOT converted stop matching. */
+    noteConversion(): void;
+    destroy(): void;
+    private once;
+    /** Subscribe once, and seed the page-start values: nothing scrolled, no
+     *  time elapsed, no exit yet, conversion as the manager recorded it. A null
+     *  here would make every AND/NOT over these signals unprovable. */
+    private listen;
+    private handle;
+    private decide;
+}
+export {};
+//# sourceMappingURL=microIntentTriggers.d.ts.map

package/dist/triggers/microIntentTriggers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"microIntentTriggers.d.ts","sourceRoot":"","sources":["../../src/triggers/microIntentTriggers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EACV,aAAa,EAEb,UAAU,EACV,mBAAmB,EAEpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,uBAAuB,CAAC;AAE/B,eAAO,MAAM,yBAAyB,iBAAiB,CAAC;AAExD,kFAAkF;AAClF,QAAA,MAAM,iBAAiB;;;;CAIb,CAAC;AACX,KAAK,eAAe,GAAG,MAAM,OAAO,iBAAiB,CAAC;AAItD,6FAA6F;AAC7F,wBAAgB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,GAAG,UAAU,GAAG,IAAI,CAe5F;AAED,iFAAiF;AACjF,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,aAAa,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,aAAa,GAAG,IAAI,CAAA;CAAE,CAAC,GAC9E,aAAa,EAAE,CAOjB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,eAAe,GAAG,MAAM,EAAE,CAgBpG;AAOD,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,mBAAmB,CAAC;IAC/B,+DAA+D;IAC/D,IAAI,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;IACtC,4EAA4E;IAC5E,YAAY,EAAE,MAAM,OAAO,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA0B;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA0D;gBAE5E,GAAG,EAAE,uBAAuB;IAIxC,yEAAyE;IACzE,GAAG,CAAC,SAAS,EAAE,aAAa,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,aAAa,GAAG,IAAI,CAAA;KAAE,CAAC,GAAG,IAAI;IAwB1F,kFAAkF;IAClF,cAAc,IAAI,IAAI;IAItB,OAAO,IAAI,IAAI;IAKf,OAAO,CAAC,IAAI;IAMZ;;uEAEmE;IACnE,OAAO,CAAC,MAAM;IAmBd,OAAO,CAAC,MAAM;IAwBd,OAAO,CAAC,MAAM;CAQf"}

package/dist/types/config.d.ts

@@ -0,0 +1,77 @@
+export type CellRegion = 'us-east' | 'us-west' | 'eu-central' | 'ap-south' | 'ap-southeast';
+export interface CellEndpoint {
+    region: CellRegion;
+    url: string;
+    priority: number;
+    healthy: boolean;
+}
+export interface AegisConfig {
+    write_key: string;
+    workspace_id?: string;
+    api_host?: string;
+    cell_endpoints?: CellEndpoint[];
+    preferred_region?: CellRegion;
+    auto_region_detection?: boolean;
+    batch_size?: number;
+    batch_interval?: number;
+    capture_utm?: boolean;
+    capture_referrer?: boolean;
+    auto_page_view?: boolean;
+    session_timeout?: number;
+    debug?: boolean;
+    respect_dnt?: boolean;
+    cross_domain_tracking?: boolean;
+    cookie_domain?: string;
+    secure_cookie?: boolean;
+    enable_offline_mode?: boolean;
+    max_offline_events?: number;
+    retry_failed_requests?: boolean;
+    max_retries?: number;
+    retry_backoff_multiplier?: number;
+    request_timeout?: number;
+    /** Client-side rate limiter — burst (token bucket capacity). Default 100. */
+    rate_limit_burst?: number;
+    /** Client-side rate limiter — sustained tokens per second. Default 20. */
+    rate_limit_per_second?: number;
+    plugins?: string[];
+    wait_for_consent?: boolean;
+    default_consent?: {
+        analytics?: boolean;
+        marketing?: boolean;
+        functional?: boolean;
+    };
+    enable_consent_mode?: boolean;
+    integrate_onetrust?: boolean;
+    integrate_cookiebot?: boolean;
+    integrate_google_consent_mode?: boolean;
+    /** Push notification configuration. When provided, AegisWebPush is initialized. */
+    push?: {
+        /** VAPID public key for Web Push subscription. */
+        vapidPublicKey: string;
+        /** Automatically prompt for push permission after SDK init. Default: false. */
+        autoPrompt?: boolean;
+        /** Delay in ms before showing auto-prompt. Default: 5000. */
+        promptDelay?: number;
+        /** Path to the service worker file. Default: '/aegis-sw.js'. */
+        serviceWorkerPath?: string;
+        /** Scope for the service worker registration. Default: '/'. Critical for e-commerce platforms. */
+        serviceWorkerScope?: string;
+    };
+}
+export interface AegisConfigInternal extends Required<Omit<AegisConfig, 'api_host' | 'cell_endpoints' | 'preferred_region' | 'cookie_domain' | 'plugins' | 'default_consent' | 'workspace_id'>> {
+    initialized: boolean;
+    workspace_id: string | null;
+    api_host: string | null;
+    cell_endpoints: CellEndpoint[];
+    preferred_region: CellRegion | null;
+    cookie_domain: string | null;
+    plugins: string[];
+    active_cell: CellEndpoint | null;
+    default_consent: {
+        analytics: boolean;
+        marketing: boolean;
+        functional: boolean;
+    };
+}
+export declare const DEFAULT_CONFIG: Partial<AegisConfigInternal>;
+//# sourceMappingURL=config.d.ts.map

package/dist/types/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"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"}