@chipmobilesdk/rn-ads 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,144 @@
 # @chipmobilesdk/rn-ads
 
+## 0.8.0
+
+### Minor Changes
+
+- Every package now ships built JavaScript with declaration files, instead of asking the
+  app to compile its TypeScript. ([#22](https://github.com/operationd8979/chip-mobile-sdk/pull/22))
+
+  Each tarball carries `lib/commonjs`, `lib/module` and `lib/typescript` (built with
+  `react-native-builder-bob`), and `src/` alongside them. What that changes for a
+  consumer:
+
+  - **Nothing to add to `transformIgnorePatterns`.** `require` resolves to the CommonJS
+    build, so an app's Jest loads this package without being told to transform it. That
+    was the one thing every consuming app had to know about us (DEP-04).
+  - **Typechecking reads our `.d.ts`** rather than compiling our source under our
+    `tsconfig`. A consumer's stricter — or looser — settings no longer meet our code.
+  - **`import` resolves to ESM**, so a bundler can tree-shake what it does not use.
+
+  No exported name changed, and no subpath moved: `.`, `./testing`, `./push`,
+  `./advanced`, `./app-auth`, `./keychain` and rn-core's twelve subpaths resolve exactly
+  as before, each now with its own declarations for both module systems. publint and
+  `attw --profile node16` pass on all twelve packages, which they could not before.
+
+  Inside the monorepo nothing changed either, and that is deliberate: every subpath also
+  declares a private `chipmobilesdk-source` condition pointing at its TypeScript, and
+  Metro, Jest and `tsc` here ask for that condition first. The demo app bundles 371
+  modules straight from `packages/*/src`, so editing a package still changes the app with
+  no build step, and coverage is still measured on the source. The condition is named for
+  this organization rather than using the conventional `source` because third-party
+  packages declare that one too — `@dr.pogodin/react-native-fs` does — and asking for it
+  pulled their sources into our stricter compile.
+
+  `npm run build:packages` builds everything, `prepack` rebuilds before any `npm pack`,
+  and `lib/` is git-ignored: the published bytes are produced by the release, never
+  committed. `npm run check:manifests` now fails a package whose `main`, `module`,
+  `types`, `source` condition, `files`, build script or `prepack` do not match this shape.
+
+- The fake engine's banner now renders a host view instead of nothing, so a test can find
+  it with the testing library. ([#24](https://github.com/operationd8979/chip-mobile-sdk/pull/24))
+
+  `createFakeAdsEngine().banner.Component` rendered `null`, which left the props the
+  package handed it — `adUnitId`, `personalizedAds`, `onLoaded`, `onFailed`, `onImpression`,
+  `onClicked` — reachable only on the component instance in the rendered tree. Nothing a
+  consumer writes with `@testing-library/react-native` can see that: its queries, like the
+  renderer underneath them, return host elements. The fake now renders a `View` carrying
+  those props under the testID exported as `FAKE_BANNER_TEST_ID` (`'ads-fake-banner'`):
+
+  ```ts
+  import { FAKE_BANNER_TEST_ID } from '@chipmobilesdk/rn-ads/testing';
+
+  const banner = screen.getByTestId(FAKE_BANNER_TEST_ID);
+  expect(banner.props.adUnitId).toBe(/* the test unit, not yours */);
+  banner.props.onLoaded();
+  ```
+
+  A test that searched the tree for a component instance with an `adUnitId` prop needs this
+  change; one driven through `engine.adUnitIds()` and the recorded call log does not. The
+  banner still draws nothing and measures nothing, so a layout assertion is unaffected.
+
+### Patch Changes
+
+- Each package's public API and its weight are now recorded in the repository, so a change
+  to either is reviewed rather than discovered. ([#23](https://github.com/operationd8979/chip-mobile-sdk/pull/23))
+
+  `packages/<pkg>/etc/*.api.md` is an api-extractor report per entrypoint — twenty-seven
+  of them, generated from the declarations the package publishes and committed. A renamed
+  type, a widened union, one more optional field: all of it shows up in a pull request's
+  diff. `npm run check:api` fails when a report is out of date and `npm run api:update`
+  rewrites them.
+
+  A report that moves now needs a **minor or major** changeset for that package.
+  `check:changesets` enforces it, because the report is generated from what the package
+  publishes, and a patch release that moves the public surface is how a consumer's build
+  breaks on `npm update`. A report added for the first time is a baseline, not a change.
+  `./testing` deliberately has no report: test doubles are not a surface a release is
+  gated on.
+
+  `npm run check:size` holds every entrypoint to a budget in `.size-limit.json`, measured
+  on the ESM build with peers and rn-core treated as external — they are what an app
+  installs beside us, not our weight. Each budget started at today's measurement plus five
+  per cent, so growth becomes a decision someone makes instead of a drift nobody sees. The
+  current figures run from 500 B (`rn-core/lazy`) to 19 kB (rn-notification).
+
+  No behaviour or API changed in this release; the entry is here so the changelog records
+  when the reports and the budgets began.
+- Updated dependencies ([#22](https://github.com/operationd8979/chip-mobile-sdk/pull/22), [#23](https://github.com/operationd8979/chip-mobile-sdk/pull/23)):
+  - @chipmobilesdk/rn-core@0.2.0
+
+## 0.7.0
+
+### Minor Changes
+
+- The ads instance is split by responsibility, and the banner host's wiring is off the
+  public type. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  - `AdsInstance` no longer has an `internals` field. It was undocumented, but any
+    consumer could use it to emit `impression` or `reward_earned` into the event stream
+    used for revenue reconciliation. `AdsBanner` now reaches an instance's wiring through
+    a private registry, so a banner given an instance the app wrote by hand renders
+    nothing instead of throwing.
+  - Banner events carry the instance's clock (`createAds({ now })`), like full-screen
+    events, and resolving a banner during render no longer mints a correlation id.
+  - `allTestAdUnits()` moved from the engine module to `@chipmobilesdk/rn-ads/testing`.
+  - Rewards from AdMob go through the one `normalizeReward`; an unused consent port guard
+    and the throttle's unused `reset`/`lastRequestAt` are gone.
+  - Internally, `createAds` is now a 142-line composition root over `core/instance/`
+    (gate, init, load, show, consent, internals), down from one 1,899-line closure. Every
+    path that closes the request gate goes through one teardown.
+
+- Four fixes to how ads behave around throttling, retries and show timeouts. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  - A banner refused by the request throttle now tries again by itself once the window
+    passes. Before, it stayed empty until it was remounted, so a banner on a screen the
+    user returned to within a minute never filled.
+  - A load retry waits at least as long as the placement's `minRequestIntervalMs`
+    requires, so a retry policy cannot request faster than the floor allows. The
+    `retry_scheduled` event reports the wait actually used.
+  - A request AdMob refuses outright (an invalid request or ad unit, a missing app id)
+    is the new non-retryable `provider_rejected` code instead of a retryable
+    `provider_error`, so a retry policy no longer spends billable requests on it. Engines
+    may classify a failure with the new optional `kind` on the `failed` event.
+  - A show that times out and then opens anyway is reported once, not twice. The late
+    ad holds the full-screen lock until it is dismissed, and its reward and dismissal
+    still reach the app.
+
+- The banner renders through the engine port. `AdsEngine` has an optional `banner`
+  capability (`isAvailable()` and a `Component` with neutral props: `adUnitId`,
+  `personalizedAds`, `onLoaded`, `onFailed`, `onImpression`, `onClicked`), and the AdMob
+  adapter supplies the adaptive `BannerAd` there. `AdsBanner` no longer loads the AdMob
+  bridge itself, so a custom or future iOS engine provides its own banner, and the fake
+  engine from `./testing` renders one in tests without a mocked native module. An engine
+  without `banner` keeps working; its banners report `unavailable`. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+### Patch Changes
+
+- Internal: no module in these packages is over 500 lines any more. The camera controller's session I/O moved to `sessionRuntime` and its contract to `contract.ts`; the Play adapter's shape translation to `iapShapes`; the purchase flow's failure mapping and its receipt-validation hook to modules of their own; the AI client's quota request to `quotaRequest`; the in-memory adapter's attachments and the fake ads engine's clock likewise. Behaviour is unchanged — the splits are by responsibility, and every package's suite passes as it stood. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  The repository also measures what it promised: `npm run perf` prints the median of nine runs of the deterministic hot paths against written budgets (recurrence expansion, theme construction, translation lookup, chart geometry, filter compilation), the demo app has a Performance screen reporting startup phases, time to interactive and the same benchmarks on Hermes, and `npm run check:file-size` keeps the limit from drifting. The budgets and the measured figures are recorded in `docs/standards.md` §VI.
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -273,7 +273,9 @@ ads.subscribeEvents(event => {
 A config value outside its band names its own field and code: a timeout or validity window is `timeout_out_of_bounds`, a retry policy `retry_out_of_bounds`, a placement's `minRequestIntervalMs` `invalid_config`.
 
 Retryable: `no_fill` `network_error` `load_timeout` `show_timeout` `ad_expired` `not_ready` `busy` `consumed` `app_inactive` `provider_error`
-Not retryable: `invalid_config` `duplicate_placement_key` `missing_ad_unit_id` `format_mismatch` `placement_not_found` `production_in_dev_build` `timeout_out_of_bounds` `retry_out_of_bounds` `unsupported_platform` `provider_missing` `disabled` `consent_required` `consent_undetermined` `requires_reinitialization` `internal_error`
+Not retryable: `invalid_config` `duplicate_placement_key` `missing_ad_unit_id` `format_mismatch` `placement_not_found` `production_in_dev_build` `timeout_out_of_bounds` `retry_out_of_bounds` `unsupported_platform` `provider_missing` `disabled` `consent_required` `consent_undetermined` `requires_reinitialization` `provider_rejected` `internal_error`
+
+`provider_rejected` (0.7.0) means AdMob refused the request itself — an invalid request or ad unit, a missing app id — so a retry policy does not spend more requests on it. Before, those were `provider_error` and were retried.
 
 Attach any logger or analytics you already use. The package depends on none:
 
@@ -804,7 +806,7 @@ On device, verify with Google's official test ads only. `npm run android`, then
 Adding iOS contributes exactly three things and changes **nothing** you have already written:
 
 1. **`PlacementDefinition.iosAdUnitId`** — the optional field already exists in v1's type, so existing Android-only catalogs stay valid.
-2. **A second engine adapter** behind the existing `AdsEngine` port. The port names no platform and no provider; that is what makes this additive.
+2. **A second engine adapter** behind the existing `AdsEngine` port. The port names no platform and no provider; that is what makes this additive. The banner is part of the port too (`AdsEngine.banner`, since 0.7.0): an adapter supplies its own banner component, which receives neutral props (`adUnitId`, `personalizedAds`, `onLoaded`, `onFailed`, `onImpression`, `onClicked`), and `AdsBanner` renders whatever the engine offers.
 3. **iOS entries in the private test-ad-unit table.**
 
 Your `createAds`, `initialize`, `load`, `show`, `AdsBanner`, and every subscription keep their current signatures. The exported state, event, and error models do not change.

package/lib/commonjs/config/resolveAdUnit.js

@@ -0,0 +1,80 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.resolveAdUnit = resolveAdUnit;
+exports.resolvePlacementAdUnits = resolvePlacementAdUnits;
+var _testAdUnits = require("../engine/testAdUnits.js");
+/**
+ * The production-traffic guarantee (FR-011, FR-011a).
+ *
+ * A pure function, deliberately. This is the single point where a production ad
+ * unit can be replaced by an official test one, which is what makes SC-002
+ * provable rather than merely intended: a guarantee enforced in one place can be
+ * asserted; one spread across three call sites is a hope.
+ *
+ * The rule, from the 2026-09-02 clarification session:
+ *
+ *   production            -> use what the app configured, always, no exceptions
+ *   development / test    -> if it is not one of our own official test units,
+ *                            replace it and say so, loudly, naming the key
+ *
+ * Substitution rather than rejection is a deliberate trade. Rejecting would
+ * block a developer whose only mistake was pulling a teammate's environment
+ * file, and turn a configuration smell into a broken integration at every
+ * startup. Substituting keeps the app working — which is what a non-production
+ * build is for — and reports the problem as a first-class signal. The accepted
+ * cost is that a warning can be ignored; it is bounded because production never
+ * substitutes, so the misconfiguration surfaces there as ordinary behavior
+ * rather than as hidden state.
+ */
+
+function resolveAdUnit(placement, environment) {
+  const configured = placement.androidAdUnitId;
+
+  // Production is the one environment where the package must not second-guess
+  // the app. Substituting here would silently rewrite configuration that was
+  // asked for on purpose, and would cost the publisher live revenue.
+  if (environment === 'production') {
+    return {
+      effectiveAdUnitId: configured,
+      substituted: false
+    };
+  }
+
+  // Structural detection: anything that is not a known official test unit is
+  // treated as production-owned. Not a parse of AdMob's publisher-id format —
+  // see the note in engine/testAdUnits.ts on why that rule would be a liability.
+  if ((0, _testAdUnits.isOfficialTestAdUnit)(configured)) {
+    return {
+      effectiveAdUnitId: configured,
+      substituted: false
+    };
+  }
+  return {
+    effectiveAdUnitId: (0, _testAdUnits.testAdUnitFor)(placement.format),
+    substituted: true
+  };
+}
+/**
+ * Resolves a whole catalog at once, so the warning can name every affected
+ * placement in a single event rather than trickling one out per load — an
+ * integrator wants to fix the whole file, not discover it a placement at a time.
+ */
+function resolvePlacementAdUnits(placements, environment) {
+  const byKey = new Map();
+  const substitutedKeys = [];
+  for (const placement of placements) {
+    const resolved = resolveAdUnit(placement, environment);
+    byKey.set(placement.key, resolved.effectiveAdUnitId);
+    if (resolved.substituted) {
+      substitutedKeys.push(placement.key);
+    }
+  }
+  return {
+    byKey,
+    substitutedKeys
+  };
+}
+//# sourceMappingURL=resolveAdUnit.js.map

package/lib/commonjs/config/resolveAdUnit.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_testAdUnits","require","resolveAdUnit","placement","environment","configured","androidAdUnitId","effectiveAdUnitId","substituted","isOfficialTestAdUnit","testAdUnitFor","format","resolvePlacementAdUnits","placements","byKey","Map","substitutedKeys","resolved","set","key","push"],"sourceRoot":"../../../src","sources":["config/resolveAdUnit.ts"],"mappings":";;;;;;;AAyBA,IAAAA,YAAA,GAAAC,OAAA;AAzBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAWO,SAASC,aAAaA,CAC5BC,SAA8B,EAC9BC,WAAwB,EACP;EACjB,MAAMC,UAAU,GAAGF,SAAS,CAACG,eAAe;;EAE5C;EACA;EACA;EACA,IAAIF,WAAW,KAAK,YAAY,EAAE;IACjC,OAAO;MAAEG,iBAAiB,EAAEF,UAAU;MAAEG,WAAW,EAAE;IAAM,CAAC;EAC7D;;EAEA;EACA;EACA;EACA,IAAI,IAAAC,iCAAoB,EAACJ,UAAU,CAAC,EAAE;IACrC,OAAO;MAAEE,iBAAiB,EAAEF,UAAU;MAAEG,WAAW,EAAE;IAAM,CAAC;EAC7D;EAEA,OAAO;IAAED,iBAAiB,EAAE,IAAAG,0BAAa,EAACP,SAAS,CAACQ,MAAM,CAAC;IAAEH,WAAW,EAAE;EAAK,CAAC;AACjF;AASA;AACA;AACA;AACA;AACA;AACO,SAASI,uBAAuBA,CACtCC,UAA0C,EAC1CT,WAAwB,EACN;EAClB,MAAMU,KAAK,GAAG,IAAIC,GAAG,CAAiB,CAAC;EACvC,MAAMC,eAAyB,GAAG,EAAE;EAEpC,KAAK,MAAMb,SAAS,IAAIU,UAAU,EAAE;IACnC,MAAMI,QAAQ,GAAGf,aAAa,CAACC,SAAS,EAAEC,WAAW,CAAC;IACtDU,KAAK,CAACI,GAAG,CAACf,SAAS,CAACgB,GAAG,EAAEF,QAAQ,CAACV,iBAAiB,CAAC;IACpD,IAAIU,QAAQ,CAACT,WAAW,EAAE;MACzBQ,eAAe,CAACI,IAAI,CAACjB,SAAS,CAACgB,GAAG,CAAC;IACpC;EACD;EAEA,OAAO;IAAEL,KAAK;IAAEE;EAAgB,CAAC;AAClC","ignoreList":[]}

package/lib/commonjs/config/types.js

@@ -0,0 +1,138 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.isFullScreenFormat = isFullScreenFormat;
+/**
+ * Public configuration and state types (FR-001, FR-003, FR-004).
+ *
+ * Nothing here names a platform or an ad provider. That is the whole point:
+ * adding an iOS adapter later contributes an optional `iosAdUnitId` and a second
+ * engine implementation, and changes nothing a consumer already wrote (FR-006).
+ *
+ * The package persists none of this. Every value below lives for the lifetime of
+ * one instance and is released by `dispose()`.
+ */
+
+/**
+ * Supported formats. Native and rewarded-interstitial remain deferred.
+ *
+ * `app_open` joined in 0.2.0. It is a member of this union rather than a
+ * separate concept because FR-132 forbids a parallel vocabulary: app-open uses
+ * the same placement states, events, and error codes as everything else. The
+ * cost is that a consumer's exhaustive `switch` over this union stops compiling
+ * — the one required migration step, documented in the 0.2.0 release notes.
+ */
+
+/**
+ * Formats that take over the screen, and so contend for the single-show lock.
+ * App-open is included deliberately: two full-screen ads at once is a broken
+ * app regardless of which formats produced them (FR-129).
+ */
+
+function isFullScreenFormat(format) {
+  return format === 'interstitial' || format === 'rewarded' || format === 'app_open';
+}
+
+/**
+ * Declared by the app, because the package cannot depend on any particular
+ * configuration mechanism (FR-015). Cross-checked against the runtime dev flag
+ * so a debug build claiming `production` is caught rather than trusted (FR-012).
+ */
+
+/**
+ * One logical ad slot. `key` is the app's own stable name — `home_footer`, not
+ * an AdMob unit. Provider identifiers appear here in configuration and nowhere
+ * else in consumer code (FR-003, FR-007).
+ */
+
+/**
+ * Bounded retry for failed loads. Off unless `AdsConfig.retry` is supplied —
+ * upgrading from 0.1.0 without configuring this issues not one extra request
+ * (FR-134).
+ *
+ * Only errors already flagged `retryable` are retried. Configuration errors,
+ * consent errors, an unsupported platform, and a disabled or undecided instance
+ * never are (FR-135).
+ *
+ * Backoff is exponential with a fixed x2 multiplier and no jitter. Jitter exists
+ * to desynchronize a fleet hitting one server; a single device retrying its own
+ * load has no herd to avoid, and omitting it keeps the attempt count an exact
+ * assertion rather than a statistical one.
+ */
+
+/**
+ * Whether the app wants ads, including the case where it does not know yet.
+ *
+ * The package never resolves `undecided` on the app's behalf and never learns
+ * why the app chose what it chose — no entitlement, no receipt, no reason
+ * (FR-119, FR-120).
+ */
+
+/**
+ * Tools for exercising the consent flow from a device outside a
+ * consent-required region.
+ *
+ * **Stripped entirely when `environment` is `production`.** That is enforced at
+ * configuration validation rather than at each call site, so no path through the
+ * consent module can forget it, and the fact that they were ignored is
+ * observable through a `config_warning` event and `getIgnoredConsentTools()` —
+ * not merely documented (FR-113).
+ */
+
+/**
+ * Consent status, normalized. Carries no provider type and no payload (FR-104).
+ *
+ * Shaped so an iOS adapter can later express both a consent flow and the
+ * platform's tracking-permission mechanism, plus the ordering between them,
+ * without changing shape.
+ */
+
+/**
+ * Whether the user must be offered a way to change their consent choice
+ * (FR-150), added in 0.4.0.
+ *
+ * The provider's verdict, forwarded — never the package's judgement about a
+ * region, exactly as `not_required` in `ConsentState` is not. `required` is the
+ * app's cue to show its own "Privacy options" entry; where that entry lives and
+ * what it says stay the app's.
+ *
+ * `unknown` before the first successful `requestInfoUpdate()`, after `reset()`,
+ * after a failed update, and on a platform with no adapter. It is not `not_required`:
+ * an app that hides the entry on `unknown` is right to, but it must not conclude
+ * the user has no right to one.
+ */
+
+/** Bounds exist because an unbounded timeout is the same defect as no timeout. */
+
+/** Content ratings, normalized. Maps onto the provider's own rating scale. */
+
+/**
+ * Supplied before initialization (FR-016). Never logged, never persisted
+ * (FR-021). Everything except `canRequestAds` must reach the provider before it
+ * initializes, which is why changing one afterwards reports
+ * `requires_reinitialization` rather than pretending it applied (FR-020).
+ */
+
+/**
+ * Why the consent gate is closed.
+ *
+ * The two original members keep their exact v1 meaning — the app's own gate —
+ * so no existing consumer's interpretation changes. The two added in 0.2.0 name
+ * the package's consent flow instead. The split exists because the gate has two
+ * independent inputs that combine as most-restrictive-wins, and a refusal has to
+ * say *which* of them is blocking or the app cannot act on it (FR-105a).
+ */
+
+/** FR-023. One per instance, observable without holding a provider object. */
+
+/**
+ * FR-026. One per placement. Banners never reach `consumed` — they are
+ * continuous, not single-use.
+ */
+
+/** FR-047. The provider's reward descriptor, normalized. */
+
+/** FR-005. Returned by every subscription; safe to call more than once. */
+//# sourceMappingURL=types.js.map

package/lib/commonjs/config/types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["isFullScreenFormat","format"],"sourceRoot":"../../../src","sources":["config/types.ts"],"mappings":";;;;;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;;AAGO,SAASA,kBAAkBA,CAACC,MAAgB,EAA8B;EAChF,OAAOA,MAAM,KAAK,cAAc,IAAIA,MAAM,KAAK,UAAU,IAAIA,MAAM,KAAK,UAAU;AACnF;;AAEA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;;AAmCA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAUA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAQA;AACA;AACA;AACA;AACA;AACA;AACA;;AAiBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAaA;;AAkDA;;AAGA;AACA;AACA;AACA;AACA;AACA;;AAaA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAMA;;AAqBA;AACA;AACA;AACA;;AAsBA;;AAMA","ignoreList":[]}

package/lib/commonjs/config/validate.js

@@ -0,0 +1,150 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.validateConfig = validateConfig;
+var _errors = require("../diagnostics/errors.js");
+var _resolveAdUnit = require("./resolveAdUnit.js");
+var _timers = require("../core/timers.js");
+var _requestThrottle = require("../core/requestThrottle.js");
+var _enablement = require("../core/enablement.js");
+var _retryPolicy = require("../core/retryPolicy.js");
+/**
+ * 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.
+ */
+
+const FORMATS = new Set(['banner', 'interstitial', 'rewarded', 'app_open']);
+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 _errors.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 _errors.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 _errors.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 _errors.AdsConfigError('duplicate_placement_key', {
+        message: `duplicate placement key "${key}"`,
+        placementKey: key
+      });
+    }
+    if (!FORMATS.has(placement.format)) {
+      throw new _errors.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 _errors.AdsConfigError('missing_ad_unit_id', {
+        message: `placement "${key}" is missing androidAdUnitId`,
+        placementKey: key,
+        format: placement.format
+      });
+    }
+    byKey.set(key, {
+      ...placement,
+      key
+    });
+  }
+  const timeouts = (0, _timers.resolveTimeouts)({
+    timeouts: config.timeouts,
+    adValidityMs: config.adValidityMs,
+    appOpenValidityMs: config.appOpenValidityMs,
+    undecidedWarningMs: config.undecidedWarningMs
+  });
+  const catalog = (0, _resolveAdUnit.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, (0, _retryPolicy.resolveEffectiveRetry)(config.retry, placement.retry, key));
+    minRequestIntervalByKey.set(key, placement.minRequestIntervalMs === undefined ? (0, _requestThrottle.defaultMinRequestIntervalMs)(placement.format) :
+    // A request floor, not a timeout: its own code (ADS-16).
+    (0, _timers.checkBand)(`placements["${key}"].minRequestIntervalMs`, placement.minRequestIntervalMs, _requestThrottle.MIN_REQUEST_INTERVAL_BOUNDS, 'invalid_config'));
+  }
+  const isProduction = config.environment === 'production';
+  const {
+    consentTesting,
+    ignoredConsentTools
+  } = resolveConsentTesting(config.consentTesting, isProduction);
+  return {
+    enablement: (0, _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/commonjs/config/validate.js.map

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