@chipmobilesdk/rn-ads 0.6.0 → 0.8.0

package/lib/commonjs/core/adOriginatedReturn.js

@@ -0,0 +1,119 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createAdOriginatedTracker = createAdOriginatedTracker;
+var _timers = require("./timers.js");
+/**
+ * Ad-originated return detection (FR-128).
+ *
+ * This is the reason app-open belongs in the package rather than in the app.
+ * Every other app-open rule — when to show one, how often, on which screens — is
+ * policy the app owns. This one is not policy; it is a fact only the package
+ * holds. When a user dismisses a full-screen ad, or comes back from a browser an
+ * ad opened, the app sees an ordinary return to the foreground and has no way to
+ * tell it apart from any other. Showing an app-open ad on that return means
+ * showing an ad immediately after an ad, which is both a poor experience and the
+ * kind of thing store review notices.
+ *
+ * The package knows, because it holds the full-screen lock and it sees the click
+ * events. So it refuses, with a reason distinct from `busy` and `not_ready` so
+ * the app can tell what happened.
+ *
+ * **Bounded on both sides, deliberately.** Arming has to be tied to something
+ * that actually happened, and it has to expire:
+ *
+ *   - Armed when the provider reports a full-screen ad opened, or on a click —
+ *     that second case is a browser the ad opened, which is the only signal the
+ *     provider gives for it. Arming is deliberately not tied to the app
+ *     reporting that it went to the background; see `noteFullScreenShown`.
+ *   - Disarmed without firing if the app was away longer than
+ *     `AD_RETURN_MAX_AWAY_MS`. Someone who left, did something else, and came
+ *     back an hour later is not returning from an ad, and treating them as if
+ *     they were would refuse a legitimate show.
+ *   - Refusals last `AD_RETURN_GRACE_MS` after the return, then stop. The window
+ *     only needs to cover the moment right after the return, where an app-open
+ *     show would otherwise fire. A window that outlived that moment would start
+ *     refusing shows that have nothing to do with the ad.
+ *
+ * Three limits are worth stating plainly, because they are limits rather than
+ * defects and the documentation must not imply otherwise:
+ *
+ *   1. It cannot survive process death. If the OS kills the app while an ad is
+ *      on screen, the return is a cold start and nothing links it to the ad.
+ *   2. It depends on the app reporting `setAppActive` faithfully — an obligation
+ *      0.1.0 already imposes for staleness re-evaluation, not a new one.
+ *   3. A browser opened by an ad without a preceding click event is undetectable.
+ *
+ * Pure state. No listener, no timer — it is driven entirely by transitions the
+ * package already observes, which is why `dispose()` has nothing extra to
+ * release for it.
+ */
+
+function createAdOriginatedTracker() {
+  let lastClickAtMs = null;
+  let armedAtMs = null;
+  let refusalUntilMs = null;
+  return {
+    /**
+     * Arming happens here — when the provider says an ad is on screen — and
+     * deliberately **not** when the app reports going to the background.
+     *
+     * That was the first design and it does not survive a real device. React
+     * Native delivers app-state changes over the bridge, and while the app is
+     * backgrounded its JS thread is throttled, so the `background` event is
+     * routinely processed only once the app is already returning. By then the
+     * ad has been dismissed and the full-screen lock released, so sampling the
+     * lock at that moment reports "no ad was showing" and the return is let
+     * through — the exact case FR-128 exists to catch. Arming on a fact the
+     * provider reports, rather than on the timeliness of an event, removes the
+     * race entirely.
+     */
+    noteFullScreenShown(nowMs) {
+      armedAtMs = nowMs;
+    },
+    noteClick(nowMs) {
+      lastClickAtMs = nowMs;
+      // A click is itself grounds to arm: the ad may be opening a browser,
+      // and if it is, no `opened` callback will follow.
+      armedAtMs = nowMs;
+    },
+    noteBackground(nowMs) {
+      // Only meaningful for the browser case, and only as a refinement: a
+      // background that closely follows a click is that browser opening.
+      if (lastClickAtMs !== null && nowMs - lastClickAtMs <= _timers.AD_CLICK_WINDOW_MS) {
+        armedAtMs = nowMs;
+      }
+    },
+    noteForeground(nowMs) {
+      if (armedAtMs === null) {
+        return;
+      }
+      const away = nowMs - armedAtMs;
+      armedAtMs = null;
+      lastClickAtMs = null;
+      if (away > _timers.AD_RETURN_MAX_AWAY_MS) {
+        // Too long to still be attributable to the ad. Not a refusal.
+        return;
+      }
+      refusalUntilMs = nowMs + _timers.AD_RETURN_GRACE_MS;
+    },
+    isRefusing(nowMs) {
+      if (refusalUntilMs === null) {
+        return false;
+      }
+      if (nowMs >= refusalUntilMs) {
+        refusalUntilMs = null;
+        return false;
+      }
+      return true;
+    },
+    reset() {
+      lastClickAtMs = null;
+      armedAtMs = null;
+      refusalUntilMs = null;
+    }
+  };
+}
+//# sourceMappingURL=adOriginatedReturn.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["_timers","require","createAdOriginatedTracker","lastClickAtMs","armedAtMs","refusalUntilMs","noteFullScreenShown","nowMs","noteClick","noteBackground","AD_CLICK_WINDOW_MS","noteForeground","away","AD_RETURN_MAX_AWAY_MS","AD_RETURN_GRACE_MS","isRefusing","reset"],"sourceRoot":"../../../src","sources":["core/adOriginatedReturn.ts"],"mappings":";;;;;;AA8CA,IAAAA,OAAA,GAAAC,OAAA;AA9CA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAmBO,SAASC,yBAAyBA,CAAA,EAAwB;EAChE,IAAIC,aAA4B,GAAG,IAAI;EACvC,IAAIC,SAAwB,GAAG,IAAI;EACnC,IAAIC,cAA6B,GAAG,IAAI;EAExC,OAAO;IACN;AACF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;IACEC,mBAAmBA,CAACC,KAAK,EAAE;MAC1BH,SAAS,GAAGG,KAAK;IAClB,CAAC;IAEDC,SAASA,CAACD,KAAK,EAAE;MAChBJ,aAAa,GAAGI,KAAK;MACrB;MACA;MACAH,SAAS,GAAGG,KAAK;IAClB,CAAC;IAEDE,cAAcA,CAACF,KAAK,EAAE;MACrB;MACA;MACA,IAAIJ,aAAa,KAAK,IAAI,IAAII,KAAK,GAAGJ,aAAa,IAAIO,0BAAkB,EAAE;QAC1EN,SAAS,GAAGG,KAAK;MAClB;IACD,CAAC;IAEDI,cAAcA,CAACJ,KAAK,EAAE;MACrB,IAAIH,SAAS,KAAK,IAAI,EAAE;QACvB;MACD;MACA,MAAMQ,IAAI,GAAGL,KAAK,GAAGH,SAAS;MAC9BA,SAAS,GAAG,IAAI;MAChBD,aAAa,GAAG,IAAI;MACpB,IAAIS,IAAI,GAAGC,6BAAqB,EAAE;QACjC;QACA;MACD;MACAR,cAAc,GAAGE,KAAK,GAAGO,0BAAkB;IAC5C,CAAC;IAEDC,UAAUA,CAACR,KAAK,EAAE;MACjB,IAAIF,cAAc,KAAK,IAAI,EAAE;QAC5B,OAAO,KAAK;MACb;MACA,IAAIE,KAAK,IAAIF,cAAc,EAAE;QAC5BA,cAAc,GAAG,IAAI;QACrB,OAAO,KAAK;MACb;MACA,OAAO,IAAI;IACZ,CAAC;IAEDW,KAAKA,CAAA,EAAG;MACPb,aAAa,GAAG,IAAI;MACpBC,SAAS,GAAG,IAAI;MAChBC,cAAc,GAAG,IAAI;IACtB;EACD,CAAC;AACF","ignoreList":[]}

