@chipmobilesdk/rn-ads 0.7.0 → 0.8.0

package/lib/commonjs/core/instance/show.js

@@ -0,0 +1,243 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createShower = createShower;
+var _types = require("../../config/types.js");
+var _errors = require("../../diagnostics/errors.js");
+var _placementMachine = require("../placementMachine.js");
+var _rewardedSession = require("../rewardedSession.js");
+var _timers = require("../timers.js");
+var _context = require("./context.js");
+var _gate = require("./gate.js");
+var _load = require("./load.js");
+/**
+ * Showing full-screen ads (FR-028, FR-030, FR-034, FR-128) and the foreground
+ * re-evaluation of what was loaded.
+ */
+
+function createShower(context) {
+  const {
+    state,
+    engine,
+    events,
+    timers,
+    resolved,
+    lock,
+    adReturn,
+    now
+  } = context;
+
+  /** Releases and expires a `ready` ad that outlived its validity (FR-034). */
+  function expireIfStale(key, at) {
+    const found = context.placement(key);
+    if (!found) {
+      return false;
+    }
+    const {
+      snapshot
+    } = found.runtime;
+    if (snapshot.state !== 'ready' || snapshot.loadedAtMs === null || !(0, _timers.isStale)(snapshot.loadedAtMs, at, (0, _context.validityFor)(context, found.definition.format))) {
+      return false;
+    }
+    context.releasePlacementResources(key);
+    context.dispatchPlacement(key, {
+      type: 'EXPIRE'
+    });
+    return true;
+  }
+  return {
+    async show(placementKey) {
+      if (state.disposed) {
+        return {
+          status: 'unavailable',
+          reason: 'provider_missing'
+        };
+      }
+      const found = context.placement(placementKey);
+      if (!found) {
+        return (0, _load.unknownPlacement)(context, placementKey, 'show');
+      }
+      const {
+        runtime,
+        definition
+      } = found;
+      if (!(0, _types.isFullScreenFormat)(definition.format)) {
+        return {
+          status: 'failed',
+          error: new _errors.AdsError('format_mismatch', {
+            operation: 'show',
+            placementKey,
+            format: definition.format,
+            message: `"${placementKey}" is a banner; banners are rendered, not shown`
+          })
+        };
+      }
+      const refusal = (0, _gate.gateRefusal)(context);
+      if (refusal) {
+        context.emitRefusal('show', refusal, placementKey, definition.format);
+        return refusal;
+      }
+      // FR-028: never open an ad while the app is not in front of the user.
+      if (!state.appActive) {
+        return {
+          status: 'app_inactive'
+        };
+      }
+      // FR-128. Only app-open is refused: it is the format that would fire on
+      // the return from an ad. An interstitial at the same moment is the app's
+      // own choice, and refusing it would be policy rather than capability.
+      if (definition.format === 'app_open' && adReturn.isRefusing(now())) {
+        return {
+          status: 'ad_originated_return'
+        };
+      }
+      if (runtime.snapshot.state === 'consumed') {
+        return {
+          status: 'consumed'
+        };
+      }
+      // FR-034: a stale ad is not shown and is not reported ready.
+      if (expireIfStale(placementKey, now())) {
+        return {
+          status: 'not_ready'
+        };
+      }
+      const handle = runtime.handle;
+      if (!(0, _placementMachine.canShow)(runtime.snapshot.state) || !handle) {
+        return {
+          status: 'not_ready'
+        };
+      }
+      // FR-030. Never queued: a refused show is refused now, not deferred to a
+      // moment the app never chose.
+      if (!lock.acquire(placementKey)) {
+        return {
+          status: 'busy'
+        };
+      }
+      const correlationId = runtime.correlationId ?? context.correlation.next();
+      runtime.rewarded = definition.format === 'rewarded' ? (0, _rewardedSession.createRewardedSession)() : null;
+      context.dispatchPlacement(placementKey, {
+        type: 'SHOW'
+      });
+      const failShow = error => {
+        lock.release(placementKey);
+        events.emit({
+          type: 'display_failed',
+          timestamp: now(),
+          placementKey,
+          format: definition.format,
+          correlationId,
+          error
+        });
+        context.dispatchPlacement(placementKey, {
+          type: 'SHOW_FAILED',
+          error
+        });
+        context.releasePlacementResources(placementKey);
+      };
+
+      // ADS-09. Whichever of the provider's answer and the timeout comes first
+      // decides the result; the other must not act on it a second time.
+      let settled = false;
+      const showTimeout = new Promise(resolve => {
+        runtime.cancelShowTimer = timers.after(resolved.timeouts.show, () => {
+          runtime.cancelShowTimer = null;
+          if (settled) {
+            return;
+          }
+          settled = true;
+          // The provider may still open the ad. Its handle and listener stay, so
+          // a late open, reward or dismissal is still heard and the reward is not
+          // lost (FR-049); they go with the next load or with dispose. The lock is
+          // released now and taken back if the ad does open.
+          lock.release(placementKey);
+          const error = new _errors.AdsError('show_timeout', {
+            operation: 'show',
+            placementKey,
+            format: definition.format,
+            message: `show timed out after ${resolved.timeouts.show}ms`
+          });
+          events.emit({
+            type: 'display_failed',
+            timestamp: now(),
+            placementKey,
+            format: definition.format,
+            correlationId,
+            error
+          });
+          context.dispatchPlacement(placementKey, {
+            type: 'SHOW_FAILED',
+            error
+          });
+          resolve({
+            status: 'timeout'
+          });
+        });
+      });
+      const attempt = engine.show(handle).then(() => {
+        if (settled) {
+          // Opened after the timeout was reported. It is on screen now, so it
+          // holds the one full-screen lock until it is dismissed (FR-030).
+          lock.acquire(placementKey);
+          return {
+            status: 'timeout'
+          };
+        }
+        settled = true;
+        runtime.cancelShowTimer?.();
+        runtime.cancelShowTimer = null;
+        return {
+          status: 'shown',
+          correlationId
+        };
+      }).catch(error => {
+        if (settled) {
+          // Failed after the timeout already said so: nothing new to report,
+          // and nothing will show, so its resources can go.
+          context.releasePlacementResources(placementKey);
+          return {
+            status: 'timeout'
+          };
+        }
+        settled = true;
+        runtime.cancelShowTimer?.();
+        runtime.cancelShowTimer = null;
+        const normalized = (0, _errors.normalizeProviderError)(error, {
+          operation: 'show',
+          placementKey,
+          format: definition.format
+        });
+        failShow(normalized);
+        return {
+          status: 'failed',
+          error: normalized
+        };
+      });
+      return Promise.race([attempt, showTimeout]);
+    },
+    setAppActive(active) {
+      if (state.disposed) {
+        return;
+      }
+      state.appActive = active;
+      if (!active) {
+        // Arming happens when the provider reports an ad opened; this event can
+        // arrive after the ad is gone. All it adds is the browser case, a
+        // background closely following a click (FR-128).
+        adReturn.noteBackground(now());
+        return;
+      }
+      adReturn.noteForeground(now());
+      // FR-034: an ad that went stale while the app was away stops reporting
+      // `ready` before the app offers a button that would fail on tap.
+      const current = now();
+      for (const key of context.placements.keys()) {
+        expireIfStale(key, current);
+      }
+    }
+  };
+}
+//# sourceMappingURL=show.js.map

