@absmartly/sdk-plugins 1.1.1 → 1.2.1

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

@@ -5,12 +5,14 @@
 import { DOMChangesPluginLite } from '../core/DOMChangesPluginLite';
 import { OverridesPluginLite } from '../overrides/OverridesPluginLite';
 import { CookiePlugin } from '../cookies/CookiePlugin';
+import { DOMPersistenceManager } from '../utils/persistence';
 export * from '../types';
 export * from '../overrides/types';
 export type { CookiePluginOptions } from '../cookies/CookiePlugin';
 export type { CookieOptions } from '../cookies/cookieUtils';
 export { DOMChangesPluginLite, OverridesPluginLite, CookiePlugin };
 export { DOMChangesPluginLite as DOMChangesPlugin };
+export { DOMPersistenceManager };
 export { getCookie, setCookie, deleteCookie, generateUniqueId, generateUUID, isLocalStorageAvailable, } from '../cookies/cookieUtils';
 export { getQueryStringOverrides, parseOverrideCookie, getCookieOverrides as getOverrideCookie, serializeOverrides, persistOverridesToCookie, getOverrides, } from '../overrides/overridesUtils';
 export type { SimpleOverride, OverrideOptions } from '../overrides/overridesUtils';

package/types/index.d.ts

@@ -3,15 +3,21 @@ import { OverridesPlugin } from './overrides/OverridesPlugin';
 import { BrowserCookieAdapter } from './overrides/BrowserCookieAdapter';
 import { CookiePlugin } from './cookies/CookiePlugin';
 import { WebVitalsPlugin } from './vitals/WebVitalsPlugin';
+import { URLRedirectPlugin } from './url-redirect/URLRedirectPlugin';
 export * from './types';
 export * from './overrides/types';
+export * from './url-redirect/types';
 export type { CookiePluginOptions } from './cookies/CookiePlugin';
 export type { CookieOptions } from './cookies/cookieUtils';
 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, };
+BrowserCookieAdapter, CookiePlugin, WebVitalsPlugin, URLRedirectPlugin, };
 export { getCookie, setCookie, deleteCookie, generateUniqueId, generateUUID, isLocalStorageAvailable, } from './cookies/cookieUtils';
-export { getQueryStringOverrides, parseOverrideCookie, getCookieOverrides, serializeOverrides, persistOverridesToCookie, getOverrides, } from './overrides/overridesUtils';
+export { DEFAULT_OVERRIDE_COOKIE_NAME, DEFAULT_OVERRIDE_QUERY_PREFIX, getQueryStringOverrides, parseOverrideCookie, getCookieOverrides, serializeOverrides, persistOverridesToCookie, getOverrides, } from './overrides/overridesUtils';
 export type { SimpleOverride, OverrideOptions } from './overrides/overridesUtils';
+export { registerPlugin, unregisterPlugin, isPluginRegistered, getRegisteredPlugins, } from './utils/plugin-registry';
+export type { PluginRegistry, PluginRegistryEntry } from './utils/plugin-registry';
+export { URLRedirectExtractor } from './url-redirect/URLRedirectExtractor';
+export { URLRedirectMatcher } from './url-redirect/URLRedirectMatcher';
 export default DOMChangesPluginLite;

package/types/overrides/OverridesPluginLite.d.ts

@@ -23,5 +23,13 @@ export declare class OverridesPluginLite {
     protected registerWithContext(): void;
     protected unregisterFromContext(): void;
     destroy(): void;
+    /**
+     * Register plugin in global registry for detection
+     */
+    protected registerGlobally(): void;
+    /**
+     * Unregister plugin from global registry
+     */
+    protected unregisterGlobally(): void;
 }
 export {};

package/types/overrides/overridesUtils.d.ts

@@ -3,6 +3,8 @@
  * These can be used independently for lightweight override operations
  * without requiring the full OverridesPlugin class
  */
