@dreamsengine/dreams-ad-engine 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dreamsengine/dreams-ad-engine",
-	"version": "0.2.1",
+	"version": "0.3.0",
 	"type": "module",
 	"license": "GPL-3.0",
 	"main": "./dist/dreams-ad-engine.js",

package/types/features/adblock/adblock.service.d.ts

@@ -0,0 +1,45 @@
+import type { AdBlockConfig, AdBlockDetectionResult } from "./adblock.types";
+declare global {
+    interface Window {
+        adBlockDetected?: boolean;
+    }
+}
+export declare class AdBlockDetector {
+    private static config;
+    private static detected;
+    private static detecting;
+    /**
+     * Configure the ad block detector
+     */
+    static configure(config: AdBlockConfig): void;
+    /**
+     * Check if ad blocker is detected (cached result)
+     */
+    static isBlocked(): boolean;
+    /**
+     * Run ad blocker detection
+     */
+    static detect(): Promise<AdBlockDetectionResult>;
+    /**
+     * Initialize detection and apply body class if blocked
+     */
+    static init(): Promise<boolean>;
+    /**
+     * Reset detection state
+     */
+    static reset(): void;
+    private static runDetection;
+    /**
+     * Method 1: Check if googletag loaded properly
+     */
+    private static testGoogleTag;
+    /**
+     * Method 2: Bait element detection
+     * Ad blockers often hide elements with common ad class names
+     */
+    private static testBaitElement;
+    /**
+     * Method 3: Fetch a known ad resource
+     */
+    private static testFetch;
+}

package/types/features/adblock/adblock.types.d.ts

@@ -0,0 +1,14 @@
+export interface AdBlockDetectionResult {
+    blocked: boolean;
+    method: "googletag" | "bait" | "fetch" | "none";
+}
+export interface AdBlockConfig {
+    /** Enable detection on load. Default: true */
+    enabled?: boolean;
+    /** Add body class when detected. Default: true */
+    addBodyClass?: boolean;
+    /** Body class name. Default: "ad-blocker-detected" */
+    bodyClass?: string;
+    /** Timeout for detection methods in ms. Default: 1000 */
+    timeout?: number;
+}

package/types/features/adblock/index.d.ts

@@ -0,0 +1,2 @@
+export { AdBlockDetector } from "./adblock.service";
+export type { AdBlockConfig, AdBlockDetectionResult } from "./adblock.types";

package/types/features/config/config.types.d.ts

@@ -16,7 +16,9 @@ export interface AdConfigInit {
     bidTimeout?: number;
     defaultLazyLoad?: LazyLoadConfig;
     slots?: Record<string, SlotConfig>;
+    /** Set to true to allow re-initialization (overwrites existing config) */
+    force?: boolean;
 }
