@active-reach/web-sdk 1.7.4 → 1.8.5

package/dist/inapp/AegisInAppManager.d.ts

@@ -48,6 +48,52 @@ export interface InAppCampaign {
     };
     assigned_variant_id?: string;
 }
+/**
+ * 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;
@@ -84,6 +130,45 @@ export declare class AegisInAppManager {
     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>;
     updateUserId(userId: string): void;

package/dist/inapp/AegisInAppManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AegisInAppManager.d.ts","sourceRoot":"","sources":["../../src/inapp/AegisInAppManager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AegisInAppManager.d.ts","sourceRoot":"","sources":["../../src/inapp/AegisInAppManager.ts"],"names":[],"mappings":"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"}

package/dist/inapp/index.d.ts

@@ -1,4 +1,4 @@
 export { AegisInAppManager } from './AegisInAppManager';
-export type { InAppCampaign, AegisInAppConfig } from './AegisInAppManager';
+export type { InAppCampaign, AegisInAppConfig, CampaignClickEvent, CampaignDismissEvent, AegisErrorEvent, InAppLifecycleEventMap, } from './AegisInAppManager';
 export { renderPreview } from './renderPreview';
 //# sourceMappingURL=index.d.ts.map

package/dist/inapp/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/inapp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/inapp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export type { AegisEvent, TrackEvent, IdentifyEvent, PageEvent, GroupEvent, Alia
 export type { Plugin, PluginRegistry } from './types/plugin';
 export { debounce, throttle } from './utils/debounce';
 export type { ConsentPreferences, ConsentCategory, ConsentStatus, } from './utils/consent';
-export type { InAppCampaign, AegisInAppConfig } from './inapp';
+export type { InAppCampaign, AegisInAppConfig, CampaignClickEvent, CampaignDismissEvent, AegisErrorEvent, InAppLifecycleEventMap, } from './inapp';
 export { renderPreview } from './inapp';
 export { AegisPlacementManager } from './placements/AegisPlacementManager';
 export type { PlacementContent, PlacementSlot, AegisPlacementConfig, } from './placements/AegisPlacementManager';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -751,6 +751,10 @@ const _AegisInAppManager = class _AegisInAppManager {
     this.isInitialized = false;
     this.reconnectAttempts = 0;
     this.maxReconnectAttempts = 5;
+    this.hooks = /* @__PURE__ */ new Map();
+    this.ready = new Promise((resolve) => {
+      this.readyResolve = resolve;
+    });
     this.writeKey = config.writeKey;
     this.apiHost = config.apiHost || "https://api.aegis.ai";
     this.userId = config.userId ?? readAnonIdFromStorage$1();
@@ -761,6 +765,92 @@ const _AegisInAppManager = class _AegisInAppManager {
     this.enableSSE = config.enableSSE === true;
     this.onInteractiveCampaign = config.onInteractiveCampaign;
   }
