@chipmobilesdk/rn-ads 0.6.0 → 0.8.0

package/lib/module/config/validate.js

@@ -0,0 +1,146 @@
+"use strict";
+
+/**
+ * Catalog and configuration validation (FR-008), plus the fail-closed check
+ * that substitution cannot cover (FR-012).
+ *
+ * Configuration faults throw rather than returning a result. They mean the app
+ * is wired wrong, and no runtime status could describe a usable outcome — every
+ * other failure in this package is a typed result instead.
+ *
+ * Every message names the offending placement key. An error that says only
+ * "invalid configuration" makes the integrator hunt through a catalog by hand.
+ */
+
+import { AdsConfigError } from "../diagnostics/errors.js";
+import { resolvePlacementAdUnits } from "./resolveAdUnit.js";
+import { checkBand, resolveTimeouts } from "../core/timers.js";
+import { defaultMinRequestIntervalMs, MIN_REQUEST_INTERVAL_BOUNDS } from "../core/requestThrottle.js";
+import { toEnablement } from "../core/enablement.js";
+import { resolveEffectiveRetry } from "../core/retryPolicy.js";
+const FORMATS = new Set(['banner', 'interstitial', 'rewarded', 'app_open']);
+export function validateConfig(config, options) {
+  // FR-012. Substitution deliberately does not apply in production, so a debug
+  // build declaring `production` is the one case it cannot make safe: it would
+  // send real requests from a build that should never generate traffic. Fail
+  // closed rather than continue.
+  if (config.environment === 'production' && options.isDevBuild) {
+    throw new AdsConfigError('production_in_dev_build', {
+      message: 'environment is "production" but this is a development build. ' + 'Non-production builds must declare "development" or "test" so the package can ' + 'substitute official Google test ad units and keep production traffic impossible.'
+    });
+  }
+  if (!Array.isArray(config.placements) || config.placements.length === 0) {
+    throw new AdsConfigError('invalid_config', {
+      message: 'placements must be a non-empty array; the package can show nothing without one'
+    });
+  }
+  const byKey = new Map();
+  for (const placement of config.placements) {
+    const key = typeof placement?.key === 'string' ? placement.key.trim() : '';
+    if (!key) {
+      throw new AdsConfigError('invalid_config', {
+        message: 'every placement needs a non-empty key'
+      });
+    }
+    if (byKey.has(key)) {
+      // Rejecting the whole catalog rather than picking a winner: a repeated
+      // key means the app's own naming produced two placements for one slot,
+      // and the package has no basis to guess which was meant.
+      throw new AdsConfigError('duplicate_placement_key', {
+        message: `duplicate placement key "${key}"`,
+        placementKey: key
+      });
+    }
+    if (!FORMATS.has(placement.format)) {
+      throw new AdsConfigError('invalid_config', {
+        message: `placement "${key}" has unsupported format "${String(placement.format)}"; supported formats are banner, interstitial, rewarded, and app_open`,
+        placementKey: key
+      });
+    }
+    if (!placement.androidAdUnitId || !placement.androidAdUnitId.trim()) {
+      throw new AdsConfigError('missing_ad_unit_id', {
+        message: `placement "${key}" is missing androidAdUnitId`,
+        placementKey: key,
+        format: placement.format
+      });
+    }
+    byKey.set(key, {
+      ...placement,
+      key
+    });
+  }
+  const timeouts = resolveTimeouts({
+    timeouts: config.timeouts,
+    adValidityMs: config.adValidityMs,
+    appOpenValidityMs: config.appOpenValidityMs,
+    undecidedWarningMs: config.undecidedWarningMs
+  });
+  const catalog = resolvePlacementAdUnits(Array.from(byKey.values()), config.environment);
+
+  // Resolved eagerly, for every placement, so an out-of-bounds override fails
+  // at construction rather than on the first failed load in production — which
+  // is the one moment nobody is watching for a configuration error.
+  const retryByKey = new Map();
+  // Resolved in the same loop and for the same reason: an out-of-bounds floor
+  // must fail at construction, not silently refuse every request in production.
+  const minRequestIntervalByKey = new Map();
+  for (const [key, placement] of byKey) {
+    retryByKey.set(key, resolveEffectiveRetry(config.retry, placement.retry, key));
+    minRequestIntervalByKey.set(key, placement.minRequestIntervalMs === undefined ? defaultMinRequestIntervalMs(placement.format) :
+    // A request floor, not a timeout: its own code (ADS-16).
+    checkBand(`placements["${key}"].minRequestIntervalMs`, placement.minRequestIntervalMs, MIN_REQUEST_INTERVAL_BOUNDS, 'invalid_config'));
+  }
+  const isProduction = config.environment === 'production';
+  const {
+    consentTesting,
+    ignoredConsentTools
+  } = resolveConsentTesting(config.consentTesting, isProduction);
+  return {
+    enablement: toEnablement(config.enabled),
+    environment: config.environment,
+    placements: byKey,
+    catalog,
+    timeouts,
+    // FR-014: debug and test-device settings must not be able to alter
+    // production behavior, so they are dropped rather than carried and
+    // conditionally ignored somewhere further down.
+    testDeviceIds: isProduction ? [] : [...(config.testDeviceIds ?? [])],
+    retryByKey,
+    minRequestIntervalByKey,
+    consentTesting,
+    ignoredConsentTools
+  };
+}
+
+/**
+ * Neutralizes the consent testing tools in production (FR-113).
+ *
+ * Dropped here, at the single validation point, rather than checked wherever
+ * they are used. That is what makes the guarantee provable: a rule enforced in
+ * one place can be asserted by a test, while one spread across the consent
+ * module's call sites is a hope. It is the same reasoning that makes the ad-unit
+ * substitution guarantee hold, and it is why both are enforced identically.
+ *
+ * The names of what was dropped are returned rather than only logged, so an
+ * automated test — and the demo app's diagnostics screen — can see it.
+ */
+function resolveConsentTesting(testing, isProduction) {
+  if (!testing || !isProduction) {
+    return {
+      consentTesting: testing,
+      ignoredConsentTools: []
+    };
+  }
+  const ignored = [];
+  if (testing.debugGeography !== undefined && testing.debugGeography !== 'disabled') {
+    ignored.push('debugGeography');
+  }
+  if (testing.resetOnStart === true) {
+    ignored.push('resetOnStart');
+  }
+  return {
+    consentTesting: undefined,
+    ignoredConsentTools: ignored
+  };
+}
+//# sourceMappingURL=validate.js.map