package/lib/commonjs/core/adsInstance.js

@@ -0,0 +1,129 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createAds = createAds;
+Object.defineProperty(exports, "getInternals", {
+  enumerable: true,
+  get: function () {
+    return _internals.getInternals;
+  }
+});
+var _consent = require("./instance/consent.js");
+var _context = require("./instance/context.js");
+var _gate = require("./instance/gate.js");
+var _init = require("./instance/init.js");
+var _internals = require("./instance/internals.js");
+var _load = require("./instance/load.js");
+var _show = require("./instance/show.js");
+/**
+ * The ads instance — the public contract's implementation.
+ *
+ * Every guarantee the specification treats as a rule rather than a convention
+ * converges here, and none of it needs a device to prove:
+ *
+ *   FR-022  one native initialization, however many callers race
+ *   FR-017  no request before the privacy gate permits one
+ *   FR-011  no production ad unit outside production
+ *   FR-029  one in-flight provider request per placement
+ *   FR-030  exactly one full-screen ad, never a queue
+ *   FR-031  a consumed ad is never reused
+ *   FR-035  after dispose, a late callback updates nothing and emits nothing
+ *
+ * This file only composes. Each responsibility lives in `core/instance/` and
+ * takes the shared context (ADS-10): the gate, initialization and enablement,
+ * full-screen load, show, consent, and the banner host's internals.
+ *
+ * Nothing here imports the provider. It talks to the engine port, which the
+ * caller injects — the AdMob adapter in production, the fake in tests.
+ */
+
+/**
+ * The instance itself. The public `createAds` (src/index.ts) passes the AdMob
+ * adapter as `defaultEngine`: core/ never loads an adapter, so it stays testable
+ * in Node and the provider stays replaceable (ADS-14).
+ */
+function createAds(config, options = {}, defaultEngine = noDefaultEngine) {
+  // Throws on a structural fault or the FR-012 fail-closed case, before
+  // anything else exists.
+  const context = (0, _context.createInstanceContext)(config, options, defaultEngine);
+  const {
+    state,
+    engine,
+    resolved,
+    events
+  } = context;
+  const init = (0, _init.createInitController)(context);
+  const loader = (0, _load.createLoader)(context);
+  const shower = (0, _show.createShower)(context);
+  const instance = {
+    initialize: privacy => init.initialize(privacy),
+    updatePrivacy: privacy => init.updatePrivacy(privacy),
+    setEnabled: enabled => init.setEnablement(enabled ? 'enabled' : 'disabled'),
+    setEnablement: next => init.setEnablement(next),
+    setAppActive: active => shower.setAppActive(active),
+    consent: (0, _consent.createConsentApi)(context, () => init.reevaluateAfterConsent()),
+    getStatus: () => state.init.status,
+    subscribeStatus: listener => context.statusListeners.add(listener),
+    load: placementKey => loader.load(placementKey),
+    show: placementKey => shower.show(placementKey),
+    getPlacementState(placementKey) {
+      if (!resolved.placements.has(placementKey)) {
+        return 'unavailable';
+      }
+      if (!engine.isAvailable() || state.enablement === 'disabled') {
+        return 'unavailable';
+      }
+      // Reported distinctly from `unavailable` so the app can choose to hold
+      // the banner's space rather than reclaim it (FR-116).
+      if (state.enablement === 'undecided') {
+        return 'undecided';
+      }
+      return context.placements.get(placementKey)?.snapshot.state ?? 'idle';
+    },
+    subscribePlacement(key, listener) {
+      return context.placements.get(key)?.listeners.add(listener) ?? (() => undefined);
+    },
+    subscribeEvents: listener => events.subscribe(listener),
+    /** FR-011a — substitution is observable state, not only a log line. */
+    getSubstitutedPlacements: () => resolved.catalog.substitutedKeys,
+    /** FR-113 — the same treatment for consent tools dropped in production. */
+    getIgnoredConsentTools: () => resolved.ignoredConsentTools,
+    dispose() {
+      // FR-005: idempotent. A second call is a no-op, not an error.
+      if (state.disposed) {
+        return;
+      }
+      state.disposed = true;
+      (0, _gate.cancelAllRetries)(context);
+      (0, _gate.disarmUndecidedWarning)(context);
+      for (const [key, runtime] of context.placements) {
+        const abort = runtime.abortLoad;
+        context.releasePlacementResources(key);
+        runtime.listeners.clear();
+        // Settled rather than left hanging, with the answer a `load` after
+        // dispose gets (FR-159). No refusal event: nothing is emitted after
+        // dispose (FR-035).
+        abort?.({
+          status: 'unavailable',
+          reason: 'provider_missing'
+        });
+      }
+      context.timers.clearAll();
+      context.requestThrottle.clear();
+      context.lock.reset();
+      context.adReturn.reset();
+      context.statusListeners.clear();
+      context.consentListeners.clear();
+      events.dispose();
+      state.inFlightInit = null;
+    }
+  };
+  (0, _internals.attachInternals)(instance, (0, _internals.createInternals)(context));
+  return instance;
+}
+function noDefaultEngine() {
+  throw new Error('core/createAds was called without an engine; production code uses createAds from the package entrypoint.');
+}
+//# sourceMappingURL=adsInstance.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["_consent","require","_context","_gate","_init","_internals","_load","_show","createAds","config","options","defaultEngine","noDefaultEngine","context","createInstanceContext","state","engine","resolved","events","init","createInitController","loader","createLoader","shower","createShower","instance","initialize","privacy","updatePrivacy","setEnabled","enabled","setEnablement","next","setAppActive","active","consent","createConsentApi","reevaluateAfterConsent","getStatus","status","subscribeStatus","listener","statusListeners","add","load","placementKey","show","getPlacementState","placements","has","isAvailable","enablement","get","snapshot","subscribePlacement","key","listeners","undefined","subscribeEvents","subscribe","getSubstitutedPlacements","catalog","substitutedKeys","getIgnoredConsentTools","ignoredConsentTools","dispose","disposed","cancelAllRetries","disarmUndecidedWarning","runtime","abort","abortLoad","releasePlacementResources","clear","reason","timers","clearAll","requestThrottle","lock","reset","adReturn","consentListeners","inFlightInit","attachInternals","createInternals","Error"],"sourceRoot":"../../../src","sources":["core/adsInstance.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/core/consentFlow.js

