@mysuperwall/react-native 0.0.0-stage → 1.1.0

package/lib/services/manifestService.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ManifestService = void 0;
+class ManifestService {
+    constructor() {
+        this.scope = '';
+        this.generation = 0;
+        this.manifest = null;
+        this.asyncStorage = null;
+        try {
+            this.asyncStorage = require('@react-native-async-storage/async-storage').default;
+        }
+        catch (_) { /* Memory-only operation remains supported. */ }
+    }
+    static scopeKey(options) {
+        return JSON.stringify([options.baseUrl.replace(/\/+$/, '') + '/', options.appKey || '',
+            options.bundleId || '', options.platform || 'ios', options.lang || 'en']);
+    }
+    configure(options) {
+        const scope = ManifestService.scopeKey(options);
+        if (scope !== this.scope) {
+            this.scope = scope;
+            this.generation++;
+            this.manifest = null;
+        }
+    }
+    key(scope) { return '@mysuperwall_manifest_v2:' + encodeURIComponent(scope); }
+    async loadFromDisk() {
+        const scope = this.scope, generation = this.generation;
+        if (!scope || !this.asyncStorage)
+            return this.manifest;
+        try {
+            const raw = await this.asyncStorage.getItem(this.key(scope));
+            if (scope !== this.scope || generation !== this.generation)
+                return null;
+            const parsed = raw ? JSON.parse(raw) : null;
+            this.manifest = parsed?.ok && parsed.paywalls && Array.isArray(parsed.triggers) ? parsed : null;
+        }
+        catch (_) { /* Never adopt a legacy or malformed cache. */ }
+        return this.manifest;
+    }
+    async saveToDisk(manifest) {
+        const scope = this.scope;
+        if (!scope)
+            return;
+        this.manifest = manifest;
+        try {
+            await this.asyncStorage?.setItem(this.key(scope), JSON.stringify(manifest));
+        }
+        catch (_) { }
+    }
+    async syncInBackground(options) {
+        this.configure(options);
+        const scope = this.scope, generation = this.generation;
+        try {
+            const headers = { 'Content-Type': 'application/json' };
+            if (this.manifest?.hash)
+                headers['If-None-Match'] = `"${this.manifest.hash}"`;
+            const response = await fetch(options.baseUrl.replace(/\/+$/, '') + '/paywall/manifest', {
+                method: 'POST', headers, body: JSON.stringify({ platform: options.platform || 'ios',
+                    appKey: options.appKey, bundleId: options.platform === 'android' ? undefined : options.bundleId,
+                    packageName: options.platform === 'android' ? options.bundleId : undefined, lang: options.lang || 'en', hash: this.manifest?.hash })
+            });
+            if (scope !== this.scope || generation !== this.generation)
+                return null;
+            if (response.status === 304)
+                return this.manifest;
+            if (response.ok) {
+                const data = await response.json();
+                if (scope !== this.scope || generation !== this.generation)
+                    return null;
+                if (!data.notModified && data.ok && data.paywalls && Array.isArray(data.triggers))
+                    await this.saveToDisk(data);
+            }
+        }
+        catch (_) { /* Keep this scope's cache on transient failure. */ }
+        return scope === this.scope && generation === this.generation ? this.manifest : null;
+    }
+}
+exports.ManifestService = ManifestService;

package/lib/services/offlineEventQueue.d.ts

@@ -0,0 +1,18 @@
+export declare class OfflineEventQueue {
+    private queueKey;
+    private asyncStorage;
+    private isFlushing;
+    private memoryQueue;
+    private mutation;
+    constructor(scope?: string);
+    private serialized;
+    private read;
+    private write;
+    enqueue(event: Record<string, any>): Promise<void>;
+    flush(options: {
+        baseUrl: string;
+        appKey?: string;
+        bundleId?: string;
+        platform?: string;
+    }): Promise<void>;
+}