package/lib/module/config/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["AdsConfigError","resolvePlacementAdUnits","checkBand","resolveTimeouts","defaultMinRequestIntervalMs","MIN_REQUEST_INTERVAL_BOUNDS","toEnablement","resolveEffectiveRetry","FORMATS","Set","validateConfig","config","options","environment","isDevBuild","message","Array","isArray","placements","length","byKey","Map","placement","key","trim","has","placementKey","format","String","androidAdUnitId","set","timeouts","adValidityMs","appOpenValidityMs","undecidedWarningMs","catalog","from","values","retryByKey","minRequestIntervalByKey","retry","minRequestIntervalMs","undefined","isProduction","consentTesting","ignoredConsentTools","resolveConsentTesting","enablement","enabled","testDeviceIds","testing","ignored","debugGeography","push","resetOnStart"],"sourceRoot":"../../../src","sources":["config/validate.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/core/adOriginatedReturn.js

@@ -0,0 +1,115 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+import { AD_CLICK_WINDOW_MS, AD_RETURN_GRACE_MS, AD_RETURN_MAX_AWAY_MS } from "./timers.js";
+export 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 <= AD_CLICK_WINDOW_MS) {
+        armedAtMs = nowMs;
+      }
+    },
+    noteForeground(nowMs) {
+      if (armedAtMs === null) {
+        return;
+      }
+      const away = nowMs - armedAtMs;
+      armedAtMs = null;
+      lastClickAtMs = null;
+      if (away > AD_RETURN_MAX_AWAY_MS) {
+        // Too long to still be attributable to the ad. Not a refusal.
+        return;
+      }
+      refusalUntilMs = nowMs + 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/module/core/adOriginatedReturn.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["AD_CLICK_WINDOW_MS","AD_RETURN_GRACE_MS","AD_RETURN_MAX_AWAY_MS","createAdOriginatedTracker","lastClickAtMs","armedAtMs","refusalUntilMs","noteFullScreenShown","nowMs","noteClick","noteBackground","noteForeground","away","isRefusing","reset"],"sourceRoot":"../../../src","sources":["core/adOriginatedReturn.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;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,kBAAkB,EAAEC,kBAAkB,EAAEC,qBAAqB,QAAQ,aAAU;AAiBxF,OAAO,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,IAAIJ,kBAAkB,EAAE;QAC1EK,SAAS,GAAGG,KAAK;MAClB;IACD,CAAC;IAEDG,cAAcA,CAACH,KAAK,EAAE;MACrB,IAAIH,SAAS,KAAK,IAAI,EAAE;QACvB;MACD;MACA,MAAMO,IAAI,GAAGJ,KAAK,GAAGH,SAAS;MAC9BA,SAAS,GAAG,IAAI;MAChBD,aAAa,GAAG,IAAI;MACpB,IAAIQ,IAAI,GAAGV,qBAAqB,EAAE;QACjC;QACA;MACD;MACAI,cAAc,GAAGE,KAAK,GAAGP,kBAAkB;IAC5C,CAAC;IAEDY,UAAUA,CAACL,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;IAEDQ,KAAKA,CAAA,EAAG;MACPV,aAAa,GAAG,IAAI;MACpBC,SAAS,GAAG,IAAI;MAChBC,cAAc,GAAG,IAAI;IACtB;EACD,CAAC;AACF","ignoreList":[]}

package/lib/module/core/adsInstance.js

@@ -0,0 +1,121 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+import { createConsentApi } from "./instance/consent.js";
+import { createInstanceContext } from "./instance/context.js";
+import { cancelAllRetries, disarmUndecidedWarning } from "./instance/gate.js";
+import { createInitController } from "./instance/init.js";
+import { attachInternals, createInternals } from "./instance/internals.js";
+import { createLoader } from "./instance/load.js";
+import { createShower } from "./instance/show.js";
+export { getInternals } from "./instance/internals.js";
+
+/**
+ * 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).
+ */
+export function createAds(config, options = {}, defaultEngine = noDefaultEngine) {
+  // Throws on a structural fault or the FR-012 fail-closed case, before
+  // anything else exists.
+  const context = createInstanceContext(config, options, defaultEngine);
+  const {
+    state,
+    engine,
+    resolved,
+    events
+  } = context;
+  const init = createInitController(context);
+  const loader = createLoader(context);
+  const shower = 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: 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;
+      cancelAllRetries(context);
+      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;
+    }
+  };
+  attachInternals(instance, 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/module/core/adsInstance.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createConsentApi","createInstanceContext","cancelAllRetries","disarmUndecidedWarning","createInitController","attachInternals","createInternals","createLoader","createShower","getInternals","createAds","config","options","defaultEngine","noDefaultEngine","context","state","engine","resolved","events","init","loader","shower","instance","initialize","privacy","updatePrivacy","setEnabled","enabled","setEnablement","next","setAppActive","active","consent","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","runtime","abort","abortLoad","releasePlacementResources","clear","reason","timers","clearAll","requestThrottle","lock","reset","adReturn","consentListeners","inFlightInit","Error"],"sourceRoot":"../../../src","sources":["core/adsInstance.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/core/consentFlow.js

@@ -0,0 +1,143 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+import { AdsError } from "../diagnostics/errors.js";
+export const 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.
+ */
+export 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).
+ */
+export function consentFailure(error) {
+  return {
+    state: 'error',
+    canRequestAds: false,
+    isFormAvailable: false,
+    privacyOptionsRequirement: 'unknown',
+    error
+  };
+}
+export function toConsentError(cause, message) {
+  return new 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.
+ */
+export 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).
+ */
+export 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).
+ */
+export 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. */
+export function needsForm(snapshot) {
+  return snapshot.isFormAvailable && (snapshot.state === 'required' || snapshot.state === 'undetermined');
+}
+//# sourceMappingURL=consentFlow.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["AdsError","INITIAL_CONSENT","state","canRequestAds","isFormAvailable","privacyOptionsRequirement","error","normalizeConsent","info","status","privacyOptions","consentFailure","toConsentError","cause","message","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/module/core/enablement.js

@@ -0,0 +1,58 @@
+"use strict";
+
+/**
+ * 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).
+ */
+export function toEnablement(value) {
+  if (value === 'undecided') {
+    return 'undecided';
+  }
+  return value ? 'enabled' : 'disabled';
+}
+
+/** Neither `disabled` nor `undecided` may reach the provider (FR-115). */
+export 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.
+ */
+export function canResume(resumeTo) {
+  return resumeTo === 'ready';
+}
+//# sourceMappingURL=enablement.js.map

package/lib/module/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;AACA,OAAO,SAASA,YAAYA,CAACC,KAA4B,EAAc;EACtE,IAAIA,KAAK,KAAK,WAAW,EAAE;IAC1B,OAAO,WAAW;EACnB;EACA,OAAOA,KAAK,GAAG,SAAS,GAAG,UAAU;AACtC;;AAEA;AACA,OAAO,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;AACA,OAAO,SAASC,SAASA,CAACC,QAA2B,EAAuB;EAC3E,OAAOA,QAAQ,KAAK,OAAO;AAC5B","ignoreList":[]}