@@ -0,0 +1,154 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.INITIAL_CONSENT = void 0;
+exports.buildConsentOptions = buildConsentOptions;
+exports.consentFailure = consentFailure;
+exports.needsForm = needsForm;
+exports.normalizeConsent = normalizeConsent;
+exports.runConsentStep = runConsentStep;
+exports.toConsentError = toConsentError;
+exports.toGateInput = toGateInput;
+var _errors = require("../diagnostics/errors.js");
+/**
+ * Consent orchestration and normalization (FR-101 – FR-110).
+ *
+ * This closes the most serious gap in 0.1.0. The package *consumed* a consent
+ * decision but nothing *produced* one, and the flow that produces it lives
+ * inside the very provider library the package promised an app would never have
+ * to import. So any app shipping to a consent-required region had to import the
+ * provider directly — breaking the package's central promise at exactly the
+ * point where it mattered most — and hand-write the same order-sensitive
+ * orchestration every other such app was also writing.
+ *
+ * What this module does **not** do is as load-bearing as what it does:
+ *
+ *   - It renders no consent UI. The form is the provider's (FR-103).
+ *   - It decides nothing about jurisdictions. Which regions require consent is
+ *     the provider's answer and the publisher's console configuration; the
+ *     package forwards it (FR-107).
+ *   - It never infers consent. An error, a cancellation, a dismissed form, a
+ *     network failure — all of them land on `error`, and `error` never carries
+ *     permission (FR-106). This is the invariant the whole module exists to
+ *     protect, because the failure it prevents is invisible: a request that
+ *     should not have happened looks exactly like one that should.
+ *
+ * Pure apart from the port calls it awaits. No React, no provider type crossing
+ * outward.
+ */
+
+const INITIAL_CONSENT = exports.INITIAL_CONSENT = {
+  state: 'undetermined',
+  canRequestAds: false,
+  isFormAvailable: false,
+  privacyOptionsRequirement: 'unknown',
+  error: null
+};
+
+/**
+ * Maps the engine's status onto the published one.
+ *
+ * `canRequestAds` is taken from the provider rather than derived from the
+ * status. The two are not the same question — a region can be `not_required`
+ * while the provider still withholds permission — and inventing the second
+ * answer from the first is how a package ends up requesting ads it should not.
+ */
+function normalizeConsent(info) {
+  const state = info.status === 'obtained' ? 'obtained' : info.status === 'required' ? 'required' : info.status === 'not_required' ? 'not_required' : 'undetermined';
+  return {
+    state,
+    canRequestAds: info.canRequestAds === true,
+    isFormAvailable: info.isFormAvailable === true,
+    privacyOptionsRequirement: info.privacyOptions,
+    error: null
+  };
+}
+
+/**
+ * The snapshot for a failed flow.
+ *
+ * `canRequestAds` is hard-coded false rather than carried through from anywhere.
+ * There is no failure mode in which "the flow broke" should mean "go ahead", and
+ * making that structural rather than conditional means no future edit can
+ * accidentally reintroduce the inference.
+ *
+ * The privacy-options requirement is `unknown` for the same reason: a broken
+ * flow has no provider verdict to forward, and reporting `not_required` would be
+ * the package deciding the user has no right to change their mind (FR-150).
+ */
+function consentFailure(error) {
+  return {
+    state: 'error',
+    canRequestAds: false,
+    isFormAvailable: false,
+    privacyOptionsRequirement: 'unknown',
+    error
+  };
+}
+function toConsentError(cause, message) {
+  return new _errors.AdsError('consent_flow_failed', {
+    message,
+    operation: 'configure',
+    cause
+  });
+}
+
+/**
+ * Projects a snapshot onto the consent gate's second input.
+ *
+ * Only `obtained` and `not_required` open it. `undetermined` and `required` are
+ * both "we do not have permission yet" and are reported as
+ * `consent_flow_required`; `error` gets its own reason so an app can tell a
+ * user who has not answered from a flow that broke.
+ */
+function toGateInput(snapshot) {
+  if (snapshot.canRequestAds && (snapshot.state === 'obtained' || snapshot.state === 'not_required')) {
+    return {
+      permitted: true
+    };
+  }
+  return {
+    permitted: false,
+    reason: snapshot.state === 'error' ? 'consent_flow_error' : 'consent_flow_required'
+  };
+}
+
+/**
+ * Builds the options for a consent information update.
+ *
+ * `testing` has already been stripped by config validation when the environment
+ * is production, so this function does not re-check. That is deliberate: the
+ * guarantee lives at one point rather than being re-asserted at each call site,
+ * which is the same reason the ad-unit substitution guarantee is provable
+ * (FR-113).
+ */
+function buildConsentOptions(testing, underAgeOfConsent, testDeviceIds) {
+  return {
+    debugGeography: testing?.debugGeography,
+    underAgeOfConsent,
+    testDeviceIds
+  };
+}
+
+/**
+ * One consent operation, with the never-infer rule applied to every exit.
+ *
+ * Every path out of here is either a normalized snapshot or a normalized error
+ * snapshot. Nothing throws, because a consent failure must not be able to block
+ * app startup or crash the host (FR-108).
+ */
+async function runConsentStep(step, failureMessage) {
+  try {
+    return normalizeConsent(await step());
+  } catch (cause) {
+    return consentFailure(toConsentError(cause, failureMessage));
+  }
+}
+
+/** Whether a form should be presented, per the provider's own report. */
+function needsForm(snapshot) {
+  return snapshot.isFormAvailable && (snapshot.state === 'required' || snapshot.state === 'undetermined');
+}
+//# sourceMappingURL=consentFlow.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["_errors","require","INITIAL_CONSENT","exports","state","canRequestAds","isFormAvailable","privacyOptionsRequirement","error","normalizeConsent","info","status","privacyOptions","consentFailure","toConsentError","cause","message","AdsError","operation","toGateInput","snapshot","permitted","reason","buildConsentOptions","testing","underAgeOfConsent","testDeviceIds","debugGeography","runConsentStep","step","failureMessage","needsForm"],"sourceRoot":"../../../src","sources":["core/consentFlow.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/core/enablement.js