package/lib/services/offlineEventQueue.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OfflineEventQueue = void 0;
+function eventId() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, char => {
+        const value = Math.floor(Math.random() * 16);
+        return (char === 'x' ? value : (value & 3) | 8).toString(16);
+    });
+}
+class OfflineEventQueue {
+    constructor(scope) {
+        this.queueKey = '@mysuperwall_offline_event_queue_v1';
+        this.asyncStorage = null;
+        this.isFlushing = false;
+        this.memoryQueue = [];
+        this.mutation = Promise.resolve();
+        if (scope)
+            this.queueKey = '@mysuperwall_event_queue_v2:' + encodeURIComponent(scope);
+        try {
+            this.asyncStorage = require('@react-native-async-storage/async-storage').default;
+        }
+        catch (_) {
+            this.asyncStorage = null;
+        }
+    }
+    serialized(operation) {
+        const next = this.mutation.then(operation, operation);
+        this.mutation = next.catch(() => undefined);
+        return next;
+    }
+    async read() {
+        if (!this.asyncStorage)
+            return [...this.memoryQueue];
+        try {
+            const raw = await this.asyncStorage.getItem(this.queueKey);
+            const parsed = raw ? JSON.parse(raw) : [];
+            if (!Array.isArray(parsed))
+                return [];
+            const list = parsed.filter(item => item && typeof item === 'object').map(item => ({ ...item, eventId: item.eventId || eventId() }));
+            this.memoryQueue = list;
+            return list;
+        }
+        catch (_) {
+            this.asyncStorage = null;
+            return [...this.memoryQueue];
+        }
+    }
+    async write(list) {
+        this.memoryQueue = list;
+        if (this.asyncStorage) {
+            try {
+                await this.asyncStorage.setItem(this.queueKey, JSON.stringify(list));
+            }
+            catch (_) {
+                this.asyncStorage = null;
+            }
+        }
+    }
+    async enqueue(event) {
+        // IDs and context are captured before asynchronous persistence, once per event.
+        const captured = JSON.parse(JSON.stringify({ ...event, eventId: event.eventId || eventId(),
+            timestamp: event.timestamp || new Date().toISOString() }));
+        await this.serialized(async () => {
+            const list = await this.read();
+            await this.write([...list, captured].slice(-200));
+        });
+    }
+    async flush(options) {
+        if (this.isFlushing)
+            return;
+        this.isFlushing = true;
+        try {
+            const batch = await this.serialized(async () => {
+                const list = await this.read();
+                await this.write(list); // Persist upgraded legacy IDs before the request.
+                return list.slice(0, 100);
+            });
+            if (!batch.length)
+                return;
+            const base = options.baseUrl.endsWith('/') ? options.baseUrl : `${options.baseUrl}/`;
+            const response = await fetch(`${base}paywall/events/batch`, {
+                method: 'POST', headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ platform: options.platform || 'react-native', appKey: options.appKey,
+                    bundleId: options.platform === 'android' ? undefined : options.bundleId,
+                    packageName: options.platform === 'android' ? options.bundleId : undefined, events: batch })
+            });
+            if (response.ok) {
+                const sent = new Set(batch.map(event => event.eventId));
+                await this.serialized(async () => {
+                    const current = await this.read();
+                    await this.write(current.filter(event => !sent.has(event.eventId)));
+                });
+            }
+        }
+        catch (_) { /* Retain the original IDs for retry. */ }
+        finally {
+            this.isFlushing = false;
+        }
+    }
+}
+exports.OfflineEventQueue = OfflineEventQueue;

package/lib/ui/PaywallModal.d.ts

@@ -0,0 +1,8 @@
+import { FC } from 'react';
+import { PaywallData, PaywallCallbackActions } from '../models/paywall';
+export interface PaywallModalProps extends PaywallCallbackActions {
+    visible: boolean;
+    paywall: PaywallData | null;
+    onClose: () => void;
+}
+export declare const PaywallModal: FC<PaywallModalProps>;

package/lib/ui/PaywallModal.js