package/lib/commonjs/core/instance/show.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_types","require","_errors","_placementMachine","_rewardedSession","_timers","_context","_gate","_load","createShower","context","state","engine","events","timers","resolved","lock","adReturn","now","expireIfStale","key","at","found","placement","snapshot","runtime","loadedAtMs","isStale","validityFor","definition","format","releasePlacementResources","dispatchPlacement","type","show","placementKey","disposed","status","reason","unknownPlacement","isFullScreenFormat","error","AdsError","operation","message","refusal","gateRefusal","emitRefusal","appActive","isRefusing","handle","canShow","acquire","correlationId","correlation","next","rewarded","createRewardedSession","failShow","release","emit","timestamp","settled","showTimeout","Promise","resolve","cancelShowTimer","after","timeouts","attempt","then","catch","normalized","normalizeProviderError","race","setAppActive","active","noteBackground","noteForeground","current","placements","keys"],"sourceRoot":"../../../../src","sources":["core/instance/show.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/core/instance/types.js

@@ -0,0 +1,6 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+//# sourceMappingURL=types.js.map

package/lib/commonjs/core/instance/types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../../src","sources":["core/instance/types.ts"],"mappings":"","ignoreList":[]}

package/lib/commonjs/core/placementMachine.js

@@ -0,0 +1,116 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.canLoad = canLoad;
+exports.canShow = canShow;
+exports.initialPlacement = void 0;
+exports.placementReducer = placementReducer;
+/**
+ * Per-placement lifecycle (FR-026 – FR-031, FR-034).
+ *
+ * Pure and synchronous, per data-model.md §3.2. Two variants share one reducer:
+ *
+ *   full-screen — load, show once, become `consumed`, reload before the next show
+ *   banner      — continuous; it renders and may refresh, and never reaches
+ *                 `consumed`, because a banner is not a single-use resource
+ *
+ * Staleness is handled here rather than at the show site so that a stale ad can
+ * never be *reported* ready either — a consumer that renders a "Watch ad" button
+ * from `state === 'ready'` would otherwise offer a button that fails on tap.
+ */
+
+const initialPlacement = exports.initialPlacement = {
+  state: 'idle',
+  loadedAtMs: null,
+  error: null,
+  correlationId: null
+};
+
+/**
+ * A load is only legal from a settled state; `loading` is where FR-029 bites.
+ * `throttled` is settled too: it records that the last request was refused, and
+ * the throttle itself decides whether the next one may proceed.
+ */
+function canLoad(state) {
+  return state === 'idle' || state === 'failed' || state === 'consumed' || state === 'ready' || state === 'throttled';
+}
+
+/** Only a ready ad may be shown. Everything else is a determinate refusal (FR-028). */
+function canShow(state) {
+  return state === 'ready';
+}
+function placementReducer(state, event, format) {
+  switch (event.type) {
+    case 'LOAD':
+      // FR-029: a load while already loading is absorbed. The instance
+      // returns the in-flight promise; the state does not restart.
+      if (state.state === 'loading' || state.state === 'showing') {
+        return state;
+      }
+      if (state.state === 'unavailable') {
+        return state;
+      }
+      return {
+        ...initialPlacement,
+        state: 'loading'
+      };
+    case 'LOADED':
+      return state.state === 'loading' ? {
+        ...state,
+        state: 'ready',
+        loadedAtMs: event.atMs,
+        error: null
+      } : state;
+    case 'LOAD_FAILED':
+      return state.state === 'loading' ? {
+        ...initialPlacement,
+        state: 'failed',
+        error: event.error
+      } : state;
+    case 'SHOW':
+      return state.state === 'ready' ? {
+        ...state,
+        state: 'showing'
+      } : state;
+    case 'SHOW_FAILED':
+      // A failed presentation consumes the ad regardless: the provider has
+      // taken it, and re-showing the same object is what FR-031 forbids.
+      return state.state === 'showing' ? {
+        ...initialPlacement,
+        state: 'failed',
+        error: event.error
+      } : state;
+    case 'DISMISSED':
+      if (state.state !== 'showing') {
+        return state;
+      }
+      // A banner is continuous — dismissal is not part of its life. A
+      // full-screen ad is spent, and must be reloaded before the next show.
+      return format === 'banner' ? {
+        ...initialPlacement,
+        state: 'idle'
+      } : {
+        ...initialPlacement,
+        state: 'consumed'
+      };
+    case 'EXPIRE':
+      // FR-034. Only a ready-and-waiting ad can go stale; one being shown is
+      // already in the user's hands.
+      return state.state === 'ready' ? {
+        ...initialPlacement,
+        state: 'idle'
+      } : state;
+    case 'UNAVAILABLE':
+      return {
+        ...initialPlacement,
+        state: 'unavailable'
+      };
+    case 'RESET':
+      return initialPlacement;
+    default:
+      return state;
+  }
+}
+//# sourceMappingURL=placementMachine.js.map