@@ -0,0 +1,64 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.canResume = canResume;
+exports.permitsRequests = permitsRequests;
+exports.toEnablement = toEnablement;
+/**
+ * Three-state enablement and the typed result of changing it (FR-114 – FR-125).
+ *
+ * 0.1.0 had a boolean, which forced an app selling an ad-removal tier to lie at
+ * startup. It does not yet know whether this user has paid — that answer arrives
+ * after a store sync — and both available answers are wrong: `true` flashes ads
+ * at someone who paid to never see them, `false` delays ads for everyone else
+ * and then runs into the silent re-enable trap below. The missing third state
+ * was a hole in the contract, not an omission in the app.
+ *
+ * The package still knows nothing about payments, entitlements, or why the app
+ * decided anything (FR-120). It only stops insisting the decision already exists
+ * at construction time.
+ *
+ * Pure — no provider, no React, no I/O.
+ */
+
+/**
+ * Normalizes the configured value. `true`/`false` keep their exact 0.1.0
+ * meaning, which is what makes the widened config type additive (BC-003).
+ */
+function toEnablement(value) {
+  if (value === 'undecided') {
+    return 'undecided';
+  }
+  return value ? 'enabled' : 'disabled';
+}
+
+/** Neither `disabled` nor `undecided` may reach the provider (FR-115). */
+function permitsRequests(enablement) {
+  return enablement === 'enabled';
+}
+
+/**
+ * The outcome of an enablement change.
+ *
+ * 0.1.0 returned `void`, which is the defect FR-122 supersedes. Re-enabling
+ * after a disable sent the init status back to `not_started`, so the app *had*
+ * to call `initialize()` again or every later load and show was refused — and
+ * nothing said so. Not the result, not the status, not the documentation. An app
+ * whose user's subscription lapsed would turn ads back on and silently show
+ * none.
+ */
+
+/**
+ * Whether re-enabling can resume, given what the instance was doing when it was
+ * turned off.
+ *
+ * Only `ready` resumes. Everything else — never started, still initializing,
+ * blocked, failed — has no completed initialization to return to, so claiming a
+ * resume would put the instance in a state it never actually reached.
+ */
+function canResume(resumeTo) {
+  return resumeTo === 'ready';
+}
+//# sourceMappingURL=enablement.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["toEnablement","value","permitsRequests","enablement","canResume","resumeTo"],"sourceRoot":"../../../src","sources":["core/enablement.ts"],"mappings":";;;;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAIA;AACA;AACA;AACA;AACO,SAASA,YAAYA,CAACC,KAA4B,EAAc;EACtE,IAAIA,KAAK,KAAK,WAAW,EAAE;IAC1B,OAAO,WAAW;EACnB;EACA,OAAOA,KAAK,GAAG,SAAS,GAAG,UAAU;AACtC;;AAEA;AACO,SAASC,eAAeA,CAACC,UAAsB,EAAW;EAChE,OAAOA,UAAU,KAAK,SAAS;AAChC;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAqBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,SAASA,CAACC,QAA2B,EAAuB;EAC3E,OAAOA,QAAQ,KAAK,OAAO;AAC5B","ignoreList":[]}

