@absmartly/sdk-plugins 1.0.1

package/types/core/DOMManipulatorLite.d.ts

@@ -0,0 +1,21 @@
+import { DOMChange } from '../types';
+import type { DOMChangesPluginLite } from './DOMChangesPluginLite';
+import { PendingChangeManager } from './PendingChangeManager';
+export declare class DOMManipulatorLite {
+    protected debug: boolean;
+    protected plugin: DOMChangesPluginLite;
+    protected pendingManager: PendingChangeManager;
+    private appliedChanges;
+    constructor(debug: boolean | undefined, plugin: DOMChangesPluginLite);
+    applyChange(change: DOMChange, experimentName: string): boolean;
+    protected moveElement(element: Element, target: Element, position?: string): void;
+    private createElement;
+    private applyStyleRules;
+    applyChangeToElement(element: Element, change: DOMChange): void;
+    private applyChangeToSpecificElement;
+    private trackAppliedChange;
+    hasChanges(experimentName: string): boolean;
+    clearTracking(experimentName?: string): void;
+    removeAllPending(experimentName: string): void;
+    destroy(): void;
+}

package/types/core/ExposureTracker.d.ts

@@ -0,0 +1,81 @@
+import { ABsmartlyContext, DOMChange } from '../types';
+export declare class ExposureTracker {
+    private context;
+    private experiments;
+    private trackedElements;
+    private observer;
+    private mutationObserver;
+    private debug;
+    private placeholders;
+    constructor(context: ABsmartlyContext, debug?: boolean);
+    /**
+     * Register an experiment with all its variants' changes for comprehensive tracking
+     */
+    registerExperiment(experimentName: string, currentVariant: number, currentChanges: DOMChange[], allVariantsChanges: DOMChange[][]): void;
+    /**
+     * Create a container-based placeholder at the hypothetical position
+     * Uses inline-block with minimal dimensions to be observable but not affect layout
+     */
+    private createContainerPlaceholder;
+    /**
+     * Get the original parent selector for move changes
+     * This should be called BEFORE the move is applied
+     */
+    getOriginalParentForMove(selector: string): string | null;
+    /**
+     * Get a stable selector for a parent element
+     */
+    private getStableParentSelector;
+    /**
+     * Set up observers for the given selectors
+     */
+    private observeSelectors;
+    /**
+     * Track an element for viewport visibility
+     */
+    private trackElement;
+    /**
+     * Watch for elements matching a selector to appear
+     */
+    private watchForSelector;
+    /**
+     * Set up the IntersectionObserver for viewport tracking
+     */
+    private setupIntersectionObserver;
+    /**
+     * Set up MutationObserver for dynamic elements
+     */
+    private setupMutationObserver;
+    /**
+     * Check if a newly added element needs tracking
+     */
+    private checkNewElement;
+    /**
+     * Handle when an element becomes visible
+     */
+    private handleElementVisible;
+    /**
+     * Trigger exposure for an experiment
+     */
+    private triggerExposure;
+    /**
+     * Clean up tracking for an experiment that has been triggered
+     */
+    private cleanupExperiment;
+    /**
+     * Get a selector string for an element (for debugging)
+     */
+    private getElementSelector;
+    /**
+     * Check if an experiment needs viewport tracking
+     */
+    needsViewportTracking(experimentName: string): boolean;
+    /**
+     * Check if an experiment has been triggered
+     */
+    isTriggered(experimentName: string): boolean;
+    /**
+     * Clean up all resources
+     */
+    destroy(): void;
+}

package/types/core/HTMLInjector.d.ts

@@ -0,0 +1,19 @@
+import { InjectionItem, InjectionLocation, InjectionDataWithFilter } from '../types';
+export declare class HTMLInjector {
+    private debug;
+    private injectedIds;
+    constructor(debug?: boolean);
+    parseInjectionKey(key: string): {
+        location: InjectionLocation;
+        priority: number;
+    } | null;
+    collectInjections(allInjectHTML: Map<string, Map<number, InjectionDataWithFilter>>, currentUrl?: string): Map<InjectionLocation, InjectionItem[]>;
+    inject(injectionsByLocation: Map<InjectionLocation, InjectionItem[]>): void;
+    private injectAtLocation;
+    private injectHeadStart;
+    private injectHeadEnd;
+    private injectBodyStart;
+    private injectBodyEnd;
+    private createContainer;
+    destroy(): void;
+}

