@amplitude/experiment-tag 0.18.0 → 0.19.0

package/dist/types/src/behavioral-targeting/behavioral-targeting-manager.d.ts

@@ -0,0 +1,73 @@
+import { BehavioralTargetingRules } from '../types';
+/**
+ * Manages all behavioral targeting functionality including event storage,
+ * session management, and rule evaluation.
+ */
+export declare class BehavioralTargetingManager {
+    private readonly sessionManager;
+    private readonly eventStorage;
+    private evaluator;
+    private readonly rules;
+    private readonly matchedBehaviors;
+    private readonly eventToBehaviors;
+    constructor(apiKey: string, initialRules?: BehavioralTargetingRules);
+    /**
+     * Track an event for behavioral targeting evaluation.
+     * Automatically updates the active behavior state for affected flags.
+     * @param eventType The event type/name
+     * @param properties Event properties
+     */
+    trackEvent(eventType: string, properties: Record<string, unknown>): void;
+    /**
+     * Check if a flag has behavioral targeting rules.
+     * @param flagKey The flag key to check
+     * @returns true if the flag has behavioral targeting rules
+     */
+    hasRules(flagKey: string): boolean;
+    /**
+     * Get the currently matched behavioral targeting rules.
+     * @returns Map of flag keys to sets of matched behavior IDs
+     */
+    getMatchedBehaviors(): Map<string, Set<string>>;
+    /**
+     * Cleanup method to remove event listeners and flush pending writes.
+     * Should be called when BehavioralTargetingManager is no longer needed.
+     */
+    cleanup(): void;
+    /**
+     * Build a map of event types to the behavior IDs and flag keys that reference them.
+     * This allows efficient lookup of which specific behaviors need re-evaluation when an event is tracked.
+     */
+    private buildEventToBehaviorsMap;
+    /**
+     * Extract all event types referenced in behavioral targeting rules.
+     * @param rules The behavioral targeting rules to scan
+     * @returns Set of event types referenced in the rules
+     */
+    private extractEventTypes;
+    /**
+     * Evaluate all behavioral targeting rules.
+     * Directly updates the matchedBehaviors state for all flags.
+     */
+    private evaluateAll;
+    /**
+     * Evaluate behavioral targeting rules for a specific event type.
+     * Only re-evaluates the specific behavior IDs that reference this event type.
+     * Directly updates the matchedBehaviors state for affected flags.
+     * @param eventType The event type/name
+     */
+    private evaluateEvent;
+    /**
+     * Evaluate behavioral targeting rules for a specific flag.
+     * Directly updates the matchedBehaviors state with all matching behavior IDs.
+     * @param flagKey The flag key to evaluate
+     */
+    private evaluateFlag;
+    /**
+     * Evaluate a specific behavior ID for a flag.
+     * Updates only the specified behavior ID in the matchedBehaviors state.
+     * @param flagKey The flag key to evaluate
+     * @param behaviorId The specific behavior ID to evaluate
+     */
+    private evaluateBehaviorId;
+}

package/dist/types/src/behavioral-targeting/evaluator.d.ts

@@ -0,0 +1,36 @@
+import { EventStorageManager } from './event-storage';
+import { BehavioralTargeting } from './types';
+/**
+ * Evaluates behavioral targeting rules using stored events.
+ */
+export declare class BehavioralTargetingEvaluator {
+    private eventStorage;
+    private evaluationEngine;
+    constructor(eventStorage: EventStorageManager);
+    /**
+     * Evaluates a behavioral targeting rule (DNF structure).
+     * Returns true if the user matches the targeting criteria.
+     */
+    evaluate(rules: BehavioralTargeting): boolean;
+    /**
+     * Evaluates an AND group of conditions.
+     */
+    private evaluateAndGroup;
+    /**
+     * Evaluates a single condition set (with optional negation).
+     */
+    private evaluateConditionSet;
+    /**
+     * Evaluates a single behavioral condition.
+     */
+    private evaluateCondition;
+    /**
+     * Evaluates property filters using EvaluationEngine.
+     * The backend has already translated property filters to EvaluationCondition format.
+     */
+    private evaluatePropertyFilters;
+    /**
+     * Evaluates count operators.
+     */
+    private evaluateCountOperator;
+}

package/dist/types/src/behavioral-targeting/event-storage.d.ts

