@namiml/sdk-core 3.5.0-dev.202611020145 → 3.5.0-dev.202611022057

package/dist/index.cjs

@@ -106,7 +106,7 @@ const {
 // version — stamped by scripts/version.sh
 NAMI_SDK_VERSION: exports.NAMI_SDK_VERSION = "3.5.0", 
 // full package version including dev suffix — stamped by scripts/version.sh
-NAMI_SDK_PACKAGE_VERSION: exports.NAMI_SDK_PACKAGE_VERSION = "3.5.0-dev.202611020145", 
+NAMI_SDK_PACKAGE_VERSION: exports.NAMI_SDK_PACKAGE_VERSION = "3.5.0-dev.202611022057", 
 // environments
 PRODUCTION: exports.PRODUCTION = "production", DEVELOPMENT: exports.DEVELOPMENT = "development", 
 // error messages
@@ -57121,6 +57121,8 @@ function isSupportedJourney(meta) {
     return true;
 }
 const isJourneyCampaign = (rule) => rule.type === exports.NamiCampaignRuleType.JOURNEY;
+/** The parsed journey metadata of a journey rule; null for a placement rule or no metadata. */
+const journeyMetadataOf = (rule) => isJourneyCampaign(rule) ? parseJourneyMetadata(rule.journey) : null;
 /**
  * Whether this SDK can use the rule. Every placement rule qualifies. A journey also needs
  * supported metadata and a flow, because journeys are flow-only. Callers skip an unsupported
@@ -62880,6 +62882,16 @@ class JourneyEngine {
     recordDismiss(s, journeyId, now) {
         return this.withRecord(s, journeyId, { ...(s.journeys[journeyId] ?? emptyJourneyRecord()), lastDismissedAt: now.getTime() });
     }
+    /**
+     * Whether a goal signal counts now (NAM-3236): the journey was entered (an impression since
+     * any earlier goal) and its `timeout_days` window, measured from entry, is still open.
+     */
+    isGoalOpen(record, journey, now) {
+        if (record?.enteredAt == null)
+            return false;
+        const timeout = journey.goal?.timeout_days;
+        return timeout == null || now.getTime() < record.enteredAt + timeout * DAY_MS;
+    }
     /** Records goal completion and clears entry so a re-entry journey starts a fresh timeout. */
     recordGoal(s, journeyId, now) {
         return this.withRecord(s, journeyId, {
@@ -63042,6 +63054,11 @@ function presentJourneyCampaign(campaign, stillValid) {
     return ui.presentCampaign(campaign, { customAttributes: {} });
 }
 
+let refreshHost = null;
+/** Called by `NamiRefs` when it is constructed. */
+const registerJourneyRefreshHost = (host) => {
+    refreshHost = host;
+};
 const monotonicNow = () => typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
 const liveJourneyEnvironment = {
     now: () => new Date(),
@@ -63056,14 +63073,21 @@ const liveJourneyEnvironment = {
         get: () => storageService.getJourneyInstallEvaluated(),
         set: () => storageService.setJourneyInstallEvaluated(),
     },
+    refresh: () => refreshHost?.fetchCampaignsAndPaywalls() ?? Promise.resolve(),
+    refreshAllowed: () => !(refreshHost?.isStartupInFlight() ?? false),
+    // Only while the platform has journey rules: an org with none sees no refresh traffic, and picks
+    // up newly added journeys on the next session's startup fetch. `journey_settings` does not
+    // count: the backend sends it in every platform config, journeys or not.
+    refreshEnabled: () => (refreshHost?.canRefreshJourneys() ?? false) && journeyCampaigns().length > 0,
 };
-const journeyIdOf = (rule) => parseJourneyMetadata(rule.journey)?.journey_id;
+const journeyIdOf = (rule) => journeyMetadataOf(rule)?.journey_id;
 /**
  * Drives journey delivery for the `app_install` and `session_start` triggers (NAM-3233):
- * evaluation, the single delay slot, the fire-time re-check, delivery and local impression
- * accounting. A port of Apple's `JourneyCoordinator` (NAM-3234) minus campaign-rule refresh,
- * which core gains in NAM-3236. JS is single-threaded, so there is no queue: the reset
- * generation alone keeps work from before a `Nami.reset()` off the fresh state.
+ * evaluation, the single delay slot, the fire-time re-check, delivery, local impression
+ * accounting, and campaign-rule refresh coalescing. A port of Apple's `JourneyCoordinator`
+ * (NAM-3234), plus goal recording (NAM-3236), which Apple gains in NAM-3237. JS is
+ * single-threaded, so there is no queue: the reset generation alone keeps work from before a
+ * `Nami.reset()` off the fresh state.
  *
  * Guards on the way to a raise:
  * - A winner chosen while the app is hidden starts its delay paused, a 0-second delay included,
@@ -63080,6 +63104,11 @@ class JourneyCoordinator {
         this.engine = new JourneyEngine();
         this.resetGeneration = 0;
         this.backgroundedAt = null;
+        this.refreshInFlight = false;
+        this.refreshPending = false;
+        /** A purchase asked for a refresh while a startup pass was running; flushed once when it ends. */
+        this.refreshDeferred = false;
+        this.refreshTimer = null;
         this.delay = new JourneyDelayTimer(env.monotonicNow);
     }
     /**
@@ -63109,14 +63138,17 @@ class JourneyCoordinator {
         }
         journeyStateStore.startSession();
         this.evaluate(isInstallCandidate);
+        this.startRefreshTimer();
     }
-    /** Pauses the delay, keeping the remainder, and starts measuring the session gap. */
+    /** Pauses the delay, keeping the remainder, stops the refresh timer and starts measuring the session gap. */
     appDidEnterBackground() {
         this.delay.pause();
+        this.stopRefreshTimer();
         this.backgroundedAt ??= this.env.monotonicNow();
     }
     /**
-     * Resumes the delay with the remaining time, including one held since a hidden start.
+     * Resumes the delay with the remaining time, including one held since a hidden start, and
+     * restarts the refresh timer.
      *
      * @returns whether this return begins a new session: it came at least {@link SESSION_GAP_MS}
      *   after the background (the session boundary Apple and Android share). A foreground with no
@@ -63126,17 +63158,152 @@ class JourneyCoordinator {
         const hiddenAt = this.backgroundedAt;
         this.backgroundedAt = null;
         this.delay.resume();
+        this.startRefreshTimer();
         return hiddenAt !== null && this.env.monotonicNow() - hiddenAt >= exports.SESSION_GAP_MS;
     }
     /** A placement campaign is about to be raised: a journey still waiting must not fire on top of it. */
     placementWillRaise() {
         this.delay.cancel();
     }
-    /** Cancels the delay and invalidates in-flight work (`Nami.reset()`), before the storage wipe. */
+    /**
+     * Cancels the delay and the refresh timer, clears refresh state and invalidates in-flight work
+     * (`Nami.reset()`), before the storage wipe.
+     */
     reset() {
         this.delay.cancel();
+        this.stopRefreshTimer();
         this.backgroundedAt = null;
         this.resetGeneration += 1;
+        this.refreshInFlight = false;
+        this.refreshPending = false;
+        this.refreshDeferred = false;
+    }
+    // Goals (NAM-3236)
+    /**
+     * A flow's completion step matched its condition. For a journey whose goal is
+     * `flow_completed`, that is the goal; the completion PATCH that reports it is the flow's own.
+     *
+     * @returns whether a goal was recorded.
+     */
+    flowCompletionSignaled(campaign) {
+        const journey = campaign ? journeyMetadataOf(campaign) : null;
+        if (journey?.goal?.type !== "flow_completed" || !this.goalReached(journey))
+            return false;
+        this.requestRefresh();
+        return true;
+    }
+    /**
+     * A customer attribute was set. Records the goal of every journey whose `user_context_set` goal
+     * watches `key`, then refreshes the rules when the value changed (journey eligibility can depend
+     * on attributes) or a goal was recorded (it can unlock the next journey).
+     */
+    customerAttributeSet(key, changed) {
+        let goal = false;
+        for (const rule of this.env.journeys()) {
+            const journey = journeyMetadataOf(rule);
+            if (journey?.goal?.type === "user_context_set" && journey.goal.context_key === key) {
+                goal = this.goalReached(journey) || goal;
+            }
+        }
+        if (changed || goal)
+            this.requestRefresh();
+    }
+    /**
+     * Records the goal and exits the journey: `goalAchievedAt` is stamped and entry cleared, so the
+     * engine rejects it (`goalAchieved`) unless it allows re-entry. Counts only while the journey is
+     * entered and inside its `timeout_days` window; anything else (never shown, already achieved,
+     * timed out) is ignored.
+     */
+    goalReached(journey) {
+        const id = journey.journey_id;
+        const now = this.env.now();
+        if (!this.engine.isGoalOpen(journeyStateStore.snapshot().journeys[id], journey, now)) {
+            logger.debug(`Journey ${id} goal ignored: not entered, already achieved or timed out`);
+            return false;
+        }
+        journeyStateStore.update((s) => this.engine.recordGoal(s, id, now));
+        logger.debug(`Journey ${id} goal achieved`);
+        return true;
+    }
+    // Refresh
+    /**
+     * Re-fetches campaign rules. At most one fetch is in flight, plus one trailing fetch if more
+     * requests arrive meanwhile. Never evaluates journeys by itself: a newly eligible journey fires on
+     * its own next trigger.
+     *
+     * While a startup pass runs the request is dropped, because the pass fetches the rules itself.
+     * A purchase passes `deferIfBusy` so it is not lost: it refreshes once when the pass ends.
+     */
+    requestRefresh(deferIfBusy = false) {
+        if (!this.env.refreshEnabled())
+            return;
+        if (this.refreshInFlight) {
+            this.refreshPending = true;
+        }
+        else if (this.env.refreshAllowed()) {
+            this.startRefresh();
+        }
+        else if (deferIfBusy) {
+            this.refreshDeferred = true;
+        }
+    }
+    /** A startup or resume pass ended, either way. Flushes a refresh a purchase deferred during it. */
+    startupPassFinished() {
+        if (!this.refreshDeferred)
+            return;
+        this.refreshDeferred = false;
+        if (!this.env.refreshEnabled())
+            return;
+        if (this.refreshInFlight) {
+            this.refreshPending = true;
+        }
+        else {
+            this.startRefresh();
+        }
+    }
+    startRefresh() {
+        this.refreshInFlight = true;
+        const generation = this.resetGeneration;
+        const settle = () => {
+            if (this.resetGeneration !== generation)
+                return;
+            this.refreshInFlight = false;
+            if (this.refreshPending) {
+                this.refreshPending = false;
+                this.requestRefresh(true);
+            }
+        };
+        let fetch;
+        try {
+            fetch = this.env.refresh();
+        }
+        catch (error) {
+            fetch = Promise.reject(error);
+        }
+        fetch.then(settle, (error) => {
+            logger.warn(`Journey refresh failed: ${error}`);
+            settle();
+        });
+    }
+    /**
+     * Starts the repeating `refresh_interval_seconds` timer, but only while the app is visible: it
+     * never runs in the background. Unreferenced in Node, so it never keeps a CLI process alive.
+     */
+    startRefreshTimer() {
+        if (this.refreshTimer !== null || !this.env.isAppVisible())
+            return;
+        const ms = this.env.settings().refresh_interval_seconds * 1000;
+        if (!(ms > 0))
+            return;
+        const timer = setInterval(() => this.requestRefresh(), ms);
+        timer.unref?.();
+        this.refreshTimer = timer;
+    }
+    stopRefreshTimer() {
+        if (this.refreshTimer === null)
+            return;
+        clearInterval(this.refreshTimer);
+        this.refreshTimer = null;
     }
     // Evaluation
     evaluate(isInstallCandidate) {
@@ -63239,6 +63406,15 @@ class NamiRefs {
         this.startupFetch = Promise.resolve();
         // Register this instance to avoid circular dependency issues
         setNamiRefsInstance(this);
+        registerJourneyRefreshHost(this);
+    }
+    /** Whether a startup or resume pass is running; journey refresh waits for it (NAM-3236). */
+    isStartupInFlight() {
+        return this.startupInFlight;
+    }
+    /** Whether configure has run with a real app platform id and startup is not disabled. */
+    canRefreshJourneys() {
+        return !!this.lastConfig?.appPlatformID?.trim() && !this.startupDisabled;
     }
     setInMemoryAnonymousMode(enabled) {
         this.inMemoryAnonymousMode = enabled;
@@ -63287,6 +63463,7 @@ class NamiRefs {
         }
         finally {
             this.startupInFlight = false;
+            JourneyCoordinator.shared.startupPassFinished();
         }
     }
     /**
@@ -63349,6 +63526,7 @@ class NamiRefs {
         }
         finally {
             this.startupInFlight = false;
+            JourneyCoordinator.shared.startupPassFinished();
         }
     }
     /** Everything startup runs once the platform-config step has found a usable config. */
@@ -64996,6 +65174,15 @@ let NamiPaywallManager$2 = class NamiPaywallManager {
      * @returns {Promise<void>} A Promise that resolves when buying SKU will be complete.
      */
     static async buySkuComplete(purchase) {
+        try {
+            await this.reportPurchaseComplete(purchase);
+        }
+        finally {
+            // A host-managed purchase changes journey eligibility too: re-fetch the rules (NAM-3236).
+            JourneyCoordinator.shared.requestRefresh(true);
+        }
+    }
+    static async reportPurchaseComplete(purchase) {
         // clear loading indicator
         PaywallState.setPurchaseInProgress(false);
         if (NamiFlowManager$2.instance.flowOpen) {
@@ -65920,6 +66107,7 @@ let NamiCustomerManager$2 = class NamiCustomerManager {
         if (!this.instance.isSDKInitialized) {
             throw new SDKNotInitializedError();
         }
+        const changed = storageService.getCustomerAttribute(key) !== value;
         storageService.setCustomerAttribute(key, value);
         if (!hasCapability(exports.Capabilities.PAYWALL_PERSONALIZATION)) {
             logger.warn(`The customer attribute ${key} is not available for using on a paywall, because your account's plan does not include paywall personalization. Contact support@nami.ml for details.`);
@@ -65931,12 +66119,19 @@ let NamiCustomerManager$2 = class NamiCustomerManager {
         if (NamiFlowManager$2.instance.flowOpen) {
             const currentFlow = NamiFlowManager$2.instance.currentFlow;
             if (currentFlow) {
+                // An open journey flow whose `user_context_set` goal watches this key reports the goal
+                // through its completion step (NAM-3236), before the lifecycle can move it off the page.
+                const goal = currentFlow.campaign ? journeyMetadataOf(currentFlow.campaign)?.goal : null;
+                if (goal?.type === "user_context_set" && goal.context_key === key) {
+                    currentFlow.completionSignal("context_set");
+                }
                 const currentStep = currentFlow.currentFlowStep;
                 if (currentStep) {
                     currentFlow.executeLifecycle(currentStep, NamiReservedActions.TAG_UPDATE);
                 }
             }
         }
+        JourneyCoordinator.shared.customerAttributeSet(key, changed);
     }
     /**
      * Retrieves the value for a given key in the on-device customer attribute key/value store.
@@ -66398,6 +66593,9 @@ class NamiFlow extends BasicNamiFlow {
         }
         if (ctx.resultSent)
             return; // R4: one completion per impression
+        // A journey's `flow_completed` goal is met here, whether or not an impression is bound yet
+        // (anonymous mode never binds one); the PATCH below is what reports it (NAM-3236).
+        JourneyCoordinator.shared.flowCompletionSignaled(this.campaign);
         if (!ctx.impressionId) {
             if (!ctx.pending.includes(condition))
                 ctx.pending.push(condition);

package/dist/index.d.ts

@@ -1030,7 +1030,9 @@ interface NamiFlowStep {
  * plain string on `completion_step.condition`; this union is the SDK-side
  * vocabulary the engine acts on.
  */
-type NamiFlowCompletionCondition = 'page_view' | 'purchase_success' | 'login_success' | 'push_authorized' | 'location_authorized' | 'tracking_authorized' | 'form_submitted';
+type NamiFlowCompletionCondition = 'page_view' | 'purchase_success' | 'login_success' | 'push_authorized' | 'location_authorized' | 'tracking_authorized' | 'form_submitted'
+/** A journey's `user_context_set` goal: its `goal.context_key` attribute was set (NAM-3236). */
+ | 'context_set';
 /**
  * Every value the SDK may PATCH as `completion_result`: the positive
  * conditions plus the two non-completion outcomes recorded when a flow
@@ -3681,6 +3683,10 @@ declare class NamiRefs {
     private startupInFlight;
     private startupFetch;
     constructor();
+    /** Whether a startup or resume pass is running; journey refresh waits for it (NAM-3236). */
+    isStartupInFlight(): boolean;
+    /** Whether configure has run with a real app platform id and startup is not disabled. */
+    canRefreshJourneys(): boolean;
     setInMemoryAnonymousMode(enabled: boolean): void;
     isInMemoryAnonymousMode(): boolean;
     isAnonymousMode(): boolean;
@@ -4543,6 +4549,7 @@ declare class NamiPaywallManager$1 {
      * @returns {Promise<void>} A Promise that resolves when buying SKU will be complete.
      */
     static buySkuComplete(purchase: NamiPurchaseSuccess): Promise<void>;
+    private static reportPurchaseComplete;
     /**
      * Notify the NamiPaywallManager that purchase flow handled by you is cancelled.
      * Used to disable product purchase-in-progress loading indicators

package/dist/index.mjs

@@ -104,7 +104,7 @@ const {
 // version — stamped by scripts/version.sh
 NAMI_SDK_VERSION = "3.5.0", 
 // full package version including dev suffix — stamped by scripts/version.sh
-NAMI_SDK_PACKAGE_VERSION = "3.5.0-dev.202611020145", 
+NAMI_SDK_PACKAGE_VERSION = "3.5.0-dev.202611022057", 
 // environments
 PRODUCTION = "production", DEVELOPMENT = "development", 
 // error messages
@@ -57119,6 +57119,8 @@ function isSupportedJourney(meta) {
     return true;
 }
 const isJourneyCampaign = (rule) => rule.type === NamiCampaignRuleType.JOURNEY;
+/** The parsed journey metadata of a journey rule; null for a placement rule or no metadata. */
+const journeyMetadataOf = (rule) => isJourneyCampaign(rule) ? parseJourneyMetadata(rule.journey) : null;
 /**
  * Whether this SDK can use the rule. Every placement rule qualifies. A journey also needs
  * supported metadata and a flow, because journeys are flow-only. Callers skip an unsupported
@@ -62878,6 +62880,16 @@ class JourneyEngine {
     recordDismiss(s, journeyId, now) {
         return this.withRecord(s, journeyId, { ...(s.journeys[journeyId] ?? emptyJourneyRecord()), lastDismissedAt: now.getTime() });
     }
+    /**
+     * Whether a goal signal counts now (NAM-3236): the journey was entered (an impression since
+     * any earlier goal) and its `timeout_days` window, measured from entry, is still open.
+     */
+    isGoalOpen(record, journey, now) {
+        if (record?.enteredAt == null)
+            return false;
+        const timeout = journey.goal?.timeout_days;
+        return timeout == null || now.getTime() < record.enteredAt + timeout * DAY_MS;
+    }
     /** Records goal completion and clears entry so a re-entry journey starts a fresh timeout. */
     recordGoal(s, journeyId, now) {
         return this.withRecord(s, journeyId, {
@@ -63040,6 +63052,11 @@ function presentJourneyCampaign(campaign, stillValid) {
     return ui.presentCampaign(campaign, { customAttributes: {} });
 }
 
+let refreshHost = null;
+/** Called by `NamiRefs` when it is constructed. */
+const registerJourneyRefreshHost = (host) => {
+    refreshHost = host;
+};
 const monotonicNow = () => typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
 const liveJourneyEnvironment = {
     now: () => new Date(),
@@ -63054,14 +63071,21 @@ const liveJourneyEnvironment = {
         get: () => storageService.getJourneyInstallEvaluated(),
         set: () => storageService.setJourneyInstallEvaluated(),
     },
+    refresh: () => refreshHost?.fetchCampaignsAndPaywalls() ?? Promise.resolve(),
+    refreshAllowed: () => !(refreshHost?.isStartupInFlight() ?? false),
+    // Only while the platform has journey rules: an org with none sees no refresh traffic, and picks
+    // up newly added journeys on the next session's startup fetch. `journey_settings` does not
+    // count: the backend sends it in every platform config, journeys or not.
+    refreshEnabled: () => (refreshHost?.canRefreshJourneys() ?? false) && journeyCampaigns().length > 0,
 };
-const journeyIdOf = (rule) => parseJourneyMetadata(rule.journey)?.journey_id;
+const journeyIdOf = (rule) => journeyMetadataOf(rule)?.journey_id;
 /**
  * Drives journey delivery for the `app_install` and `session_start` triggers (NAM-3233):
- * evaluation, the single delay slot, the fire-time re-check, delivery and local impression
- * accounting. A port of Apple's `JourneyCoordinator` (NAM-3234) minus campaign-rule refresh,
- * which core gains in NAM-3236. JS is single-threaded, so there is no queue: the reset
- * generation alone keeps work from before a `Nami.reset()` off the fresh state.
+ * evaluation, the single delay slot, the fire-time re-check, delivery, local impression
+ * accounting, and campaign-rule refresh coalescing. A port of Apple's `JourneyCoordinator`
+ * (NAM-3234), plus goal recording (NAM-3236), which Apple gains in NAM-3237. JS is
+ * single-threaded, so there is no queue: the reset generation alone keeps work from before a
+ * `Nami.reset()` off the fresh state.
  *
  * Guards on the way to a raise:
  * - A winner chosen while the app is hidden starts its delay paused, a 0-second delay included,
@@ -63078,6 +63102,11 @@ class JourneyCoordinator {
         this.engine = new JourneyEngine();
         this.resetGeneration = 0;
         this.backgroundedAt = null;
+        this.refreshInFlight = false;
+        this.refreshPending = false;
+        /** A purchase asked for a refresh while a startup pass was running; flushed once when it ends. */
+        this.refreshDeferred = false;
+        this.refreshTimer = null;
         this.delay = new JourneyDelayTimer(env.monotonicNow);
     }
     /**
@@ -63107,14 +63136,17 @@ class JourneyCoordinator {
         }
         journeyStateStore.startSession();
         this.evaluate(isInstallCandidate);
+        this.startRefreshTimer();
     }
-    /** Pauses the delay, keeping the remainder, and starts measuring the session gap. */
+    /** Pauses the delay, keeping the remainder, stops the refresh timer and starts measuring the session gap. */
     appDidEnterBackground() {
         this.delay.pause();
+        this.stopRefreshTimer();
         this.backgroundedAt ??= this.env.monotonicNow();
     }
     /**
-     * Resumes the delay with the remaining time, including one held since a hidden start.
+     * Resumes the delay with the remaining time, including one held since a hidden start, and
+     * restarts the refresh timer.
      *
      * @returns whether this return begins a new session: it came at least {@link SESSION_GAP_MS}
      *   after the background (the session boundary Apple and Android share). A foreground with no
@@ -63124,17 +63156,152 @@ class JourneyCoordinator {
         const hiddenAt = this.backgroundedAt;
         this.backgroundedAt = null;
         this.delay.resume();
+        this.startRefreshTimer();
         return hiddenAt !== null && this.env.monotonicNow() - hiddenAt >= SESSION_GAP_MS;
     }
     /** A placement campaign is about to be raised: a journey still waiting must not fire on top of it. */
     placementWillRaise() {
         this.delay.cancel();
     }
-    /** Cancels the delay and invalidates in-flight work (`Nami.reset()`), before the storage wipe. */
+    /**
+     * Cancels the delay and the refresh timer, clears refresh state and invalidates in-flight work
+     * (`Nami.reset()`), before the storage wipe.
+     */
     reset() {
         this.delay.cancel();
+        this.stopRefreshTimer();
         this.backgroundedAt = null;
         this.resetGeneration += 1;
+        this.refreshInFlight = false;
+        this.refreshPending = false;
+        this.refreshDeferred = false;
+    }
+    // Goals (NAM-3236)
+    /**
+     * A flow's completion step matched its condition. For a journey whose goal is
+     * `flow_completed`, that is the goal; the completion PATCH that reports it is the flow's own.
+     *
+     * @returns whether a goal was recorded.
+     */
+    flowCompletionSignaled(campaign) {
+        const journey = campaign ? journeyMetadataOf(campaign) : null;
+        if (journey?.goal?.type !== "flow_completed" || !this.goalReached(journey))
+            return false;
+        this.requestRefresh();
+        return true;
+    }
+    /**
+     * A customer attribute was set. Records the goal of every journey whose `user_context_set` goal
+     * watches `key`, then refreshes the rules when the value changed (journey eligibility can depend
+     * on attributes) or a goal was recorded (it can unlock the next journey).
+     */
+    customerAttributeSet(key, changed) {
+        let goal = false;
+        for (const rule of this.env.journeys()) {
+            const journey = journeyMetadataOf(rule);
+            if (journey?.goal?.type === "user_context_set" && journey.goal.context_key === key) {
+                goal = this.goalReached(journey) || goal;
+            }
+        }
+        if (changed || goal)
+            this.requestRefresh();
+    }
+    /**
+     * Records the goal and exits the journey: `goalAchievedAt` is stamped and entry cleared, so the
+     * engine rejects it (`goalAchieved`) unless it allows re-entry. Counts only while the journey is
+     * entered and inside its `timeout_days` window; anything else (never shown, already achieved,
+     * timed out) is ignored.
+     */
+    goalReached(journey) {
+        const id = journey.journey_id;
+        const now = this.env.now();
+        if (!this.engine.isGoalOpen(journeyStateStore.snapshot().journeys[id], journey, now)) {
+            logger.debug(`Journey ${id} goal ignored: not entered, already achieved or timed out`);
+            return false;
+        }
+        journeyStateStore.update((s) => this.engine.recordGoal(s, id, now));
+        logger.debug(`Journey ${id} goal achieved`);
+        return true;
+    }
+    // Refresh
+    /**
+     * Re-fetches campaign rules. At most one fetch is in flight, plus one trailing fetch if more
+     * requests arrive meanwhile. Never evaluates journeys by itself: a newly eligible journey fires on
+     * its own next trigger.
+     *
+     * While a startup pass runs the request is dropped, because the pass fetches the rules itself.
+     * A purchase passes `deferIfBusy` so it is not lost: it refreshes once when the pass ends.
+     */
+    requestRefresh(deferIfBusy = false) {
+        if (!this.env.refreshEnabled())
+            return;
+        if (this.refreshInFlight) {
+            this.refreshPending = true;
+        }
+        else if (this.env.refreshAllowed()) {
+            this.startRefresh();
+        }
+        else if (deferIfBusy) {
+            this.refreshDeferred = true;
+        }
+    }
+    /** A startup or resume pass ended, either way. Flushes a refresh a purchase deferred during it. */
+    startupPassFinished() {
+        if (!this.refreshDeferred)
+            return;
+        this.refreshDeferred = false;
+        if (!this.env.refreshEnabled())
+            return;
+        if (this.refreshInFlight) {
+            this.refreshPending = true;
+        }
+        else {
+            this.startRefresh();
+        }
+    }
+    startRefresh() {
+        this.refreshInFlight = true;
+        const generation = this.resetGeneration;
+        const settle = () => {
+            if (this.resetGeneration !== generation)
+                return;
+            this.refreshInFlight = false;
+            if (this.refreshPending) {
+                this.refreshPending = false;
+                this.requestRefresh(true);
+            }
+        };
+        let fetch;
+        try {
+            fetch = this.env.refresh();
+        }
+        catch (error) {
+            fetch = Promise.reject(error);
+        }
+        fetch.then(settle, (error) => {
+            logger.warn(`Journey refresh failed: ${error}`);
+            settle();
+        });
+    }
+    /**
+     * Starts the repeating `refresh_interval_seconds` timer, but only while the app is visible: it
+     * never runs in the background. Unreferenced in Node, so it never keeps a CLI process alive.
+     */
+    startRefreshTimer() {
+        if (this.refreshTimer !== null || !this.env.isAppVisible())
+            return;
+        const ms = this.env.settings().refresh_interval_seconds * 1000;
+        if (!(ms > 0))
+            return;
+        const timer = setInterval(() => this.requestRefresh(), ms);
+        timer.unref?.();
+        this.refreshTimer = timer;
+    }
+    stopRefreshTimer() {
+        if (this.refreshTimer === null)
+            return;
+        clearInterval(this.refreshTimer);
+        this.refreshTimer = null;
     }
     // Evaluation
     evaluate(isInstallCandidate) {
@@ -63237,6 +63404,15 @@ class NamiRefs {
         this.startupFetch = Promise.resolve();
         // Register this instance to avoid circular dependency issues
         setNamiRefsInstance(this);
+        registerJourneyRefreshHost(this);
+    }
+    /** Whether a startup or resume pass is running; journey refresh waits for it (NAM-3236). */
+    isStartupInFlight() {
+        return this.startupInFlight;
+    }
+    /** Whether configure has run with a real app platform id and startup is not disabled. */
+    canRefreshJourneys() {
+        return !!this.lastConfig?.appPlatformID?.trim() && !this.startupDisabled;
     }
     setInMemoryAnonymousMode(enabled) {
         this.inMemoryAnonymousMode = enabled;
@@ -63285,6 +63461,7 @@ class NamiRefs {
         }
         finally {
             this.startupInFlight = false;
+            JourneyCoordinator.shared.startupPassFinished();
         }
     }
     /**
@@ -63347,6 +63524,7 @@ class NamiRefs {
         }
         finally {
             this.startupInFlight = false;
+            JourneyCoordinator.shared.startupPassFinished();
         }
     }
     /** Everything startup runs once the platform-config step has found a usable config. */
@@ -64994,6 +65172,15 @@ let NamiPaywallManager$2 = class NamiPaywallManager {
      * @returns {Promise<void>} A Promise that resolves when buying SKU will be complete.
      */
     static async buySkuComplete(purchase) {
+        try {
+            await this.reportPurchaseComplete(purchase);
+        }
+        finally {
+            // A host-managed purchase changes journey eligibility too: re-fetch the rules (NAM-3236).
+            JourneyCoordinator.shared.requestRefresh(true);
+        }
+    }
+    static async reportPurchaseComplete(purchase) {
         // clear loading indicator
         PaywallState.setPurchaseInProgress(false);
         if (NamiFlowManager$2.instance.flowOpen) {
@@ -65918,6 +66105,7 @@ let NamiCustomerManager$2 = class NamiCustomerManager {
         if (!this.instance.isSDKInitialized) {
             throw new SDKNotInitializedError();
         }
+        const changed = storageService.getCustomerAttribute(key) !== value;
         storageService.setCustomerAttribute(key, value);
         if (!hasCapability(Capabilities.PAYWALL_PERSONALIZATION)) {
             logger.warn(`The customer attribute ${key} is not available for using on a paywall, because your account's plan does not include paywall personalization. Contact support@nami.ml for details.`);
@@ -65929,12 +66117,19 @@ let NamiCustomerManager$2 = class NamiCustomerManager {
         if (NamiFlowManager$2.instance.flowOpen) {
             const currentFlow = NamiFlowManager$2.instance.currentFlow;
             if (currentFlow) {
+                // An open journey flow whose `user_context_set` goal watches this key reports the goal
+                // through its completion step (NAM-3236), before the lifecycle can move it off the page.
+                const goal = currentFlow.campaign ? journeyMetadataOf(currentFlow.campaign)?.goal : null;
+                if (goal?.type === "user_context_set" && goal.context_key === key) {
+                    currentFlow.completionSignal("context_set");
+                }
                 const currentStep = currentFlow.currentFlowStep;
                 if (currentStep) {
                     currentFlow.executeLifecycle(currentStep, NamiReservedActions.TAG_UPDATE);
                 }
             }
         }
+        JourneyCoordinator.shared.customerAttributeSet(key, changed);
     }
     /**
      * Retrieves the value for a given key in the on-device customer attribute key/value store.
@@ -66396,6 +66591,9 @@ class NamiFlow extends BasicNamiFlow {
         }
         if (ctx.resultSent)
             return; // R4: one completion per impression
+        // A journey's `flow_completed` goal is met here, whether or not an impression is bound yet
+        // (anonymous mode never binds one); the PATCH below is what reports it (NAM-3236).
+        JourneyCoordinator.shared.flowCompletionSignaled(this.campaign);
         if (!ctx.impressionId) {
             if (!ctx.pending.includes(condition))
                 ctx.pending.push(condition);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namiml/sdk-core",
-  "version": "3.5.0-dev.202611020145",
+  "version": "3.5.0-dev.202611022057",
   "description": "Platform-agnostic core for the Nami SDK — business logic, API, types, and state management",
   "type": "module",
   "main": "./dist/index.cjs",