package/types/core/PendingChangeManager.d.ts

@@ -0,0 +1,31 @@
+import { DOMChange } from '../types';
+export interface PendingChange {
+    change: DOMChange;
+    experimentName: string;
+    observerRoot?: string;
+}
+export declare class PendingChangeManager {
+    private applyFn;
+    private pending;
+    private observers;
+    private appliedSelectors;
+    private debug;
+    private batchTimer;
+    private batchedWork;
+    constructor(applyFn: (change: DOMChange, experimentName: string, element?: Element) => boolean, debug?: boolean);
+    addPending(pendingChange: PendingChange): void;
+    removePending(selector: string, experimentName: string, observerRoot?: string): void;
+    removeAllPending(experimentName: string): void;
+    private ensureObserver;
+    private handleMutations;
+    private batchWork;
+    private processBatchedWork;
+    private applyChange;
+    private getObserverRoot;
+    private checkObserverCleanup;
+    private cleanupObservers;
+    destroy(): void;
+    getPendingCount(): number;
+    getAppliedCount(): number;
+    hasPendingForExperiment(experimentName: string): boolean;
+}

package/types/core/StyleSheetManager.d.ts

@@ -0,0 +1,16 @@
+export declare class StyleSheetManager {
+    private id;
+    private styleEl;
+    private rules;
+    private debug;
+    constructor(id: string, debug?: boolean);
+    ensure(): HTMLStyleElement;
+    setRule(key: string, css: string): void;
+    deleteRule(key: string): void;
+    hasRule(key: string): boolean;
+    clear(): void;
+    destroy(): void;
+    private render;
+    getRulesCount(): number;
+    getCssText(): string;
+}

package/types/entries/cookie-only.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Entry point for CookiePlugin only
+ * Standalone cookie management and tracking functionality
+ */
+import { CookiePlugin } from '../cookies/CookiePlugin';
+export type { CookiePluginOptions } from '../cookies/CookiePlugin';
+export { CookiePlugin };
+export default CookiePlugin;

package/types/entries/dom-only.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Entry point for DOM Changes Plugin only
+ * Smallest bundle - just core DOM manipulation functionality
+ */
+import { DOMChangesPluginLite } from '../core/DOMChangesPluginLite';
+export * from '../types';
+export { DOMChangesPluginLite };
+export { DOMChangesPluginLite as DOMChangesPlugin };
+export default DOMChangesPluginLite;

package/types/entries/dom-with-overrides-full.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Entry point for DOM Changes Plugin + Overrides Full
+ * Full bundle - DOM manipulation + full override capabilities with API support
+ */
+import { DOMChangesPluginLite } from '../core/DOMChangesPluginLite';
+import { OverridesPluginFull } from '../overrides/OverridesPluginFull';
+import { BrowserCookieAdapter } from '../overrides/BrowserCookieAdapter';
+import { CookiePlugin } from '../cookies/CookiePlugin';
+import { WebVitalsPlugin } from '../vitals/WebVitalsPlugin';
+export * from '../types';
+export * from '../overrides/types';
+export { DOMChangesPluginLite, DOMChangesPluginLite as DOMChangesPlugin, // Alias for backward compatibility
+OverridesPluginFull, OverridesPluginFull as OverridesPlugin, // Alias for backward compatibility
+BrowserCookieAdapter, CookiePlugin, WebVitalsPlugin, };
+export default DOMChangesPluginLite;

