@chipmobilesdk/rn-ads 0.7.0 → 0.8.0

package/lib/commonjs/core/retryPolicy.js

@@ -0,0 +1,120 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.canRetry = canRetry;
+exports.delayForAttempt = delayForAttempt;
+exports.resolveEffectiveRetry = resolveEffectiveRetry;
+exports.resolveRetryPolicy = resolveRetryPolicy;
+var _rnCore = require("@chipmobilesdk/rn-core");
+var _errors = require("../diagnostics/errors.js");
+var _timers = require("./timers.js");
+/**
+ * Bounded, opt-in retry for failed loads (FR-134 – FR-139).
+ *
+ * 0.1.0 shipped no retry on purpose, and the reason was sound: every retry is a
+ * billable request, and only the app knows what that costs. But the practical
+ * result was that every app rewrote the same backoff loop, and the cost of
+ * writing it wrong landed on a bill. This ships the loop once, keeps it **off by
+ * default**, and makes every attempt visible.
+ *
+ * Three properties do the work:
+ *
+ *   - Off unless configured, so upgrading from 0.1.0 issues not one extra
+ *     request (FR-134, and the compat test proves it rather than asserting it).
+ *   - Only `retryable` errors. Configuration and consent errors, an unsupported
+ *     platform, and a disabled or undecided instance are states another attempt
+ *     cannot change, so retrying them would spend money on a certainty (FR-135).
+ *   - Every attempt is an event carrying the load cycle's correlation id, so a
+ *     bill can be reconciled against the event stream alone (FR-138).
+ *
+ * Pure — the schedule is computed here, the waiting happens in the instance's
+ * TimerSet so `dispose()` can prove it released everything.
+ */
+
+/**
+ * Validates one policy against the bounds.
+ *
+ * Out-of-range values **throw** rather than being clamped, matching the rule
+ * `timers.ts` already follows: silently clamping a request for ten retries down
+ * to five tells the app it configured something it did not, and the discrepancy
+ * only surfaces later as a bill that does not match the code.
+ *
+ * `label` names the offending field precisely — an error that says only
+ * "invalid retry policy" makes an integrator hunt through a catalog by hand.
+ */
+function resolveRetryPolicy(policy, label) {
+  const maxRetries = (0, _timers.checkBand)(`${label}.maxRetries`, policy.maxRetries ?? _timers.DEFAULT_RETRY_POLICY.maxRetries, _timers.RETRY_BOUNDS.maxRetries, 'retry_out_of_bounds', '');
+  const initialDelayMs = (0, _timers.checkBand)(`${label}.initialDelayMs`, policy.initialDelayMs ?? _timers.DEFAULT_RETRY_POLICY.initialDelayMs, _timers.RETRY_BOUNDS.initialDelayMs, 'retry_out_of_bounds');
+  const maxDelayMs = (0, _timers.checkBand)(`${label}.maxDelayMs`, policy.maxDelayMs ?? _timers.DEFAULT_RETRY_POLICY.maxDelayMs, _timers.RETRY_BOUNDS.maxDelayMs, 'retry_out_of_bounds');
+  if (!Number.isInteger(maxRetries)) {
+    throw new _errors.AdsConfigError('retry_out_of_bounds', {
+      message: `${label}.maxRetries must be a whole number; received ${maxRetries}`
+    });
+  }
+  if (initialDelayMs > maxDelayMs) {
+    throw new _errors.AdsConfigError('retry_out_of_bounds', {
+      message: `${label}.initialDelayMs (${initialDelayMs}ms) exceeds ${label}.maxDelayMs (${maxDelayMs}ms); the first retry would already be past the ceiling`
+    });
+  }
+  return {
+    maxRetries,
+    initialDelayMs,
+    maxDelayMs
+  };
+}
+
+/**
+ * Resolves the effective policy for one placement.
+ *
+ * An override **replaces** the instance-wide policy rather than merging into it.
+ * Merging would mean the effective policy for a placement could not be read off
+ * the configuration — you would have to simulate the merge to know what it was —
+ * and a per-field merge makes "this placement retries twice" quietly depend on a
+ * value written somewhere else.
+ *
+ * Both are validated against the same bounds, so an override narrows behavior
+ * but can never exceed a ceiling (FR-136a).
+ */
+function resolveEffectiveRetry(instancePolicy, placementPolicy, placementKey) {
+  if (placementPolicy === false) {
+    // Explicit opt-out for this placement alone. A banner retry is cheap and
+    // invisible; a rewarded retry happens with a user waiting on the other
+    // side of it. An app may reasonably want one and not the other.
+    return null;
+  }
+  if (placementPolicy) {
+    return resolveRetryPolicy(placementPolicy, `placements.${placementKey}.retry`);
+  }
+  if (instancePolicy) {
+    return resolveRetryPolicy(instancePolicy, 'retry');
+  }
+  // Nothing configured anywhere: retry is entirely off, which is the default
+  // and the only behavior a 0.1.0 consumer can observe (FR-134).
+  return null;
+}
+
+/**
+ * Delay before the given attempt. `attempt` is 1-based — the first retry is 1.
+ *
+ * Exponential with a fixed x2 multiplier and **no jitter**. Jitter exists to
+ * desynchronize a fleet of clients hitting one server; a single device retrying
+ * its own load has no herd to avoid. Leaving it out keeps "two retries, 2s then
+ * 4s" an exact assertion instead of a statistical one, which matters more here
+ * than a property that does not apply.
+ */
+function delayForAttempt(policy, attempt) {
+  return (0, _rnCore.computeBackoff)(attempt, {
+    initialDelayMs: policy.initialDelayMs,
+    maxDelayMs: policy.maxDelayMs,
+    factor: 2,
+    jitter: 'none'
+  });
+}
+
+/** Whether another attempt is permitted. `attemptsMade` counts retries only. */
+function canRetry(policy, attemptsMade) {
+  return policy !== null && attemptsMade < policy.maxRetries;
+}
+//# sourceMappingURL=retryPolicy.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["_rnCore","require","_errors","_timers","resolveRetryPolicy","policy","label","maxRetries","checkBand","DEFAULT_RETRY_POLICY","RETRY_BOUNDS","initialDelayMs","maxDelayMs","Number","isInteger","AdsConfigError","message","resolveEffectiveRetry","instancePolicy","placementPolicy","placementKey","delayForAttempt","attempt","computeBackoff","factor","jitter","canRetry","attemptsMade"],"sourceRoot":"../../../src","sources":["core/retryPolicy.ts"],"mappings":";;;;;;;;;AAuBA,IAAAA,OAAA,GAAAC,OAAA;AAEA,IAAAC,OAAA,GAAAD,OAAA;AACA,IAAAE,OAAA,GAAAF,OAAA;AA1BA;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;AACO,SAASG,kBAAkBA,CAACC,MAAmB,EAAEC,KAAa,EAAuB;EAC3F,MAAMC,UAAU,GAAG,IAAAC,iBAAS,EAC3B,GAAGF,KAAK,aAAa,EACrBD,MAAM,CAACE,UAAU,IAAIE,4BAAoB,CAACF,UAAU,EACpDG,oBAAY,CAACH,UAAU,EACvB,qBAAqB,EACrB,EACD,CAAC;EACD,MAAMI,cAAc,GAAG,IAAAH,iBAAS,EAC/B,GAAGF,KAAK,iBAAiB,EACzBD,MAAM,CAACM,cAAc,IAAIF,4BAAoB,CAACE,cAAc,EAC5DD,oBAAY,CAACC,cAAc,EAC3B,qBACD,CAAC;EACD,MAAMC,UAAU,GAAG,IAAAJ,iBAAS,EAC3B,GAAGF,KAAK,aAAa,EACrBD,MAAM,CAACO,UAAU,IAAIH,4BAAoB,CAACG,UAAU,EACpDF,oBAAY,CAACE,UAAU,EACvB,qBACD,CAAC;EAED,IAAI,CAACC,MAAM,CAACC,SAAS,CAACP,UAAU,CAAC,EAAE;IAClC,MAAM,IAAIQ,sBAAc,CAAC,qBAAqB,EAAE;MAC/CC,OAAO,EAAE,GAAGV,KAAK,gDAAgDC,UAAU;IAC5E,CAAC,CAAC;EACH;EACA,IAAII,cAAc,GAAGC,UAAU,EAAE;IAChC,MAAM,IAAIG,sBAAc,CAAC,qBAAqB,EAAE;MAC/CC,OAAO,EAAE,GAAGV,KAAK,oBAAoBK,cAAc,eAAeL,KAAK,gBAAgBM,UAAU;IAClG,CAAC,CAAC;EACH;EAEA,OAAO;IAAEL,UAAU;IAAEI,cAAc;IAAEC;EAAW,CAAC;AAClD;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASK,qBAAqBA,CACpCC,cAAuC,EACvCC,eAAgD,EAChDC,YAAoB,EACS;EAC7B,IAAID,eAAe,KAAK,KAAK,EAAE;IAC9B;IACA;IACA;IACA,OAAO,IAAI;EACZ;EACA,IAAIA,eAAe,EAAE;IACpB,OAAOf,kBAAkB,CAACe,eAAe,EAAE,cAAcC,YAAY,QAAQ,CAAC;EAC/E;EACA,IAAIF,cAAc,EAAE;IACnB,OAAOd,kBAAkB,CAACc,cAAc,EAAE,OAAO,CAAC;EACnD;EACA;EACA;EACA,OAAO,IAAI;AACZ;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASG,eAAeA,CAAChB,MAA2B,EAAEiB,OAAe,EAAU;EACrF,OAAO,IAAAC,sBAAc,EAACD,OAAO,EAAE;IAC9BX,cAAc,EAAEN,MAAM,CAACM,cAAc;IACrCC,UAAU,EAAEP,MAAM,CAACO,UAAU;IAC7BY,MAAM,EAAE,CAAC;IACTC,MAAM,EAAE;EACT,CAAC,CAAC;AACH;;AAEA;AACO,SAASC,QAAQA,CAACrB,MAAkC,EAAEsB,YAAoB,EAAW;EAC3F,OAAOtB,MAAM,KAAK,IAAI,IAAIsB,YAAY,GAAGtB,MAAM,CAACE,UAAU;AAC3D","ignoreList":[]}