-export interface AdConfigData extends Required<Omit<AdConfigInit, "slots">> {
+export interface AdConfigData extends Required<Omit<AdConfigInit, "slots" | "force">> {
     slots: Record<string, SlotConfig>;
 }

package/types/features/dreamsAdEngine/components/ad.component.d.ts

@@ -2,12 +2,26 @@ import { LitElement } from "lit";
 import type { TemplateResult } from "lit/html.js";
 import "../types/interfaces";
 import { DreamsAdMapping, DreamsAdTargeting } from "../types/interfaces";
+import "../../skeleton/skeleton.component";
 export declare class DreamsAdComponent extends LitElement {
     #private;
     static styles: import("lit").CSSResult;
     static initialized: boolean;
     static old_url: string;
     static initialized_aps: boolean;
+    static navigationListenersAttached: boolean;
+    static servicesWereAlreadyEnabled: boolean;
+    static lazyLoadConfigured: boolean;
+    private adSlot;
+    private slotRenderHandler;
+    /**
+     * Handle SPA navigation - destroys all slots and clears targeting cache
+     */
+    private static _handleNavigation;
+    /**
+     * Set up global navigation listeners for SPA support
+     */
+    private static _setupNavigationListeners;
     networkId: string;
     adUnit: string;
     divId: string;
@@ -31,7 +45,10 @@ export declare class DreamsAdComponent extends LitElement {
     bidTimeout: number;
     title: string;
     adLoaded: boolean;
+    trackViewability: boolean;
+    showSkeleton: boolean;
     connectedCallback(): void;
+    disconnectedCallback(): void;
     firstUpdated(): Promise<void>;
     protected render(): TemplateResult;
 }

package/types/features/dreamsAdEngine/index.d.ts

@@ -1 +1 @@
-export * from './components/ad.component';
+export * from "./components/ad.component";

package/types/features/dreamsAdEngine/types/interfaces.d.ts

@@ -1,6 +1,7 @@
 export interface Googletag {
     cmd: Array<() => void>;
     pubads: () => PubAdsService;
+    pubadsReady?: boolean;
     defineSlot: (adUnitPath: string, size: Array<number> | Array<Array<number>>, divId: string) => Slot;
     display: (divId: string) => void;
     enableServices: () => void;
@@ -27,9 +28,12 @@ interface LazyLoadObject {
 interface PubAdsService {
     disableInitialLoad: () => void;
     enableSingleRequest: () => void;
-    refresh: (slots?: Slot[]) => void;
+    refresh: (slots?: Slot[], options?: {
+        changeCorrelator?: boolean;
+    }) => void;
     addService: (service: ServiceType) => Slot;
     addEventListener: (eventType: string, handler: (event: any) => void) => void;
+    removeEventListener: (eventType: string, handler: (event: any) => void) => void;
     setCentering: (centerAds: boolean) => void;
     enableLazyLoad: (config: LazyLoadObject) => void;
 }

package/types/features/index.d.ts

@@ -1,3 +1,9 @@
 export * from "./dreamsAdEngine/";
 export * from "./targeting/";
 export * from "./config/";
+export * from "./viewability/";
+export * from "./skeleton/";
+export * from "./adblock/";
+export * from "./refresh/";
+export * from "./logging/";
+export * from "./sticky/";

package/types/features/logging/index.d.ts

@@ -0,0 +1,2 @@
+export { Logger } from "./logger";
+export type { LoggerConfig } from "./logger";

package/types/features/logging/logger.d.ts

@@ -0,0 +1,56 @@
+export interface LoggerConfig {
+    /** Enable logging. Default: auto (dev only) */
+    enabled?: boolean | "auto";
+    /** Log prefix. Default: "[DreamsAdEngine]" */
+    prefix?: string;
+    /** Enable verbose logging. Default: false */
+    verbose?: boolean;
+}
+/**
+ * Production-aware logger for Dreams Ad Engine
+ */
+export declare class Logger {
+    private static config;
+    /**
+     * Configure the logger
+     */
+    static configure(config: LoggerConfig): void;
+    /**
+     * Log info message
+     */
+    static log(message: string, ...args: unknown[]): void;
+    /**
+     * Log warning message
+     */
+    static warn(message: string, ...args: unknown[]): void;
+    /**
+     * Log error message (always logs in production, but less verbose)
+     */
+    static error(message: string, ...args: unknown[]): void;
+    /**
+     * Log verbose/debug message (only when verbose is enabled)
+     */
+    static debug(message: string, ...args: unknown[]): void;
+    /**
+     * Log a table (useful for metrics)
+     */
+    static table(data: unknown[]): void;
+    /**
+     * Group logs together
+     */
+    static group(label: string): void;
+    /**
+     * End log group
+     */
+    static groupEnd(): void;
+    /**
+     * Time a operation
+     */
+    static time(label: string): void;
+    /**
+     * End timing
+     */
+    static timeEnd(label: string): void;
+    private static shouldLog;
+    private static isProduction;
+}

package/types/features/refresh/index.d.ts

@@ -0,0 +1,2 @@
+export { RefreshManager } from "./refresh.service";
+export type { RefreshConfig, RefreshEvent } from "./refresh.types";

package/types/features/refresh/refresh.service.d.ts

@@ -0,0 +1,46 @@
+import type { RefreshConfig } from "./refresh.types";
+declare global {
+    interface Window {
+        DreamsBlockedRefresh?: boolean;
+        lastAdRefresh?: number;
+        isTabVisible?: boolean;
+    }
+}
+export declare class RefreshManager {
+    private static config;
+    private static refreshTimer;
+    private static running;
+    /**
+     * Configure the refresh manager
+     */
+    static configure(config: RefreshConfig): void;
+    /**
+     * Start auto-refresh loop
+     */
+    static start(): void;
+    /**
+     * Stop auto-refresh loop
+     */
+    static stop(): void;
+    /**
+     * Manually trigger a refresh (respects safeguards)
+     */
+    static refresh(slots?: any[]): boolean;
+    /**
+     * Block refresh (e.g., during user interaction)
+     */
+    static block(): void;
+    /**
+     * Unblock refresh
+     */
+    static unblock(): void;
+    /**
+     * Check if refresh is currently blocked
+     */
+    static isBlocked(): boolean;
+    private static setupVisibilityTracking;
+    private static scheduleRefresh;
+    private static executeRefresh;
+    private static safeRefresh;
+    private static dispatchEvent;
+}

package/types/features/refresh/refresh.types.d.ts

@@ -0,0 +1,18 @@
+export interface RefreshConfig {
+    /** Enable auto-refresh. Default: false */
+    enabled?: boolean;
+    /** Refresh interval in ms. Minimum 30000 (30s). Default: 60000 */
+    interval?: number;
+    /** Skip refresh when tab is hidden. Default: true */
+    checkVisibility?: boolean;
+    /** Disable on single-post pages. Default: true */
+    disableOnSinglePost?: boolean;
+    /** CSS selector for single-post detection. Default: "body.single" */
+    singlePostSelector?: string;
+}
+export interface RefreshEvent {
+    type: "refresh" | "skipped";
+    reason?: "hidden" | "blocked" | "throttled";
+    slots: number;
+    timestamp: number;
+}

package/types/features/skeleton/index.d.ts

@@ -0,0 +1 @@
+export { DreamsAdSkeleton, getSkeletonDimensions } from "./skeleton.component";

package/types/features/skeleton/skeleton.component.d.ts

@@ -0,0 +1,20 @@
+import { LitElement } from "lit";
+/**
+ * Skeleton loader component for ad placeholders
+ * Displays shimmer animation while ad loads
+ */
+export declare class DreamsAdSkeleton extends LitElement {
+    static styles: import("lit").CSSResult;
+    width: number;
+    height: number;
+    showLabel: boolean;
+    label: string;
+    render(): import("lit").TemplateResult<1>;
+}
+/**
+ * Get skeleton dimensions based on slot type and viewport width
+ */
+export declare function getSkeletonDimensions(slotType: string, viewportWidth: number): {
+    width: number;
+    height: number;
+};

package/types/features/sticky/index.d.ts

@@ -0,0 +1,2 @@
+export { StickyManager } from "./sticky.service";
+export type { StickyConfig, StickyMetrics } from "./sticky.types";

package/types/features/sticky/sticky.service.d.ts

@@ -0,0 +1,38 @@
+import type { StickyConfig, StickyMetrics } from "./sticky.types";
+export declare class StickyManager {
+    private static config;
+    private static stickyAds;
+    private static lastScrollTime;
+    /**
+     * Configure the sticky manager
+     */
+    static configure(config: StickyConfig): void;
+    /**
+     * Check if a position supports sticky
+     */
+    static isStickyPosition(position: string): boolean;
+    /**
+     * Enable sticky behavior for an ad element
+     */
+    static enable(container: HTMLElement, adId: string, position: string): boolean;
+    /**
+     * Disable sticky behavior for an ad
+     */
+    static disable(adId: string): void;
+    /**
+     * Get metrics for a sticky ad
+     */
+    static getMetrics(adId: string): StickyMetrics | null;
+    /**
+     * Get all sticky metrics
+     */
+    static getAllMetrics(): StickyMetrics[];
+    /**
+     * Reset all sticky ads
+     */
+    static reset(): void;
+    private static getTopOffset;
+    private static handleScroll;
+    private static checkSticky;
+    private static dispatchEvent;
+}

package/types/features/sticky/sticky.types.d.ts

@@ -0,0 +1,23 @@
+export interface StickyConfig {
+    /** Enable sticky behavior. Default: false */
+    enabled?: boolean;
+    /** Positions that support sticky (e.g., ["box-2", "box-3"]). Default: [] */
+    positions?: string[];
+    /** Minimum viewport height for sticky. Default: 768 */
+    minViewportHeight?: number;
+    /** Top offset in pixels. Default: 80 */
+    topOffset?: number;
+    /** CSS selector for header (for dynamic offset). Default: null */
+    headerSelector?: string | null;
+    /** Enable smooth transitions. Default: true */
+    smoothTransition?: boolean;
+    /** Transition duration in ms. Default: 150 */
+    transitionDuration?: number;
+}
+export interface StickyMetrics {
+    adId: string;
+    position: string;
+    stickyTime: number;
+    totalTime: number;
+    isCurrentlySticky: boolean;
+}

package/types/features/viewability/index.d.ts

@@ -0,0 +1,2 @@
+export { ViewabilityService } from "./viewability.service";
+export type { ViewabilityConfig, ViewabilityEvent, ViewabilityMetrics, } from "./viewability.types";

package/types/features/viewability/viewability.service.d.ts

@@ -0,0 +1,38 @@
+import type { ViewabilityConfig, ViewabilityMetrics } from "./viewability.types";
+export declare class ViewabilityService {
+    private static config;
+    private static trackedAds;
+    /**
+     * Configure the viewability service
+     */
+    static configure(config: ViewabilityConfig): void;
+    /**
+     * Start tracking an ad element for viewability
+     */
+    static track(element: HTMLElement, adId: string, position: string): void;
+    /**
+     * Stop tracking an ad element
+     */
+    static untrack(adId: string): void;
+    /**
+     * Get metrics for a specific ad
+     */
+    static getMetrics(adId: string): ViewabilityMetrics | null;
+    /**
+     * Get all tracked metrics
+     */
+    static getAllMetrics(): ViewabilityMetrics[];
+    /**
+     * Show metrics summary in console
+     */
+    static showMetrics(): void;
+    /**
+     * Clear all tracking
+     */
+    static reset(): void;
+    private static handleIntersection;
+    private static startViewabilityTimer;
+    private static stopViewabilityTimer;
+    private static updateMetrics;
+    private static dispatchEvent;
+}

package/types/features/viewability/viewability.types.d.ts

@@ -0,0 +1,22 @@
+export interface ViewabilityMetrics {
+    adId: string;
+    position: string;
+    isViewable: boolean;
+    viewableTime: number;
+    totalTime: number;
+    viewabilityRate: number;
+}
+export interface ViewabilityEvent {
+    type: "viewable" | "impression" | "hidden";
+    adId: string;
+    metrics: ViewabilityMetrics;
+    timestamp: number;
+}
+export interface ViewabilityConfig {
+    /** Minimum visibility ratio (0-1). Default: 0.5 (IAB standard) */
+    threshold?: number;
+    /** Time in ms to be considered viewable. Default: 2000 (IAB standard) */
+    duration?: number;
+    /** Enable console metrics output */
+    debug?: boolean;
+}