package/types/entries/dom-with-overrides-lite.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Entry point for DOM Changes Plugin + Overrides Lite
+ * Medium bundle - DOM manipulation + lightweight override detection
+ */
+import { DOMChangesPluginLite } from '../core/DOMChangesPluginLite';
+import { OverridesPluginLite } from '../overrides/OverridesPluginLite';
+export * from '../types';
+export * from '../overrides/types';
+export { DOMChangesPluginLite, OverridesPluginLite };
+export { DOMChangesPluginLite as DOMChangesPlugin };
+export default DOMChangesPluginLite;

package/types/entries/overrides-full-only.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Entry point for Overrides Full Plugin only
+ * Full override capabilities with API support, no DOM manipulation
+ */
+import { OverridesPluginFull } from '../overrides/OverridesPluginFull';
+import { BrowserCookieAdapter } from '../overrides/BrowserCookieAdapter';
+import { CookiePlugin } from '../cookies/CookiePlugin';
+export * from '../overrides/types';
+export { OverridesPluginFull, OverridesPluginFull as OverridesPlugin, // Alias for backward compatibility
+BrowserCookieAdapter, CookiePlugin, };
+export default OverridesPluginFull;

package/types/entries/overrides-lite-only.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Entry point for Overrides Lite Plugin only
+ * Minimal bundle - just lightweight override detection and application
+ */
+import { OverridesPluginLite } from '../overrides/OverridesPluginLite';
+export * from '../overrides/types';
+export { OverridesPluginLite };
+export default OverridesPluginLite;

package/types/entries/vitals-only.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Entry point for WebVitalsPlugin only
+ * Standalone web vitals and page metrics tracking
+ */
+import { WebVitalsPlugin } from '../vitals/WebVitalsPlugin';
+export type { WebVitalsPluginOptions, Metric } from '../vitals/WebVitalsPlugin';
+export { WebVitalsPlugin };
+export default WebVitalsPlugin;

package/types/index.d.ts

@@ -0,0 +1,13 @@
+import { DOMChangesPluginLite } from './core/DOMChangesPluginLite';
+import { OverridesPlugin } from './overrides/OverridesPlugin';
+import { BrowserCookieAdapter } from './overrides/BrowserCookieAdapter';
+import { CookiePlugin } from './cookies/CookiePlugin';
+import { WebVitalsPlugin } from './vitals/WebVitalsPlugin';
+export * from './types';
+export * from './overrides/types';
+export type { CookiePluginOptions } from './cookies/CookiePlugin';
+export type { WebVitalsPluginOptions, Metric } from './vitals/WebVitalsPlugin';
+export { DOMChangesPluginLite, DOMChangesPluginLite as DOMChangesPlugin, // Alias for backward compatibility
+OverridesPlugin, // Legacy export - this is the original full-featured version
+BrowserCookieAdapter, CookiePlugin, WebVitalsPlugin, };
+export default DOMChangesPluginLite;

package/types/overrides/BrowserCookieAdapter.d.ts

@@ -0,0 +1,6 @@
+import { CookieAdapter, CookieOptions } from './types';
+export declare class BrowserCookieAdapter implements CookieAdapter {
+    get(name: string): string | null;
+    set(name: string, value: string, options?: CookieOptions): void;
+    delete(name: string, options?: CookieOptions): void;
+}

package/types/overrides/OverridesPlugin.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Full-featured version of OverridesPlugin
+ * Extends OverridesPluginLite with API fetching for non-running experiments
+ * Supports server-side rendering, cookie adapters, and dev environments
+ */
+import { OverridesPluginLite } from './OverridesPluginLite';
+import { OverridesPluginConfig, CookieAdapter } from './types';
+export declare class OverridesPlugin extends OverridesPluginLite {
+    protected fullConfig: Required<Omit<OverridesPluginConfig, 'cookieName' | 'url' | 'cookieAdapter'>> & {
+        cookieName?: string;
+        url?: string | URL;
+        cookieAdapter?: CookieAdapter;
+    };
+    protected isServerSide: boolean;
+    private onExperimentsAddedCallbacks;
+    constructor(config: OverridesPluginConfig);
+    ready(): Promise<void>;
+    initialize(): Promise<void>;
+    private getOverrides;
+    private getEnhancedQueryStringOverrides;
+    private getEnhancedCookieOverrides;
+    private parseEnhancedCookieValue;
+    private persistEnhancedOverridesToCookie;
+    private applyOverridesWithFetching;
+    private fetchFromAPI;
+    private fetchFromDevSDK;
+    private injectExperimentsIntoContext;
+    onExperimentsAdded(callback: () => void): void;
+    private notifyExperimentsAdded;
+    protected registerWithContext(): void;
+    protected unregisterFromContext(): void;
+    destroy(): void;
+}