package/lib/commonjs/core/rewardedSession.js

@@ -0,0 +1,65 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createRewardedSession = createRewardedSession;
+/**
+ * Rewarded session bookkeeping (FR-046 – FR-049).
+ *
+ * Two independent booleans, never derived from one another:
+ *
+ *              rewardConfirmed=false        rewardConfirmed=true
+ *   dismissed=false   in progress           reward emitted, awaiting dismissal
+ *   dismissed=true    dismissed_no_reward   earned
+ *
+ * The defect this exists to prevent is inferring "earned" from dismissal. It is
+ * the most common way rewarded integrations go wrong, and it is a direct revenue
+ * and fairness fault: a user who closed the ad after two seconds gets the prize,
+ * and the publisher is billed for nothing.
+ *
+ * Tracking two flags and deriving the outcome makes both callback orderings
+ * produce the same result *by construction* rather than by the provider
+ * happening to fire in a convenient order (SC-007).
+ */
+
+function createRewardedSession() {
+  let confirmed = false;
+  let dismissed = false;
+  let earnedReward = null;
+  return {
+    confirmReward(reward) {
+      if (confirmed) {
+        return null;
+      }
+      confirmed = true;
+      earnedReward = reward;
+      return reward;
+    },
+    dismiss() {
+      if (dismissed) {
+        return false;
+      }
+      dismissed = true;
+      return true;
+    },
+    outcome() {
+      if (!dismissed) {
+        return 'in_progress';
+      }
+      // Read at dismissal time, so a reward that arrived first is honored and
+      // one that never arrives is not invented.
+      return confirmed ? 'earned' : 'dismissed_without_reward';
+    },
+    get rewardEarned() {
+      return confirmed;
+    },
+    get dismissed() {
+      return dismissed;
+    },
+    reward() {
+      return earnedReward;
+    }
+  };
+}
+//# sourceMappingURL=rewardedSession.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["createRewardedSession","confirmed","dismissed","earnedReward","confirmReward","reward","dismiss","outcome","rewardEarned"],"sourceRoot":"../../../src","sources":["core/rewardedSession.ts"],"mappings":";;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAsBO,SAASA,qBAAqBA,CAAA,EAAoB;EACxD,IAAIC,SAAS,GAAG,KAAK;EACrB,IAAIC,SAAS,GAAG,KAAK;EACrB,IAAIC,YAA2B,GAAG,IAAI;EAEtC,OAAO;IACNC,aAAaA,CAACC,MAAM,EAAE;MACrB,IAAIJ,SAAS,EAAE;QACd,OAAO,IAAI;MACZ;MACAA,SAAS,GAAG,IAAI;MAChBE,YAAY,GAAGE,MAAM;MACrB,OAAOA,MAAM;IACd,CAAC;IAEDC,OAAOA,CAAA,EAAG;MACT,IAAIJ,SAAS,EAAE;QACd,OAAO,KAAK;MACb;MACAA,SAAS,GAAG,IAAI;MAChB,OAAO,IAAI;IACZ,CAAC;IAEDK,OAAOA,CAAA,EAAG;MACT,IAAI,CAACL,SAAS,EAAE;QACf,OAAO,aAAa;MACrB;MACA;MACA;MACA,OAAOD,SAAS,GAAG,QAAQ,GAAG,0BAA0B;IACzD,CAAC;IAED,IAAIO,YAAYA,CAAA,EAAG;MAClB,OAAOP,SAAS;IACjB,CAAC;IAED,IAAIC,SAASA,CAAA,EAAG;MACf,OAAOA,SAAS;IACjB,CAAC;IAEDG,MAAMA,CAAA,EAAG;MACR,OAAOF,YAAY;IACpB;EACD,CAAC;AACF","ignoreList":[]}