package/lib/commonjs/core/placementMachine.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["initialPlacement","exports","state","loadedAtMs","error","correlationId","canLoad","canShow","placementReducer","event","format","type","atMs"],"sourceRoot":"../../../src","sources":["core/placementMachine.ts"],"mappings":";;;;;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAuBO,MAAMA,gBAAmC,GAAAC,OAAA,CAAAD,gBAAA,GAAG;EAClDE,KAAK,EAAE,MAAM;EACbC,UAAU,EAAE,IAAI;EAChBC,KAAK,EAAE,IAAI;EACXC,aAAa,EAAE;AAChB,CAAC;;AAED;AACA;AACA;AACA;AACA;AACO,SAASC,OAAOA,CAACJ,KAAqB,EAAW;EACvD,OACCA,KAAK,KAAK,MAAM,IAChBA,KAAK,KAAK,QAAQ,IAClBA,KAAK,KAAK,UAAU,IACpBA,KAAK,KAAK,OAAO,IACjBA,KAAK,KAAK,WAAW;AAEvB;;AAEA;AACO,SAASK,OAAOA,CAACL,KAAqB,EAAW;EACvD,OAAOA,KAAK,KAAK,OAAO;AACzB;AAEO,SAASM,gBAAgBA,CAC/BN,KAAwB,EACxBO,KAAqB,EACrBC,MAAgB,EACI;EACpB,QAAQD,KAAK,CAACE,IAAI;IACjB,KAAK,MAAM;MACV;MACA;MACA,IAAIT,KAAK,CAACA,KAAK,KAAK,SAAS,IAAIA,KAAK,CAACA,KAAK,KAAK,SAAS,EAAE;QAC3D,OAAOA,KAAK;MACb;MACA,IAAIA,KAAK,CAACA,KAAK,KAAK,aAAa,EAAE;QAClC,OAAOA,KAAK;MACb;MACA,OAAO;QAAE,GAAGF,gBAAgB;QAAEE,KAAK,EAAE;MAAU,CAAC;IAEjD,KAAK,QAAQ;MACZ,OAAOA,KAAK,CAACA,KAAK,KAAK,SAAS,GAC7B;QAAE,GAAGA,KAAK;QAAEA,KAAK,EAAE,OAAO;QAAEC,UAAU,EAAEM,KAAK,CAACG,IAAI;QAAER,KAAK,EAAE;MAAK,CAAC,GACjEF,KAAK;IAET,KAAK,aAAa;MACjB,OAAOA,KAAK,CAACA,KAAK,KAAK,SAAS,GAC7B;QAAE,GAAGF,gBAAgB;QAAEE,KAAK,EAAE,QAAQ;QAAEE,KAAK,EAAEK,KAAK,CAACL;MAAM,CAAC,GAC5DF,KAAK;IAET,KAAK,MAAM;MACV,OAAOA,KAAK,CAACA,KAAK,KAAK,OAAO,GAAG;QAAE,GAAGA,KAAK;QAAEA,KAAK,EAAE;MAAU,CAAC,GAAGA,KAAK;IAExE,KAAK,aAAa;MACjB;MACA;MACA,OAAOA,KAAK,CAACA,KAAK,KAAK,SAAS,GAC7B;QAAE,GAAGF,gBAAgB;QAAEE,KAAK,EAAE,QAAQ;QAAEE,KAAK,EAAEK,KAAK,CAACL;MAAM,CAAC,GAC5DF,KAAK;IAET,KAAK,WAAW;MACf,IAAIA,KAAK,CAACA,KAAK,KAAK,SAAS,EAAE;QAC9B,OAAOA,KAAK;MACb;MACA;MACA;MACA,OAAOQ,MAAM,KAAK,QAAQ,GACvB;QAAE,GAAGV,gBAAgB;QAAEE,KAAK,EAAE;MAAO,CAAC,GACtC;QAAE,GAAGF,gBAAgB;QAAEE,KAAK,EAAE;MAAW,CAAC;IAE9C,KAAK,QAAQ;MACZ;MACA;MACA,OAAOA,KAAK,CAACA,KAAK,KAAK,OAAO,GAAG;QAAE,GAAGF,gBAAgB;QAAEE,KAAK,EAAE;MAAO,CAAC,GAAGA,KAAK;IAEhF,KAAK,aAAa;MACjB,OAAO;QAAE,GAAGF,gBAAgB;QAAEE,KAAK,EAAE;MAAc,CAAC;IAErD,KAAK,OAAO;MACX,OAAOF,gBAAgB;IAExB;MACC,OAAOE,KAAK;EACd;AACD","ignoreList":[]}