package/types/overrides/OverridesPluginFull.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Full-featured version of OverridesPlugin
+ * This is now just an alias for OverridesPlugin to maintain backward compatibility.
+ *
+ * @deprecated Use OverridesPlugin directly instead
+ */
+import { OverridesPlugin } from './OverridesPlugin';
+export declare class OverridesPluginFull extends OverridesPlugin {
+}

package/types/overrides/OverridesPluginLite.d.ts

@@ -0,0 +1,27 @@
+interface ABSmartlyContextLite {
+    override?: (experimentName: string, variant: number) => void;
+    __plugins?: Record<string, unknown>;
+}
+interface LiteConfig {
+    context: ABSmartlyContextLite;
+    cookieName?: string;
+    useQueryString?: boolean;
+    queryPrefix?: string;
+    persistQueryToCookie?: boolean;
+    debug?: boolean;
+}
+export declare class OverridesPluginLite {
+    private config;
+    protected initialized: boolean;
+    constructor(config: LiteConfig);
+    ready(): Promise<void>;
+    initialize(): Promise<void>;
+    private getQueryStringOverrides;
+    private getCookieOverrides;
+    private parseCookieValue;
+    private persistOverridesToCookie;
+    protected registerWithContext(): void;
+    protected unregisterFromContext(): void;
+    destroy(): void;
+}
+export {};

package/types/overrides/index.d.ts

@@ -0,0 +1,3 @@
+export { OverridesPlugin } from './OverridesPlugin';
+export { BrowserCookieAdapter } from './BrowserCookieAdapter';
+export * from './types';

package/types/overrides/types.d.ts

@@ -0,0 +1,43 @@
+export interface OverrideValue {
+    variant: number;
+    env?: number;
+    id?: number;
+}
+export interface CookieOverrides {
+    [experimentName: string]: number | OverrideValue;
+}
+export interface ParsedCookie {
+    overrides: CookieOverrides;
+    devEnv: string | null;
+}
+export interface CookieOptions {
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none';
+    domain?: string;
+    path?: string;
+    maxAge?: number;
+}
+export interface CookieAdapter {
+    get(name: string): string | null;
+    set(name: string, value: string, options?: CookieOptions): void;
+    delete(name: string, options?: CookieOptions): void;
+}
+export interface OverridesPluginConfig {
+    context: any;
+    cookieName?: string;
+    cookieAdapter?: CookieAdapter;
+    cookieOptions?: CookieOptions;
+    useQueryString?: boolean;
+    queryPrefix?: string;
+    envParam?: string;
+    persistQueryToCookie?: boolean;
+    url?: string | URL;
+    absmartlyEndpoint?: string;
+    sdkEndpoint?: string;
+    domChangesFieldName?: string;
+    sdkApiKey?: string;
+    application?: string;
+    environment?: string;
+    debug?: boolean;
+}

package/types/parsers/VariantExtractor.d.ts