+export declare const DEFAULT_OVERRIDE_COOKIE_NAME = "absmartly_overrides";
+export declare const DEFAULT_OVERRIDE_QUERY_PREFIX = "exp_";
 export interface SimpleOverride {
     variant: number;
     env?: number;
@@ -15,7 +17,7 @@ export interface OverrideOptions {
 }
 /**
  * Parse query string parameters for experiment overrides
- * @param queryPrefix - Prefix for experiment parameters (e.g., '_exp_')
+ * @param queryPrefix - Prefix for experiment parameters (default: DEFAULT_OVERRIDE_QUERY_PREFIX)
  * @param searchParams - Optional URLSearchParams instance (defaults to window.location.search)
  */
 export declare function getQueryStringOverrides(queryPrefix?: string, searchParams?: URLSearchParams): Record<string, number | SimpleOverride>;
@@ -26,8 +28,10 @@ export declare function getQueryStringOverrides(queryPrefix?: string, searchPara
 export declare function parseOverrideCookie(value: string): Record<string, number | SimpleOverride>;
 /**
  * Get experiment overrides from cookie
+ * @param cookieName - Name of the cookie to read (default: DEFAULT_OVERRIDE_COOKIE_NAME)
+ * @param cookieHeader - Optional cookie header string (for server-side use). If not provided, uses document.cookie
  */
-export declare function getCookieOverrides(cookieName?: string): Record<string, number | SimpleOverride>;
+export declare function getCookieOverrides(cookieName?: string, cookieHeader?: string): Record<string, number | SimpleOverride>;
 /**
  * Serialize overrides to cookie value format
  */
@@ -40,9 +44,10 @@ export declare function persistOverridesToCookie(overrides: Record<string, numbe
  * Get experiment overrides from query string or cookie
  * Returns normalized Record<string, number> for use with SDK createContext
  *
- * @param cookieName - Name of the cookie to read/write (default: 'absmartly_overrides')
- * @param queryPrefix - Prefix for query string parameters (default: '_exp_')
+ * @param cookieName - Name of the cookie to read/write (default: DEFAULT_OVERRIDE_COOKIE_NAME)
+ * @param queryPrefix - Prefix for query string parameters (default: DEFAULT_OVERRIDE_QUERY_PREFIX)
  * @param searchParams - Optional URLSearchParams instance (defaults to window.location.search)
+ * @param cookieHeader - Optional cookie header string (for server-side use). If not provided, uses document.cookie
  * @returns Normalized overrides as Record<string, number>
  */
-export declare function getOverrides(cookieName?: string, queryPrefix?: string, searchParams?: URLSearchParams): Record<string, number>;
+export declare function getOverrides(cookieName?: string, queryPrefix?: string, searchParams?: URLSearchParams, cookieHeader?: string): Record<string, number>;

package/types/parsers/VariantExtractor.d.ts

@@ -1,11 +1,10 @@
 import { DOMChange, ABsmartlyContext, ExperimentData, DOMChangesData, InjectionDataWithFilter } from '../types';
 export declare class VariantExtractor {
     private context;
-    private dataSource;
-    private dataFieldName;
+    private variableName;
     private debug;
     private cachedAllChanges;
-    constructor(context: ABsmartlyContext, dataSource?: 'variable' | 'customField', dataFieldName?: string, debug?: boolean);
+    constructor(context: ABsmartlyContext, variableName?: string, debug?: boolean);
     clearCache(): void;
     extractAllChanges(): Map<string, Map<number, DOMChange[]>>;
     private extractAllVariantsForExperiment;
@@ -38,12 +37,12 @@ export declare class VariantExtractor {
     anyVariantMatchesURL(experimentName: string, url?: string): boolean;
     /**
      * Extract __inject_html from all variants for all experiments
-     * Only extracts from variant.variables (not from config)
+     * Checks both variant.variables and variant.config
      */
     extractAllInjectHTML(): Map<string, Map<number, InjectionDataWithFilter>>;
     /**
      * Extract __inject_html for a single experiment
-     * Only from variant.variables (not from config)
+     * Checks both variant.variables and variant.config
      */
     private extractInjectHTMLForExperiment;
 }

package/types/types/index.d.ts

@@ -28,6 +28,7 @@ export interface DOMChange {
     observerRoot?: string;
     waitForElement?: boolean;
     persistStyle?: boolean;
+    persistAttribute?: boolean;
     trigger_on_view?: boolean;
 }
 export interface DOMChangesConfig {
@@ -69,13 +70,8 @@ export interface ElementState {
         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;
+import type { Context } from '@absmartly/javascript-sdk';
+export interface ABsmartlyContext extends Context {
     __plugins?: {
         [key: string]: PluginRegistration | undefined;
     };
@@ -102,13 +98,10 @@ export interface PluginConfig {
      */
     spa?: boolean;
     visibilityTracking?: boolean;
-    extensionBridge?: boolean;
-    dataSource?: 'variable' | 'customField';
-    dataFieldName?: string;
+    variableName?: string;
     debug?: boolean;
-    hideUntilReady?: boolean | 'body' | 'elements';
+    hideUntilReady?: string | false;
     hideTimeout?: number;
-    hideSelector?: string;
     hideTransition?: string | false;
 }
 export interface AppliedChange {

package/types/url-redirect/URLRedirectExtractor.d.ts

@@ -0,0 +1,16 @@
+import { ABsmartlyContext } from '../types';
+import { URLRedirectConfig } from './types';
+export declare class URLRedirectExtractor {
+    private context;
+    private variableName;
+    private debug;
+    private cachedConfigs;
+    constructor(context: ABsmartlyContext, variableName?: string, debug?: boolean);
+    clearCache(): void;
+    extractAllConfigs(): Map<string, Map<number, URLRedirectConfig>>;
+    private extractConfigsForExperiment;
+    private parseConfig;
+    private isValidRedirect;
+    getConfigForExperiment(experimentName: string): URLRedirectConfig | null;
+    getAllVariantConfigs(experimentName: string): Map<number, URLRedirectConfig>;
+}

package/types/url-redirect/URLRedirectMatcher.d.ts

@@ -0,0 +1,8 @@
+import { URLRedirect, RedirectMatch } from './types';
+export declare class URLRedirectMatcher {
+    static findMatch(currentUrl: string, redirects: URLRedirect[], experimentName: string, variant: number): RedirectMatch | null;
+    private static matchRedirect;
+    private static matchDomainRedirect;
+    private static matchPageRedirect;
+    static buildTargetUrl(currentUrl: string, redirect: URLRedirect): string;
+}

package/types/url-redirect/URLRedirectPlugin.d.ts

@@ -0,0 +1,21 @@
+import { URLRedirectPluginConfig, RedirectMatch } from './types';
+import { URLRedirectExtractor } from './URLRedirectExtractor';
+export declare class URLRedirectPlugin {
+    static readonly VERSION: string;
+    private config;
+    private extractor;
+    private initialized;
+    private readyPromise;
+    constructor(config: URLRedirectPluginConfig);
+    ready(): Promise<RedirectMatch | null>;
+    private initialize;
+    findRedirectMatch(url?: string): RedirectMatch | null;
+    private getAnyConfig;
+    executeRedirect(match: RedirectMatch): Promise<void>;
+    private publishViaBeacon;
+    getExtractor(): URLRedirectExtractor;
+    refreshExperiments(): void;
+    destroy(): void;
+    private registerWithContext;
+    private unregisterFromContext;
+}

package/types/url-redirect/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export { URLRedirectPlugin } from './URLRedirectPlugin';
+export { URLRedirectExtractor } from './URLRedirectExtractor';
+export { URLRedirectMatcher } from './URLRedirectMatcher';

package/types/url-redirect/types.d.ts

@@ -0,0 +1,29 @@
+import type { URLFilter } from '../types';
+export type RedirectType = 'domain' | 'page';
+export type ControlBehavior = 'redirect-same' | 'no-redirect';
+export interface URLRedirect {
+    from: string;
+    to: string;
+    preservePath?: boolean;
+    type: RedirectType;
+}
+export interface URLRedirectConfig {
+    redirects: URLRedirect[];
+    urlFilter?: URLFilter;
+    controlBehavior?: ControlBehavior;
+}
+export interface RedirectMatch {
+    redirect: URLRedirect;
+    targetUrl: string;
+    experimentName: string;
+    variant: number;
+    isControl: boolean;
+}
+export interface URLRedirectPluginConfig {
+    context: import('../types').ABsmartlyContext;
+    variableName?: string;
+    debug?: boolean;
+    autoApply?: boolean;
+    useBeacon?: boolean;
+    onBeforeRedirect?: (match: RedirectMatch) => void | Promise<void>;
+}

package/types/utils/persistence.d.ts

@@ -0,0 +1,23 @@
+import type { DOMChange } from '../types';
+export interface PersistenceConfig {
+    debug?: boolean;
+    onReapply: (change: DOMChange, experimentName: string) => void;
+}
+export declare class DOMPersistenceManager {
+    private watchedElements;
+    private persistenceObserver;
+    private reapplyingElements;
+    private reapplyLogThrottle;
+    private appliedChanges;
+    private config;
+    constructor(config: PersistenceConfig);
+    watchElement(element: Element, experimentName: string, change: DOMChange): void;
+    unwatchElement(element: Element, experimentName: string): void;
+    unwatchExperiment(experimentName: string): void;
+    getAppliedChanges(): Map<string, DOMChange[]>;
+    clearAll(): void;
+    destroy(): void;
+    private setupPersistenceObserver;
+    private checkStyleOverwritten;
+    private checkAttributeOverwritten;
+}

package/types/utils/plugin-registry.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Global plugin registry for ABsmartly plugins
+ * Allows detection and inspection of loaded plugins
+ */
+export interface PluginRegistryEntry {
+    name: string;
+    version: string;
+    initialized: boolean;
+    timestamp: number;
+    capabilities?: string[];
+    instance?: any;
+}
+export interface PluginRegistry {
+    dom?: PluginRegistryEntry;
+    overrides?: PluginRegistryEntry;
+    cookie?: PluginRegistryEntry;
+    vitals?: PluginRegistryEntry;
+    urlRedirect?: PluginRegistryEntry;
+}
+declare global {
+    interface Window {
+        __ABSMARTLY_PLUGINS__?: PluginRegistry;
+    }
+}
+/**
+ * Register a plugin in the global registry
+ */
+export declare function registerPlugin(pluginType: keyof PluginRegistry, entry: PluginRegistryEntry): void;
+/**
+ * Unregister a plugin from the global registry
+ */
+export declare function unregisterPlugin(pluginType: keyof PluginRegistry): void;
+/**
+ * Check if a plugin is registered
+ */
+export declare function isPluginRegistered(pluginType: keyof PluginRegistry): boolean;
+/**
+ * Get all registered plugins
+ */
+export declare function getRegisteredPlugins(): PluginRegistry;

package/types/vitals/WebVitalsPlugin.d.ts

@@ -31,6 +31,8 @@ export declare class WebVitalsPlugin {
     trackPageMetricsData(context?: Context): void;
     private trackImmediateMetrics;
     private trackLoadMetrics;
+    start(): Promise<void>;
+    ready(): Promise<void>;
     initialize(): Promise<void>;
     reset(): void;
 }