web-push-notifications 3.62.12 → 3.63.0

package/widgets/WebPopups/WebPopupsWidget.d.ts

@@ -1,19 +1,80 @@
+import { type IWebPopupsPublicApi, type WebPopupsPublicState } from './types';
 import { type Pushwoosh } from '../../core/Pushwoosh';
-export declare class WebPopupsWidget {
+export declare class WebPopupsWidget implements IWebPopupsPublicApi {
     private readonly pw;
     private isRecurringVisitor;
-    private readonly loadedPopups;
-    private readonly pendingTimers;
+    /** Every popup the server returned, keyed by code. Never pruned. */
+    private readonly entries;
+    /** Codes whose delay has elapsed, waiting for the display slot. */
+    private readonly queue;
+    /** The single popup on screen, if any. */
+    private visible;
+    private drainTimeoutId;
+    private autoShowEnabled;
     private isNavigationSubscribed;
     private openPopupsCount;
     private bodyOverflowBeforeLock;
-    private lockBodyScroll;
-    private unlockBodyScroll;
+    private readyResolve;
+    private readonly readyPromise;
     constructor(pw: Pushwoosh);
     run(): Promise<void>;
-    private loadWebPopup;
+    /**
+     * Show a popup immediately, ignoring EVERY display condition: delay, page
+     * rules, device_type, visitors_type, frequency capping and trigger_type.
+     * An already visible popup is closed to make room.
+     *
+     * Stats and frequency bookkeeping are recorded exactly as for an automatic
+     * display. Never rejects: resolves false and logs the reason on failure.
+     */
+    show(code: string): Promise<boolean>;
+    /**
+     * Hide the visible popup, optionally only if it is the given one.
+     * Returns false when nothing was hidden.
+     */
+    hide(code?: string): boolean;
+    /**
+     * Hide the visible popup and dismiss everything still pending for this page
+     * load. show() keeps working afterwards.
+     */
+    hideAll(): boolean;
+    isVisible(code?: string): boolean;
+    getVisibleCode(): string | null;
+    getAvailableCodes(): Array<string>;
+    getState(): WebPopupsPublicState;
+    /**
+     * Resolve the entry's renderable content, fetching it at most once. A failed
+     * fetch clears the memo so a later show() can retry.
+     */
+    private ensureContent;
+    private loadContent;
+    private loadedCodes;
     private renderForCurrentPage;
-    private cancelPendingForUnmatchedPages;
+    private canAutoDisplay;
+    private isAutoTrigger;
+    private armDelay;
+    /**
+     * VISIT is reported once per page load, when the popup is armed for the
+     * current page — the same moment as before the queue existed.
+     */
+    private recordVisit;
+    /** Ordering: shorter delay first, then the order the server returned them. */
+    private insertIntoQueue;
+    /**
+     * Release popups whose page rules stopped matching, both the ones still
+     * waiting out their delay and the ones already queued. They return to `idle`
+     * and are re-armed with a full delay if the visitor comes back.
+     */
+    private releaseUnmatchedPending;
+    /** Clear an entry's armed timer and queue slot, leaving its state to the caller. */
+    private detachFromAutoPipeline;
+    /** Show the head of the queue if the display slot is free. */
+    private drain;
+    private scheduleDrain;
+    private cancelScheduledDrain;
+    private present;
+    private renderSubscriptionForm;
+    private lockBodyScroll;
+    private unlockBodyScroll;
     private subscribeToNavigation;
     private checkStrongCondition;
     private checkSoftCondition;
@@ -24,6 +85,4 @@ export declare class WebPopupsWidget {
     private checkCanBeShownByVisitorsTypeCondition;
     private markAsShown;
     private getSessionStorageKey;
-    private addToQueue;
-    private renderSubscriptionForm;
 }

package/widgets/WebPopups/constants.d.ts

@@ -1,5 +1,7 @@
 export declare const WEB_POPUPS_WIDGET_NAMESPACE = "pushwoosh-web-popups";
+export declare const WEB_POPUPS_LOG_PREFIX = "[WebPopups]";
 export declare const POPUP_HOST_Z_INDEX = 2147483647;
+export declare const QUEUE_GAP_MS = 400;
 export declare const SUBSCRIPTION_FORMS_WIDGET_URL = "https://cdn.pushwoosh.com/subscription-forms/widget.js";
 export declare const SUBSCRIPTION_FORMS_WIDGET_TAG = "pushwoosh-subscribe-widget";
 export declare const SUBSCRIPTION_FORMS_API_URL = "https://subscription-form.svc-nue.pushwoosh.com/api/v1";

package/widgets/WebPopups/renderer.d.ts

@@ -14,3 +14,9 @@ export declare const parseWebPopupContent: (json: string) => WebPopupParams | nu
  * submit through the subscription-form service.
  */
 export declare const renderWebPopup: (container: HTMLElement, params: WebPopupParams, onRequestClose: () => void) => void;
+/**
+ * Unmount a popup rendered by `renderWebPopup`. Dropping the host element alone
+ * leaves the tree mounted on a detached node, so component cleanup never runs —
+ * harmless for a popup shown once, not harmless now that popups cycle.
+ */
+export declare const unmountWebPopup: (container: HTMLElement) => void;

package/widgets/WebPopups/types.d.ts

@@ -1,11 +1,22 @@
+import { type WebPopupParams } from 'smart-blocks-utils';
 export type IWebPopupsConfig = {
     enable: boolean;
+    /**
+     * `false` turns off automatic display entirely: the SDK still loads the
+     * popups but never shows one by itself, leaving the site to drive everything
+     * through `Pushwoosh.moduleRegistry.webPopups.show(code)`. Defaults to `true`.
+     *
+     * This is the site-wide switch; the per-popup equivalent is the dashboard's
+     * trigger setting (`WebPopup.trigger_type`).
+     */
+    autoShow?: boolean;
 };
 export type PageRuleOperator = 'EQUALS' | 'STARTS_WITH' | (string & {});
 export type PageRule = {
     path: string;
     operator: PageRuleOperator;
 };
+export type WebPopupTriggerType = 'PAGE_LOAD' | 'API' | (string & {});
 export type WebPopup = {
     code: string;
     popup_form_content_code?: string;
@@ -17,9 +28,75 @@ export type WebPopup = {
     excluded_pages?: PageRule[];
     delay: number;
     frequency: 'ONCE' | 'ONCE_PER_SESSION' | 'EVERY_VISIT';
+    trigger_type?: WebPopupTriggerType;
 };
 export type WebPopupContent = {
     code: string;
     json: string;
     html: string | null;
 };
+/** Renderable popup payload: either parsed content or a hosted form code. */
+export type WebPopupContentBundle = {
+    kind: 'content';
+    parsed: WebPopupParams;
+} | {
+    kind: 'subscription-form';
+    formCode: string;
+};
+/**
+ * Where a popup is in the automatic display pipeline for the current page load.
+ *
+ * `idle` -> `waiting` (delay timer armed) -> `queued` (delay served, waiting for
+ * the display slot) -> `visible` -> `done`. Navigation can send a `waiting` or
+ * `queued` popup back to `idle` when its page rules stop matching.
+ */
+export type WebPopupEntryState = 'idle' | 'waiting' | 'queued' | 'visible' | 'done';
+/** Everything the widget knows about one popup, for the whole page load. */
+export type WebPopupEntry = {
+    popup: WebPopup;
+    /** Index in the server response — the ordering tiebreaker after `delay`. */
+    order: number;
+    state: WebPopupEntryState;
+    /** Renderable content; null until fetched, or if the fetch/parse failed. */
+    content: WebPopupContentBundle | null;
+    /** In-flight fetch, memoised so run() and show() never duplicate a request. */
+    loading: Promise<WebPopupContentBundle | null> | null;
+    /** device_type + visitors_type + frequency, evaluated exactly once in run(). */
+    passedStrongConditions: boolean;
+    /** Armed delay timer while state === 'waiting'. */
+    timeoutId: number | null;
+    /** VISIT already reported for this page load. */
+    visitRecorded: boolean;
+};
+export type WebPopupHideReason = 'user' | 'api' | 'preempted';
+export type WebPopupShowTrigger = 'auto' | 'api';
+/** Handle to the single popup currently on screen. */
+export type VisibleWebPopup = {
+    code: string;
+    host: HTMLElement;
+    modal: boolean;
+    /** Idempotent teardown. */
+    close: (reason: WebPopupHideReason) => void;
+};
+export type WebPopupsPublicState = {
+    /** Code of the popup on screen, if any. */
+    visible: string | null;
+    /** Delay served, waiting for the display slot. */
+    queued: string[];
+    /** Delay timer armed for the current page. */
+    waiting: string[];
+    /** Every code the server returned for this device. */
+    available: string[];
+};
+/**
+ * The programmatic surface exposed as `Pushwoosh.moduleRegistry.webPopups`.
+ */
+export interface IWebPopupsPublicApi {
+    show(code: string): Promise<boolean>;
+    hide(code?: string): boolean;
+    hideAll(): boolean;
+    isVisible(code?: string): boolean;
+    getVisibleCode(): string | null;
+    getAvailableCodes(): string[];
+    getState(): WebPopupsPublicState;
+}