@@ -0,0 +1,49 @@
+import { DOMChange, ABsmartlyContext, ExperimentData, DOMChangesData, InjectionDataWithFilter } from '../types';
+export declare class VariantExtractor {
+    private context;
+    private dataSource;
+    private dataFieldName;
+    private debug;
+    private cachedAllChanges;
+    constructor(context: ABsmartlyContext, dataSource?: 'variable' | 'customField', dataFieldName?: string, debug?: boolean);
+    clearCache(): void;
+    extractAllChanges(): Map<string, Map<number, DOMChange[]>>;
+    private extractAllVariantsForExperiment;
+    /**
+     * Extract changes from DOMChangesData (handles both legacy array and new wrapped format)
+     */
+    private extractChangesFromData;
+    getExperimentChanges(experimentName: string): DOMChange[] | null;
+    private parseChanges;
+    private isValidChange;
+    /**
+     * Get all variant changes for an experiment (not just the current variant)
+     * This is needed for proper exposure tracking across variants
+     */
+    getAllVariantChanges(experimentName: string): DOMChange[][];
+    /**
+     * Get the experiment data by name
+     * Note: This requires the context to be ready, otherwise it will throw
+     */
+    getExperiment(experimentName: string): ExperimentData | null;
+    /**
+     * Get the raw DOMChangesData for all variants of an experiment (includes URL filters and metadata)
+     * This is needed for URL filtering logic
+     */
+    getAllVariantsData(experimentName: string): Map<number, DOMChangesData>;
+    /**
+     * Check if any variant of an experiment has changes that match the current URL
+     * This is critical for SRM prevention - if ANY variant matches URL, ALL variants must be tracked
+     */
+    anyVariantMatchesURL(experimentName: string, url?: string): boolean;
+    /**
+     * Extract __inject_html from all variants for all experiments
+     * Only extracts from variant.variables (not from config)
+     */
+    extractAllInjectHTML(): Map<string, Map<number, InjectionDataWithFilter>>;
+    /**
+     * Extract __inject_html for a single experiment
+     * Only from variant.variables (not from config)
+     */
+    private extractInjectHTMLForExperiment;
+}

package/types/types/index.d.ts