package/lib/commonjs/core/privacyGate.js

@@ -0,0 +1,93 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.evaluateGate = evaluateGate;
+exports.requiresReinitialization = requiresReinitialization;
+exports.toEnginePrivacy = toEnginePrivacy;
+exports.toEngineRequest = toEngineRequest;
+/**
+ * The privacy gate (FR-016 – FR-021).
+ *
+ * The package enforces ordering; the app owns policy. It renders no consent UI,
+ * writes no legal copy, and decides nothing about a jurisdiction — it accepts a
+ * gate outcome and refuses to let any request precede it.
+ *
+ * That refusal is the whole value. Consent ordering is easy to get wrong by
+ * accident, and the failure is invisible: an ad request that should not have
+ * happened looks exactly like one that should. A package that enforces the order
+ * is worth more than documentation that describes it.
+ *
+ * Pure — no provider, no React, no I/O. The engine adapter translates the
+ * outcome into provider configuration.
+ */
+
+function evaluateGate(privacy) {
+  if (!privacy) {
+    return {
+      allowed: false,
+      reason: 'consent_required'
+    };
+  }
+  if (privacy.canRequestAds) {
+    return {
+      allowed: true
+    };
+  }
+  // Distinguishing "not asked yet" from "asked and refused" matters: the first
+  // is a prompt the app still owes the user, the second is a settled answer.
+  // Collapsing them would leave the app unable to tell which (FR-018).
+  return {
+    allowed: false,
+    reason: privacy.consentUndetermined ? 'consent_undetermined' : 'consent_required'
+  };
+}
+
+/**
+ * Flags the provider only honors at initialization time.
+ *
+ * Changing one of these after `initialize()` cannot take effect, which is why
+ * `updatePrivacy` reports `requires_reinitialization` instead of accepting the
+ * change and leaving the package in a state that is half old and half new
+ * (FR-020).
+ *
+ * `canRequestAds` is absent on purpose: resolving the gate after being blocked
+ * is the normal, supported flow, not a reinitialization (FR-019).
+ */
+const INIT_TIME_ONLY = ['childDirected', 'underAgeOfConsent', 'maxAdContentRating'];
+function requiresReinitialization(applied, next) {
+  if (!applied) {
+    return false;
+  }
+  return INIT_TIME_ONLY.some(field => applied[field] !== next[field]);
+}
+
+/**
+ * Projects consumer privacy options onto what the engine needs.
+ *
+ * `personalizedAds` is carried through rather than inverted here; the adapter
+ * owns the translation to the provider's `requestNonPersonalizedAdsOnly`, so
+ * the polarity flip lives next to the API that requires it.
+ */
+function toEnginePrivacy(privacy, testDeviceIds) {
+  return {
+    childDirected: privacy.childDirected,
+    underAgeOfConsent: privacy.underAgeOfConsent,
+    maxAdContentRating: privacy.maxAdContentRating,
+    personalizedAds: privacy.personalizedAds,
+    testDeviceIds
+  };
+}
+
+/**
+ * What every ad request carries. Unset means personalized, matching the
+ * documented default of `PrivacyOptions.personalizedAds`; only an explicit
+ * `false` opts out.
+ */
+function toEngineRequest(privacy) {
+  return {
+    personalizedAds: privacy?.personalizedAds !== false
+  };
+}
+//# sourceMappingURL=privacyGate.js.map

