@active-reach/web-sdk 1.41.0 → 1.43.0

package/dist/inapp/AegisInAppManager.d.ts

@@ -1,877 +0,0 @@
-/**
- * AegisInAppManager - Web SDK In-App Messaging Module
- *
- * HTTP polling architecture with client-side evaluation.
- *
- * Security:
- * - XSS Protection: Uses DOM APIs (createElement, textContent) instead of innerHTML
- * - URL Validation: Prevents javascript: protocol injection
- * - CSP Compatible: No inline styles in HTML strings
- *
- * Architecture (RFC 2026-04-16):
- * - Polls /v1/in-app/active on initialize + on identity change
- * - Caches campaigns locally in memory
- * - Evaluates trigger rules client-side
- * - Tracks events (impression, click, dismiss) asynchronously
- *
- * NOTE: Persistent SSE for downstream delivery is disabled by default
- * (enableSSE=false). Tenant dashboards that need realtime (inbox, chat,
- * live page) open SSE directly via Next.js API routes — not via this SDK.
- * End-user storefronts use polling + Web Push for background delivery.
- */
-import type { CartState } from './renderers';
-import { type AegisAction } from './actions';
-export interface InAppCampaign {
-    id: string;
-    type: 'modal' | 'banner' | 'tooltip' | 'full_screen' | 'half_interstitial' | 'alert' | 'pip' | 'video' | 'stories' | 'carousel_cards' | 'sticky_bar' | 'progress_bar' | 'coachmark_tour' | 'product_recommendation' | 'active_web_chat' | 'custom_html';
-    sub_type?: string;
-    title: string;
-    body: string;
-    image_url?: string;
-    video_url?: string;
-    action_url?: string;
-    button_text?: string;
-    background_color?: string;
-    text_color?: string;
-    priority: number;
-    expires_at?: string;
-    frequency?: {
-        max_impressions?: number;
-        max_impressions_per_day?: number;
-        cooldown_seconds?: number;
-        suppress_after_conversion_seconds?: number;
-        suppress_after_dismiss_seconds?: number;
-        scope?: 'session' | 'user' | 'user_sku';
-    };
-    interactive_config?: Record<string, unknown>;
-    client_trigger?: {
-        type: string;
-        config?: Record<string, unknown>;
-    };
-    assigned_variant_id?: string;
-    delivery_modes?: Array<'in_app_overlay' | 'embedded_card' | 'standalone_page'>;
-    widget_category?: 'feedback' | 'loyalty' | 'promo' | 'commerce' | 'support' | 'custom' | 'onboarding' | 'hero' | 'announcement' | 'reorder' | 'reviews';
-    page_key?: 'bill' | 'rewards' | 'feedback' | 'reviews' | 'members';
-    surface?: string[];
-    target_screens?: string[];
-    journey_step_execution_id?: string | null;
-}
-/**
- * Payload for `campaign-click` lifecycle event. CANCELLABLE — return `false`
- * (or call `evt.preventDefault()`) from the handler to suppress the SDK's
- * default `window.location.href` navigation, e.g. to route via a SPA router.
- */
-export interface CampaignClickEvent {
-    campaign: InAppCampaign;
-    /** Sanitized destination URL — already passed through `sanitizeUrl()`. */
-    action_url: string;
-    /** Best-effort button identifier — populated when the click came from a
-     * named button in a multi-button campaign (modals, alerts). `cta` for the
-     * primary CTA on single-button campaigns. */
-    button_id?: string;
-    /** Mutate via `evt.preventDefault()` to signal the SDK to skip its
-     * default hard-navigation. Identical semantics to DOM CustomEvent. */
-    preventDefault: () => void;
-    defaultPrevented: boolean;
-}
-/** Payload for `campaign-dismiss` lifecycle event. */
-export interface CampaignDismissEvent {
-    campaign: InAppCampaign;
-    /** Source of dismissal — close button, swipe, ESC key, programmatic. */
-    source: 'close_button' | 'overlay' | 'esc' | 'auto_timeout' | 'programmatic';
-}
-/** Payload for `error` lifecycle event. Aggregates non-fatal SDK errors so
- * host apps can wire them into Sentry / Datadog RUM / similar. */
-export interface AegisErrorEvent {
-    message: string;
-    error: unknown;
-    /** Optional structured context — `{ event: 'campaign-click' }` for handler
-     * throws, `{ campaign_id, stage }` for render path failures, etc. */
-    context: Record<string, unknown>;
-}
-/**
- * Map of lifecycle event name → handler signature. Used by the typed
- * `on(event, handler)` overload below so TS correctly narrows the payload
- * type per event without a discriminated union at the call site.
- */
-export interface InAppLifecycleEventMap {
-    'campaigns-loaded': (campaigns: InAppCampaign[]) => void;
-    'campaign-will-show': (campaign: InAppCampaign) => void | false;
-    'campaign-shown': (campaign: InAppCampaign) => void;
-    'campaign-click': (evt: CampaignClickEvent) => void | false;
-    'campaign-dismiss': (evt: CampaignDismissEvent) => void;
-    'error': (evt: AegisErrorEvent) => void;
-}
-export interface AegisInAppConfig {
-    writeKey: string;
-    apiHost?: string;
-    userId?: string;
-    contactId?: string;
-    /** Server-minted proof of `contactId` (S/C1). Without it, in-app answers are
-     *  kept as anonymous events and never written onto the contact's profile. */
-    contactToken?: string;
-    organizationId?: string;
-    propertyId?: string;
-    debugMode?: boolean;
-    enableSSE?: boolean;
-    /**
-     * Canonical CTA-action handler (CANONICAL_ACTION_MODEL_TRACKER.md). ONE host
-     * callback receives every CTA action (add_to_cart / open_product / open_cart /
-     * open_login / navigate / custom …) — the CEP-standard shape. Return `true`
-     * when handled; otherwise the SDK applies the canonical fallback (navigate to
-     * the product/cart page) so a CTA is never a dead no-op. Legacy `aegis:*` DOM
-     * events still fire alongside this during the migration.
-     */
-    onAction?: (action: AegisAction) => boolean | void;
-    /**
-     * Platform-aware product-URL resolver (sku → PDP url). Lets a Shopify/Woo/
-     * Magento adapter map to `/products/{handle}` etc. instead of the canonical
-     * `/p/{sku}`. Defaults to `/p/{sku}` when unset.
-     */
-    productUrl?: (sku: string) => string;
-    /**
-     * Workspace cascade reader. Set this from the host SDK as
-     * `getWorkspaceId: () => aegis.getEffectiveWorkspaceId()` so in-app
-     * impressions/clicks/dismisses carry the same workspace context the
-     * main analytics SDK sees (URL path slug, ?ws=, setWorkspace runtime).
-     * Without it, in-app engagement events arrive at event-ingress with
-     * no workspace_id stamped → cross-outlet attribution silently falls
-     * back to the org's primary workspace.
-     */
-    getWorkspaceId?: () => string | undefined;
-    /**
-     * Live cart-state reader, set by the runtime from its imperative
-     * `setCartState(...)`. Threaded into the renderer `RenderContext` so the
-     * progress-bar renderer can read a first-party cart value instead of
-     * `window.*` cart globals. Undefined for embeds that never feed a cart.
-     */
-    getCartState?: () => CartState | undefined;
-}
-export declare function productIdentitiesFor(campaign: unknown): string | undefined;
-export declare class AegisInAppManager {
-    private writeKey;
-    private apiHost;
-    private userId?;
-    private contactId?;
-    private contactToken?;
-    private organizationId?;
-    private propertyId?;
-    private debugMode;
-    private enableSSE;
-    private onActionHandler?;
-    private productUrl;
-    private getWorkspaceId?;
-    private getCartState?;
-    private campaigns;
-    private displayedCampaigns;
-    private _displaySizeMul;
-    private suppressedUntil;
-    private eventSource?;
-    private isInitialized;
-    private reconnectAttempts;
-    private maxReconnectAttempts;
-    private static readonly CONVERSION_STORAGE_PREFIX;
-    private hooks;
-    private readyResolve;
-    readonly ready: Promise<void>;
-    private emit;
-    private emitError;
-    private register;
-    /**
-     * Subscribe to in-app message lifecycle events. Returns an unsubscribe
-     * function — call to remove the handler (matches React `useEffect` cleanup
-     * convention).
-     *
-     * Supported events: `campaigns-loaded`, `campaign-will-show` (cancellable),
-     * `campaign-shown`, `campaign-click` (cancellable), `campaign-dismiss`,
-     * `error`. Cancellable events: handler returns `false` to suppress the
-     * SDK's default behaviour (e.g., prevent the hard navigation on click,
-     * skip rendering on will-show).
-     */
-    on<E extends keyof InAppLifecycleEventMap>(event: E, handler: InAppLifecycleEventMap[E]): () => void;
-    /** Sugar: subscribe to `campaigns-loaded`. Fires after every successful
-     * `/v1/in-app/active` poll with the full active-campaign list. */
-    onCampaignsLoaded(handler: (campaigns: InAppCampaign[]) => void): () => void;
-    /** Sugar: subscribe to `campaign-will-show`. CANCELLABLE — return `false`
-     * to suppress rendering this campaign (host-side suppression rules,
-     * route-aware blocking, etc.). */
-    onCampaignWillShow(handler: (campaign: InAppCampaign) => void | false): () => void;
-    /** Sugar: subscribe to `campaign-shown`. Fires after the SDK has painted
-     * the campaign to the DOM (post-impression). */
-    onCampaignShown(handler: (campaign: InAppCampaign) => void): () => void;
-    /** Sugar: subscribe to `campaign-click`. CANCELLABLE — return `false` (or
-     * call `evt.preventDefault()`) to suppress the SDK's default
-     * `window.location.href` navigation, e.g. to route via a SPA router. */
-    onCampaignClick(handler: (evt: CampaignClickEvent) => void | false): () => void;
-    /** Sugar: subscribe to `campaign-dismiss`. Fires when user closes/swipes
-     * away the campaign before clicking through. */
-    onCampaignDismiss(handler: (evt: CampaignDismissEvent) => void): () => void;
-    /** Sugar: subscribe to `error`. Aggregates non-fatal SDK errors — fetch
-     * failures, render exceptions, host-handler throws. Wire this into your
-     * error monitoring (Sentry, Datadog RUM, etc.). */
-    onError(handler: (evt: AegisErrorEvent) => void): () => void;
-    constructor(config: AegisInAppConfig);
-    initialize(): Promise<void>;
-    private _lastHealOutcome;
-    private _sendPushBootBeacon;
-    updateUserId(userId: string): void;
-    updateContactId(contactId: string, contactToken?: string): void;
-    private refreshDebounceTimer?;
-    private static readonly REFRESH_DEBOUNCE_MS;
-    private pendingPreInitRefresh;
-    private currentSurface;
-    private currentScreen;
-    private currentLocationId;
-    private static readonly KNOWN_SURFACES;
-    /**
-     * Qualifying-event refresh — schedule a debounced `refreshCampaigns()`
-     * call in response to a host-app SDK event (`aegis.page()`,
-     * `aegis.screen()`, `aegis.track(name)`). Matches CleverTap / MoEngage /
-     * WebEngage's "refresh on qualifying event" shape, translated to the
-     * browser session.
-     *
-     * Why: new server-side eligibility opens on these events (a `page` view
-     * arms route-targeted campaigns; a `track('product_viewed')` arms
-     * trigger-gated campaigns whose `client_trigger.config.event` matches).
-     * Pre-P1, the SDK only refreshed on `initialize()` + `updateContactId()`
-     * + the SSE update channel (which storefront has disabled by design),
-     * so newly armed campaigns were invisible until the next identity flip.
-     *
-     * Debounce: 300ms. Five `page()` calls inside the window coalesce to
-     * one fetch; a sixth call ≥300ms after the prior burst starts a new
-     * fetch. The trailing-edge schedule (re-arm on every call) is correct
-     * for storefront rage-clicks + SPA route bursts — we want the LATEST
-     * URL's eligibility, not the first.
-     *
-     * Safe to call on the server (no-op when `setTimeout` is unavailable
-     * — though that's vanishingly rare in any modern environment we ship to).
-     *
-     * Surface capture (In-App Surface Filter tracker P2): when `eventName`
-     * matches one of the 8 canonical surface keys, it is captured into
-     * `currentSurface` and threaded to `/v1/in-app/active?current_surface=<name>`
-     * on the next refresh — wiring the existing `aegis.page(name)` /
-     * `aegis.screen(name)` argument through to campaign targeting. Unknown names
-     * (e.g. `aegis.track('product_viewed')`) still trigger a refresh but do NOT
-     * change `currentSurface`, so arbitrary events never poison the surface gate.
-     */
-    refreshOnEvent(eventName: string, isScreenDeclaration?: boolean): void;
-    /**
-     * Outlet context — declare the outlet the customer is actively viewing
-     * (storefront outlet switcher / location-code). The host calls this when the
-     * shopper picks an outlet (or on initial outlet-scoped page load) and again
-     * with the new id when they switch. Threaded to
-     * `/v1/in-app/active?location_id=<id>` so the server serves outlet-scoped
-     * campaigns for THIS outlet (preferred over the property's static outlet) —
-     * the fix that makes a SHARED multi-outlet storefront's switcher actually
-     * drive in-app targeting. Pass `null` to clear (back to property/brand-wide).
-     *
-     * No-ops when the value is unchanged; otherwise debounce-refreshes so the
-     * armed campaign set follows the switcher within ~300ms.
-     */
-    setLocation(locationId: string | null): void;
-    /**
-     * Conversion-aware suppression. Call this when the host app observes a
-     * goal event (purchase, order_placed, checkout_completed, or any custom
-     * goal the workspace has configured per-campaign).
-     *
-     * For every armed campaign whose `frequency.suppress_after_conversion_seconds`
-     * is set, this:
-     *   1. Persists the conversion in sessionStorage (so subsequent page
-     *      loads in the same tab retain silence).
-     *   2. Computes an expiry epoch_ms and stores it in `suppressedUntil`.
-     *   3. The two campaign-evaluation paths (`tryDisplayNextCampaign`
-     *      and `onClientEvent`) skip campaigns whose `suppressedUntil`
-     *      has not yet passed.
-     *
-     * Scope: only `session` is implemented in P0a. `user` and `user_sku`
-     * scopes degrade to session-only with a debug log; the schema accepts
-     * them so future expansion is non-breaking.
-     *
-     * Safe to call repeatedly for the same goal — each call refreshes the
-     * sessionStorage timestamp and re-applies suppression to any campaigns
-     * loaded since the last call.
-     */
-    notifyConversion(goalName: string): void;
-    /**
-     * Compute and store `suppressedUntil` entries for every armed campaign
-     * whose `frequency.suppress_after_conversion_seconds` is set. Called by
-     * `notifyConversion()` and `refreshCampaigns()` (the latter rehydrates
-     * suppression for newly-loaded campaigns when a prior conversion event
-     * exists in sessionStorage).
-     *
-     * `convertedAt` is the epoch_ms of the conversion; pass `Date.now()`
-     * when called from `notifyConversion`, or the `ts` recovered from
-     * sessionStorage when rehydrating.
-     */
-    private applySuppressionFromCampaigns;
-    /**
-     * Recover any prior conversion timestamps from sessionStorage and apply
-     * suppression to currently-loaded campaigns. Called from
-     * `refreshCampaigns()` after `this.campaigns` is populated. This is the
-     * mechanism that prevents a converted buyer from seeing a discount popup
-     * on the next page load within the same session.
-     */
-    private rehydrateSuppressionFromStorage;
-    /**
-     * Returns true if the campaign is currently suppressed (Date.now() is
-     * before the stored expiry). Used by both display paths.
-     */
-    private isSuppressed;
-    private connectSSE;
-    private disconnectSSE;
-    private attemptReconnect;
-    private refreshCampaigns;
-    private static readonly SERVED_DEDUP_PREFIX;
-    private emitServedEvents;
-    private detectDeviceType;
-    private getABAssignments;
-    private processABAssignments;
-    private getVariantId;
-    private tryDisplayNextCampaign;
-    private _lastDispatch;
-    /** Persistent launchers (active_web_chat) mount AMBIENTLY on every arm — a
-     *  single always-on entry point, NOT an interruption, so they must not
-     *  compete in the one-at-a-time overlay queue (tryDisplayNextCampaign).
-     *  Idempotent: renderActiveWebChatLauncher no-ops once a launcher is live and
-     *  displayedCampaigns guards re-display. Before this, the launcher only
-     *  mounted when it happened to be the single campaign tryDisplayNextCampaign
-     *  picked — so aegis.chat.open() / the mobile "Ask" tab silently did nothing
-     *  whenever another non-triggered campaign was armed first. */
-    private mountPersistentLaunchers;
-    private filledSlots;
-    private slotSignatures;
-    private slotTimers;
-    private slotObserver;
-    private slotRenderScheduled;
-    private slotUnfilledBeaconed;
-    private slotUnfilledSweepTimer;
-    /**
-     * Scan the page for `[data-aegis-slot]` anchors and render any
-     * campaign whose `widget_category` matches the slot key AND whose
-     * `delivery_modes` includes `'embedded_card'`.
-     *
-     * Runs after every refresh-campaigns success — the WeakSet guard
-     * keeps it idempotent across re-fetches. The slot key is the campaign's
-     * `widget_category` (the wide grouping discriminator from F3), so a
-     * `<div data-aegis-slot="feedback">` will accept the first active
-     * campaign with `widget_category='feedback'` + embedded_card mode.
-     */
-    /** Normalize a declared free-form screen name to a canonical surface key
-     * ('storefront.catalog' → 'storefront_catalog'), or null when it maps
-     * outside the enum (e.g. 'shopify.product'). Mirrors the server's
-     * `_canonical_surface_from_screen`. */
-    private canonicalSurfaceFromScreen;
-    /**
-     * Dynamic Screens P2 + substrate isolation — combined surface + free-form
-     * screen predicate, mirroring the server's `_screen_or_surface_matches`:
-     *   - screen-only campaign matches strictly on `currentScreen`
-     *   - a declared screen NORMALIZES into the canonical tier
-     *     ('storefront.catalog' → storefront_catalog) so surface pins match
-     *   - a declared screen that maps OUTSIDE the enum (e.g. 'shopify.product')
-     *     does NOT fall through to the all-surfaces default for surface-pinned
-     *     campaigns — actii.me-pinned campaigns never render on Shopify
-     *   - hosts that declare nothing keep the legacy render-everything default
-     */
-    private matchesCurrentScreenOrSurface;
-    private ensureSlotObserver;
-    private renderIntoSlots;
-    /**
-     * slot_unfilled telemetry (Surface/Slot Contract tracker P2).
-     *
-     * A served embedded_card campaign whose `widget_category` has NO
-     * `data-aegis-slot` anchor on the page is silently discarded by
-     * `renderIntoSlots` — the exact failure mode that made the storefront
-     * value bar dark for browse traffic while the dashboard reported the
-     * campaign "active". This sweep runs ~3s after a render attempt (late
-     * mounts / SPA hydration get time to appear; the MutationObserver re-fill
-     * handles anchors that arrive even later) and beacons one `slot_unfilled`
-     * per (campaign, path) per session so the dashboard can show
-     * "served but never rendered".
-     */
-    private scheduleSlotUnfilledSweep;
-    private sweepUnfilledSlots;
-    /**
-     * Rotating slot — cycles eligible campaigns one at a time inside a single host
-     * slot (the storefront sticky-footer "value bar"). Each campaign is pre-rendered
-     * into its own hidden pane so a live `progress_bar` keeps tracking the cart even
-     * while off-screen; only the visibility toggles every `rotateMs`. The impression
-     * is deferred at render and fired per campaign on FIRST visibility, so hidden
-     * panes never over-count. One rendered pane → no rotation (just shows it).
-     */
-    private renderRotatingSlot;
-    /**
-     * Surface-Canvas inline element anchoring (Plotline / WebEngage model).
-     *
-     * Render inline-format campaigns into a HOST element the operator picked via
-     * the element inspector — `interactive_config.anchor.element_selector` — instead
-     * of a host-declared `[data-aegis-slot]`. `position` controls placement:
-     *   inside (default) — append into the element (e.g. the storefront footer card)
-     *   replace          — clear the element's host-default children, then render in
-     *   before / after   — render into a wrapper inserted as a sibling
-     *
-     * Reuses `renderCampaignIntoSlot` (same sub_type dispatch → `renderProgressBarInline`
-     * etc.) so inline render code is single-sourced with the slot path. Embedded-card
-     * gated (so an anchored campaign never ALSO renders as an overlay), surface-gated,
-     * and idempotent via `filledSlots` keyed on the resolved element. A selector that
-     * doesn't resolve emits `anchor_unresolved` (parity with tooltip anchoring).
-     */
-    private renderIntoAnchors;
-    /**
-     * U7 — render server-injected token-bound campaigns.
-     *
-     * The standalone-page route at `apps/cashier-portal/src/app/s/[slug]/
-     * [workspace]/[page_key]/page.tsx` (and the `/c/[token]` Aegis-hosted
-     * fallback) verify the URL token server-side via the F16 internal
-     * endpoint, then embed the resolved campaign payload as JSON inside
-     * a `<div data-aegis-token-data="...">` anchor. This SDK method
-     * scans for those anchors, parses the payload, and dispatches to
-     * the SAME `renderCampaignIntoSlot` used by the [data-aegis-slot]
-     * path — so widget rendering code is single-sourced.
-     *
-     * Why server-injected (not client-fetched): keeps INTERNAL_API_SECRET
-     * server-side, avoids an extra browser round-trip for verify, gives
-     * Next.js SSR-friendly initial HTML for SEO/no-JS users (rendered
-     * via the page handler's React tree alongside the SDK anchor).
-     *
-     * Idempotency: filledSlots is the same WeakSet used by
-     * renderIntoSlots — re-running on SSE/poll refresh is a no-op for
-     * already-filled anchors.
-     */
-    private renderTokenAnchors;
-    /**
-     * Slot-mode counterpart to `displayCampaign`. Reuses the existing
-     * lifecycle hooks (`campaign-will-show`, `displayedCampaigns`,
-     * `campaign-shown`, impression tracking) so analytics + frequency
-     * caps work the same way as overlay renders.
-     *
-     * Only the sub_types that make UX sense embedded are handled; the
-     * rest (modal, full_screen, half_interstitial, alert, pip) silently
-     * skip — those types only make sense as fullscreen overlays.
-     */
-    private renderCampaignIntoSlot;
-    /** §7.13.H — generic embedded card: image / title / body / coupon chip / CTA.
-     *  The catch-all for banner + nudge sub_types (birthday, referral, app-install,
-     *  win-back, etc.) so EVERY gallery nudge renders on the bill (previously only
-     *  star_rating / nps_survey / form were handled → nudges never appeared). */
-    /**
-     * Whether `interactive_config` carries a composed `card_template` (non-empty
-     * `elements[]`). The ONE detector shared by all three composed-card cutover
-     * gates — inline slot, chrome overlay, and the P6 survey-overlay cutover — so
-     * they can't drift (the inline gate previously omitted the non-empty check).
-     */
-    private _hasComposedTemplate;
-    /**
-     * P6.full — flat survey → card_template adapter. A `nps_survey` / `star_rating`
-     * / `quick_poll` authored WITHOUT a card_template gets one synthesised in place
-     * (carrying its follow-up config), so the EXISTING composed-template gates route
-     * it through the ONE card-template engine + the shared element builders (with
-     * the ported reason-capture/thank-you flows) — overlay AND slot. Back-compat:
-     * the field names + follow-up defaults match the retired bespoke renderers.
-     * No-op when a template already exists or the type isn't a single-card survey.
-     */
-    private _ensureSurveyTemplate;
-    /**
-     * Composed single card — renders a campaign's top-level `card_template`
-     * (frame + elements: icon/text/progress/image/cta/group/…) through the generic
-     * `renderCardFromTemplate` engine. The canonical path for the rich card editor:
-     * the storefront value bar, loyalty nudges, and any operator-composed card all
-     * render here from declarative JSON, on ACS / custom / third-party sites.
-     */
-    private renderComposedCardSlot;
-    /**
-     * C2 — composed card body in an OVERLAY (modal / banner / full_screen /
-     * half_interstitial). The overlay counterpart to `renderComposedCardSlot`: it
-     * builds the same `TemplateCard` from the campaign's canonical fields and paints
-     * it with the generic `renderCardFromTemplate` engine, then wraps it in the
-     * standard overlay chrome (close button + size scaling) so a composed card looks
-     * identical whether overlaid or slotted. Only invoked when a `card_template` is
-     * present (see displayCampaign) — flat campaigns never reach here.
-     * See IN_APP_FORMAT_LOCK_AND_COMPOSABLE_CARDS_TRACKER.md (Part B / C2).
-     */
-    private renderComposedCardOverlay;
-    private renderGenericCardSlot;
-    /**
-     * §7.13.I — embedded profile FORM. Renders one input per `form_fields` entry
-     * and, on submit, POSTs `{response_type:'form', payload:{fields:{key:value}}}`
-     * to `/in-app/responses` — the cell-plane enrichment writes the mapped answers
-     * back onto the contact. Keyed by each field's `key` so it matches the
-     * campaign's field→contact map.
-     */
-    private renderFormSlot;
-    /** Shared form body — the input fields + submit. Used embedded (slot) today;
-     *  the overlay form path reuses it too. */
-    private _buildFormBody;
-    /** POST a form response to /in-app/responses (gateway → cell-plane). The
-     *  cell-plane enriches the contact from the campaign's field-map. Best-effort. */
-    private submitFormResponse;
-    /**
-     * Generic interactive response submit → POST /v1/in-app/responses. Returns the
-     * parsed server response (which for spin/scratch carries the server-picked
-     * `prize`) or null. Interactive Widgets Parity tracker — every embedded widget
-     * records a response so analytics + prize-from-segments work uniformly.
-     */
-    private submitWidgetResponse;
-    /**
-     * Built-in embedded SPIN WHEEL (no AegisMessageRuntime callback dependency —
-     * works on the bill). Slices come from `interactive_config.segments`; on Spin
-     * it submits to /in-app/responses, the server picks the prize from the AUTHORED
-     * segments, and the wheel animates to that segment + reveals the prize/coupon.
-     */
-    private renderSpinWheelSlot;
-    /**
-     * Built-in embedded IMAGE/VIDEO CAROUSEL — a swipeable horizontal strip of
-     * `interactive_config.cards` (image OR video + title + body + CTA), contained
-     * to the slot (the parent overflow:hidden + this strip's own scroll). Each card
-     * reuses the same shape as the In-App carousel editor authors.
-     */
-    private renderCarouselCardsSlot;
-    /** Built-in embedded COUNTDOWN — live H:M:S digits that pulse red in the
-     *  final stretch (<60s) to create urgency, plus the CTA. */
-    private renderCountdownSlot;
-    /** Foil palette — a brushed-metal gradient + a contrast "ink" (for the
-     *  SCRATCH-HERE text, sparkle motif, and logo tint) derived from the operator's
-     *  chosen foil colour (brand primary / custom hex). Unset / invalid → the
-     *  default silver. Light foils get dark ink, dark foils get white ink, so the
-     *  prompt stays legible on any colour. */
-    private _scratchFoilPalette;
-    /** Built-in embedded SCRATCH CARD — a canvas foil the customer scratches to
-     *  reveal the server-picked prize, then submits (records + grants). Confetti
-     *  on reveal. No AegisMessageRuntime callback dependency (works on the bill). */
-    private renderScratchCardSlot;
-    /** Extract a human prize label from a spin/scratch server response. */
-    private _extractPrizeLabel;
-    /** Extract a redeemable coupon code from a spin/scratch server response. */
-    private _extractCouponCode;
-    /**
-     * Slot styling — the operator's look-&-feel knobs (Style panel) applied to the
-     * EMBEDDED render, CLAMPED to boundary-safe ranges so an authored value can
-     * never break out of the dynamic block. Unauthored knobs are `undefined` so
-     * each renderer keeps its own compact default (no visual regression). Colors
-     * default to the current slot defaults. The slot card keeps `width:100%;
-     * overflow:hidden` regardless, so the boundary guarantee is independent of
-     * these values.
-     */
-    private _slotStyle;
-    private _wrapInSlotCard;
-    /**
-     * Flush a rendered slot card into its host card — drop the per-campaign radius
-     * + shadow so it reads as one unit with the host wrapper (used for the
-     * storefront value bar via `data-aegis-slot-flush`). Targets every
-     * `[data-campaign-id]` card inside `container` (or the container itself).
-     */
-    private _flattenSlotCard;
-    /**
-     * Evaluate the currently armed campaigns against a client-side event
-     * and render any that match their `client_trigger`.
-     *
-     * Called by the host app (e.g., the EcommerceTracker on product_viewed),
-     * or by future TriggerEngine bridges. Safe to call repeatedly for the
-     * same event — dedup happens via `displayedCampaigns`.
-     *
-     * Supported trigger types (align with the cell-plane server-side
-     * `display_rules.trigger_type`):
-     *   - `custom_event`  : fire when eventName matches config.event
-     *   - `product_match` : fire on `product_viewed` when eventData.product_id
-     *                       matches config.product_id (string or string[])
-     *   - `delay`         : client-side setTimeout — evaluated at armeng
-     *                       time (kicked off from `displayCampaign`), not here.
-     *   - `exit_intent` / `scroll_depth` / `time_on_page` / `inactivity` : the
-     *                       TriggerEngine event named by `behaviouralTriggerEvent`;
-     *                       AegisMessageRuntime arms the engine and forwards it.
-     */
-    onClientEvent(eventName: string, eventData?: Record<string, unknown>): void;
-    private matchesClientTrigger;
-    private displayCampaign;
-    /** The single chat launcher on the page (Active Web Chat). Persistent — not
-     *  re-mounted on SSE/poll refresh; torn down on manager teardown. */
-    private activeWebChat?;
-    /**
-     * Mount the Active Web Chat launcher. Idempotent: a repeat delivery of the
-     * same (or another) chat campaign is a no-op once one launcher is live — at
-     * most one bubble per page, and an open session is never yanked out from
-     * under the customer.
-     */
-    private renderActiveWebChatLauncher;
-    /**
-     * Build the shared context passed into the preload-first renderers.
-     * Matches the interface in `./renderers/types.ts`. Kept as a private
-     * method (rather than inlined at each call-site) so future renderer
-     * additions stay consistent and easy to audit.
-     */
-    private buildRenderContext;
-    /**
-     * Renders interactive sub-type campaigns (spin wheel, NPS, quiz, etc.)
-     * using DOM-safe rendering. These sub-types use the campaign's
-     * interactive_config payload for type-specific behavior.
-     */
-    private renderInteractive;
-    /**
-     * Built-in overlay for spin_wheel / scratch_card when no host runtime is
-     * wired (dashboard preview, runtime-less hosts). Wraps the same interactive
-     * slot renderers (`renderSpinWheelSlot` / `renderScratchCardSlot`) in a modal
-     * so the gamified widget is fully playable — not a dead frame.
-     */
-    /** Display-size multiplier — operator control over how big a bounded overlay
-     *  renders (small 0.82 / medium 1 / large 1.18). Default medium = prior size.
-     *  Read from interactive_config.display_size; mirrors the schema enum + the
-     *  dashboard preview harness so the operator's choice is honored identically. */
-    private _sizeMul;
-    private renderGamificationOverlay;
-    /** A circular ✕ close button in the modal's top-right corner. */
-    private _addCornerClose;
-    /**
-     * Custom HTML type — render operator-authored HTML in a SANDBOXED iframe.
-     * The frame runs with `sandbox="allow-scripts"` and NO `allow-same-origin`, so
-     * it's an opaque/null origin: no access to the host DOM, cookies, localStorage,
-     * the SDK write-key, or same-origin creds. The only channel out is a validated
-     * `postMessage` bridge (close / track / cta / resize), exposed to authors as a
-     * tiny injected `aegis` shim. See IN_APP_CUSTOM_HTML_TRACKER.md (security model).
-     */
-    private renderCustomHtml;
-    /** Build the sandboxed iframe + the validated message bridge. Reused by the
-     *  overlay + embedded-slot custom-HTML renderers. */
-    private _buildCustomHtmlFrame;
-    /** Embedded-slot custom HTML (e.g. on the bill) — the same sandboxed frame in
-     *  a slot card instead of an overlay. */
-    private renderCustomHtmlSlot;
-    private renderCountdownOffer;
-    /**
-     * Multi-step form (SDK Demo v4 W1b) — in-app render type matching the
-     * Plotline multi-step flow pattern: a progress bar + per-step question with
-     * options, Back/Next navigation, Submit on the last step. `ic.steps` is an
-     * array of `{ question, options[] }`. DOM-safe (no innerHTML).
-     */
-    private renderMultiStepForm;
-    /**
-     * Push primer (SDK Demo v4 W3) — in-app render type that "soft-asks" before
-     * the OS hard-ask. The Enable CTA calls `Notification.requestPermission()`;
-     * we report `permission_granted` / `permission_denied` / `permission_default`
-     * so journeys can react. Degrades gracefully where Notification is absent.
-     */
-    private renderPushPrimer;
-    private _pushOptInCache;
-    private _pushOptInLoading;
-    /** Synchronous "can the primer render RIGHT NOW" gate used by the overlay
-     *  selection loop. Never tracks events — an ineligible primer is a
-     *  non-event, not a dismissal. */
-    private _primerEligibleNow;
-    /**
-     * Fetch the property's push opt-in mode/trigger from /v1/sdk/config
-     * (browser HTTP cache + ETag make repeat calls cheap). Fail-open to
-     * 'standard'/'immediate' — a config blip must not silently kill the
-     * only web-push opt-in surface.
-     */
-    private _fetchPushOptInConfig;
-    /**
-     * Prompt-timing gate for the standard primer.
-     *   immediate        → always
-     *   second_page_view → from the 2nd page load on (localStorage counter,
-     *                      incremented once per manager init)
-     *   after_first_order→ once `aegis_ordered` is set (host runtimes set it
-     *                      on purchase; storefront checkout does)
-     *   manual           → never auto-shows; host calls the primer explicitly
-     */
-    private _promptTriggerSatisfied;
-    private _renderPushPrimerModal;
-    /**
-     * Push-primer Enable handler — runs the SAME end-to-end subscribe flow the
-     * (now-retired) ACS PushOptInBanner did, so the primer is a complete web-push
-     * opt-in on every surface (ACS / Shopify / 3rd-party site), not just an OS
-     * permission prompt. Steps: fetch VAPID public key → register SW → hard-ask →
-     * subscribe → POST /v1/web_push/subscriptions → stitch known contact.
-     *
-     * Push runtime resolution prefers the already-loaded `window.AegisWebPush`
-     * global (the Shopify embed lazy-loads it via /apps/active_reach/push.js, so
-     * we reuse that single instance instead of registering the SW twice), and
-     * only dynamic-imports the module as a fallback for hosts that didn't preload
-     * it (ACS / 3rd-party sites). Returns the resolved permission string for
-     * engagement reporting; falls back to a bare permission ask if push can't be
-     * wired (no propertyId, no VAPID).
-     */
-    private _subscribeFromPushPrimer;
-    private renderQuiz;
-    /**
-     * Embedded quiz on a bill/page slot — same question-stepping flow as the
-     * overlay, rendered inline with no overlay/close (Open/Closed: both paths
-     * share `_runQuizFlow`, so a feature added once lights up both). Returns
-     * false when there are no questions so dispatch can fall back to a card.
-     */
-    private renderQuizSlot;
-    /**
-     * Shared quiz engine — drives the question stepper, scoring (knowledge =
-     * correct_index/points, personality = outcome tally), result-band selection,
-     * CTA, reaction and the `quiz` response submit. Renders into the provided
-     * `body`. `overlay` is the dismiss target for the close button on the overlay
-     * path; pass null on the slot path (no close affordance inline).
-     */
-    private _runQuizFlow;
-    private createOverlay;
-    /** Wrap a card in a display-size scaling container (no-op at medium/×1). Used
-     *  by formats that build their overlay inline (renderModal) rather than via
-     *  createOverlay, so size is honored identically. */
-    private _wrapScaled;
-    private createCTAButton;
-    private addCloseButton;
-    /**
-     * Navigate to a campaign CTA URL.
-     *
-     * Dispatches a cancellable `aegis:campaign-click` CustomEvent so host
-     * apps (e.g., the storefront SPA) can intercept and route in-place via
-     * their client-side router, avoiding a full page reload that re-runs
-     * SSR + re-renders the location picker / banner / cart drawer state.
-     *
-     * The host calls `event.preventDefault()` to suppress the hard nav and
-     * handle the URL itself. If no listener calls preventDefault, the SDK
-     * falls through to `window.location.href` so plain HTML pages without a
-     * SPA still get the user to the destination.
-     *
-     * Industry parallel: CleverTap dispatches `clevertap-deeplink-click`,
-     * MoEngage dispatches `MoE_inappRedirect`. The pattern lets the same
-     * SDK serve both vanilla websites (full nav fallback) and SPAs
-     * (in-place state change) without per-host configuration.
-     */
-    private navigateToCampaignAction;
-    /** Register/replace the canonical CTA-action handler after construction (the
-     *  config `onAction` is the construct-time equivalent). Idempotent. */
-    setOnAction(handler: (action: AegisAction) => boolean | void): void;
-    /**
-     * Canonical CTA-action dispatcher (CANONICAL_ACTION_MODEL_TRACKER.md). ONE path
-     * for every host-facing CTA action:
-     *   1. give the host's `onAction` handler first refusal (return `true` = handled);
-     *   2. ALSO fire the legacy `aegis:*` DOM event (cancelable) so existing
-     *      listeners (ACS) keep working unchanged during the migration;
-     *   3. if STILL unhandled → canonical fallback (navigate to the product/cart
-     *      page) so a CTA is never a dead no-op (the rail-"Add" 3rd-party gap).
-     * Both add-to-cart paths (card "Add" + the `aegis://cart-add` verb) funnel here,
-     * so they're one behaviour delivered to the host's single `onAction` handler.
-     * (Phase E.2 hard cutover — the legacy `aegis:*` DOM events were removed.)
-     */
-    dispatchAction(action: AegisAction, _campaignId?: string): void;
-    /**
-     * Phase-2 CTA action verbs (`aegis://<verb>?<params>`). Performs an in-app
-     * behaviour instead of navigating. Verbs:
-     *   dismiss         — close the message (tracked as dismissed)
-     *   request-push    — prompt for web-push permission, then close
-     *   cart-add?sku=X  — canonical `add_to_cart` action via dispatchAction
-     *                     (cancelable + product-page fallback)
-     */
-    private runCampaignActionVerb;
-    /** Remove a rendered campaign's element(s) from the DOM by campaign id. */
-    private removeCampaignEl;
-    /**
-     * Resolve the operator's colour + style choices into concrete CSS values.
-     * Mirrors the studio preview's styleFrom() 1:1 (apps/web/src/app/api/preview/
-     * in-app/route.tsx) — same keys, same defaults — so what the operator designs
-     * in the editor is what the live SDK renders. The container uses the
-     * campaign's background_color/text_color and the CTA button is the inverse
-     * (so it pops on the coloured surface), exactly like the preview. Earlier the
-     * card renderers hardcoded a white card + dark text and ignored the Style
-     * panel entirely, so the live message looked nothing like the preview.
-     */
-    /** Pick a legible label colour (#fff or near-black) for a solid fill, by
-     *  relative luminance — so a brand-accent button is always readable. */
-    private _contrastText;
-    /** Central surface palette — the ONE place the brand colour becomes either a
-     *  surface fill or an accent, so every widget is consistent.
-     *
-     *  `surface_style` (interactive_config), default `clean`:
-     *   - `clean`  → NEUTRAL surface (white) + dark text + the brand colour as the
-     *                CTA ACCENT. The 60-30-10 / WCAG-safe default: legible copy and
-     *                a CTA that actually pops (higher CTR than a flat colour card).
-     *   - `branded`→ brand-colour SURFACE + contrasting text + inverse CTA. For
-     *                high-impact, low-text moments (flash sale, celebration).
-     *  `background_color` is the operator's brand colour in BOTH modes — surface
-     *  fill when branded, CTA accent when clean. */
-    private _surfacePalette;
-    private inAppStyle;
-    private renderBanner;
-    private renderModal;
-    private _heroVideo;
-    private renderFullScreen;
-    private renderHalfInterstitial;
-    private renderAlert;
-    private _pipCornerCss;
-    private renderPIP;
-    private removeBanner;
-    private removeModal;
-    /**
-     * Spotlight backdrop colour → a dim of the chosen base at `dim` opacity.
-     * `dark` (slate, default) · `brand` (the campaign brand colour) · `black` ·
-     * `custom` (a picked hex). Encoded as 8-digit hex alpha; falls back to slate
-     * rgba when the base isn't a 6-digit hex (e.g. an rgb() brand colour).
-     */
-    private _spotlightDimColor;
-    private renderTooltip;
-    /** Fire a short confetti burst from the top of an anchor element. Vanilla
-     *  (no deps) — mirrors the cashier-portal confetti. Respects
-     *  prefers-reduced-motion. Used on positive moments (high rating, won prize,
-     *  form complete). */
-    private _fireConfetti;
-    /**
-     * Emotional reaction layer (CEP parity — CleverTap exposes configurable
-     * outcome animation; MoEngage sets distinct win/lose icons). Three CONTEXT-
-     * AWARE intents drive a premium Lottie animation (with an instant SVG
-     * placeholder + graceful fallback):
-     *
-     *   - `celebrate` → a real WIN in a game (spin/scratch prize). Trophy Lottie,
-     *                   gold rings, confetti. The big, earned moment.
-     *   - `affirm`    → positive FEEDBACK (high rating, NPS promoter, quiz/form
-     *                   done). An animated success check — friendly, NOT a trophy
-     *                   (a survey isn't a contest).
-     *   - `empathize` → a negative outcome (low rating, NPS detractor, no-prize /
-     *                   "Try again"). A soft breathing heart — supportive, NO
-     *                   confetti, NO rings.
-     *
-     * Honors prefers-reduced-motion (static badge, no motion).
-     */
-    private _playReaction;
-    /** Hand-built, brand-neutral animated SVG badges for the reaction layer — a
-     *  premium alternative to system emoji (consistent across browsers, no Lottie
-     *  dependency). The check strokes itself in; the heart breathes gently. */
-    private _reactionSvg;
-    /** Resolve the base URL the SDK assets are served from (so Lottie JSON +
-     *  player load from the same origin/path as the SDK bundle — works in the
-     *  dashboard preview and same-origin installs; cross-origin CDN installs fall
-     *  back to the inline SVG when the asset 404s). */
-    private _assetBase;
-    /** Lazy-load the Lottie player once (cached on window). Resolves to the
-     *  global `lottie`, or rejects if it can't be fetched (→ SVG fallback). */
-    private _loadLottie;
-    private addAnimationStyles;
-    private sanitizeUrl;
-    private sanitizeColor;
-    /**
-     * Track in-app event via the standard Event Ingress pipeline.
-     *
-     * Events flow: SDK → Event Ingress → Kafka → Governance Consumer
-     * → Event Engine → ClickHouse (in_app_events + events_with_ttl)
-     *
-     * The event_type uses the canonical prefix `in_app.` so the event
-     * switchboard maps it to the correct canonical form:
-     *   in_app.impression → engagement.view
-     *   in_app.clicked    → engagement.click
-     *   in_app.dismissed  → engagement.dismiss
-     */
-    private trackEvent;
-    /** campaign id → journey_step_execution_id for queued items seen this page. */
-    private journeyStepByCampaign;
-    /** `${step}:${action}` acks sent (or in flight) this page — one per render. */
-    private journeyAcks;
-    private static readonly JOURNEY_ACK_RETRY_MS;
-    /**
-     * POST /v1/in-app/widgets/{step}/ack — the canonical writer of a queue row's
-     * seen-state (the same endpoint the Android and iOS SDKs call). Fail-soft by
-     * construction: it runs after the render, is never awaited by it, and never
-     * throws. A network error or 5xx is retried once; if that also fails the key
-     * is released, so the next render of the (still re-served) message tries
-     * again. A 4xx is the server's answer and is not retried. The server side is
-     * idempotent — a repeated action is answered `late_arrival` and writes
-     * nothing — so a duplicate ack is harmless.
-     */
-    private ackJourneyQueueItem;
-    private log;
-    destroy(options?: {
-        clearABState?: boolean;
-    }): void;
-}
-//# sourceMappingURL=AegisInAppManager.d.ts.map