package/lib/commonjs/core/fullScreenLock.js

@@ -0,0 +1,48 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createFullScreenLock = createFullScreenLock;
+/**
+ * The single full-screen lock (FR-030).
+ *
+ * One token per instance, not per placement, because the constraint is about the
+ * screen rather than about any particular ad: two full-screen ads stacked on top
+ * of each other is a broken app regardless of which placements produced them.
+ *
+ * **There is no queue.** A refused show is refused, and the caller is told so
+ * immediately. Queueing would mean an ad opening at a moment the app never
+ * chose — seconds later, on a different screen, after the user moved on — which
+ * is exactly the behavior FR-045 forbids the package from deciding on its own.
+ */
+
+function createFullScreenLock() {
+  let held = null;
+  return {
+    acquire(placementKey) {
+      if (held !== null) {
+        return false;
+      }
+      held = placementKey;
+      return true;
+    },
+    release(placementKey) {
+      // Guarded so a late dismissal from an earlier ad cannot release the
+      // lock out from under the ad currently on screen.
+      if (held === placementKey) {
+        held = null;
+      }
+    },
+    holder() {
+      return held;
+    },
+    isHeld() {
+      return held !== null;
+    },
+    reset() {
+      held = null;
+    }
+  };
+}
+//# sourceMappingURL=fullScreenLock.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["createFullScreenLock","held","acquire","placementKey","release","holder","isHeld","reset"],"sourceRoot":"../../../src","sources":["core/fullScreenLock.ts"],"mappings":";;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAcO,SAASA,oBAAoBA,CAAA,EAAmB;EACtD,IAAIC,IAAmB,GAAG,IAAI;EAE9B,OAAO;IACNC,OAAOA,CAACC,YAAY,EAAE;MACrB,IAAIF,IAAI,KAAK,IAAI,EAAE;QAClB,OAAO,KAAK;MACb;MACAA,IAAI,GAAGE,YAAY;MACnB,OAAO,IAAI;IACZ,CAAC;IACDC,OAAOA,CAACD,YAAY,EAAE;MACrB;MACA;MACA,IAAIF,IAAI,KAAKE,YAAY,EAAE;QAC1BF,IAAI,GAAG,IAAI;MACZ;IACD,CAAC;IACDI,MAAMA,CAAA,EAAG;MACR,OAAOJ,IAAI;IACZ,CAAC;IACDK,MAAMA,CAAA,EAAG;MACR,OAAOL,IAAI,KAAK,IAAI;IACrB,CAAC;IACDM,KAAKA,CAAA,EAAG;MACPN,IAAI,GAAG,IAAI;IACZ;EACD,CAAC;AACF","ignoreList":[]}