@@ -0,0 +1,177 @@
+export type ChangeType = 'text' | 'html' | 'style' | 'styleRules' | 'class' | 'attribute' | 'javascript' | 'move' | 'create' | 'delete';
+export type DOMChangeValue = string | number | boolean | Record<string, string> | undefined;
+export interface URLFilterConfig {
+    include?: string[];
+    exclude?: string[];
+    mode?: 'simple' | 'regex';
+    matchType?: 'full-url' | 'path' | 'domain' | 'query' | 'hash';
+}
+export type URLFilter = string | string[] | URLFilterConfig;
+export interface StyleRuleStates {
+    normal?: Record<string, string>;
+    hover?: Record<string, string>;
+    active?: Record<string, string>;
+    focus?: Record<string, string>;
+}
+export interface DOMChange {
+    selector: string;
+    type: ChangeType;
+    value?: DOMChangeValue;
+    enabled?: boolean;
+    add?: string[];
+    remove?: string[];
+    targetSelector?: string;
+    position?: 'before' | 'after' | 'firstChild' | 'lastChild';
+    element?: string;
+    states?: StyleRuleStates;
+    important?: boolean;
+    observerRoot?: string;
+    waitForElement?: boolean;
+    persistStyle?: boolean;
+    trigger_on_view?: boolean;
+}
+export interface DOMChangesConfig {
+    changes: DOMChange[];
+    urlFilter?: URLFilter;
+    waitForElement?: boolean;
+    persistStyle?: boolean;
+    important?: boolean;
+    observerRoot?: string;
+}
+export type DOMChangesData = DOMChange[] | DOMChangesConfig;
+export interface InjectionData {
+    headStart?: string;
+    headEnd?: string;
+    bodyStart?: string;
+    bodyEnd?: string;
+}
+export type InjectionLocation = 'headStart' | 'headEnd' | 'bodyStart' | 'bodyEnd';
+export interface InjectionItem {
+    code: string;
+    priority: number;
+    location: InjectionLocation;
+}
+export type RawInjectionData = Record<string, string | URLFilter>;
+export interface InjectionDataWithFilter {
+    data: RawInjectionData;
+    urlFilter?: URLFilter;
+}
+export interface ElementState {
+    selector: string;
+    type: string;
+    originalState: {
+        text?: string;
+        html?: string;
+        style?: string;
+        classList?: string[];
+        attributes?: Record<string, string>;
+        parent?: Element | null;
+        nextSibling?: Element | null;
+    };
+}
+export interface ABsmartlyContext {
+    ready(): Promise<void>;
+    data(): ContextData | null;
+    peek(experimentName: string): number | undefined;
+    treatment(experimentName: string): number;
+    override(experimentName: string, variant: number): void;
+    customFieldValue(experimentName: string, fieldName: string): unknown;
+    __plugins?: {
+        [key: string]: PluginRegistration | undefined;
+    };
+    __domPlugin?: PluginRegistration;
+}
+export interface PluginRegistration {
+    name: string;
+    version: string;
+    initialized: boolean;
+    capabilities: string[];
+    instance: unknown;
+    timestamp: number;
+}
+export interface PluginConfig {
+    context: ABsmartlyContext;
+    autoApply?: boolean;
+    /**
+     * SPA mode - Enables features for Single Page Applications (React, Vue, Angular, etc.)
+     * When enabled, automatically activates:
+     * - Wait for element: Observes DOM for elements that don't exist yet
+     * - Style persistence: Re-applies styles when frameworks overwrite them (e.g., on hover)
+     *
+     * Set to true for dynamic apps where DOM changes after page load
+     */
+    spa?: boolean;
+    visibilityTracking?: boolean;
+    extensionBridge?: boolean;
+    dataSource?: 'variable' | 'customField';
+    dataFieldName?: string;
+    debug?: boolean;
+    hideUntilReady?: boolean | 'body' | 'elements';
+    hideTimeout?: number;
+    hideSelector?: string;
+    hideTransition?: string | false;
+}
+export interface AppliedChange {
+    experimentName: string;
+    change: DOMChange;
+    elements: Element[];
+    timestamp: number;
+}
+export interface PendingChange {
+    experimentName: string;
+    change: DOMChange;
+    retryCount: number;
+}
+export type MessagePayloadData = {
+    changes?: DOMChange[];
+    experimentName?: string;
+    count?: number;
+    version?: string;
+    capabilities?: string[];
+    experiments?: ExperimentData[];
+    overrides?: Record<string, unknown>;
+    locations?: string[];
+    error?: string;
+    variant?: number;
+    changeCount?: number;
+    headStart?: string;
+    headEnd?: string;
+    bodyStart?: string;
+    bodyEnd?: string;
+};
+export interface MessagePayload {
+    source: string;
+    type: string;
+    payload?: MessagePayloadData;
+}
+export interface ExperimentVariant {
+    variables?: Record<string, unknown>;
+    config?: string | Record<string, unknown>;
+}
+export interface ExperimentData {
+    name: string;
+    variants?: ExperimentVariant[];
+}
+export interface ContextData {
+    experiments?: ExperimentData[];
+}
+export type EventCallback = (data?: EventCallbackData) => void;
+export interface EventCallbackData {
+    count?: number;
+    experimentName?: string;
+    changeCount?: number;
+    locations?: string[];
+    error?: string;
+    removedChanges?: AppliedChange[];
+    change?: DOMChange;
+}
+export type MessageHandler = (payload: MessagePayloadData) => void;
+export interface ExperimentTracking {
+    experimentName: string;
+    variant: number;
+    changes: DOMChange[];
+    allPossibleSelectors: Set<string>;
+    triggered: boolean;
+    hasImmediateTrigger: boolean;
+    hasViewportTrigger: boolean;
+}

package/types/utils/URLMatcher.d.ts

@@ -0,0 +1,20 @@
+export interface URLFilterConfig {
+    include?: string[];
+    exclude?: string[];
+    mode?: 'simple' | 'regex';
+    matchType?: 'full-url' | 'path' | 'domain' | 'query' | 'hash';
+}
+export type URLFilter = string | string[] | URLFilterConfig;
+export declare class URLMatcher {
+    /**
+     * Check if current URL matches the filter
+     */
+    static matches(filter: URLFilter, url?: string): boolean;
+    /**
+     * Extract the relevant part of the URL based on matchType
+     */
+    private static extractURLPart;
+    private static matchesPatterns;
+    private static matchSimplePattern;
+    private static normalizeFilter;
+}