package/lib/commonjs/core/timers.js

@@ -0,0 +1,162 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.UNDECIDED_WARNING_BOUNDS = exports.SHOW_TIMEOUT_BOUNDS = exports.RETRY_BOUNDS = exports.LOAD_TIMEOUT_BOUNDS = exports.DEFAULT_UNDECIDED_WARNING_MS = exports.DEFAULT_SHOW_TIMEOUT_MS = exports.DEFAULT_RETRY_POLICY = exports.DEFAULT_LOAD_TIMEOUT_MS = exports.DEFAULT_APP_OPEN_VALIDITY_MS = exports.DEFAULT_AD_VALIDITY_MS = exports.APP_OPEN_VALIDITY_BOUNDS = exports.AD_VALIDITY_BOUNDS = exports.AD_RETURN_MAX_AWAY_MS = exports.AD_RETURN_GRACE_MS = exports.AD_CLICK_WINDOW_MS = void 0;
+exports.checkBand = checkBand;
+Object.defineProperty(exports, "createTimerSet", {
+  enumerable: true,
+  get: function () {
+    return _rnCore.createTimerSet;
+  }
+});
+exports.isStale = isStale;
+exports.resolveTimeouts = resolveTimeouts;
+var _rnCore = require("@chipmobilesdk/rn-core");
+var _errors = require("../diagnostics/errors.js");
+/**
+ * Timeout and staleness policy (FR-032, FR-034).
+ *
+ * Defaults and bounds live here rather than at each call site so there is one
+ * place to read what the package will wait for. Values outside a band are a
+ * configuration error rather than being silently clamped: silently clamping a
+ * one-second load timeout to five would mean the app is told it configured
+ * something it did not (FR-008).
+ */
+
+/** Comfortably longer than a normal fill on a slow mobile network, still bounded. */
+const DEFAULT_LOAD_TIMEOUT_MS = exports.DEFAULT_LOAD_TIMEOUT_MS = 30_000;
+/** Generous for what is essentially a local presentation. */
+const DEFAULT_SHOW_TIMEOUT_MS = exports.DEFAULT_SHOW_TIMEOUT_MS = 10_000;
+/**
+ * Google documents that a loaded ad object expires about an hour after load.
+ * Sixty minutes is the provider's own number; choosing anything else would be
+ * inventing a constraint (R7).
+ */
+const DEFAULT_AD_VALIDITY_MS = exports.DEFAULT_AD_VALIDITY_MS = 3_600_000;
+
+/**
+ * App-open's own window, deliberately shorter than the hour the other
+ * full-screen formats get (FR-130).
+ *
+ * Worth being explicit about why: Google expires app-open ads after **four
+ * hours**, which is *longer* than DEFAULT_AD_VALIDITY_MS, so the provider does
+ * not constrain this at all. The shorter window is a product decision. An
+ * app-open ad shows at the most prominent moment the app has, and a creative
+ * cached for an hour is stale by then; thirty minutes still spares a returning
+ * user the spinner of a cold load, which is both the worst app-open experience
+ * and the specific behavior store policy penalizes.
+ */
+const DEFAULT_APP_OPEN_VALIDITY_MS = exports.DEFAULT_APP_OPEN_VALIDITY_MS = 1_800_000;
+
+/**
+ * How long `enabled: 'undecided'` may go unresolved before one warning fires.
+ *
+ * Ten seconds is several times a realistic worst case for the round trip this
+ * state exists to cover — asking a store whether the user owns an ad-removal
+ * entitlement — so an app doing the right thing essentially never trips it,
+ * while an app that forgot to resolve trips it inside a single QA session,
+ * which is where it needs to be caught (FR-119).
+ */
+const DEFAULT_UNDECIDED_WARNING_MS = exports.DEFAULT_UNDECIDED_WARNING_MS = 10_000;
+const LOAD_TIMEOUT_BOUNDS = exports.LOAD_TIMEOUT_BOUNDS = {
+  min: 5_000,
+  max: 120_000
+};
+const SHOW_TIMEOUT_BOUNDS = exports.SHOW_TIMEOUT_BOUNDS = {
+  min: 5_000,
+  max: 30_000
+};
+const AD_VALIDITY_BOUNDS = exports.AD_VALIDITY_BOUNDS = {
+  min: 60_000,
+  max: 3_600_000
+};
+/** Ceiling is one hour so app-open can never outlive the general window. */
+const APP_OPEN_VALIDITY_BOUNDS = exports.APP_OPEN_VALIDITY_BOUNDS = {
+  min: 60_000,
+  max: 3_600_000
+};
+const UNDECIDED_WARNING_BOUNDS = exports.UNDECIDED_WARNING_BOUNDS = {
+  min: 1_000,
+  max: 120_000
+};
+
+/**
+ * Retry defaults (FR-136).
+ *
+ * Two retries rather than more: each one is a billable request, and two covers
+ * the transient network failure and the momentary no-fill — the cases where
+ * trying again plausibly helps. A third mostly pays for a failure that was not
+ * transient. 2s then 4s keeps both inside a window the user still associates
+ * with the action that triggered the load.
+ */
+const DEFAULT_RETRY_POLICY = exports.DEFAULT_RETRY_POLICY = {
+  maxRetries: 2,
+  initialDelayMs: 2_000,
+  maxDelayMs: 30_000
+};
+const RETRY_BOUNDS = exports.RETRY_BOUNDS = {
+  maxRetries: {
+    min: 1,
+    max: 5
+  },
+  initialDelayMs: {
+    min: 500,
+    max: 30_000
+  },
+  maxDelayMs: {
+    min: 1_000,
+    max: 60_000
+  }
+};
+
+/**
+ * Ad-originated return detection (FR-128).
+ *
+ * A background transition within CLICK_WINDOW of a click is attributed to a
+ * browser the ad opened. An absence longer than MAX_AWAY is no longer
+ * attributable to the ad — the user did something else in between. GRACE covers
+ * the moment right after the return, where an app-open show would otherwise
+ * fire, without outliving it and refusing a genuinely later show.
+ */
+const AD_CLICK_WINDOW_MS = exports.AD_CLICK_WINDOW_MS = 2_000;
+const AD_RETURN_MAX_AWAY_MS = exports.AD_RETURN_MAX_AWAY_MS = 300_000;
+const AD_RETURN_GRACE_MS = exports.AD_RETURN_GRACE_MS = 10_000;
+/**
+ * `value` when it is inside `bounds`, else an `AdsConfigError` with `code`: each
+ * field reports the code its documentation names, so a retry policy out of bounds
+ * is `retry_out_of_bounds`, not a timeout's code (CORE-04, ADS-16).
+ */
+function checkBand(label, value, bounds, code = 'timeout_out_of_bounds', unit = 'ms') {
+  return (0, _rnCore.checkRange)(label, value, bounds, message => new _errors.AdsConfigError(code, {
+    message
+  }), unit);
+}
+function resolveTimeouts(input) {
+  const {
+    timeouts,
+    adValidityMs,
+    appOpenValidityMs,
+    undecidedWarningMs
+  } = input;
+  return {
+    load: checkBand('timeouts.load', timeouts?.load ?? DEFAULT_LOAD_TIMEOUT_MS, LOAD_TIMEOUT_BOUNDS),
+    show: checkBand('timeouts.show', timeouts?.show ?? DEFAULT_SHOW_TIMEOUT_MS, SHOW_TIMEOUT_BOUNDS),
+    adValidity: checkBand('adValidityMs', adValidityMs ?? DEFAULT_AD_VALIDITY_MS, AD_VALIDITY_BOUNDS),
+    appOpenValidity: checkBand('appOpenValidityMs', appOpenValidityMs ?? DEFAULT_APP_OPEN_VALIDITY_MS, APP_OPEN_VALIDITY_BOUNDS),
+    undecidedWarning: checkBand('undecidedWarningMs', undecidedWarningMs ?? DEFAULT_UNDECIDED_WARNING_MS, UNDECIDED_WARNING_BOUNDS)
+  };
+}
+
+/**
+ * How timers are scheduled, and the set that tracks them so `dispose()` can prove
+ * it released every one (SC-008): rn-core's, injectable so a test drives retry
+ * backoff, app-open expiry and the undecided warning by moving a clock.
+ */
+
+/** A loaded ad past its validity window must never be reported ready (FR-034). */
+function isStale(loadedAtMs, nowMs, adValidityMs) {
+  return nowMs - loadedAtMs >= adValidityMs;
+}
+//# sourceMappingURL=timers.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["_rnCore","require","_errors","DEFAULT_LOAD_TIMEOUT_MS","exports","DEFAULT_SHOW_TIMEOUT_MS","DEFAULT_AD_VALIDITY_MS","DEFAULT_APP_OPEN_VALIDITY_MS","DEFAULT_UNDECIDED_WARNING_MS","LOAD_TIMEOUT_BOUNDS","min","max","SHOW_TIMEOUT_BOUNDS","AD_VALIDITY_BOUNDS","APP_OPEN_VALIDITY_BOUNDS","UNDECIDED_WARNING_BOUNDS","DEFAULT_RETRY_POLICY","maxRetries","initialDelayMs","maxDelayMs","RETRY_BOUNDS","AD_CLICK_WINDOW_MS","AD_RETURN_MAX_AWAY_MS","AD_RETURN_GRACE_MS","checkBand","label","value","bounds","code","unit","checkRange","message","AdsConfigError","resolveTimeouts","input","timeouts","adValidityMs","appOpenValidityMs","undecidedWarningMs","load","show","adValidity","appOpenValidity","undecidedWarning","isStale","loadedAtMs","nowMs"],"sourceRoot":"../../../src","sources":["core/timers.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/diagnostics/correlation.js

