@chipmobilesdk/rn-ads 0.7.0 → 0.8.0

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

@@ -0,0 +1,238 @@
+"use strict";
+
+/**
+ * Showing full-screen ads (FR-028, FR-030, FR-034, FR-128) and the foreground
+ * re-evaluation of what was loaded.
+ */
+import { isFullScreenFormat } from "../../config/types.js";
+import { AdsError, normalizeProviderError } from "../../diagnostics/errors.js";
+import { canShow } from "../placementMachine.js";
+import { createRewardedSession } from "../rewardedSession.js";
+import { isStale } from "../timers.js";
+import { validityFor } from "./context.js";
+import { gateRefusal } from "./gate.js";
+import { unknownPlacement } from "./load.js";
+export 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 || !isStale(snapshot.loadedAtMs, at, 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 unknownPlacement(context, placementKey, 'show');
+      }
+      const {
+        runtime,
+        definition
+      } = found;
+      if (!isFullScreenFormat(definition.format)) {
+        return {
+          status: 'failed',
+          error: new AdsError('format_mismatch', {
+            operation: 'show',
+            placementKey,
+            format: definition.format,
+            message: `"${placementKey}" is a banner; banners are rendered, not shown`
+          })
+        };
+      }
+      const refusal = 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 (!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' ? 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 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 = 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/module/core/instance/show.js.map

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

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

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=types.js.map

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

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

package/lib/module/core/placementMachine.js

@@ -0,0 +1,109 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+export const 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.
+ */
+export 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). */
+export function canShow(state) {
+  return state === 'ready';
+}
+export 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/module/core/placementMachine.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["initialPlacement","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;;AAuBA,OAAO,MAAMA,gBAAmC,GAAG;EAClDC,KAAK,EAAE,MAAM;EACbC,UAAU,EAAE,IAAI;EAChBC,KAAK,EAAE,IAAI;EACXC,aAAa,EAAE;AAChB,CAAC;;AAED;AACA;AACA;AACA;AACA;AACA,OAAO,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;AACA,OAAO,SAASK,OAAOA,CAACL,KAAqB,EAAW;EACvD,OAAOA,KAAK,KAAK,OAAO;AACzB;AAEA,OAAO,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,GAAGD,gBAAgB;QAAEC,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,GAAGD,gBAAgB;QAAEC,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,GAAGD,gBAAgB;QAAEC,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,GAAGT,gBAAgB;QAAEC,KAAK,EAAE;MAAO,CAAC,GACtC;QAAE,GAAGD,gBAAgB;QAAEC,KAAK,EAAE;MAAW,CAAC;IAE9C,KAAK,QAAQ;MACZ;MACA;MACA,OAAOA,KAAK,CAACA,KAAK,KAAK,OAAO,GAAG;QAAE,GAAGD,gBAAgB;QAAEC,KAAK,EAAE;MAAO,CAAC,GAAGA,KAAK;IAEhF,KAAK,aAAa;MACjB,OAAO;QAAE,GAAGD,gBAAgB;QAAEC,KAAK,EAAE;MAAc,CAAC;IAErD,KAAK,OAAO;MACX,OAAOD,gBAAgB;IAExB;MACC,OAAOC,KAAK;EACd;AACD","ignoreList":[]}

package/lib/module/core/privacyGate.js

@@ -0,0 +1,86 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+export 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'];
+export 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.
+ */
+export 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.
+ */
+export function toEngineRequest(privacy) {
+  return {
+    personalizedAds: privacy?.personalizedAds !== false
+  };
+}
+//# sourceMappingURL=privacyGate.js.map

package/lib/module/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;;AAQA,OAAO,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;AAEtD,OAAO,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;AACA,OAAO,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;AACA,OAAO,SAASK,eAAeA,CAACjB,OAA8B,EAAwB;EACrF,OAAO;IAAEgB,eAAe,EAAEhB,OAAO,EAAEgB,eAAe,KAAK;EAAM,CAAC;AAC/D","ignoreList":[]}

package/lib/module/core/requestThrottle.js

@@ -0,0 +1,146 @@
+"use strict";
+
+/**
+ * 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.
+ */
+export const 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.
+ */
+export const DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS = 0;
+export const MIN_REQUEST_INTERVAL_BOUNDS = {
+  min: 0,
+  max: 600_000
+};
+
+/** The format-aware default, applied when a placement configures nothing. */
+export function defaultMinRequestIntervalMs(format) {
+  return format === 'banner' ? DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS : DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS;
+}
+export 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/module/core/requestThrottle.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS","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":[]}