@@ -0,0 +1,136 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaywallModal = void 0;
+const react_1 = __importStar(require("react"));
+const MySuperwall_1 = require("../MySuperwall");
+const react_native_1 = require("react-native");
+const PaywallModal = props => {
+    if (!props.visible || !props.paywall)
+        return null;
+    // Remount the displayed session when HTML or attribution changes, even if the
+    // paywall ID stays the same. Freeze the payload to the HTML sent to WebView.
+    const captured = JSON.parse(JSON.stringify(props.paywall));
+    const sessionKey = JSON.stringify(captured);
+    return react_1.default.createElement(PaywallModalContent, { key: sessionKey, ...props, paywall: captured });
+};
+exports.PaywallModal = PaywallModal;
+const PaywallModalContent = ({ visible, paywall, onClose, onPurchase, onRestore, onDismiss, onOpenUrl }) => {
+    const shown = (0, react_1.useRef)(false);
+    const dismissed = (0, react_1.useRef)(false);
+    if (!visible || !paywall)
+        return null;
+    const track = (type, productId) => {
+        void MySuperwall_1.MySuperwall.shared.trackPaywallEvent(type, paywall, productId);
+    };
+    const dismiss = () => {
+        if (dismissed.current)
+            return;
+        dismissed.current = true;
+        track('paywall_dismissed');
+        onClose();
+        void onDismiss?.();
+    };
+    let WebViewComponent = null;
+    try {
+        WebViewComponent = require('react-native-webview').WebView;
+    }
+    catch (_) {
+        console.warn('[MySuperwall] react-native-webview is required to render paywalls.');
+        return null;
+    }
+    const injectedJavaScript = `
+    window.MySuperWall = {
+      postMessage: function(msg) {
+        if (window.ReactNativeWebView && window.ReactNativeWebView.postMessage) {
+          window.ReactNativeWebView.postMessage(typeof msg === 'string' ? msg : JSON.stringify(msg));
+        }
+      }
+    };
+    true;
+  `;
+    const handleMessage = (event) => {
+        try {
+            const data = JSON.parse(event.nativeEvent.data);
+            const action = typeof data.action === 'string' ? data.action : data.type;
+            const type = typeof action === 'string' ? action.toLowerCase() : '';
+            switch (type) {
+                case 'purchase': {
+                    const productId = data.productId || data.product_id;
+                    if (typeof productId === 'string' && productId.trim()) {
+                        track('purchase_started', productId);
+                        if (onPurchase)
+                            onPurchase(productId);
+                    }
+                    break;
+                }
+                case 'restore': {
+                    track('restore_started');
+                    if (onRestore)
+                        onRestore();
+                    break;
+                }
+                case 'close':
+                case 'dismiss': {
+                    dismiss();
+                    break;
+                }
+                case 'open_url':
+                case 'openurl': {
+                    if (typeof data.url === 'string' && data.url.trim() && onOpenUrl)
+                        onOpenUrl(data.url);
+                    break;
+                }
+            }
+        }
+        catch (_) { }
+    };
+    return (react_1.default.createElement(react_native_1.Modal, { visible: visible, animationType: "slide", transparent: false, onRequestClose: dismiss },
+        react_1.default.createElement(react_native_1.SafeAreaView, { style: styles.container },
+            react_1.default.createElement(WebViewComponent, { originWhitelist: ['*'], source: { html: paywall.html, baseUrl: 'https://mysuperwall.com' }, injectedJavaScriptBeforeContentLoaded: injectedJavaScript, onMessage: handleMessage, onLoad: () => { if (!shown.current) {
+                    shown.current = true;
+                    track('paywall_shown');
+                } }, style: styles.webview, javaScriptEnabled: true, domStorageEnabled: true, bounces: false }))));
+};
+const styles = react_native_1.StyleSheet.create({
+    container: {
+        flex: 1,
+        backgroundColor: '#000000'
+    },
+    webview: {
+        flex: 1,
+        backgroundColor: 'transparent'
+    }
+});

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@mysuperwall/react-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "React Native SDK for MySuperWall paywalls, targeting and offline rule evaluation",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "react-native",
+    "mysuperwall",
+    "paywall",
+    "remote-config",
+    "in-app-purchases"
+  ],
+  "author": "MySuperwall",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-native": ">=0.64.0",
+    "react-native-webview": ">=11.0.0",
+    "@react-native-async-storage/async-storage": ">=1.15.0"
+  },
+  "react-native": "src/index.ts",
+  "files": [
+    "lib",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@types/node": "^22.0.0",
+    "react": "18.2.0",
+    "@types/react": "^18.2.0",
+    "react-native": "0.73.4",
+    "react-native-webview": "13.8.1",
+    "@react-native-async-storage/async-storage": "1.21.0"
+  },
+  "homepage": "https://mysuperwall.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Unevenn/mysuperwall_react_native.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/MySuperwall.ts