@@ -0,0 +1,33 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createCorrelationIssuer = createCorrelationIssuer;
+/**
+ * Correlation identifiers (FR-052).
+ *
+ * One value is minted when a load begins and carried by every event of that
+ * load/show cycle through its terminal event. It is what lets a consumer
+ * reconstruct a single ad's life from an event stream alone (SC-009) without the
+ * package having to store any history of its own.
+ *
+ * Opaque and monotonic per instance. Not a UUID, and deliberately not derived
+ * from anything about the device or the user — it exists to group events, and
+ * anything with more meaning than that would be a payload the package has
+ * promised not to carry (FR-021).
+ */
+
+function createCorrelationIssuer(prefix = 'ad') {
+  let counter = 0;
+  // Distinguishes cycles from two instances in one process, which otherwise
+  // both start at 1 and would collide in a merged log.
+  const instance = Math.random().toString(36).slice(2, 8);
+  return {
+    next() {
+      counter += 1;
+      return `${prefix}-${instance}-${counter}`;
+    }
+  };
+}
+//# sourceMappingURL=correlation.js.map

package/lib/commonjs/diagnostics/correlation.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createCorrelationIssuer","prefix","counter","instance","Math","random","toString","slice","next"],"sourceRoot":"../../../src","sources":["diagnostics/correlation.ts"],"mappings":";;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAMO,SAASA,uBAAuBA,CAACC,MAAM,GAAG,IAAI,EAAqB;EACzE,IAAIC,OAAO,GAAG,CAAC;EACf;EACA;EACA,MAAMC,QAAQ,GAAGC,IAAI,CAACC,MAAM,CAAC,CAAC,CAACC,QAAQ,CAAC,EAAE,CAAC,CAACC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;EAEvD,OAAO;IACNC,IAAIA,CAAA,EAAG;MACNN,OAAO,IAAI,CAAC;MACZ,OAAO,GAAGD,MAAM,IAAIE,QAAQ,IAAID,OAAO,EAAE;IAC1C;EACD,CAAC;AACF","ignoreList":[]}