package/lib/commonjs/core/privacyGate.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["evaluateGate","privacy","allowed","reason","canRequestAds","consentUndetermined","INIT_TIME_ONLY","requiresReinitialization","applied","next","some","field","toEnginePrivacy","testDeviceIds","childDirected","underAgeOfConsent","maxAdContentRating","personalizedAds","toEngineRequest"],"sourceRoot":"../../../src","sources":["core/privacyGate.ts"],"mappings":";;;;;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAQO,SAASA,YAAYA,CAACC,OAA8B,EAAgB;EAC1E,IAAI,CAACA,OAAO,EAAE;IACb,OAAO;MAAEC,OAAO,EAAE,KAAK;MAAEC,MAAM,EAAE;IAAmB,CAAC;EACtD;EACA,IAAIF,OAAO,CAACG,aAAa,EAAE;IAC1B,OAAO;MAAEF,OAAO,EAAE;IAAK,CAAC;EACzB;EACA;EACA;EACA;EACA,OAAO;IACNA,OAAO,EAAE,KAAK;IACdC,MAAM,EAAEF,OAAO,CAACI,mBAAmB,GAAG,sBAAsB,GAAG;EAChE,CAAC;AACF;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMC,cAAc,GAAG,CACtB,eAAe,EACf,mBAAmB,EACnB,oBAAoB,CACiC;AAE/C,SAASC,wBAAwBA,CACvCC,OAA8B,EAC9BC,IAAoB,EACV;EACV,IAAI,CAACD,OAAO,EAAE;IACb,OAAO,KAAK;EACb;EACA,OAAOF,cAAc,CAACI,IAAI,CAACC,KAAK,IAAIH,OAAO,CAACG,KAAK,CAAC,KAAKF,IAAI,CAACE,KAAK,CAAC,CAAC;AACpE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,eAAeA,CAC9BX,OAAuB,EACvBY,aAAgC,EAChB;EAChB,OAAO;IACNC,aAAa,EAAEb,OAAO,CAACa,aAAa;IACpCC,iBAAiB,EAAEd,OAAO,CAACc,iBAAiB;IAC5CC,kBAAkB,EAAEf,OAAO,CAACe,kBAAkB;IAC9CC,eAAe,EAAEhB,OAAO,CAACgB,eAAe;IACxCJ;EACD,CAAC;AACF;;AAEA;AACA;AACA;AACA;AACA;AACO,SAASK,eAAeA,CAACjB,OAA8B,EAAwB;EACrF,OAAO;IAAEgB,eAAe,EAAEhB,OAAO,EAAEgB,eAAe,KAAK;EAAM,CAAC;AAC/D","ignoreList":[]}

