@scalebun-release/react-native 2.5.0

package/lib/commonjs/features/engage/engageThrottle.js

@@ -0,0 +1,404 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.EngageThrottleStore = void 0;
+exports.isCampaignEligible = isCampaignEligible;
+exports.isInAppEligible = isInAppEligible;
+exports.normalizeInAppTrigger = normalizeInAppTrigger;
+exports.selectCampaignToRender = selectCampaignToRender;
+exports.selectInAppToRender = selectInAppToRender;
+exports.selectInAppVariant = selectInAppVariant;
+exports.selectLatestUnseenTest = selectLatestUnseenTest;
+exports.testRunIdOf = testRunIdOf;
+var _internalLogger = require("../../core/logger/internalLogger");
+var _StorageBackend = require("../../storage/StorageBackend");
+/**
+ * ScaleBun SDK — Engage Prompt Throttle + Decision Logic
+ *
+ * Pure, presentation-free logic that the shared cross-platform JS overlay (D4)
+ * uses to decide WHICH campaign (if any) to render from a fetched
+ * `EngageConfigResponse`, honoring each campaign's `throttle`/`Throttle` rules
+ * (§1.3) so a user is never re-prompted on every render.
+ *
+ * State (per-campaign impression count + last-shown timestamp) is persisted via
+ * the same synchronous KV backend used for the device id, so frequency capping
+ * survives app restarts. No React, no `any`, no network — this is the testable
+ * core of the renderer's Open/Closed decision seam.
+ */
+
+/** Persisted frequency-capping state for a single campaign. */
+
+const STORAGE_PREFIX = 'scalebun_engage_throttle:';
+
+/**
+ * Persistent, restart-surviving store for per-campaign throttle state. Backed by
+ * the shared first-party StorageBackend (durable native store, memory only as an
+ * emergency fallback), so frequency caps hold across sessions exactly like the
+ * device id.
+ */
+class EngageThrottleStore {
+  /**
+   * Shows in THIS session, backing `maxImpressionsPerSession`.
+   *
+   * Deliberately in-memory rather than persisted: on mobile a session is an app run, and this
+   * store is constructed once per provider mount, so the map's lifetime already is the session's.
+   * Persisting it would outlive the session it is meant to bound.
+   */
+  sessionShows = new Map();
+  constructor(backend = (0, _StorageBackend.createStorageBackend)()) {
+    this.backend = backend;
+  }
+
+  /** How many times this surface has been shown in the current session. */
+  sessionShowCount(campaignId) {
+    return this.sessionShows.get(campaignId) ?? 0;
+  }
+  keyFor(campaignId) {
+    return `${STORAGE_PREFIX}${campaignId}`;
+  }
+
+  /** Read the persisted state for a campaign (zeroed default when absent). */
+  get(campaignId) {
+    try {
+      const raw = this.backend.get(this.keyFor(campaignId));
+      if (raw) {
+        const parsed = JSON.parse(raw);
+        return {
+          impressions: typeof parsed.impressions === 'number' ? parsed.impressions : 0,
+          lastShownAt: typeof parsed.lastShownAt === 'number' ? parsed.lastShownAt : 0,
+          completed: parsed.completed === true,
+          revision: typeof parsed.revision === 'string' ? parsed.revision : undefined
+        };
+      }
+    } catch (err) {
+      __DEV__ && _internalLogger.logger.debug('[Engage] throttle state read failed:', err?.message);
+    }
+    return {
+      impressions: 0,
+      lastShownAt: 0,
+      completed: false
+    };
+  }
+
+  /** Delete one campaign's persisted throttle state (debug/dev reset, or per-id clear). */
+  clearOne(campaignId) {
+    try {
+      this.backend.delete(this.keyFor(campaignId));
+    } catch (err) {
+      __DEV__ && _internalLogger.logger.debug('[Engage] throttle clearOne failed:', err?.message);
+    }
+  }
+
+  /**
+   * Delete ALL persisted in-app/campaign throttle state (every `scalebun_engage_throttle:*`
+   * key). Backs the public `ScaleBun.engage.resetInAppState()` debug reset — clears
+   * dismissed/impression/cooldown/showOnce so a tester sees messages again WITHOUT an
+   * uninstall. Does NOT touch the device id (a separate key) — identity is preserved.
+   */
+  clearAll() {
+    let n = 0;
+    try {
+      for (const key of this.backend.getAllKeys()) {
+        if (key.startsWith(STORAGE_PREFIX)) {
+          this.backend.delete(key);
+          n += 1;
+        }
+      }
+    } catch (err) {
+      __DEV__ && _internalLogger.logger.debug('[Engage] throttle clearAll failed:', err?.message);
+    }
+    return n;
+  }
+  write(campaignId, state) {
+    try {
+      this.backend.set(this.keyFor(campaignId), JSON.stringify(state));
+    } catch (err) {
+      __DEV__ && _internalLogger.logger.debug('[Engage] throttle state write failed:', err?.message);
+    }
+  }
+
+  /**
+   * Record that a campaign was shown (bumps impressions + last-shown time). When a
+   * `revision` is supplied and differs from the stored one, the prior counters are a
+   * stale (pre-edit) generation and reset to a single fresh impression — so changing a
+   * campaign's content never inherits the old cap.
+   */
+  recordImpression(campaignId, now = Date.now(), revision) {
+    const prev = this.get(campaignId);
+    const fresh = revision !== undefined && prev.revision !== undefined && prev.revision !== revision;
+    this.write(campaignId, {
+      impressions: fresh ? 1 : prev.impressions + 1,
+      lastShownAt: now,
+      completed: fresh ? false : prev.completed,
+      revision: revision ?? prev.revision
+    });
+    // A new revision is a new design: its session count starts over with its durable counters.
+    this.sessionShows.set(campaignId, fresh ? 1 : this.sessionShowCount(campaignId) + 1);
+  }
+
+  /**
+   * Mark a campaign as completed (response submitted, or an in-app message closed) — a hard stop.
+   *
+   * The `revision` MUST be carried through. This wrote the record without one, which silently
+   * disabled the revision check in `passesThrottle` for the rest of that campaign's life on the
+   * device: that check only fires when BOTH the live config and the stored state carry a revision,
+   * so a state stamped `undefined` can never be invalidated. The result was the exact opposite of
+   * the web bug — once a user closed an in-app message, editing the campaign could never bring the
+   * new version back to them. Callers that know the served revision pass it; legacy callers that
+   * don't keep whatever was already stored rather than erasing it.
+   */
+  markCompleted(campaignId, now = Date.now(), revision) {
+    const prev = this.get(campaignId);
+    this.write(campaignId, {
+      impressions: prev.impressions,
+      lastShownAt: prev.lastShownAt || now,
+      completed: true,
+      revision: revision ?? prev.revision
+    });
+  }
+}
+
+/** Deterministic 0–99 bucket for a string seed (stable across sessions/devices). */
+exports.EngageThrottleStore = EngageThrottleStore;
+function stableBucket(seed) {
+  let hash = 0;
+  for (let i = 0; i < seed.length; i += 1) {
+    hash = hash * 31 + seed.charCodeAt(i) | 0;
+  }
+  return Math.abs(hash) % 100;
+}
+
+/** Deterministic 0–99 bucket for `samplePct` gating (stable per campaign id). */
+function sampleBucket(campaignId) {
+  return stableBucket(campaignId);
+}
+
+/**
+ * Shared frequency-cap predicate for any throttled Engage surface (campaigns AND
+ * in-app messages share the `Throttle` shape + persisted `CampaignThrottleState`).
+ * Pure: no side effects. `id` is used only for the stable `samplePct` bucket.
+ */
+function passesThrottle(id, throttle, state, now, revision, sessionShows = 0) {
+  // Revision invalidation: if the live config carries a newer revision than the one
+  // the persisted state was recorded against, the campaign's content/design changed —
+  // the old impression/showOnce/cooldown counters are stale and must not suppress the
+  // updated message. Treat it as never-shown. (Legacy state with no revision is
+  // unaffected — the check only fires when BOTH sides carry a revision.)
+  if (revision !== undefined && state.revision !== undefined && state.revision !== revision) {
+    return true;
+  }
+  if (!throttle) {
+    // No throttle config: still respect a prior completion so we never loop.
+    return !state.completed;
+  }
+
+  // showOnce: never re-show after a successful submit, or after first impression.
+  if (throttle.showOnce && (state.completed || state.impressions >= 1)) {
+    return false;
+  }
+
+  // maxImpressions: hard cap on how many times we render.
+  if (typeof throttle.maxImpressions === 'number' && state.impressions >= throttle.maxImpressions) {
+    return false;
+  }
+
+  // maxImpressionsPerSession: cap within this app run, under any lifetime cap above.
+  if (typeof throttle.maxImpressionsPerSession === 'number' && throttle.maxImpressionsPerSession > 0 && sessionShows >= throttle.maxImpressionsPerSession) {
+    return false;
+  }
+
+  // cooldownHours: enforce a quiet window since the last impression.
+  if (typeof throttle.cooldownHours === 'number' && state.lastShownAt > 0) {
+    const elapsedMs = now - state.lastShownAt;
+    if (elapsedMs < throttle.cooldownHours * 60 * 60 * 1000) {
+      return false;
+    }
+  }
+
+  // samplePct: include only a stable percentage slice of users/campaigns.
+  if (typeof throttle.samplePct === 'number' && throttle.samplePct < 100) {
+    if (sampleBucket(id) >= Math.max(0, throttle.samplePct)) {
+      return false;
+    }
+  }
+
+  // A completed surface without showOnce is still done — don't re-show.
+  return !state.completed;
+}
+
+/**
+ * Decide whether a single campaign is eligible to show right now, given its
+ * `throttle` rules and the persisted impression state. Pure: no side effects.
+ */
+function isCampaignEligible(campaign, state, now = Date.now(), sessionShows = 0) {
+  if (!campaign.enabled) return false;
+  return passesThrottle(campaign.id, campaign.throttle, state, now, undefined, sessionShows);
+}
+
+/**
+ * Decide whether a single in-app message is eligible to show right now. In-app
+ * messages have no `enabled` flag (the config-serve lane only returns active ones,
+ * §2.4) — eligibility is purely the SHARED throttle/frequency-cap rules. So an
+ * impression-capped message is never re-shown, exactly like a campaign.
+ */
+function isInAppEligible(message, state, now = Date.now(), sessionShows = 0) {
+  return passesThrottle(message.id, message.throttle, state, now, message.revision, sessionShows);
+}
+
+/**
+ * Pick the FIRST eligible campaign from a config payload, optionally filtered by
+ * a campaign type whitelist (e.g. `['NPS']` for the NPS-first slice) and/or a
+ * `targetScreen`. This is the renderer's config→render decision: config drives
+ * which prompt shows, throttle decides whether it shows at all.
+ */
+function selectCampaignToRender(campaigns, store, options = {}) {
+  const now = options.now ?? Date.now();
+  for (const campaign of campaigns) {
+    if (options.types && !options.types.includes(campaign.type)) continue;
+    if (options.trigger && campaign.trigger !== options.trigger) continue;
+    if (options.screen && campaign.targetScreen && campaign.targetScreen !== options.screen) {
+      continue;
+    }
+    // Event/action targeting: a configured target must match the fired value.
+    // Unconfigured campaigns (no triggerConfig.event/action) stay trigger-agnostic.
+    if (options.event && campaign.triggerConfig?.event && campaign.triggerConfig.event !== options.event) {
+      continue;
+    }
+    if (options.action && campaign.triggerConfig?.action && campaign.triggerConfig.action !== options.action) {
+      continue;
+    }
+    if (options.trigger === 'time_in_app' && typeof options.seconds === 'number' && typeof campaign.triggerConfig?.seconds === 'number' && campaign.triggerConfig.seconds !== options.seconds) continue;
+    if (isCampaignEligible(campaign, store.get(campaign.id), now, store.sessionShowCount(campaign.id))) {
+      return campaign;
+    }
+  }
+  return null;
+}
+
+/**
+ * Pick the FIRST eligible in-app message from a config payload (`inAppMessages[]`,
+ * §2.4), optionally filtered by `targetScreen`. Mirrors `selectCampaignToRender`:
+ * config drives which message shows, the SHARED throttle decides whether it shows
+ * at all (an impression-capped message isn't reshown).
+ */
+function selectInAppToRender(messages, store, options = {}) {
+  const now = options.now ?? Date.now();
+  for (const message of messages) {
+    // Behavioral-trigger path: only messages whose `trigger` matches the fired
+    // trigger are eligible. A message with no configured trigger is manual-only
+    // (never auto-fired). When `options.trigger` is omitted (manual call), any
+    // eligible message qualifies — preserving the existing host-driven behavior.
+    if (options.trigger && normalizeInAppTrigger(message.trigger) !== normalizeInAppTrigger(options.trigger)) {
+      continue;
+    }
+    const targetScreen = message.targetScreen ?? message.screenName;
+    if (options.screen && targetScreen && targetScreen !== options.screen) {
+      continue;
+    }
+    if (options.event && message.eventName && message.eventName !== options.event) continue;
+    const actionName = message.action;
+    if (options.action && actionName && actionName !== options.action) continue;
+    if (normalizeInAppTrigger(options.trigger) === 'time_in_app' && message.trigger === 'time_delay' && typeof options.seconds === 'number' && message.delaySeconds !== options.seconds) continue;
+    if (isInAppEligible(message, store.get(message.id), now, store.sessionShowCount(message.id))) {
+      return message;
+    }
+  }
+  return null;
+}
+
+/** Dashboard trigger aliases normalized onto the SDK signal names. */
+function normalizeInAppTrigger(trigger) {
+  switch (trigger) {
+    case 'event':
+    case 'custom':
+      return 'custom_event';
+    case 'time_delay':
+      return 'time_in_app';
+    default:
+      return trigger;
+  }
+}
+
+/** Resolve the one-shot dedupe key for a test preview (testRunId → previewId → id). */
+function testRunIdOf(message) {
+  return message.testRunId ?? message.previewId ?? message.id;
+}
+
+/**
+ * [T1] Pure one-shot test-preview selection — the testable core of the renderer's
+ * "show the latest UNSEEN test, never re-show a dismissed/displayed one" rule.
+ *
+ * From a fetched config's messages it:
+ *   1. keeps only test previews (`preview` / `isTest`),
+ *   2. de-dupes by `testRunId` (the SAME run served twice collapses to one),
+ *   3. drops any already DISPLAYED-or-DISMISSED run (persistent `seen`, survives cold
+ *      restart) or closed-this-session run (`consumed`, in-memory),
+ *   4. returns the LATEST remaining by `createdAt` (so old tests never stack up).
+ *
+ * `seen`/`consumed` are injected predicates (the provider passes its persistent
+ * `EngageTestSeenStore` and its session `Set`), so this stays React-free and unit-
+ * testable. Returns `null` when nothing eligible remains.
+ */
+function selectLatestUnseenTest(messages, deps) {
+  const previews = messages.filter(m => m.preview === true || m.isTest === true);
+  if (previews.length === 0) return null;
+  // De-dupe by testRunId first so a config that (wrongly) serves the same run twice
+  // can never enqueue it twice — keep the first occurrence.
+  const byRun = new Map();
+  for (const m of previews) {
+    const runId = testRunIdOf(m);
+    if (!byRun.has(runId)) byRun.set(runId, m);
+  }
+  const eligible = [...byRun.values()].filter(m => {
+    const runId = testRunIdOf(m);
+    if (deps.seen(runId)) return false;
+    if (deps.consumed(m.previewId ?? m.id)) return false;
+    return true;
+  });
+  if (eligible.length === 0) return null;
+  return eligible.sort((a, b) => new Date(b.createdAt ?? 0).getTime() - new Date(a.createdAt ?? 0).getTime())[0];
+}
+
+/**
+ * Resolve the A/B experiment arm for an in-app message (D8/J6). Minimal,
+ * deterministic, side-effect-free — NOT a general experimentation framework.
+ *
+ * - No experiment, disabled, or no `variantB` ⇒ variant `A` (the base `spec`).
+ * - Otherwise the user/device is bucketed 0–99 by a STABLE hash of
+ *   `messageId + ':' + deviceId`, so the same device always sees the same arm
+ *   for a given message (and the message id salts the hash so a device is not
+ *   pinned to the same arm across every experiment). Buckets `< split` get
+ *   variant B; the rest get variant A. `split<=0`⇒all A, `split>=100`⇒all B.
+ *
+ * Returns both the chosen `variant` id (for event attribution) and the `spec`
+ * to render, so callers never re-derive which arm won.
+ */
+function selectInAppVariant(message, deviceId) {
+  const exp = message.experiment;
+  if (!exp || !exp.enabled || !exp.variantB) {
+    return {
+      variant: 'A',
+      spec: message.spec
+    };
+  }
+  const split = Math.max(0, Math.min(100, exp.split));
+  if (split <= 0) return {
+    variant: 'A',
+    spec: message.spec
+  };
+  if (split >= 100) return {
+    variant: 'B',
+    spec: exp.variantB
+  };
+  const bucket = stableBucket(`${message.id}:${deviceId}`);
+  return bucket < split ? {
+    variant: 'B',
+    spec: exp.variantB
+  } : {
+    variant: 'A',
+    spec: message.spec
+  };
+}
+//# sourceMappingURL=engageThrottle.js.map