@@ -0,0 +1,92 @@
+import { SessionManager } from './session-manager';
+/**
+ * Represents a stored event record.
+ */
+export interface EventRecord {
+    id: number;
+    event_type: string;
+    timestamp: number;
+    session_id: string;
+    properties: Record<string, unknown>;
+}
+/**
+ * Manages event storage with in-memory cache and debounced localStorage persistence.
+ * All reads are from memory for performance, writes are debounced to localStorage.
+ */
+export declare class EventStorageManager {
+    private static readonly MAX_EVENTS;
+    private static readonly DEBOUNCE_MS;
+    private sessionManager;
+    private memoryCache;
+    private debouncedWriteTimeout;
+    private hasPendingWrites;
+    private persistedEvents?;
+    private storageKey;
+    constructor(apiKey: string, sessionManager: SessionManager, persistedEvents?: Set<string>);
+    /**
+     * Adds an event to in-memory cache with automatic session tracking.
+     * Triggers debounced write to localStorage.
+     * If persistedEvents is set, only events with matching event types will be stored.
+     */
+    addEvent(eventType: string, properties?: Record<string, unknown>, eventTime?: number): void;
+    /**
+     * Gets all events from in-memory cache (for testing/debugging).
+     */
+    getAllEvents(): EventRecord[];
+    /**
+     * Gets events filtered by event type from in-memory cache.
+     */
+    getEventsByType(eventType: string): EventRecord[];
+    /**
+     * Gets events in a time window from in-memory cache.
+     */
+    getEventsInTimeWindow(eventType: string, timeType: 'current_session' | 'rolling', timeValue: number, interval?: 'day' | 'hour'): EventRecord[];
+    /**
+     * Clears all events from memory and localStorage.
+     */
+    clearEvents(): void;
+    /**
+     * Manually flushes pending writes to localStorage.
+     * Useful for testing or when immediate persistence is required.
+     */
+    flush(): void;
+    /**
+     * Gets event count for an event type.
+     */
+    getEventCount(eventType: string): number;
+    /**
+     * Gets event count in a time window.
+     */
+    getEventCountInTimeWindow(eventType: string, timeType: 'current_session' | 'rolling', timeValue: number, interval?: 'day' | 'hour'): number;
+    /**
+     * Loads data from localStorage into memory on initialization.
+     */
+    private loadFromLocalStorage;
+    /**
+     * Schedules a debounced write to localStorage.
+     * Resets the timer on each call to batch multiple writes together.
+     */
+    private scheduleDebouncedWrite;
+    /**
+     * Immediately writes in-memory cache to localStorage.
+     */
+    private flushToLocalStorage;
+    /**
+     * Sets up event handlers to flush data before page unload or when tab is hidden.
+     * This prevents data loss on page close or backgrounding.
+     */
+    private setupFlushHandlers;
+    /**
+     * Handler for beforeunload event.
+     */
+    private handleBeforeUnload;
+    /**
+     * Handler for visibilitychange event.
+     */
+    private handleVisibilityChange;
+    /**
+     * Cleanup method to remove event listeners.
+     * Should be called when EventStorageManager is no longer needed.
+     */
+    cleanup(): void;
+}

package/dist/types/src/behavioral-targeting/index.d.ts

@@ -0,0 +1,2 @@
+export { BehavioralTargetingManager } from './behavioral-targeting-manager';
+export { BehavioralTargeting, BehavioralCondition, BehavioralConditionSet, } from './types';

package/dist/types/src/behavioral-targeting/session-manager.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Manages browser session ID using sessionStorage.
+ * Session ID is unique per browser tab and cleared when tab closes.
+ */
+export declare class SessionManager {
+    private storageKey;
+    private sessionId?;
+    private sessionStartTime?;
+    constructor(apiKey: string);
+    /**
+     * Gets the current session ID, creating one if it doesn't exist.
+     * Uses sessionStorage (cleared when tab closes).
+     */
+    getOrCreateSessionId(): string;
+    /**
+     * Gets the session start time in milliseconds since epoch.
+     */
+    getSessionStartTime(): number | undefined;
+    /**
+     * Generates a unique session ID.
+     */
+    private generateSessionId;
+    /**
+     * Clears the current session (for testing).
+     */
+    clearSession(): void;
+}

package/dist/types/src/behavioral-targeting/types.d.ts

