@namiml/sdk-core 3.4.4-dev.202606241934 → 3.4.4-dev.202606241952

package/dist/index.cjs

@@ -98,7 +98,7 @@ const {
 // version — stamped by scripts/version.sh
 NAMI_SDK_VERSION: exports.NAMI_SDK_VERSION = "3.4.4", 
 // full package version including dev suffix — stamped by scripts/version.sh
-NAMI_SDK_PACKAGE_VERSION: exports.NAMI_SDK_PACKAGE_VERSION = "3.4.4-dev.202606241934", 
+NAMI_SDK_PACKAGE_VERSION: exports.NAMI_SDK_PACKAGE_VERSION = "3.4.4-dev.202606241952", 
 // environments
 PRODUCTION: exports.PRODUCTION = "production", DEVELOPMENT: exports.DEVELOPMENT = "development", 
 // error messages
@@ -6986,8 +6986,21 @@ class NamiAPI {
         const resp = await this.requestBodyAPI(path, options, "POST", true);
         if (resp.id) {
             storageService.setLastImpressionId(resp.id);
+            // Notify the flow-completion engine (no-op unless a flow is open) so it
+            // can bind this impression to the current screen's completion context.
+            NamiAPI.impressionListener?.(resp.id);
         }
     }
+    /**
+     * Reports a flow completion result against a prior impression
+     * (NAM-1545 / Flow Completion Step). UPDATE-only on the server; the
+     * impression must already exist. `keepalive` so a dismiss-triggered PATCH
+     * survives page unload on web.
+     */
+    async patchImpressionCompletion(impressionId, completion_result, completion_result_date) {
+        const path = `device/${this.deviceID}/impression/${impressionId}/`;
+        await this.requestBodyAPI(path, { completion_result, completion_result_date }, "PATCH", true);
+    }
     async postConversion(options) {
         const path = `device/${this.deviceID}/transaction/`;
         await this.requestBodyAPI(path, options, "POST", true);
@@ -7026,6 +7039,9 @@ __decorate([
 __decorate([
     requireDeviceID
 ], NamiAPI.prototype, "postImpression", null);
+__decorate([
+    requireDeviceID
+], NamiAPI.prototype, "patchImpressionCompletion", null);
 __decorate([
     requireDeviceID
 ], NamiAPI.prototype, "postConversion", null);
@@ -12623,6 +12639,70 @@ exports.NamiFlowActionFunction = void 0;
 const HandoffTag = {
     SEQUENCE: '__handoff_sequence__',
 };
+/**
+ * Prefix marking SDK-reserved handoff tags. Reserved tags are consumed
+ * internally and are NEVER delivered to host-registered handoff handlers.
+ */
+const RESERVED_HANDOFF_TAG_PREFIX = '__';
+/**
+ * Customer-facing handoff tag vocabulary.
+ *
+ * Keep in sync with `FlowHandoffTag` in nami-platform
+ * `services/frontend/src/api/types/flow.types.tsx` (minus the `__*__`
+ * internal tags, which never reach host handlers). The builder constrains
+ * authoring to this set, but the vocabulary evolves — treat unknown tags as
+ * pass-through, never as errors.
+ *
+ * Note `Tracking` is the legacy `att` authoring convention; the permission
+ * enum value is `tracking` and the completion wire value is
+ * `tracking_authorized`. Aliasing is intentional — do not rename.
+ */
+const NamiHandoffTag = {
+    Push: 'push',
+    Location: 'location',
+    Tracking: 'att',
+    Deeplink: 'deeplink',
+    Complete: 'complete',
+    SignIn: 'signin',
+    Restore: 'restore',
+    SignInMvpd: 'signin_mvpd',
+    BuySku: 'buysku',
+    UserData: 'userdata',
+};
+/**
+ * Permission types reportable through a handoff outcome.
+ *
+ * Tier 1 (`push`, `location`, `tracking`) map to impression
+ * `completion_result` wire values; the remaining tier-2 types are accepted
+ * (flow state + lifecycle only) and gain wire values via backend tickets
+ * without SDK API churn.
+ */
+const NamiPermissionOutcome = {
+    Push: 'push',
+    Location: 'location',
+    Tracking: 'tracking',
+    Camera: 'camera',
+    Microphone: 'microphone',
+    Photos: 'photos',
+    Contacts: 'contacts',
+    Bluetooth: 'bluetooth',
+    Calendar: 'calendar',
+    Biometrics: 'biometrics',
+    Health: 'health',
+    Motion: 'motion',
+    Speech: 'speech',
+    LocalNetwork: 'localNetwork',
+};
+/**
+ * Tier-1 permission → impression completion_result wire value. Keep in sync
+ * with omaha `Impression.CompletionResult` / breakwater
+ * `ValidCompletionResults`.
+ */
+const COMPLETION_MAPPED_PERMISSIONS = {
+    [NamiPermissionOutcome.Push]: 'push_authorized',
+    [NamiPermissionOutcome.Location]: 'location_authorized',
+    [NamiPermissionOutcome.Tracking]: 'tracking_authorized',
+};
 const NamiReservedActions = {
     BUY_SKU: '__buy_sku__',
     DEFAULT: '__default__',
@@ -12637,6 +12717,7 @@ const NamiReservedActions = {
     RESUME: '__resume__',
     REMOTE_BACK: '__remoteback__',
     TAG_UPDATE: '__tag_update__',
+    PERMISSION_GRANTED: '__permission_granted__',
 };
 
 const LogicalOperator = {
@@ -13385,6 +13466,198 @@ exports.AccountStateAction = void 0;
     AccountStateAction["NAMI_DEVICE_ID_CLEARED"] = "nami_device_id_cleared";
 })(exports.AccountStateAction || (exports.AccountStateAction = {}));
 
+const postConversion = async (transactionInfo) => {
+    if (isAnonymousMode()) {
+        logger.info("Skipping transaction post - anonymous mode");
+        return;
+    }
+    try {
+        await NamiAPI.instance.postConversion(transactionInfo);
+    }
+    catch (e) {
+        logger.error("Error posting conversion", e);
+    }
+};
+
+/**
+ * @class NamiPaywallManager
+ * Provides methods for managing all aspects of a paywall in the Nami SDK.
+ */
+let NamiPaywallManager$2 = class NamiPaywallManager {
+    constructor() {
+        this.emitter = NamiEventEmitter.getInstance();
+    }
+    /**
+     * @returns {IPaywall[]} a list of Paywall
+     */
+    static allPaywalls() {
+        if (!this.instance.sdkInitialized) {
+            throw new SDKNotInitializedError();
+        }
+        return allPaywalls();
+    }
+    /**
+     * Used to set product details when store products are unavailable. For advanced use cases only.
+     */
+    static setProductDetails(productDetails) {
+        this.instance.productDetails = productDetails;
+        PaywallState.setProductDetails(productDetails);
+    }
+    /**
+     * Register a callback which would be invoked when user will sign-in
+     */
+    static registerSignInHandler(handler) {
+        this.instance.emitter.addListener(exports.PaywallManagerEvents.SignIn, handler);
+        return () => {
+            this.instance.emitter.removeListener(exports.PaywallManagerEvents.SignIn, handler);
+        };
+    }
+    /**
+     * Register a callback which would be invoked when user close a paywall raised by Nami system
+     */
+    static registerCloseHandler(handler) {
+        this.instance.emitter.addListener(exports.PaywallManagerEvents.Close, handler);
+        return () => {
+            this.instance.emitter.removeListener(exports.PaywallManagerEvents.Close, handler);
+        };
+    }
+    /**
+     * Register a callback which would be invoked when user will take action on deeplink
+     */
+    static registerDeeplinkActionHandler(handler) {
+        this.instance.emitter.addListener(exports.PaywallManagerEvents.DeeplinkAction, handler);
+        return () => {
+            this.instance.emitter.removeListener(exports.PaywallManagerEvents.DeeplinkAction, handler);
+        };
+    }
+    /**
+     * Register a [NamiBuySkuHandler] which would be invoked when a user triggers
+     * a buy sku action on a paywall.
+     *
+     * Only available for plans where Nami is not handling subscription & IAP management.
+     */
+    static registerBuySkuHandler(handler) {
+        if (hasPurchaseManagement()) {
+            logger.debug("This handler will not be invoked because this account's plan includes " +
+                "built-in purchase management. Contact support@namiml.com for details.");
+        }
+        this.instance.emitter.addListener(exports.PaywallManagerEvents.BuySku, handler);
+        return () => {
+            this.instance.emitter.removeListener(exports.PaywallManagerEvents.BuySku, handler);
+        };
+    }
+    /**
+     * Register a callback which would be invoked when user restore a product
+     */
+    static registerRestoreHandler(handler) {
+        this.instance.emitter.addListener(exports.PaywallManagerEvents.Restore, handler);
+        return () => {
+            this.instance.emitter.removeListener(exports.PaywallManagerEvents.Restore, handler);
+        };
+    }
+    /**
+     * Notify the NamiPaywallManager that a purchase initiated from the
+     * [NamiBuySkuHandler] is complete.
+     *
+     * Only available for plans where Nami is not handling subscription & IAP management.
+     *
+     * @returns {Promise<void>} A Promise that resolves when buying SKU will be complete.
+     */
+    static async buySkuComplete(purchase) {
+        // clear loading indicator
+        PaywallState.setPurchaseInProgress(false);
+        if (NamiFlowManager$2.instance.flowOpen) {
+            const flow = NamiFlowManager$2.instance.currentFlow;
+            const currentStep = flow?.currentFlowStep;
+            if (flow && currentStep) {
+                flow.executeLifecycle(currentStep, NamiReservedActions.PURCHASE_SUCCESS);
+            }
+        }
+        if (NamiCustomerManager$2.inAnonymousMode()) {
+            logger.debug("Skipping purchase validation - anonymous mode");
+            return;
+        }
+        const session = storageService.getSessionId();
+        const impression = storageService.getPurchaseImpression();
+        if (!impression) {
+            logger.debug("Not sending paywall conversion call complete due to unknown impression");
+            return;
+        }
+        // send conversion
+        try {
+            await postConversion({
+                purchase_env: "production",
+                app_env: "production",
+                impression,
+                session,
+                amount: purchase.amount,
+                currency: purchase.currency,
+                transaction_id: purchase.transactionId,
+                sku: purchase.skuId,
+            });
+        }
+        catch (e) {
+            logger.error('Error posting conversion', e);
+        }
+        // validate purchase
+        if (!hasCapability(exports.Capabilities.THIRD_PARTY_TRANSACTIONS)) {
+            try {
+                await NamiAPI.instance.purchaseValidation({
+                    app_env: "production",
+                    payload: '', // token to be added when here a direct integration is done
+                    sku: purchase.skuId,
+                });
+            }
+            catch (e) {
+                logger.error("Error validating purchase", e);
+            }
+        }
+    }
+    /**
+     * Notify the NamiPaywallManager that purchase flow handled by you is cancelled.
+     * Used to disable product purchase-in-progress loading indicators
+     */
+    static buySkuCancel() {
+        if (!hasCapability(exports.Capabilities.THIRD_PARTY_TRANSACTIONS)) {
+            logger.warn("Call this method is not needed for this app because Nami is responsible for purchase management. Contact support@nami.ml for details.");
+            return;
+        }
+        PaywallState.setPurchase(false);
+    }
+    /**
+     * Set the video details for the app supplied video
+     * @param url The URL of the video
+     * @param name The name of the video
+     */
+    static setAppSuppliedVideoDetails(url, name) {
+        if (isValidUrl(url)) {
+            logger.debug(`NamiPaywallManager: setAppSuppliedVideoDetails received valid url ${url}`);
+            PaywallState.setAppSuppliedVideoDetails({ url, name });
+        }
+        else {
+            logger.debug(`NamiPaywallManager: setAppSuppliedVideoDetails received invalid url ${url}`);
+        }
+    }
+    /**
+     * Enables or disables user interaction on Nami paywalls.
+     *
+     * @param {boolean} allowed - Whether user interaction should be allowed.
+     * @returns {void}
+     */
+    static allowUserInteraction(allowed) {
+        logger.debug(`NamiPaywallManager: allowUserInteraction called with ${allowed}`);
+        PaywallState.setUserInteractionEnabled(allowed);
+    }
+    /**
+     * Private Instance Methods
+     */
+    get sdkInitialized() {
+        return Nami.instance.isInitialized;
+    }
+};
+NamiPaywallManager$2.instance = new NamiPaywallManager$2();
+NamiPaywallManager$2.emitter = NamiEventEmitter.getInstance();
+
 let NamiFlowManager$2 = class NamiFlowManager {
     static get instance() {
         if (!NamiFlowManager._instance) {
@@ -13413,10 +13686,24 @@ let NamiFlowManager$2 = class NamiFlowManager {
         i.flowOpen = false;
         i.lastAnimatedFlowProgress = new Map();
         i.navGraphCache = new WeakMap();
+        i.pendingHandoff = undefined;
     }
     /**
      * Registers a handoff step handler and returns an unsubscribe callback.
      *
+     * The handler receives `(tag, data, complete)`. Call `complete(outcome)`
+     * exactly once with a typed {@link NamiHandoffOutcome}: completing
+     * reports the outcome AND resumes the flow in one call. A bare
+     * `complete()` is equivalent to `complete({ kind: 'done' })`. The
+     * outcome's routing (lifecycles, purchase/login machinery) runs before
+     * the resume, matching the pre-outcome `buySkuComplete(); resume()`
+     * call order.
+     *
+     * Handlers written against the old `(tag, data)` signature still run —
+     * the extra argument is ignored at runtime, and their existing
+     * `resume()` call degrades to `complete({kind:'done'})` with a
+     * migration warning.
+     *
      * The returned callback clears the registered handler only if it is still
      * the active one (identity-check guard). This protects against React 18
      * StrictMode dev-mode double-mount where a stale unsubscribe from the
@@ -13439,6 +13726,131 @@ let NamiFlowManager$2 = class NamiFlowManager {
             }
         };
     }
+    /** Whether a handoff handler is registered. */
+    get hasHandoffHandler() {
+        return !!this.handoffStepHandler;
+    }
+    /**
+     * Single delivery point for handoffs reaching the host app. Flow code must
+     * route through here (never invoke the handler field directly) so every
+     * handler receives a working `complete` and reserved-tag guarding stays
+     * upstream in the dispatcher.
+     */
+    deliverHandoff(tag, data) {
+        const handler = this.handoffStepHandler;
+        if (!handler)
+            return;
+        const pending = { tag, completed: false };
+        this.pendingHandoff = pending;
+        const complete = (outcome) => {
+            if (pending.completed) {
+                logger.warn(`[NamiFlowManager] complete() called more than once for handoff '${tag}' — ignored`);
+                return;
+            }
+            const current = NamiFlowManager.instance.pendingHandoff;
+            if (current && current !== pending) {
+                logger.warn(`[NamiFlowManager] stale complete() for handoff '${tag}' — a newer handoff ('${current.tag}') is pending; ignored`);
+                return;
+            }
+            pending.completed = true;
+            if (this.pendingHandoff === pending) {
+                this.pendingHandoff = undefined;
+            }
+            // No argument means "nothing to report" — the done outcome.
+            NamiFlowManager.routeHandoffOutcome(outcome ?? { kind: 'done' });
+            NamiFlowManager.resume();
+        };
+        handler(tag, data, complete);
+    }
+    /**
+     * Applies a typed handoff outcome to the SDK before the flow resumes.
+     * Ordering contract: outcome routing first (its lifecycles may navigate),
+     * `resume()` last — identical to the legacy integrator call order.
+     */
+    static routeHandoffOutcome(outcome) {
+        const flow = NamiFlowManager.instance.currentFlow;
+        const step = flow?.currentFlowStep;
+        switch (outcome.kind) {
+            case 'done':
+                return;
+            case 'permission': {
+                if (!flow)
+                    return;
+                flow.handoffState.permissions[outcome.permission] = outcome.granted;
+                if (!outcome.granted)
+                    return;
+                if (step)
+                    flow.executeLifecycle(step, NamiReservedActions.PERMISSION_GRANTED);
+                const wireValue = COMPLETION_MAPPED_PERMISSIONS[outcome.permission];
+                if (wireValue) {
+                    // Permissions have no flow lifecycle to ride, so the completion
+                    // signal is fired directly here (purchase/login ride
+                    // executeLifecycle instead — see below).
+                    flow.completionSignal(wireValue);
+                }
+                else {
+                    logger.debug(`[NamiFlowManager] permission '${outcome.permission}' granted — no completion_result mapping yet (state/lifecycle only)`);
+                }
+                return;
+            }
+            case 'purchase': {
+                if (outcome.result === 'success') {
+                    // buySkuComplete fires __purchase_success__ (and the conversion)
+                    // itself; executeLifecycle raises the completion signal. Don't
+                    // double-dispatch here.
+                    void NamiPaywallManager$2.buySkuComplete(outcome.details);
+                }
+                else {
+                    PaywallState.setPurchase(false);
+                    if (flow && step)
+                        flow.executeLifecycle(step, NamiReservedActions.PURCHASE_FAILURE);
+                }
+                return;
+            }
+            case 'login': {
+                if (outcome.result === 'success') {
+                    const { details } = outcome;
+                    if (flow) {
+                        // Open-ended host-asserted experience data — exposed to branch
+                        // conditions and smart text via the `login.*` namespace using
+                        // the host's own key names (e.g. login.subscriberStatus).
+                        flow.handoffState.login = { ...(details.attributes ?? {}) };
+                    }
+                    // Identity writes are idempotent: skip when the asserted ids
+                    // already match what the SDK holds, so re-asserting an existing
+                    // login doesn't re-run profile sync or device updates.
+                    if (NamiCustomerManager$2.loggedInId() === details.loginId) {
+                        // Already this user — login() would be a no-op network-wise,
+                        // but the flow still needs its __login_success__ actions
+                        // (login() owns that dispatch on the fresh-login path).
+                        if (flow && step)
+                            flow.executeLifecycle(step, NamiReservedActions.LOGIN_SUCCESS);
+                    }
+                    else {
+                        // login() fires __login_success__/__login_failure__ itself — do
+                        // not double-dispatch lifecycles here.
+                        void Promise.resolve(NamiCustomerManager$2.login(details.loginId)).catch((err) => {
+                            logger.error('[NamiFlowManager] login from handoff outcome failed', err);
+                        });
+                    }
+                    const currentCdpId = storageService.getDevice()?.customer_data_platform_id;
+                    if (details.cdpId && details.cdpId !== currentCdpId) {
+                        void Promise.resolve(NamiCustomerManager$2.setCustomerDataPlatformId(details.cdpId)).catch((err) => {
+                            logger.error('[NamiFlowManager] CDP id write-through from handoff outcome failed', err);
+                        });
+                    }
+                    // Both the fresh-login and idempotent-skip paths above dispatch
+                    // __login_success__ via executeLifecycle, which raises the
+                    // completion signal — no direct call needed here.
+                }
+                else {
+                    if (flow && step)
+                        flow.executeLifecycle(step, NamiReservedActions.LOGIN_FAILURE);
+                }
+                return;
+            }
+        }
+    }
     /**
      * Registers an event handler and returns an unsubscribe callback.
      *
@@ -13464,6 +13876,14 @@ let NamiFlowManager$2 = class NamiFlowManager {
         if (Nami.instance.maxLogging) {
             logger.debug(`[NamiFlowManager] resume() — flowOpen=${flowOpen}, hasFlow=${!!currentFlow}, currentStep=${currentFlow?.currentFlowStep?.id ?? 'none'}, isPaused=${currentFlow?.isPaused ?? 'N/A'}`);
         }
+        // A v2 handler calling bare resume() instead of complete() is treated as
+        // complete({kind:'done'}) — flow continues, but nudge toward migration.
+        const pending = NamiFlowManager.instance.pendingHandoff;
+        if (pending && !pending.completed) {
+            pending.completed = true;
+            NamiFlowManager.instance.pendingHandoff = undefined;
+            logger.warn(`[NamiFlowManager] resume() called during handoff '${pending.tag}' with a v2 handler registered — treated as complete({kind:'done'}); prefer complete(outcome)`);
+        }
         if (!flowOpen || !currentFlow || !currentFlow.currentFlowStep) {
             logger.warn('Cannot resume: no active flow or current step');
             return;
@@ -13485,8 +13905,11 @@ let NamiFlowManager$2 = class NamiFlowManager {
             logger.debug('Cannot finish: no active flow or current step');
             return;
         }
+        // Host-initiated close is a dismissal — records dismiss_page against the
+        // current screen's impression (R5) before teardown (no-op if a positive
+        // completion was already recorded).
         logger.debug(`Finishing flow programmatically at step ${currentFlow.currentFlowStep.id}`);
-        currentFlow.finished();
+        currentFlow.dismiss();
     }
     static pause() {
         const { flowOpen, currentFlow } = NamiFlowManager.instance;
@@ -13508,6 +13931,13 @@ let NamiFlowManager$2 = class NamiFlowManager {
         const flow = new NamiFlow(campaign, paywall, this, context);
         this.flowOpen = true;
         this.currentFlow = flow;
+        // Bind each impression posted for this flow's screens to the active
+        // flow's per-raise completion context (NAM-1545, R1). Registered here so
+        // the listener is in place before the first screen's impression posts;
+        // it no-ops for non-flow impressions because currentFlow clears on finish.
+        NamiAPI.impressionListener = (impressionId) => {
+            NamiFlowManager.instance.currentFlow?.bindImpression(impressionId);
+        };
         return flow;
     }
     finishFlow() {
@@ -14296,6 +14726,14 @@ class NamiFlow extends BasicNamiFlow {
         this.isPaused = false;
         this.flowPath = "";
         this.timerStates = {};
+        /**
+         * Flow-scoped state written by typed handoff outcomes (Variant D).
+         * Exposed to branch conditions and smart text via the `login.*` and
+         * `permissions.*` namespaces registered in {@link registerResolvers}.
+         * `login` holds the host's open-ended attributes verbatim, keyed by the
+         * host's own names (e.g. `login.subscriberStatus`, `login.tier`).
+         */
+        this.handoffState = { permissions: {} };
         this.campaign = campaign;
         this.component = paywall;
         this.context = context;
@@ -14337,6 +14775,17 @@ class NamiFlow extends BasicNamiFlow {
                     return undefined;
             }
         });
+        // Variant D handoff-outcome state: `login.<attributeKey>` (host-named,
+        // open-ended) and `permissions.<type>` for branch conditions and smart
+        // text.
+        NamiConditionEvaluator.shared.registerNamespaceResolver('login', (identifier) => {
+            const key = identifier.replace(/^login\./, '');
+            return this.handoffState.login?.[key];
+        });
+        NamiConditionEvaluator.shared.registerNamespaceResolver('permissions', (identifier) => {
+            const key = identifier.replace(/^permissions\./, '');
+            return this.handoffState.permissions[key];
+        });
         NamiConditionEvaluator.shared.registerNamespaceResolver('__first_session__', () => {
             return NamiRefs.instance.getIsFirstSession();
         });
@@ -14387,6 +14836,18 @@ class NamiFlow extends BasicNamiFlow {
         this.manager.finishFlow();
         // UI is responsible for closing paywall when flow ends
     }
+    /**
+     * Dismiss the flow (hard close): records `dismiss_page` against the current
+     * screen's impression (R5) before tearing down. The single choke point for
+     * host-initiated dismissal, the `flowDismiss` action, back-button exits,
+     * and platform swipe-down dismissals — anything that ends the flow without
+     * a user "skip" or a programmatic `flowDone`. Never overwrites a positive
+     * completion (R4 guard inside `signalNonCompletion`).
+     */
+    dismiss() {
+        this.signalNonCompletion('dismiss_page');
+        this.finished();
+    }
     back() {
         if (this.previousFlowStep?.allow_back_to === false) {
             logger.debug(`Not allowed to go back to ${this.previousFlowStep.id}`);
@@ -14397,12 +14858,89 @@ class NamiFlow extends BasicNamiFlow {
             .slice(0, -1)
             .some(step => step.type === 'screen');
         if (!hasPreviousScreen) {
-            this.flowLog(`back() — no previous screen step, exiting flow`);
-            this.finished();
+            this.flowLog(`back() — no previous screen step, dismissing flow`);
+            this.dismiss();
             return;
         }
         this.backToPreviousScreenStep();
     }
+    // ─── Flow completion (NAM-1545) ──────────────────────────────────────────
+    /**
+     * Binds a freshly-posted impression id to the current screen's raise.
+     * Called via `NamiAPI.impressionListener` whenever an impression posts
+     * while this flow is open. Starts a fresh completion context for the raise
+     * (a re-render — e.g. back-navigation — rebinds with a clean result),
+     * fires `page_view` completion immediately if applicable (R2), and flushes
+     * any condition signals that arrived before the id (R1).
+     */
+    bindImpression(impressionId) {
+        const step = this.currentFlowStep;
+        if (!step)
+            return;
+        const ctx = this.completionContext;
+        if (ctx && ctx.stepId === step.id && !ctx.impressionId) {
+            // A signal already created the context for this raise — fill the id.
+            ctx.impressionId = impressionId;
+        }
+        else {
+            this.completionContext = { stepId: step.id, impressionId, resultSent: false, pending: [] };
+        }
+        const cs = step.completion_step;
+        if (cs?.enabled && cs.condition === 'page_view') {
+            this.completionSignal('page_view');
+        }
+        const queued = this.completionContext.pending;
+        this.completionContext.pending = [];
+        queued.forEach((condition) => this.completionSignal(condition));
+    }
+    /**
+     * Reports that `condition` was satisfied on the current page. PATCHes the
+     * completion result only when the current step is a matching, enabled
+     * completion step and no result has been sent for this impression yet.
+     * Signals arriving before the impression id is bound are queued (R1).
+     */
+    completionSignal(condition) {
+        const step = this.currentFlowStep;
+        const cs = step?.completion_step;
+        if (!step || !cs?.enabled || cs.condition !== condition)
+            return;
+        let ctx = this.completionContext;
+        if (!ctx || ctx.stepId !== step.id) {
+            ctx = this.completionContext = { stepId: step.id, resultSent: false, pending: [] };
+        }
+        if (ctx.resultSent)
+            return; // R4: one completion per impression
+        if (!ctx.impressionId) {
+            if (!ctx.pending.includes(condition))
+                ctx.pending.push(condition);
+            return; // R1: flushed once the impression id binds
+        }
+        ctx.resultSent = true;
+        void this.patchCompletion(ctx.impressionId, condition);
+    }
+    /**
+     * Records a non-completion outcome (`skip_page` / `dismiss_page`) against
+     * the current page's impression when the flow terminates without
+     * completing (R5 — feeds the flow-conversion cube). Applies to any page,
+     * completion-step or not, but never overwrites a positive result (R4) and
+     * no-ops when no impression is bound (e.g. anonymous mode).
+     */
+    signalNonCompletion(result) {
+        const ctx = this.completionContext;
+        if (!ctx || !ctx.impressionId || ctx.resultSent)
+            return;
+        ctx.resultSent = true;
+        void this.patchCompletion(ctx.impressionId, result);
+    }
+    async patchCompletion(impressionId, result) {
+        this.flowLog(`patchCompletion(${result}) — impression=${impressionId}, step=${this.currentFlowStep?.id}`);
+        try {
+            await NamiAPI.instance.patchImpressionCompletion(impressionId, result, new Date().toISOString());
+        }
+        catch (err) {
+            logger.error(`[NamiFlow] completion PATCH failed for '${result}'`, err);
+        }
+    }
     next() {
         const nextStep = this.nextFlowStep;
         if (nextStep) {
@@ -14487,6 +15025,17 @@ class NamiFlow extends BasicNamiFlow {
         this.forward(resumeId);
     }
     executeLifecycle(step, key, data) {
+        // Completion signals ride the lifecycle dispatch so every path that
+        // raises these events — SDK-managed purchase, host-managed purchase,
+        // login (fresh + idempotent-skip), buffered replay — funnels through one
+        // site (NAM-1545). Fired before the no-actions early-return: completion
+        // is about the event happening, not about the step defining flow actions.
+        if (key === NamiReservedActions.PURCHASE_SUCCESS) {
+            this.completionSignal('purchase_success');
+        }
+        else if (key === NamiReservedActions.LOGIN_SUCCESS) {
+            this.completionSignal('login_success');
+        }
         const lifecycles = step.actions[key];
         if (!lifecycles) {
             this.flowLog(`executeLifecycle(${key}) — no actions on step ${step.id}`);
@@ -14633,10 +15182,18 @@ class NamiFlow extends BasicNamiFlow {
                     }
                     break;
                 case exports.NamiFlowActionFunction.FINISHED:
-                case exports.NamiFlowActionFunction.DISMISS:
+                    // "Navigate to end of flow" — not a dismissal, not a completion;
+                    // no completion result is recorded (R5).
                     this.finished();
                     break;
+                case exports.NamiFlowActionFunction.DISMISS:
+                    this.dismiss();
+                    break;
                 case exports.NamiFlowActionFunction.EXIT: {
+                    // User skip / exit-to-end-of-flow → skip_page (R5). Signalled here,
+                    // not at the exit step, because routing through the exit step's own
+                    // flowDone would otherwise overwrite the skip intent.
+                    this.signalNonCompletion('skip_page');
                     const exit = this.steps.find((step) => step.type === NamiFlowStepType.EXIT);
                     if (exit)
                         this.forward(exit.id);
@@ -14648,34 +15205,58 @@ class NamiFlow extends BasicNamiFlow {
                 case exports.NamiFlowActionFunction.RESUME:
                     this.resumeFromPause();
                     break;
-                case exports.NamiFlowActionFunction.HANDOFF:
-                    if (action.parameters?.handoffTag) {
-                        if (!this.manager.handoffStepHandler) {
-                            logger.debug('No handoffStepHandler found', action);
-                        }
-                        else if (action.parameters.handoffData) {
-                            logger.debug(`Invoking handoffStepHandler with ${action.parameters.handoffTag} ${JSON.stringify(action.parameters.handoffData)}`);
-                            this.manager.handoffStepHandler(action.parameters.handoffTag, action.parameters.handoffData);
-                        }
-                        else if (data) {
-                            logger.debug(`Invoking handoffStepHandler with ${action.parameters.handoffTag} ${JSON.stringify(data)}`);
-                            this.manager.handoffStepHandler(action.parameters.handoffTag, data);
-                        }
-                        else if (action.parameters.handoffFormId) {
-                            const formData = this.getFormData();
-                            if (action.parameters.handoffTag === HandoffTag.SEQUENCE) {
-                                this.flowHandoffFormSequence();
-                            }
-                            else {
-                                this.manager.handoffStepHandler(action.parameters.handoffTag, formData);
-                            }
+                case exports.NamiFlowActionFunction.HANDOFF: {
+                    const tag = action.parameters?.handoffTag;
+                    if (!tag)
+                        break;
+                    // Form-commit choke point: a flowHandoff carrying a form id IS the
+                    // form submit (R3). Fired before the reserved-tag early-out so the
+                    // `__handoff_sequence__` form path signals too; the condition guard
+                    // means it only completes on a `form_submitted` page (the push POC
+                    // also carries a form id — harmless, its condition is push_authorized).
+                    if (action.parameters?.handoffFormId) {
+                        this.completionSignal('form_submitted');
+                    }
+                    // Reserved tags are SDK-internal and must NEVER reach the host
+                    // handler — checked FIRST, before any payload branching, so a
+                    // sequence action that also carries handoffData cannot leak
+                    // (NAM-1556).
+                    if (tag.startsWith(RESERVED_HANDOFF_TAG_PREFIX)) {
+                        if (tag === HandoffTag.SEQUENCE && action.parameters?.handoffFormId) {
+                            this.flowHandoffFormSequence();
                         }
                         else {
-                            logger.debug(`Invoking handoffStepHandler with ${action.parameters.handoffTag} and no data`);
-                            this.manager.handoffStepHandler(action.parameters.handoffTag);
+                            logger.warn(`Ignoring reserved handoff tag '${tag}' — resuming flow`);
+                            this.manager.resume();
                         }
+                        break;
+                    }
+                    if (!this.manager.hasHandoffHandler) {
+                        logger.debug('No handoffStepHandler found', action);
+                        break;
+                    }
+                    // userdata is an outbound data delivery: always a structured
+                    // envelope, never the bare form dict.
+                    if (tag === NamiHandoffTag.UserData && action.parameters?.handoffFormId) {
+                        this.manager.deliverHandoff(tag, this.buildUserDataEnvelope(action.parameters.handoffFormId));
+                        break;
+                    }
+                    // Legacy payload precedence, unchanged: embedded handoffData →
+                    // trigger data → form data (when a form id is present) → none.
+                    let payload;
+                    if (action.parameters?.handoffData) {
+                        payload = action.parameters.handoffData;
                     }
+                    else if (data) {
+                        payload = data;
+                    }
+                    else if (action.parameters?.handoffFormId) {
+                        payload = this.getFormData();
+                    }
+                    logger.debug(`Invoking handoff handler with ${tag}${payload ? ` ${JSON.stringify(payload)}` : ' and no data'}`);
+                    this.manager.deliverHandoff(tag, payload);
                     break;
+                }
                 case exports.NamiFlowActionFunction.LOG:
                     if (action.parameters?.eventName) {
                         logger.info(`logEvent → ${action.parameters.eventName}`);
@@ -14746,9 +15327,19 @@ class NamiFlow extends BasicNamiFlow {
                     }
                     break;
                 case exports.NamiFlowActionFunction.SET_TAGS_FROM_FORM: {
+                    // Writes captured form values to customer attributes (Apple
+                    // parity: skip null / empty-string, KEEP false / 0 — enforced by
+                    // formTagValue). Optional `include` lists the only field keys
+                    // retained — the orthogonal half of userdata delivery: everything is
+                    // delivered to the host, only explicitly routed fields are retained
+                    // by Nami.
+                    const include = action.parameters?.include;
+                    const includeSet = Array.isArray(include) ? new Set(include) : undefined;
                     const formData = this.getFormData();
                     const tags = {};
                     Object.entries(formData).forEach(([key, raw]) => {
+                        if (includeSet && !includeSet.has(key))
+                            return;
                         const value = formTagValue(raw);
                         if (value === undefined) {
                             return; // skip null / "" (false and 0 are kept by formTagValue)
@@ -14860,6 +15451,19 @@ class NamiFlow extends BasicNamiFlow {
     getFormData() {
         return { ...PaywallState.currentProvider?.state?.formStates ?? {} };
     }
+    /**
+     * Structured payload for `userdata` handoffs: Nami delivering the host
+     * app the data the user provided in a Nami-rendered form. Fields ride
+     * verbatim; the customer owns interpretation.
+     */
+    buildUserDataEnvelope(formId) {
+        return {
+            form_id: formId,
+            step_id: this.currentFlowStep?.id ?? '',
+            collected_at: new Date().toISOString(),
+            fields: this.getFormData(),
+        };
+    }
     flowHandoffFormSequence() {
         const formStates = this.currentScreenState?.formStates;
         if (!formStates) {
@@ -14902,8 +15506,9 @@ class NamiFlow extends BasicNamiFlow {
         logger.debug(`Starting handoff for ${nextKey} → ${String(value)}`);
         // persist updated sequence (remainingKeys mutated)
         this.activeHandoffSequence = sequence;
-        const handoffTag = `${nextKey}`;
-        this.manager.handoffStepHandler?.(handoffTag, undefined);
+        // Route through the manager's single delivery point so v2 handlers get
+        // a working complete() for sequence-key handoffs too.
+        this.manager.deliverHandoff(`${nextKey}`, undefined);
     }
 }
 
@@ -15251,198 +15856,6 @@ const NamiEntitlementManager$1 = NamiEntitlementManager$2;
 // `src/managers/campaign.ts` and NAM-1207.
 const NamiFlowManager$1 = NamiFlowManager$2;
 
-const postConversion = async (transactionInfo) => {
-    if (isAnonymousMode()) {
-        logger.info("Skipping transaction post - anonymous mode");
-        return;
-    }
-    try {
-        await NamiAPI.instance.postConversion(transactionInfo);
-    }
-    catch (e) {
-        logger.error("Error posting conversion", e);
-    }
-};
-
-/**
- * @class NamiPaywallManager
- * Provides methods for managing all aspects of a paywall in the Nami SDK.
- */
-let NamiPaywallManager$2 = class NamiPaywallManager {
-    constructor() {
-        this.emitter = NamiEventEmitter.getInstance();
-    }
-    /**
-     * @returns {IPaywall[]} a list of Paywall
-     */
-    static allPaywalls() {
-        if (!this.instance.sdkInitialized) {
-            throw new SDKNotInitializedError();
-        }
-        return allPaywalls();
-    }
-    /**
-     * Used to set product details when store products are unavailable. For advanced use cases only.
-     */
-    static setProductDetails(productDetails) {
-        this.instance.productDetails = productDetails;
-        PaywallState.setProductDetails(productDetails);
-    }
-    /**
-     * Register a callback which would be invoked when user will sign-in
-     */
-    static registerSignInHandler(handler) {
-        this.instance.emitter.addListener(exports.PaywallManagerEvents.SignIn, handler);
-        return () => {
-            this.instance.emitter.removeListener(exports.PaywallManagerEvents.SignIn, handler);
-        };
-    }
-    /**
-     * Register a callback which would be invoked when user close a paywall raised by Nami system
-     */
-    static registerCloseHandler(handler) {
-        this.instance.emitter.addListener(exports.PaywallManagerEvents.Close, handler);
-        return () => {
-            this.instance.emitter.removeListener(exports.PaywallManagerEvents.Close, handler);
-        };
-    }
-    /**
-     * Register a callback which would be invoked when user will take action on deeplink
-     */
-    static registerDeeplinkActionHandler(handler) {
-        this.instance.emitter.addListener(exports.PaywallManagerEvents.DeeplinkAction, handler);
-        return () => {
-            this.instance.emitter.removeListener(exports.PaywallManagerEvents.DeeplinkAction, handler);
-        };
-    }
-    /**
-     * Register a [NamiBuySkuHandler] which would be invoked when a user triggers
-     * a buy sku action on a paywall.
-     *
-     * Only available for plans where Nami is not handling subscription & IAP management.
-     */
-    static registerBuySkuHandler(handler) {
-        if (hasPurchaseManagement()) {
-            logger.debug("This handler will not be invoked because this account's plan includes " +
-                "built-in purchase management. Contact support@namiml.com for details.");
-        }
-        this.instance.emitter.addListener(exports.PaywallManagerEvents.BuySku, handler);
-        return () => {
-            this.instance.emitter.removeListener(exports.PaywallManagerEvents.BuySku, handler);
-        };
-    }
-    /**
-     * Register a callback which would be invoked when user restore a product
-     */
-    static registerRestoreHandler(handler) {
-        this.instance.emitter.addListener(exports.PaywallManagerEvents.Restore, handler);
-        return () => {
-            this.instance.emitter.removeListener(exports.PaywallManagerEvents.Restore, handler);
-        };
-    }
-    /**
-     * Notify the NamiPaywallManager that a purchase initiated from the
-     * [NamiBuySkuHandler] is complete.
-     *
-     * Only available for plans where Nami is not handling subscription & IAP management.
-     *
-     * @returns {Promise<void>} A Promise that resolves when buying SKU will be complete.
-     */
-    static async buySkuComplete(purchase) {
-        // clear loading indicator
-        PaywallState.setPurchaseInProgress(false);
-        if (NamiFlowManager$2.instance.flowOpen) {
-            const flow = NamiFlowManager$2.instance.currentFlow;
-            const currentStep = flow?.currentFlowStep;
-            if (flow && currentStep) {
-                flow.executeLifecycle(currentStep, NamiReservedActions.PURCHASE_SUCCESS);
-            }
-        }
-        if (NamiCustomerManager$2.inAnonymousMode()) {
-            logger.debug("Skipping purchase validation - anonymous mode");
-            return;
-        }
-        const session = storageService.getSessionId();
-        const impression = storageService.getPurchaseImpression();
-        if (!impression) {
-            logger.debug("Not sending paywall conversion call complete due to unknown impression");
-            return;
-        }
-        // send conversion
-        try {
-            await postConversion({
-                purchase_env: "production",
-                app_env: "production",
-                impression,
-                session,
-                amount: purchase.amount,
-                currency: purchase.currency,
-                transaction_id: purchase.transactionId,
-                sku: purchase.skuId,
-            });
-        }
-        catch (e) {
-            logger.error('Error posting conversion', e);
-        }
-        // validate purchase
-        if (!hasCapability(exports.Capabilities.THIRD_PARTY_TRANSACTIONS)) {
-            try {
-                await NamiAPI.instance.purchaseValidation({
-                    app_env: "production",
-                    payload: '', // token to be added when here a direct integration is done
-                    sku: purchase.skuId,
-                });
-            }
-            catch (e) {
-                logger.error("Error validating purchase", e);
-            }
-        }
-    }
-    /**
-     * Notify the NamiPaywallManager that purchase flow handled by you is cancelled.
-     * Used to disable product purchase-in-progress loading indicators
-     */
-    static buySkuCancel() {
-        if (!hasCapability(exports.Capabilities.THIRD_PARTY_TRANSACTIONS)) {
-            logger.warn("Call this method is not needed for this app because Nami is responsible for purchase management. Contact support@nami.ml for details.");
-            return;
-        }
-        PaywallState.setPurchase(false);
-    }
-    /**
-     * Set the video details for the app supplied video
-     * @param url The URL of the video
-     * @param name The name of the video
-     */
-    static setAppSuppliedVideoDetails(url, name) {
-        if (isValidUrl(url)) {
-            logger.debug(`NamiPaywallManager: setAppSuppliedVideoDetails received valid url ${url}`);
-            PaywallState.setAppSuppliedVideoDetails({ url, name });
-        }
-        else {
-            logger.debug(`NamiPaywallManager: setAppSuppliedVideoDetails received invalid url ${url}`);
-        }
-    }
-    /**
-     * Enables or disables user interaction on Nami paywalls.
-     *
-     * @param {boolean} allowed - Whether user interaction should be allowed.
-     * @returns {void}
-     */
-    static allowUserInteraction(allowed) {
-        logger.debug(`NamiPaywallManager: allowUserInteraction called with ${allowed}`);
-        PaywallState.setUserInteractionEnabled(allowed);
-    }
-    /**
-     * Private Instance Methods
-     */
-    get sdkInitialized() {
-        return Nami.instance.isInitialized;
-    }
-};
-NamiPaywallManager$2.instance = new NamiPaywallManager$2();
-NamiPaywallManager$2.emitter = NamiEventEmitter.getInstance();
-
 // Re-export the class itself, typed as the narrow public interface. Same
 // object identity as the underlying class so jest.spyOn works. See
 // `src/managers/campaign.ts` and NAM-1207.
@@ -65050,8 +65463,10 @@ exports.NamiEventEmitter = NamiEventEmitter;
 exports.NamiFlow = NamiFlow;
 exports.NamiFlowManager = NamiFlowManager$1;
 exports.NamiFlowStepType = NamiFlowStepType;
+exports.NamiHandoffTag = NamiHandoffTag;
 exports.NamiPaywallManager = NamiPaywallManager$1;
 exports.NamiPaywallManagerEvents = exports.PaywallManagerEvents;
+exports.NamiPermissionOutcome = NamiPermissionOutcome;
 exports.NamiPurchaseManager = NamiPurchaseManager$1;
 exports.NamiRefs = NamiRefs;
 exports.NamiReservedActions = NamiReservedActions;