+  emit(eventName, payload) {
+    const handlers = this.hooks.get(eventName);
+    if (!handlers || handlers.size === 0) return true;
+    let proceed = true;
+    for (const handler of handlers) {
+      try {
+        const result = handler(payload);
+        if (result === false) proceed = false;
+      } catch (err) {
+        this.emitError(err, { event: eventName });
+      }
+    }
+    return proceed;
+  }
+  emitError(err, context) {
+    const handlers = this.hooks.get("error");
+    if (!handlers || handlers.size === 0) {
+      this.log(`Aegis SDK error: ${err instanceof Error ? err.message : String(err)}`, "error");
+      return;
+    }
+    for (const handler of handlers) {
+      try {
+        handler({
+          message: err instanceof Error ? err.message : String(err),
+          error: err,
+          context: context ?? {}
+        });
+      } catch {
+      }
+    }
+  }
+  register(eventName, handler) {
+    if (!this.hooks.has(eventName)) this.hooks.set(eventName, /* @__PURE__ */ new Set());
+    this.hooks.get(eventName).add(handler);
+    return () => {
+      var _a;
+      (_a = this.hooks.get(eventName)) == null ? void 0 : _a.delete(handler);
+    };
+  }
+  /**
+   * 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(event, handler) {
+    return this.register(event, handler);
+  }
+  /** Sugar: subscribe to `campaigns-loaded`. Fires after every successful
+   * `/v1/in-app/active` poll with the full active-campaign list. */
+  onCampaignsLoaded(handler) {
+    return this.register("campaigns-loaded", handler);
+  }
+  /** Sugar: subscribe to `campaign-will-show`. CANCELLABLE — return `false`
+   * to suppress rendering this campaign (host-side suppression rules,
+   * route-aware blocking, etc.). */
+  onCampaignWillShow(handler) {
+    return this.register("campaign-will-show", handler);
+  }
+  /** Sugar: subscribe to `campaign-shown`. Fires after the SDK has painted
+   * the campaign to the DOM (post-impression). */
+  onCampaignShown(handler) {
+    return this.register("campaign-shown", handler);
+  }
+  /** 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) {
+    return this.register("campaign-click", handler);
+  }
+  /** Sugar: subscribe to `campaign-dismiss`. Fires when user closes/swipes
+   * away the campaign before clicking through. */
+  onCampaignDismiss(handler) {
+    return this.register("campaign-dismiss", handler);
+  }
+  /** 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) {
+    return this.register("error", handler);
+  }
   async initialize() {
     if (this.isInitialized) {
       this.log("AegisInApp already initialized");
@@ -1006,8 +1096,11 @@ const _AegisInAppManager = class _AegisInAppManager {
       this.processABAssignments(this.campaigns);
       this.rehydrateSuppressionFromStorage();
       this.log(`Fetched ${this.campaigns.length} campaigns`);
+      this.emit("campaigns-loaded", this.campaigns);
+      this.readyResolve();
       this.tryDisplayNextCampaign();
     } catch (error) {
+      this.emitError(error, { stage: "refresh-campaigns" });
       this.log(`Error refreshing campaigns: ${error}`, "error");
     }
   }
@@ -1103,6 +1196,11 @@ const _AegisInAppManager = class _AegisInAppManager {
     }
   }
   displayCampaign(campaign) {
+    const proceed = this.emit("campaign-will-show", campaign);
+    if (!proceed) {
+      this.log(`campaign ${campaign.id} suppressed by campaign-will-show handler`);
+      return;
+    }
     this.displayedCampaigns.add(campaign.id);
     const interactiveSubTypes = /* @__PURE__ */ new Set([
       "spin_wheel",
@@ -1116,6 +1214,7 @@ const _AegisInAppManager = class _AegisInAppManager {
     if (campaign.sub_type && interactiveSubTypes.has(campaign.sub_type)) {
       this.renderInteractive(campaign);
       this.trackEvent(campaign.id, "impression");
+      this.emit("campaign-shown", campaign);
       return;
     }
     switch (campaign.type) {
@@ -1146,24 +1245,30 @@ const _AegisInAppManager = class _AegisInAppManager {
       case "carousel_cards":
         renderCarouselCards(this.buildRenderContext(campaign));
         this.trackEvent(campaign.id, "impression");
+        this.emit("campaign-shown", campaign);
         return;
       case "sticky_bar":
         renderStickyBar(this.buildRenderContext(campaign));
         this.trackEvent(campaign.id, "impression");
+        this.emit("campaign-shown", campaign);
         return;
       case "progress_bar":
         renderProgressBar(this.buildRenderContext(campaign));
         this.trackEvent(campaign.id, "impression");
+        this.emit("campaign-shown", campaign);
         return;
       case "coachmark_tour":
         renderCoachmarkTour(this.buildRenderContext(campaign));
+        this.emit("campaign-shown", campaign);
         return;
       case "product_recommendation":
         renderProductRecommendation(this.buildRenderContext(campaign));
         this.trackEvent(campaign.id, "impression");
+        this.emit("campaign-shown", campaign);
         return;
     }
     this.trackEvent(campaign.id, "impression");
+    this.emit("campaign-shown", campaign);
   }
   /**
    * Build the shared context passed into the preload-first renderers.
@@ -1532,18 +1637,32 @@ const _AegisInAppManager = class _AegisInAppManager {
    * SDK serve both vanilla websites (full nav fallback) and SPAs
    * (in-place state change) without per-host configuration.
    */
-  navigateToCampaignAction(campaign, safeUrl) {
+  navigateToCampaignAction(campaign, safeUrl, buttonId = "cta") {
     if (typeof window === "undefined") return;
-    const event = new CustomEvent("aegis:campaign-click", {
+    let typedDefaultPrevented = false;
+    const typedEvent = {
+      campaign,
+      action_url: safeUrl,
+      button_id: buttonId,
+      preventDefault: () => {
+        typedDefaultPrevented = true;
+        typedEvent.defaultPrevented = true;
+      },
+      defaultPrevented: false
+    };
+    const typedProceed = this.emit("campaign-click", typedEvent);
+    const domEvent = new CustomEvent("aegis:campaign-click", {
       detail: {
         campaign_id: campaign.id,
         campaign_type: campaign.type,
-        action_url: safeUrl
+        action_url: safeUrl,
+        button_id: buttonId
       },
       cancelable: true
     });
-    const proceeded = window.dispatchEvent(event);
-    if (proceeded && !event.defaultPrevented) {
+    const domProceed = window.dispatchEvent(domEvent);
+    const suppressed = !typedProceed || typedDefaultPrevented || !domProceed || domEvent.defaultPrevented;
+    if (!suppressed) {
       window.location.href = safeUrl;
     }
   }
@@ -2353,6 +2472,15 @@ const _AegisInAppManager = class _AegisInAppManager {
    *   in_app.dismissed  → engagement.dismiss
    */
   async trackEvent(campaignId, eventType) {
+    if (eventType === "dismissed") {
+      const campaign = this.campaigns.find((c) => c.id === campaignId);
+      if (campaign) {
+        this.emit("campaign-dismiss", {
+          campaign,
+          source: "close_button"
+        });
+      }
+    }
     try {
       const url = `${this.apiHost}/v1/in_app/events`;
       const externalEventId = `inapp_${campaignId}_${eventType}_${Date.now()}`;