package/lib/commonjs/core/gates.js

@@ -0,0 +1,95 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.evaluateGates = evaluateGates;
+/**
+ * The one place that decides why a request was refused (FR-140, FR-141).
+ *
+ * After 0.2.0 there are three independent ways to be blocked — platform
+ * availability, the app's three-state enable flag, and consent — and they can be
+ * closed in any combination. A precedence spread across four call sites is not a
+ * precedence; it is four coincidences that currently agree. So every refusal
+ * path in the package routes through `evaluateGates` and nothing else compares
+ * gate state.
+ *
+ * **The order is availability, then enablement, then consent — most immovable
+ * first.** Two reasons, and they agree:
+ *
+ * 1. It is what 0.1.0 already did. `initMachine`'s BLOCK transition is refused
+ *    outright when the status is `disabled` or `unavailable`, so consent was
+ *    already the weakest of the three. Any other order would change observable
+ *    behavior for a consumer who configured nothing new.
+ * 2. It is the most useful order for whoever is debugging. An unsupported
+ *    platform makes the other two unfixable, so reporting "consent required" on
+ *    a platform that can never serve an ad sends a developer off to build a flow
+ *    that will never help. Reporting `unavailable` to an app that has also
+ *    disabled ads costs nothing — that app was not going to show an ad either
+ *    way.
+ *
+ * The accepted cost is that an app which *deliberately* disabled ads on an
+ * unsupported platform is told about the platform rather than about its own
+ * switch. That is fine: neither answer changes what the app does next.
+ *
+ * Pure. No provider, no React, no I/O — which is what lets the full combination
+ * table be a unit test rather than an integration one.
+ */
+
+/** What the consent flow contributes, or `null` when the app never opted in. */
+
+function evaluateGates(input) {
+  // 1. Availability. Nothing downstream can be fixed while this is closed.
+  if (!input.available.ok) {
+    return {
+      allowed: false,
+      kind: 'unavailable',
+      reason: input.available.reason
+    };
+  }
+
+  // 2. Enablement. `undecided` is reported separately from `disabled` because
+  // that distinction is the entire reason the third state exists (FR-116).
+  if (input.enablement === 'disabled') {
+    return {
+      allowed: false,
+      kind: 'disabled'
+    };
+  }
+  if (input.enablement === 'undecided') {
+    return {
+      allowed: false,
+      kind: 'undecided'
+    };
+  }
+
+  // 3. Consent, whose two inputs combine as most-restrictive-wins (FR-105a).
+  //
+  // Requesting is permitted only when both permit it, and neither can widen
+  // what the other allows. The case this protects is an app that obtained
+  // consent successfully but independently blocked ads for a reason of its own
+  // — a reason FR-120 forbids the package from knowing, and therefore one it
+  // must never overrule.
+  //
+  // When both are closed the app's own gate is reported: it is the input the
+  // app controls directly, and the flow's state is separately readable through
+  // `consent.getState()` at any time.
+  if (!input.appGate.permitted) {
+    return {
+      allowed: false,
+      kind: 'blocked',
+      reason: input.appGate.reason
+    };
+  }
+  if (input.consentGate && !input.consentGate.permitted) {
+    return {
+      allowed: false,
+      kind: 'blocked',
+      reason: input.consentGate.reason
+    };
+  }
+  return {
+    allowed: true
+  };
+}
+//# sourceMappingURL=gates.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["evaluateGates","input","available","ok","allowed","kind","reason","enablement","appGate","permitted","consentGate"],"sourceRoot":"../../../src","sources":["core/gates.ts"],"mappings":";;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAIA;;AAyBO,SAASA,aAAaA,CAACC,KAAgB,EAAgB;EAC7D;EACA,IAAI,CAACA,KAAK,CAACC,SAAS,CAACC,EAAE,EAAE;IACxB,OAAO;MAAEC,OAAO,EAAE,KAAK;MAAEC,IAAI,EAAE,aAAa;MAAEC,MAAM,EAAEL,KAAK,CAACC,SAAS,CAACI;IAAO,CAAC;EAC/E;;EAEA;EACA;EACA,IAAIL,KAAK,CAACM,UAAU,KAAK,UAAU,EAAE;IACpC,OAAO;MAAEH,OAAO,EAAE,KAAK;MAAEC,IAAI,EAAE;IAAW,CAAC;EAC5C;EACA,IAAIJ,KAAK,CAACM,UAAU,KAAK,WAAW,EAAE;IACrC,OAAO;MAAEH,OAAO,EAAE,KAAK;MAAEC,IAAI,EAAE;IAAY,CAAC;EAC7C;;EAEA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,IAAI,CAACJ,KAAK,CAACO,OAAO,CAACC,SAAS,EAAE;IAC7B,OAAO;MAAEL,OAAO,EAAE,KAAK;MAAEC,IAAI,EAAE,SAAS;MAAEC,MAAM,EAAEL,KAAK,CAACO,OAAO,CAACF;IAAO,CAAC;EACzE;EACA,IAAIL,KAAK,CAACS,WAAW,IAAI,CAACT,KAAK,CAACS,WAAW,CAACD,SAAS,EAAE;IACtD,OAAO;MAAEL,OAAO,EAAE,KAAK;MAAEC,IAAI,EAAE,SAAS;MAAEC,MAAM,EAAEL,KAAK,CAACS,WAAW,CAACJ;IAAO,CAAC;EAC7E;EAEA,OAAO;IAAEF,OAAO,EAAE;EAAK,CAAC;AACzB","ignoreList":[]}