package/lib/commonjs/diagnostics/errors.js

@@ -0,0 +1,152 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.AdsError = exports.AdsConfigError = void 0;
+exports.isAdsError = isAdsError;
+exports.normalizeProviderError = normalizeProviderError;
+exports.redact = redact;
+var _rnCore = require("@chipmobilesdk/rn-core");
+/**
+ * Normalized error model (FR-053) and redaction (NFR-006).
+ *
+ * Codes are stable public API: renaming one is a breaking change under LIB-008.
+ * They exist so a consuming app branches on `code` and `retryable` rather than
+ * string-matching a provider message that may change under it.
+ *
+ * `cause` is a redacted string, never the provider's error object. A provider
+ * object reaching a consumer would be a contract leak (FR-002) and a potential
+ * carrier for identifiers the package promises never to emit (FR-021).
+ */
+
+/**
+ * "Retrying this operation could plausibly succeed" — not "retry immediately".
+ *
+ * 0.2.0 added an opt-in retry policy, and this set is what it is allowed to act
+ * on. Everything outside it is excluded deliberately: configuration and consent
+ * errors, an unsupported platform, and a disabled or undecided instance are all
+ * states another attempt cannot change, so retrying them would spend a billable
+ * request on a certainty (FR-135).
+ */
+const RETRYABLE = new Set(['no_fill', 'network_error', 'load_timeout', 'show_timeout', 'ad_expired', 'not_ready', 'busy', 'consumed', 'app_inactive', 'provider_error']);
+/** The package's error; an `SdkError` (`@chipmobilesdk/rn-core`) with `pkg: 'rn-ads'`. */
+class AdsError extends _rnCore.SdkError {
+  /** Redacted provider detail. Never a provider object. */
+
+  constructor(code, options = {}) {
+    const cause = options.cause === undefined ? undefined : redact(options.cause);
+    super('rn-ads', code, {
+      message: options.message,
+      retryable: RETRYABLE.has(code),
+      redactedCause: cause
+    });
+    this.name = 'AdsError';
+    this.operation = options.operation;
+    this.placementKey = options.placementKey;
+    this.format = options.format;
+    this.cause = cause;
+  }
+}
+
+/**
+ * Configuration faults are thrown rather than returned, because they mean the
+ * app is wired wrong and no runtime result could describe a usable outcome.
+ * Every other failure in the package is a typed result (FR-004).
+ */
+exports.AdsError = AdsError;
+class AdsConfigError extends AdsError {
+  constructor(code, options = {}) {
+    super(code, {
+      ...options,
+      operation: options.operation ?? 'configure'
+    });
+    this.name = 'AdsConfigError';
+  }
+}
+exports.AdsConfigError = AdsConfigError;
+function isAdsError(value) {
+  return value instanceof AdsError;
+}
+
+/** An AdMob unit or app id. Redacted so a log never carries a live identifier. */
+const AD_UNIT_PATTERN = /ca-app-pub-\d+[~/]\d+/g;
+
+/**
+ * Keys dropped wholesale rather than pattern-matched, because their values are
+ * sensitive regardless of shape — a bare advertising id has no separator for a
+ * pattern to catch.
+ */
+const SENSITIVE_KEYS = ['adid', 'adUnitId', 'advertisingId', 'consent', 'consentString', 'gaid', 'idfa', 'tcString', 'token', 'userId'];
+
+/**
+ * rn-core's pattern redaction (URLs, JWTs, e-mail addresses, UUIDs, payload-sized
+ * runs) plus ad unit ids, with the keys above dropped. Provider messages are kept
+ * readable: they describe the failure, and every identifier in them is shaped.
+ */
+const redactor = (0, _rnCore.createRedactor)({
+  text: 'patterns',
+  patterns: [AD_UNIT_PATTERN],
+  dropKeys: SENSITIVE_KEYS,
+  maxDepth: 2
+});
+
+/**
+ * Reduces an arbitrary provider value to a safe string (FR-053, NFR-006).
+ *
+ * Returns a string rather than a structure on purpose: a redacted object still
+ * hands the consumer a reference into provider-owned memory, and the contract
+ * promises no provider object crosses the boundary. An `AdsError` reduces to its
+ * code.
+ */
+function redact(value) {
+  return redactor.text(value);
+}
+
+/**
+ * Maps a provider failure onto the normalized taxonomy.
+ *
+ * The adapter's classification wins when it gave one (ADS-08). Otherwise the
+ * match is on substrings that have been stable across provider releases, and
+ * anything unrecognized becomes a retryable `provider_error` rather than being
+ * reshaped into a code that means something specific.
+ */
+function normalizeProviderError(value, options = {}, kind) {
+  switch (kind) {
+    case 'no_fill':
+      return new AdsError('no_fill', {
+        ...options,
+        cause: value
+      });
+    case 'network':
+      return new AdsError('network_error', {
+        ...options,
+        cause: value
+      });
+    case 'rejected':
+      return new AdsError('provider_rejected', {
+        ...options,
+        cause: value
+      });
+    default:
+  }
+  const text = value instanceof Error ? value.message : String(value ?? '');
+  const lowered = text.toLowerCase();
+  if (lowered.includes('no-fill') || lowered.includes('no fill')) {
+    return new AdsError('no_fill', {
+      ...options,
+      cause: value
+    });
+  }
+  if (lowered.includes('network')) {
+    return new AdsError('network_error', {
+      ...options,
+      cause: value
+    });
+  }
+  return new AdsError('provider_error', {
+    ...options,
+    cause: value
+  });
+}
+//# sourceMappingURL=errors.js.map

package/lib/commonjs/diagnostics/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_rnCore","require","RETRYABLE","Set","AdsError","SdkError","constructor","code","options","cause","undefined","redact","message","retryable","has","redactedCause","name","operation","placementKey","format","exports","AdsConfigError","isAdsError","value","AD_UNIT_PATTERN","SENSITIVE_KEYS","redactor","createRedactor","text","patterns","dropKeys","maxDepth","normalizeProviderError","kind","Error","String","lowered","toLowerCase","includes"],"sourceRoot":"../../../src","sources":["diagnostics/errors.ts"],"mappings":"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","ignoreList":[]}