@@ -0,0 +1,29 @@
+import { EvaluationCondition } from '@amplitude/experiment-core';
+/**
+ * Behavioral targeting uses DNF (Disjunctive Normal Form): OR of ANDs
+ * Structure: [[ConditionSet, ConditionSet], [ConditionSet]]
+ * - Outer array: OR operator between groups
+ * - Inner array: AND operator within each group
+ * - Each condition can be negated individually
+ */
+export type BehavioralTargeting = Array<Array<BehavioralConditionSet>>;
+/**
+ * A condition set with optional negation.
+ */
+export interface BehavioralConditionSet {
+    condition: BehavioralCondition;
+    negated?: boolean;
+}
+/**
+ * A behavioral condition
+ */
+export interface BehavioralCondition {
+    type: 'event';
+    type_value: string;
+    operator: '>=' | '>' | '=' | '<' | '<=' | '!=' | 'is set' | 'is not set';
+    operator_value: number;
+    time_type: 'current_session' | 'rolling';
+    time_value: number;
+    interval?: 'day' | 'hour';
+    event_props?: EvaluationCondition[];
+}

package/dist/types/src/experiment.d.ts

@@ -1,7 +1,7 @@
 import { Plugin } from '@amplitude/analytics-types';
 import { ExperimentClient, Variants } from '@amplitude/experiment-js-client';
 import { MutationController } from 'dom-mutator';
-import { PageChangeEvent } from './subscriptions';
+import { PageChangeEvent } from './subscriptions/subscriptions';
 import { WebExperimentClient, WebExperimentConfig } from './types';
 import { ApplyVariantsOptions, PageObject, PageObjects, PreviewVariantsOptions, RevertVariantsOptions } from './types';
 import type { DebugState } from './types/debug';

package/dist/types/src/subscriptions/subscription-refactor.d.ts

@@ -0,0 +1,46 @@
+import { DefaultWebExperimentClient } from '../experiment';
+import { PageObjects } from '../types';
+import { MessageBus } from './message-bus';
+type initOptions = {
+    useDefaultNavigationHandler?: boolean;
+    isVisualEditorMode?: boolean;
+};
+export type PageChangeEvent = {
+    activePages: PageObjects;
+};
+export declare class SubscriptionManager {
+    private webExperimentClient;
+    private messageBus;
+    private pageObjects;
+    private options;
+    private readonly globalScope;
+    private triggerManagers;
+    private pageChangeSubscribers;
+    private lastNotifiedActivePages;
+    constructor(webExperimentClient: DefaultWebExperimentClient, messageBus: MessageBus, pageObjects: PageObjects, options: initOptions, globalScope: typeof globalThis);
+    setPageObjects: (pageObjects: PageObjects) => void;
+    markUrlAsPublished: (url: string) => void;
+    initSubscriptions: () => void;
+    /**
+     * Adds a subscriber to the page change event. Returns a function to unsubscribe.
+     */
+    addPageChangeSubscriber: (callback: (event: PageChangeEvent) => void) => (() => void);
+    /**
+     * Get debug snapshots from all trigger managers
+     */
+    getManagerSnapshots(): Record<string, any>;
+    /**
+     * Create trigger managers only for trigger types that have page objects.
+     * Special handling:
+     * - element_appeared tracks selectors from element_appeared, element_visible, and scrolled_to
+     * - url_change is always initialized with ALL page objects
+     */
+    private initializeTriggerManagers;
+    private initializeManager;
+    private groupPageObjectsByType;
+    private setupPageObjectSubscriptions;
+    private isPageObjectActive;
+    private resetAllTriggers;
+    private revertInjections;
+}
+export {};

package/dist/types/src/{subscriptions.d.ts → subscriptions/subscriptions.d.ts}