@@ -0,0 +1,272 @@
+import { AnonymousIdentity } from './services/anonymousIdentity';
+import { FollowUpService } from './services/followUpService';
+import { LocalRuleEngine } from './engine/localRuleEngine';
+import { ManifestService } from './services/manifestService';
+import { OfflineEventQueue } from './services/offlineEventQueue';
+import { PaywallResult, PaywallData, PaywallCallbackActions } from './models/paywall';
+
+export interface MySuperwallInitOptions {
+  appKey?: string;
+  userId?: string;
+  baseUrl?: string;
+  bundleId?: string;
+  platform?: 'ios' | 'android' | 'web';
+  locale?: string;
+  country?: string;
+  appVersion?: string;
+}
+
+export class MySuperwall {
+  private static instance: MySuperwall;
+
+  public appKey?: string;
+  public userId?: string;
+  public baseUrl: string = 'https://mysuperwall.com/';
+  public bundleId?: string;
+  public platform: string = 'ios';
+  public locale: string = 'en';
+  public country: string = '';
+  public appVersion?: string;
+  private premium = false;
+  private epoch = 0;
+  private presentationSequence = 0;
+  private followUps = new FollowUpService();
+  private activeFlow?: { paywall: PaywallData; callbacks: PaywallCallbackActions; metadata?: Record<string, any>; depth: number; seen: string[]; epoch: number; outcome?: boolean };
+  public userAttributes: Record<string, any> = {};
+
+  public manifestService: ManifestService;
+  public ruleEngine: LocalRuleEngine;
+  public eventQueue: OfflineEventQueue;
+
+  private onPresentPaywallListener?: (paywall: PaywallData, callbacks: PaywallCallbackActions) => void;
+
+  private constructor() {
+    this.manifestService = new ManifestService();
+    this.ruleEngine = new LocalRuleEngine();
+    this.eventQueue = new OfflineEventQueue();
+  }
+
+  public static get shared(): MySuperwall {
+    if (!MySuperwall.instance) {
+      MySuperwall.instance = new MySuperwall();
+    }
+    return MySuperwall.instance;
+  }
+
+  /**
+   * Initializes MySuperwall with cached local rule evaluation.
+   */
+  public static async initialize(options: MySuperwallInitOptions = {}): Promise<MySuperwall> {
+    const inst = MySuperwall.shared;
+    inst.resetFlow();
+    inst.userAttributes = {};
+    inst.premium = false;
+    inst.appKey = options.appKey;
+    inst.baseUrl = options.baseUrl
+      ? options.baseUrl.endsWith('/')
+        ? options.baseUrl
+        : `${options.baseUrl}/`
+      : 'https://mysuperwall.com/';
+    inst.bundleId = options.bundleId;
+    inst.platform = options.platform || 'ios';
+    let deviceLocale = 'en';
+    try { deviceLocale = Intl.DateTimeFormat().resolvedOptions().locale; } catch (_) {}
+    inst.locale = (options.locale || deviceLocale).replace(/_/g, '-').toLowerCase();
+    inst.country = (options.country || inst.locale.match(/-([a-z]{2})(?:-|$)/i)?.[1] || '').toUpperCase();
+    inst.appVersion = options.appVersion;
+    inst.manifestService.configure(inst.manifestOptions());
+    inst.eventQueue = new OfflineEventQueue(JSON.stringify([inst.baseUrl, inst.appKey, inst.bundleId, inst.platform]));
+
+    const epoch = inst.epoch;
+    const userId = options.userId?.trim() || await AnonymousIdentity.get(
+      JSON.stringify([inst.baseUrl, inst.appKey, inst.bundleId, inst.platform])
+    );
+    if (epoch !== inst.epoch) return inst;
+    inst.userId = userId;
+
+    // 1. Load this app’s cached manifest into memory
+    await inst.manifestService.loadFromDisk();
+    if (epoch !== inst.epoch) return inst;
+
+    // 2. Background non-blocking sync with ETag / 304 validation
+    void inst.manifestService.syncInBackground(inst.manifestOptions());
+
+    return inst;
+  }
+
+  public identify(userId: string): void {
+    if (!userId.trim()) throw new Error('User ID cannot be empty');
+    if (this.userId !== userId.trim()) { this.resetFlow(); this.userAttributes = {}; this.premium = false; }
+    this.userId = userId.trim();
+  }
+
+  private resetFlow(): void { this.epoch++; this.followUps.reset(); this.activeFlow = undefined; }
+  private manifestOptions() {
+    return { baseUrl: this.baseUrl, appKey: this.appKey, bundleId: this.bundleId, platform: this.platform, lang: this.locale };
+  }
+  public async setLocale(locale: string): Promise<void> {
+    const normalized = locale.trim().replace(/_/g, '-').toLowerCase();
+    if (!normalized || normalized === this.locale) return;
+    this.resetFlow(); this.locale = normalized;
+    const epoch = this.epoch;
+    this.manifestService.configure(this.manifestOptions());
+    await this.manifestService.loadFromDisk();
+    if (epoch === this.epoch) await this.manifestService.syncInBackground(this.manifestOptions());
+  }
+  public setCountry(country: string): void { this.country = country.trim().toUpperCase(); }
+  public setAppVersion(version: string): void { this.appVersion = version; }
+  public setSubscriptionStatus(premium: boolean): void { this.premium = premium; }
+
+  public setUserAttributes(attributes: Record<string, any>): void {
+    Object.assign(this.userAttributes, attributes);
+  }
+
+  public registerPresenter(listener: (paywall: PaywallData, callbacks: PaywallCallbackActions) => void): () => void {
+    this.onPresentPaywallListener = listener;
+    return () => {
+      if (this.onPresentPaywallListener === listener) {
+        this.onPresentPaywallListener = undefined;
+      }
+    };
+  }
+
+  /**
+   * Evaluates rules locally in-memory in memory.
+   */
+  public resolveTrigger(triggerKey: string, metadata?: Record<string, any>): PaywallResult {
+    const manifest = this.manifestService.manifest;
+    if (!manifest) {
+      return { show: false, paywall: null, reason: 'manifest_not_cached' };
+    }
+
+    const trigger = (manifest.triggers || []).find(
+      t => t.key.trim().toLowerCase() === triggerKey.trim().toLowerCase()
+    );
+    if (!trigger) {
+      return { show: false, paywall: null, reason: 'trigger_not_found' };
+    }
+
+    const evalContext: Record<string, any> = {
+      platform: this.platform,
+      country: this.country,
+      appVersion: this.appVersion,
+      metadata: metadata || {},
+      userAttributes: this.userAttributes,
+      ...(metadata || {})
+    };
+
+    const resolution = this.ruleEngine.resolveTrigger(trigger, this.userId, evalContext);
+
+    if (resolution.isHoldout) {
+      return { show: false, paywall: null, reason: 'holdout' };
+    }
+
+    if (resolution.show && resolution.paywallId) {
+      const manifestPaywall = manifest.paywalls[resolution.paywallId];
+      if (manifestPaywall) {
+        const paywallData: PaywallData = {
+          followUpRules: manifestPaywall.contentJson?.followUpRules,
+          dismissFollowUpPaywallId: trigger.dismissAction?.type === 'follow_up_paywall' ? trigger.dismissAction.followUpPaywallId || undefined : undefined,
+          id: manifestPaywall.id,
+          name: manifestPaywall.name,
+          html: manifestPaywall.html,
+          productIds: manifestPaywall.productIds,
+          products: manifestPaywall.products,
+          triggerKey,
+          abVariant: resolution.abVariant || 'A',
+          attributionUserId: this.userId,
+          attributionScope: ManifestService.scopeKey(this.manifestOptions()),
+          experimentContext: (() => {
+            const rule = trigger.rules.find(rule => rule.id === resolution.matchedRuleId);
+            const audience = rule || trigger;
+            const matches = audience.variants.filter(variant =>
+              variant.paywallId === manifestPaywall.id && variant.variant === resolution.abVariant);
+            const variant = matches.length === 1 ? matches[0] : undefined;
+            if (!variant?.variantId || !audience.experimentId || !audience.experimentVersion ||
+                !audience.audienceId || manifestPaywall.publishedVersion == null) return undefined;
+            return { experimentId: audience.experimentId, experimentVersion: audience.experimentVersion,
+              audienceId: audience.audienceId, variantId: variant.variantId,
+              variantLabel: variant.variantLabel || variant.variant,
+              paywallId: manifestPaywall.id, paywallVersion: manifestPaywall.publishedVersion };
+          })()
+        };
+
+        return { show: true, paywall: paywallData, reason: resolution.reason };
+      }
+    }
+
+    return { show: false, paywall: null, reason: resolution.reason };
+  }
+
+  /** Attribute actions to the displayed paywall, never a new assignment. */
+  public async trackPaywallEvent(type: string, paywall: PaywallData, productId?: string): Promise<void> {
+    if (paywall.attributionScope !== undefined && paywall.attributionScope !== ManifestService.scopeKey(this.manifestOptions())) return;
+    if (paywall.attributionUserId !== undefined && paywall.attributionUserId !== this.userId) return;
+    const flow = this.activeFlow;
+    if (flow && flow.paywall.presentationId === paywall.presentationId && flow.epoch === this.epoch) {
+      const keys: Record<string, string> = { purchase: 'onPurchase', purchase_success: 'onPurchase', purchase_failed: 'onPurchaseFailed', restore: 'onRestore', restore_success: 'onRestore' };
+      if (keys[type]) { flow.outcome = true; this.scheduleFollowUp(flow, keys[type]); }
+    }
+    await this.eventQueue.enqueue({ type, paywallId: paywall.id,
+      triggerKey: paywall.triggerKey, abVariant: paywall.abVariant,
+      experimentContext: paywall.attributionUserId === this.userId ? paywall.experimentContext : undefined, userId: this.userId, productId });
+    await this.eventQueue.flush({ baseUrl: this.baseUrl, appKey: this.appKey,
+      bundleId: this.bundleId, platform: this.platform });
+  }
+
+  /**
+   * Fires a trigger, presents the paywall if resolved, and wires up callbacks.
+   */
+  public handleTrigger(
+    triggerKey: string,
+    callbacks?: PaywallCallbackActions & { metadata?: Record<string, any> }
+  ): PaywallResult {
+    this.epoch++; this.followUps.cancel(); this.activeFlow = undefined;
+    const result = this.resolveTrigger(triggerKey, callbacks?.metadata);
+    if (result.show && result.paywall) {
+      const paywall = this.present(result.paywall, callbacks || {}, callbacks?.metadata, 0, []);
+      return { ...result, paywall };
+    }
+    return result;
+  }
+
+  private present(paywall: PaywallData, callbacks: PaywallCallbackActions, metadata: Record<string, any> | undefined, depth: number, seen: string[]): PaywallData {
+    paywall = { ...paywall, presentationId: `${this.epoch}:${++this.presentationSequence}` };
+    const flow: NonNullable<MySuperwall['activeFlow']> = { paywall, callbacks, metadata, depth, seen: [...seen, paywall.id], epoch: this.epoch };
+    this.activeFlow = flow;
+    let dismissed = false;
+    this.onPresentPaywallListener?.(paywall, { ...callbacks, onDismiss: () => {
+      if (dismissed) return;
+      dismissed = true;
+      if (this.activeFlow !== flow || flow.epoch !== this.epoch) return;
+      if (!flow.outcome) this.scheduleFollowUp(flow, 'onDismiss');
+      void callbacks.onDismiss?.();
+    } });
+    return paywall;
+  }
+
+  private scheduleFollowUp(flow: NonNullable<MySuperwall['activeFlow']>, event: string): void {
+    const rule = flow.paywall.followUpRules?.[event];
+    const valid = () => this.activeFlow === flow && flow.epoch === this.epoch && flow.paywall.attributionUserId === this.userId;
+    if (!valid()) return;
+    if (rule?.enabled && (rule.actionType || 'trigger') === 'trigger' && rule.triggerKey?.trim()) {
+      this.followUps.schedule(`${flow.paywall.id}:${event}:${rule.triggerKey}`, rule, flow.depth, this.premium, () => {
+        if (!valid()) return;
+        const result = this.resolveTrigger(rule.triggerKey!, flow.metadata);
+        if (!result.show || !result.paywall || (rule.skipIfPremium && this.premium) ||
+            (rule.preventRepeatPaywall !== false && flow.seen.includes(result.paywall.id))) return;
+        this.present(result.paywall, flow.callbacks, flow.metadata, flow.depth + 1, flow.seen);
+      });
+      return;
+    }
+    // Legacy close recovery is one additional screen, never an unbounded chain.
+    const id = flow.paywall.dismissFollowUpPaywallId;
+    if (event !== 'onDismiss' || flow.depth !== 0 || !id || flow.seen.includes(id)) return;
+    const next = this.manifestService.manifest?.paywalls[id];
+    if (!next) return;
+    this.followUps.schedule(`${flow.paywall.id}:legacy`, { enabled: true, actionType: 'trigger', triggerKey: 'legacy', maxChainDepth: 1 }, 0, false, () => {
+      if (valid()) this.present({ ...next, attributionUserId: this.userId, attributionScope: ManifestService.scopeKey(this.manifestOptions()), triggerKey: flow.paywall.triggerKey,
+        followUpRules: next.contentJson?.followUpRules }, flow.callbacks, flow.metadata, 1, flow.seen);
+    });
+  }
+}