package/lib/commonjs/core/requestThrottle.js

@@ -0,0 +1,152 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.MIN_REQUEST_INTERVAL_BOUNDS = exports.DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS = exports.DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS = void 0;
+exports.createRequestThrottle = createRequestThrottle;
+exports.defaultMinRequestIntervalMs = defaultMinRequestIntervalMs;
+/**
+ * Per-placement request throttle (FR-140).
+ *
+ * This exists to protect the **ad account**, not to shape product behaviour, and
+ * that distinction is the whole reason it lives in the package:
+ *
+ * | Decision | Owner |
+ * |---|---|
+ * | How often to *show* an interstitial | the app — product policy |
+ * | How often the same placement may *request* | the package — account safety |
+ *
+ * Rapid repeat requests for one placement are read by ad networks as invalid
+ * traffic, and the penalty is account-level and not recoverable by shipping a
+ * fix. That puts it in the same class as the test-ad substitution the package
+ * already enforces: a safety property the library guarantees rather than
+ * documents and hopes each app remembers.
+ *
+ * ## The pattern it is built for
+ *
+ * A banner mounted inside a view the user navigates between — a day in a
+ * calendar, a tab, a row in a list — is unmounted and remounted by React on every
+ * navigation. Each remount is a fresh provider request. A user swiping quickly
+ * through ten days produces ten requests in a few seconds, and nothing about that
+ * is the app author doing something wrong.
+ *
+ * Full-screen formats do not have this problem: they are loaded by an explicit
+ * call, not mounted by a renderer. That asymmetry is why the default differs by
+ * format — see `defaultMinRequestIntervalMs`.
+ *
+ * The better *architectural* answer is to keep the banner outside the subtree that
+ * remounts. This throttle is the safety net for when that is not possible, not a
+ * licence to ignore the problem; the README says so where an app author will read
+ * it.
+ */
+
+/**
+ * AdMob's own documented floor for banner auto-refresh is 60 seconds, so
+ * requesting the same banner placement more often than that is, by the provider's
+ * own standard, more often than it considers reasonable. Taking the provider's
+ * number rather than inventing one means the default is defensible rather than
+ * arbitrary.
+ */
+const DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS = exports.DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS = 60_000;
+
+/**
+ * Off by default for full-screen formats.
+ *
+ * `load` → `show` → `load` is the normal, healthy cycle for an interstitial, and
+ * an app that sells three things in two minutes legitimately loads three times.
+ * Throttling that by default would break correct apps to solve a problem those
+ * formats do not have. An app that wants a floor here can set one.
+ */
+const DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS = exports.DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS = 0;
+const MIN_REQUEST_INTERVAL_BOUNDS = exports.MIN_REQUEST_INTERVAL_BOUNDS = {
+  min: 0,
+  max: 600_000
+};
+
+/** The format-aware default, applied when a placement configures nothing. */
+function defaultMinRequestIntervalMs(format) {
+  return format === 'banner' ? DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS : DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS;
+}
+function createRequestThrottle(now) {
+  const lastAt = new Map();
+  /** The token and verdict of the most recent acquisition, for idempotency. */
+  const lastToken = new Map();
+  const decide = (key, minIntervalMs) => {
+    // Zero is the documented way to turn the throttle off, so it must never
+    // consult the clock — an app that sets 0 should behave exactly as it did
+    // before this feature existed.
+    if (minIntervalMs <= 0) {
+      return {
+        allowed: true
+      };
+    }
+    const previous = lastAt.get(key);
+    if (previous === undefined) {
+      return {
+        allowed: true
+      };
+    }
+    const elapsed = now() - previous;
+    // A clock that moved backwards — a manual time change, or an NTP
+    // correction — must not lock a placement out until the clock catches up.
+    // Treating it as "enough time passed" fails open, which is right: the
+    // throttle protects against bursts, and a backwards clock is not a burst.
+    if (elapsed < 0) {
+      return {
+        allowed: true
+      };
+    }
+    if (elapsed >= minIntervalMs) {
+      return {
+        allowed: true
+      };
+    }
+    return {
+      allowed: false,
+      retryAfterMs: minIntervalMs - elapsed
+    };
+  };
+  return {
+    waitFor(key, minIntervalMs) {
+      const decision = decide(key, minIntervalMs);
+      return decision.allowed ? 0 : decision.retryAfterMs;
+    },
+    tryAcquire(key, minIntervalMs, token) {
+      if (token !== undefined) {
+        const previous = lastToken.get(key);
+        if (previous?.token === token) {
+          // Same cycle asking again. Replaying the stored verdict keeps a
+          // double-invoked render from charging twice, and keeps a refused
+          // cycle refused rather than letting a retry slip through.
+          return previous.decision;
+        }
+      }
+
+      // Nothing is recorded when the throttle is off for this placement.
+      // Recording would be dead work, and it would also mean that turning the
+      // throttle on later immediately compared against a stale timestamp.
+      if (minIntervalMs <= 0) {
+        return {
+          allowed: true
+        };
+      }
+      const decision = decide(key, minIntervalMs);
+      if (decision.allowed) {
+        lastAt.set(key, now());
+      }
+      if (token !== undefined) {
+        lastToken.set(key, {
+          token,
+          decision
+        });
+      }
+      return decision;
+    },
+    clear() {
+      lastAt.clear();
+      lastToken.clear();
+    }
+  };
+}
+//# sourceMappingURL=requestThrottle.js.map

package/lib/commonjs/core/requestThrottle.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS","exports","DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS","MIN_REQUEST_INTERVAL_BOUNDS","min","max","defaultMinRequestIntervalMs","format","createRequestThrottle","now","lastAt","Map","lastToken","decide","key","minIntervalMs","allowed","previous","get","undefined","elapsed","retryAfterMs","waitFor","decision","tryAcquire","token","set","clear"],"sourceRoot":"../../../src","sources":["core/requestThrottle.ts"],"mappings":"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","ignoreList":[]}