@@ -1,7 +1,7 @@
-import { DefaultWebExperimentClient } from './experiment';
-import { MessageBus } from './subscriptions/message-bus';
-import { PageObjects } from './types';
-import type { DebugState, PageObjectDebugInfo } from './types/debug';
+import { DefaultWebExperimentClient } from '../experiment';
+import { PageObjects } from '../types';
+import { DebugState, PageObjectDebugInfo } from '../types/debug';
+import { MessageBus } from './message-bus';
 type initOptions = {
     useDefaultNavigationHandler?: boolean;
     isVisualEditorMode?: boolean;
@@ -37,6 +37,8 @@ export declare class SubscriptionManager {
     private lastPublishedUrl;
     private debugStateSubscribers;
     private debugDebounceTimer;
+    private get contentDocument();
+    private get contentWindow();
     constructor(webExperimentClient: DefaultWebExperimentClient, messageBus: MessageBus, pageObjects: PageObjects, options: initOptions, globalScope: typeof globalThis);
     setPageObjects: (pageObjects: PageObjects) => void;
     markUrlAsPublished: (url: string) => void;

package/dist/types/src/triggers/base-trigger-manager.d.ts

@@ -0,0 +1,80 @@
+import { MessageBus, MessagePayloads, MessageType } from '../subscriptions/message-bus';
+import { PageObject } from '../types';
+import { TriggerManagerOptions } from './index';
+/**
+ * Base interface that all trigger managers must implement.
+ * Each trigger type (element_visible, user_interaction, etc.) has its own manager.
+ */
+export interface TriggerManager<TPayload = any> {
+    /**
+     * Trigger type this manager handles
+     */
+    readonly triggerType: MessageType;
+    /**
+     * Initialize listeners, observers, and event handlers for this trigger type.
+     * Called once during setup.
+     */
+    initialize(): void;
+    /**
+     * Check if a specific page object is currently active based on trigger state.
+     * @param page - The page object to check
+     * @param payload - Optional message payload (for event-driven triggers)
+     */
+    isActive(page: PageObject, payload?: TPayload): boolean;
+    /**
+     * Reset trigger state (called on URL change).
+     * Should clear state but may keep listeners active if appropriate.
+     */
+    reset(): void;
+    /**
+     * Get debug snapshot of current state (optional, for debugging).
+     */
+    getSnapshot?(): Record<string, any>;
+    /**
+     * Mark a URL as published (optional, for url_change manager).
+     */
+    markUrlAsPublished?(url: string): void;
+    /**
+     * Trigger an initial check (optional, for element_appeared manager).
+     */
+    triggerInitialCheck?(): void;
+}
+/**
+ * Abstract base class providing common functionality for trigger managers.
+ * Reduces boilerplate in individual managers.
+ */
+export declare abstract class BaseTriggerManager<TPayload = any> implements TriggerManager<TPayload> {
+    protected readonly pageObjects: PageObject[];
+    protected readonly messageBus: MessageBus;
+    protected readonly globalScope: typeof globalThis;
+    protected readonly options?: TriggerManagerOptions | undefined;
+    constructor(pageObjects: PageObject[], messageBus: MessageBus, globalScope: typeof globalThis, options?: TriggerManagerOptions | undefined);
+    abstract readonly triggerType: MessageType;
+    abstract initialize(): void;
+    abstract isActive(page: PageObject, payload?: TPayload): boolean;
+    abstract reset(): void;
+    /**
+     * Publish message to message bus
+     */
+    protected publish(payload?: MessagePayloads[MessageType]): void;
+    /**
+     * Helper to get trigger value with proper typing
+     */
+    protected getTriggerValue<T>(page: PageObject): T;
+    /**
+     * Helper to clear a timeout safely
+     */
+    protected clearTimeout(timeoutId: ReturnType<typeof setTimeout>): void;
+    /**
+     * Helper to clear multiple timeouts
+     */
+    protected clearTimeouts(timeouts: Iterable<ReturnType<typeof setTimeout>>): void;
+    /**
+     * Helper to disconnect an observer safely
+     */
+    protected disconnectObserver(observer: IntersectionObserver): void;
+    /**
+     * Helper to disconnect multiple observers
+     */
+    protected disconnectObservers(observers: Iterable<IntersectionObserver>): void;
+}

package/dist/types/src/triggers/index.d.ts

@@ -0,0 +1,20 @@
+import { MessageBus, MessageType } from '../subscriptions/message-bus';
+import { PageObject } from '../types';
+import { TriggerManager } from './base-trigger-manager';
+export * from './base-trigger-manager';
+/**
+ * Options that can be passed to trigger managers during initialization.
+ */
+export interface TriggerManagerOptions {
+    useDefaultNavigationHandler?: boolean;
+}
+/**
+ * Trigger types that have dedicated managers.
+ * Note: element_appeared_internal is a message type but not a trigger type.
+ */
+type TriggerType = Exclude<MessageType, 'element_appeared_internal'>;
+/**
+ * Registry of trigger managers available in this version.
+ * Trigger managers will be added in subsequent PRs.
+ */
+export declare const TRIGGER_MANAGER_REGISTRY: Partial<Record<TriggerType, new (pageObjects: PageObject[], messageBus: MessageBus, globalScope: typeof globalThis, options?: TriggerManagerOptions) => TriggerManager>>;

package/dist/types/src/types.d.ts

@@ -1,6 +1,7 @@
 import { EvaluationCondition } from '@amplitude/experiment-core';
 import { ExperimentConfig, ExperimentUser } from '@amplitude/experiment-js-client';
 import { ExperimentClient, Variants } from '@amplitude/experiment-js-client';
+import { BehavioralTargeting } from './behavioral-targeting';
 import { MessageType } from './subscriptions/message-bus';
 import type { DebugState } from './types/debug';
 export type ApplyVariantsOptions = {
@@ -69,6 +70,15 @@ export type PageObjects = {
         [id: string]: PageObject;
     };
 };
+/**
+ * Map of behavioral targeting rules per flag key.
+ * Each flag has ONE outer OR array for behavioral targeting.
+ */
+export type BehavioralTargetingRules = {
+    [flagKey: string]: {
+        [id: string]: BehavioralTargeting;
+    };
+};
 export interface WebExperimentConfig extends ExperimentConfig {
     /**
      * Determines whether the default implementation for handling navigation  will be used

package/dist/types/src/util/shell.d.ts

@@ -1,4 +1,21 @@
 export declare function isMobileModeActive(): boolean;
+/**
+ * Returns the device iframe element when the customer page is rendered inside
+ * it (mobile viewport mode), or null when running in the top frame.
+ */
+export declare function getDeviceIframe(): HTMLIFrameElement | null;
+/**
+ * Returns the Document for the customer page. In mobile viewport mode the
+ * customer site lives inside a same-origin iframe; otherwise it is the
+ * top-level document.
+ */
+export declare function getCustomerDocument(globalScope: typeof globalThis): Document;
+/**
+ * Returns the Window for the customer page. In mobile viewport mode the
+ * customer site lives inside a same-origin iframe; otherwise it is the
+ * top-level window.
+ */
+export declare const getCustomerWindow: (globalScope: typeof globalThis) => Window & typeof globalThis;
 /**
  * Replaces the page DOM with a shell container that loads the customer site
  * in a same-origin iframe. Deferred until the document is fully parsed so

package/dist/types/src/util/triggers/mutation.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared utilities for working with MutationObserver.
+ */
+/**
+ * Check if a mutation is relevant to a specific CSS selector.
+ * Returns true if the mutation affects elements matching the selector.
+ *
+ * @param mutationList - List of mutations to check
+ * @param selector - CSS selector to match against
+ * @returns true if any mutation is relevant to the selector
+ */
+export declare function isMutationRelevantToSelector(mutationList: MutationRecord[], selector: string): boolean;

package/dist/types/src/util/triggers/trigger-state-keys.d.ts

@@ -0,0 +1,44 @@
+import { UserInteractionType } from '../../types';
+/**
+ * Utilities for generating consistent state keys.
+ * All key generation is centralized here to ensure consistency across the codebase.
+ *
+ * Keys use null character (\0) as delimiter to avoid collisions with user input.
+ */
+export declare class TriggerStateKeys {
+    private static readonly DELIMITER;
+    /**
+     * Create visibility key: "selector\0ratio"
+     * Used for element_visible triggers with IntersectionObserver
+     */
+    static visibility(selector: string, ratio: number): string;
+    /**
+     * Parse visibility key back to components
+     */
+    static parseVisibility(key: string): {
+        selector: string;
+        ratio: number;
+    };
+    /**
+     * Create user interaction key: "selector\0type\0threshold"
+     * Used for tracking click/hover/focus interactions
+     */
+    static userInteraction(selector: string, type: UserInteractionType, threshold: number): string;
+    /**
+     * Create scrolled-to key: "selector\0offset"
+     * Used for element-based scrolled_to triggers
+     */
+    static scrolledTo(selector: string, offset: number): string;
+    /**
+     * Parse scrolled-to key back to components
+     */
+    static parseScrolledTo(key: string): {
+        selector: string;
+        offset: number;
+    };
+    /**
+     * Create timeout key for threshold-based interactions
+     * Used internally for managing hover/focus timeouts
+     */
+    static timeout(selector: string, threshold: number): string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amplitude/experiment-tag",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Amplitude Experiment Javascript Snippet",
   "author": "Amplitude",
   "homepage": "https://github.com/amplitude/experiment-js-client",
@@ -30,7 +30,7 @@
     "@amplitude/analytics-core": "^2.21.0",
     "@amplitude/analytics-types": "^2.11.0",
     "@amplitude/experiment-core": "^0.12.0",
-    "@amplitude/experiment-js-client": "^1.20.3",
+    "@amplitude/experiment-js-client": "^1.20.4",
     "dom-mutator": "git+ssh://git@github.com/amplitude/dom-mutator#0294e723c6a8f85d448bdfa59999591f2ae9e476",
     "rollup-plugin-license": "^3.6.0"
   },
@@ -42,5 +42,5 @@
   "files": [
     "dist"
   ],
-  "gitHead": "3f9fcfdf64e686fbd12f975c98537cd2262cfef2"
+  "gitHead": "5ddeb989c0c9ef622e80605fecbe7ac52702d608"
 }