@chipmobilesdk/rn-ads 0.2.0 → 0.3.0

package/package.json

@@ -1,49 +1,49 @@
-{
-	"name": "@chipmobilesdk/rn-ads",
-	"version": "0.2.0",
-	"private": false,
-	"license": "UNLICENSED",
-	"main": "src/index.ts",
-	"types": "src/index.ts",
-	"exports": {
-		".": {
-			"types": "./src/index.ts",
-			"react-native": "./src/index.ts",
-			"default": "./src/index.ts"
-		},
-		"./testing": {
-			"types": "./src/testing/index.ts",
-			"react-native": "./src/testing/index.ts",
-			"default": "./src/testing/index.ts"
-		}
-	},
-	"files": [
-		"src/index.ts",
-		"src/config",
-		"src/core",
-		"src/diagnostics",
-		"src/engine",
-		"src/react",
-		"src/testing",
-		"skills",
-		"README.md",
-		"CHANGELOG.md"
-	],
-	"sideEffects": false,
-	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
-		"pack:dry-run": "npm pack --dry-run"
-	},
-	"peerDependencies": {
-		"react": ">=19",
-		"react-native": ">=0.85",
-		"react-native-google-mobile-ads": ">=16.0.3 <16.1.0"
-	},
-	"engines": {
-		"node": ">=22.11.0"
-	},
-	"publishConfig": {
-		"access": "public",
-		"registry": "https://registry.npmjs.org/"
-	}
-}
+{
+	"name": "@chipmobilesdk/rn-ads",
+	"version": "0.3.0",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"react-native": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./testing": {
+			"types": "./src/testing/index.ts",
+			"react-native": "./src/testing/index.ts",
+			"default": "./src/testing/index.ts"
+		}
+	},
+	"files": [
+		"src/index.ts",
+		"src/config",
+		"src/core",
+		"src/diagnostics",
+		"src/engine",
+		"src/react",
+		"src/testing",
+		"skills",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"pack:dry-run": "npm pack --dry-run"
+	},
+	"peerDependencies": {
+		"react": ">=19",
+		"react-native": ">=0.85",
+		"react-native-google-mobile-ads": ">=16.0.3 <16.1.0"
+	},
+	"engines": {
+		"node": ">=22.11.0"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

package/skills/sdk-rn-ads/SKILL.md

@@ -1,98 +1,240 @@
----
-name: sdk-rn-ads
-description: "Advertising via @chipmobilesdk/rn-ads: AdMob banner/interstitial/rewarded behind a provider-neutral contract, placement keys, consent gating, per-environment test-ad substitution. Use when adding ads to a screen, debugging an ad that never loads, mapping ad units per environment, or answering a Data safety question about advertising."
-metadata:
-  package: "@chipmobilesdk/rn-ads"
-  packageVersion: "0.1.0"
-user-invocable: true
-disable-model-invocation: false
----
-
-# @chipmobilesdk/rn-ads
-
-Adaptive banner, interstitial and rewarded ads on Android via Google AdMob, behind a
-contract that names no provider. The app names a placement key; the package owns the
-request. Consuming code never imports the Google Mobile Ads SDK.
-
-## Use this when
-
-- Adding a banner, interstitial or rewarded ad to a screen
-- Mapping AdMob ad units to placement keys per environment
-- Debugging an ad that never loads, or a `blocked` / `unavailable` / `provider_error`
-- Wiring consent so requests cannot precede it
-- Answering a Data safety / App Privacy question about advertising
-
-## Do not use this for
-
-- **Consent UI or copy** — the package consumes a gate outcome and enforces ordering; it
-  renders no dialog and ships no legal text.
-- **Where or how often ads appear** — no frequency cap, no placement rule, no auto-insert.
-- **Granting the reward** — it reports `reward_earned`; entitlement is the app's.
-- iOS — not implemented; every call returns `unavailable` / `unsupported_platform`.
-
-## Nothing loads until consent and initialization complete
-
-This is enforced, and it is the answer to almost every "the ad never appears". With the
-gate withheld, **zero** provider calls occur — not even configuration. `childDirected`,
-`underAgeOfConsent` and `maxAdContentRating` take effect only if they reach
-`initialize()` *before* the provider starts; changing one later returns
-`requires_reinitialization` rather than silently not applying.
-See `## Initialize — consent comes first`.
-
-## Never gate `<AdsBanner>` on its own placement state
-
-`AdsBanner` is what measures the container and starts the load, so it must be mounted
-unconditionally. Rendering it only when the state is `loading`/`ready` deadlocks at
-`idle` and no ad ever appears. Use the state for the *surrounding* placeholder and to
-decide whether to hold or reclaim space — never to decide whether to mount the host. It
-renders `null` on its own when there is nothing to show.
-
-## Two things not to "fix"
-
-- **The bridge pin.** `react-native-google-mobile-ads` is peered at `>=16.0.3 <16.1.0`;
-  16.1.0+ carries Kotlin 2.3 metadata that React Native 0.85's pinned compiler cannot
-  read, and the Android build fails outright. Read `## Compatibility` before widening it.
-- **Test ads in dev.** Outside `production`, non-official ad units are replaced with
-  Google's test units and reported via `config_warning` / `getSubstitutedPlacements()`.
-  That is the safety guarantee working, not a misconfiguration. Never click a production
-  ad to verify anything.
-
-## Public API (v0.1.0)
-
-Runtime: `createAds` (throws `AdsConfigError` on a bad catalog; everything else returns a
-typed result rather than throwing) · `AdsProvider`, `useAds` · `AdsBanner` ·
-`usePlacementState`, `useAdsStatus`, `useAdsEvents` · `AdsError`, `AdsConfigError`,
-`isAdsError`, `isFullScreenFormat` · `DEFAULT_LOAD_TIMEOUT_MS`, `DEFAULT_SHOW_TIMEOUT_MS`,
-`DEFAULT_AD_VALIDITY_MS`, `LOAD_TIMEOUT_BOUNDS`, `SHOW_TIMEOUT_BOUNDS`,
-`AD_VALIDITY_BOUNDS` · `createFakeAdsEngine` from `@chipmobilesdk/rn-ads/testing`
-(test doubles only).
-
-Instance: `initialize`, `updatePrivacy`, `setEnabled`, `setAppActive`, `getStatus`,
-`subscribeStatus`, `load`, `show`, `getPlacementState`, `subscribePlacement`,
-`subscribeEvents`, `getSubstitutedPlacements`, `dispose`.
-
-Types: `AdsInstance`, `AdsConfig`, `PlacementDefinition`, `PrivacyOptions`, `AdFormat`,
-`FullScreenFormat`, `Environment`, `InitStatus`, `PlacementState`, `InitResult`,
-`LoadResult`, `ShowResult`, `PrivacyUpdateResult`, `Reward`, `AdEvent`, `AdEventType`,
-`AdEventListener`, `ImpressionSource`, `AdsErrorCode`, `AdsOperation`, `TimeoutConfig`,
-`AdContentRating`, `PrivacyBlockReason`, `UnavailableReason`, `Unsubscribe`,
-`AdsBannerProps`, `AdsProviderProps`.
-
-Call `dispose()` when the owning screen unmounts; it is idempotent, and so is every
-`Unsubscribe`.
-
-## Where the detail lives
-
-Read one section of `node_modules/@chipmobilesdk/rn-ads/README.md`:
-
-| Need | Section |
-|---|---|
-| First integration | `## Install`, `## Configure` |
-| Consent ordering | `## Initialize — consent comes first` |
-| Rendering a banner | `## Banner` |
-| Full-screen formats | `## Interstitial and rewarded` |
-| Results, events, errors, timeouts, cleanup | `## State, events, and errors` |
-| Tests without a device | `## Testing` |
-| Permissions, Data safety, families | `## Install`, `## Release checklists` |
-| Build failure after a bridge upgrade | `## Compatibility` |
-| What is deferred | `## Known limitations`, `## Extending to iOS` |
+---
+name: sdk-rn-ads
+description: "Advertising via @chipmobilesdk/rn-ads: AdMob banner/interstitial/rewarded/app-open behind a provider-neutral contract, placement keys, optional consent orchestration, three-state enablement, bounded retry, per-environment test-ad substitution, per-placement request throttling. Use when adding ads to a screen, running a consent flow without importing AdMob, deferring ads until a purchase check resolves, debugging an ad that never loads or reports throttled, placing a banner inside a list or a view the user swipes between, mapping ad units per environment, or answering a Data safety question about advertising."
+metadata:
+  package: "@chipmobilesdk/rn-ads"
+  packageVersion: "0.3.0"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# @chipmobilesdk/rn-ads
+
+Adaptive banner, interstitial, rewarded and app-open ads on Android via Google AdMob,
+behind a contract that names no provider. The app names a placement key; the package owns
+the request. Consuming code never imports the Google Mobile Ads SDK — including for
+consent.
+
+## Use this when
+
+- Adding a banner, interstitial, rewarded or app-open ad to a screen
+- Running a consent flow in a region that requires one, without importing AdMob
+- Deferring ads at startup until a purchase or entitlement check answers
+- Turning ads back on after a subscription lapses or a refund lands
+- Mapping AdMob ad units to placement keys per environment
+- Debugging an ad that never loads, or a `blocked` / `undecided` / `unavailable` /
+  `ad_originated_return` / `provider_error`
+- Answering a Data safety / App Privacy question about advertising
+
+## Do not use this for
+
+- **Consent UI or copy** — the package *orchestrates* the provider's flow and normalizes
+  the outcome, but the form is drawn by the provider and the legal text is theirs. Timing,
+  surrounding copy and the "change your mind" path stay yours.
+- **Where or how often ads appear** — no frequency cap, no placement rule, no auto-insert.
+  The package never shows an ad on its own, app-open included.
+- **Granting the reward** — it reports `reward_earned`; entitlement is the app's.
+- **Anything about payments** — the undecided state exists *because* apps sell ad removal,
+  but the package receives a decision and never a reason, receipt or entitlement.
+- iOS — not implemented; every call returns `unavailable` / `unsupported_platform`.
+
+## Nothing loads until consent and initialization complete
+
+This is enforced, and it is the answer to almost every "the ad never appears". With the
+gate withheld, **zero** provider calls occur — not even configuration. `childDirected`,
+`underAgeOfConsent` and `maxAdContentRating` take effect only if they reach
+`initialize()` *before* the provider starts; changing one later returns
+`requires_reinitialization` rather than silently not applying.
+See `## Initialize — consent comes first` and `## Consent`.
+
+## Three gates, one reason — check this order first
+
+A refused request reports exactly one reason, and the precedence is fixed:
+**platform availability → enablement → consent**, most immovable first. So
+`unsupported_platform` on a disabled instance is reported as `unsupported_platform` —
+turning ads on would not have helped. Full table in `## Why an ad did not show`.
+
+## Never gate `<AdsBanner>` on its own placement state
+
+`AdsBanner` is what measures the container and starts the load, so it must be mounted
+unconditionally. Rendering it only when the state is `loading`/`ready` deadlocks at
+`idle` and no ad ever appears. Use the state for the *surrounding* placeholder and to
+decide whether to hold or reclaim space — never to decide whether to mount the host. It
+renders `null` on its own when there is nothing to show.
+
+## `undecided` is not `disabled`, and that is the whole point
+
+`enabled` takes `true`, `false` or `'undecided'`. All three send zero requests except
+`true`. `'undecided'` reports itself distinctly — in `getStatus()` and in the banner's
+placement state — so an app that has not yet heard back from the store can **hold** the
+banner's space instead of reclaiming it, and a paying user never sees an ad flash in and
+out. `disabled` means a settled no; reclaim the space.
+
+The package never resolves it for you. Leave it unresolved past `undecidedWarningMs`
+(default 10s) and you get exactly one `config_warning`, never a stream.
+
+## `setEnabled` returns a result — read it
+
+In 0.1.0 it returned `void` and re-enabling after a disable silently dropped the init
+status, so every later `load` and `show` was refused with nothing to say so. That was a
+defect and it is fixed. The result now says which happened:
+
+- `resumed` — the provider was never un-initialized; load away, zero provider calls made.
+- `requires_initialization` — call `initialize()` yourself. The package will **not** do it
+  implicitly, because that would hide an async, billable operation behind a setter.
+
+Existing `ads.setEnabled(false);` call sites still compile untouched.
+
+## A banner in a list or a swipeable view gets throttled — by design
+
+New in 0.3.0. A banner mounted inside a view the user navigates between — a day in a
+calendar, a tab, a row that scrolls in and out — is unmounted and remounted by React on
+every navigation, and **each remount is a billable request**. Ten quick swipes used to be
+ten requests in a few seconds, which ad networks read as invalid traffic. The penalty is
+account-level and no shipped fix recovers it.
+
+So each placement now has a minimum interval between *requests*: **60s for a banner**
+(AdMob's own refresh floor), **off for full-screen formats** — those are loaded by an
+explicit call, not mounted by a renderer, so they never had the problem. A refusal reports
+`throttled` on the placement and emits `request_throttled` with `retryAfterMs`.
+
+Three things to know before you reach for `minRequestIntervalMs: 0`:
+
+- **`throttled` is not `failed` and not a no-fill.** Nothing is wrong and nothing was
+  requested. Collapse the space if you like, but do not log it as an error.
+- **Rotation is exempt.** A width re-adaptation inside one mount is not charged, so a
+  rotated screen keeps its banner.
+- **The better fix is architectural.** Keep the banner outside the subtree that remounts
+  and the throttle never fires. It is a safety net, not a licence to ignore the problem.
+
+This is **not** a frequency cap. It limits how often a placement may *ask*; how often you
+*show* is yours, and the package deliberately ships no pacing (see `## Do not use this for`).
+
+## Five things not to "fix"
+
+- **The bridge pin.** `react-native-google-mobile-ads` is peered at `>=16.0.3 <16.1.0`;
+  16.1.0+ carries Kotlin 2.3 metadata that React Native 0.85's pinned compiler cannot
+  read, and the Android build fails outright. `0.2.0` needed no bump — consent and
+  app-open are both already in `16.0.3`. Read `## Compatibility` before widening it.
+- **Test ads in dev.** Outside `production`, non-official ad units are replaced with
+  Google's test units and reported via `config_warning` / `getSubstitutedPlacements()`.
+  That is the safety guarantee working, not a misconfiguration. Never click a production
+  ad to verify anything.
+- **Consent tools going quiet in production.** `consentTesting.debugGeography` and
+  `resetOnStart` are stripped at config validation in `production` and listed by
+  `getIgnoredConsentTools()`. Working as designed.
+- **A declined consent still reporting `obtained` / `canRequestAds: true`.** That is UMP's
+  meaning, not a bug: `OBTAINED` means *an answer was recorded*, and non-personalized ads
+  stay servable. The package forwards the provider's verdict rather than inventing one.
+- **A banner reporting `throttled` right after a navigation.** That is 0.3.0's request
+  floor working — see the section above. Lower it knowingly or move the banner out of the
+  remounting subtree; do not set `0` to make the symptom go away.
+
+## Retry is off unless you ask
+
+No `retry` in config means the request count is byte-identical to 0.1.0 — a test in the
+package proves it. When enabled it is bounded (default 2 retries, 2s then 4s, no jitter),
+retries only errors already flagged `retryable`, and cancels everything on disable,
+undecided, consent loss or `dispose()`. Every attempt emits `retry_scheduled` carrying the
+load cycle's `correlationId`, because every attempt is a billable request.
+Per-placement `retry: false` turns it off for one placement.
+
+## App-open: the one rule you cannot implement yourself
+
+App-open shares the single full-screen lock with interstitial and rewarded, and expires on
+its own shorter window (30 min default, vs 60). The part worth knowing: a show requested
+on a return **from an ad** — or from a browser an ad opened — is refused with
+`ad_originated_return`, distinct from `busy` and `not_ready`. Your app cannot tell that
+return apart from any other; the package can. It cannot survive process death, and a
+browser opened without a preceding click is undetectable. See `## App open`.
+
+## Public API (v0.3.0)
+
+Runtime: `createAds` (throws `AdsConfigError` on a bad catalog or an out-of-range retry
+policy; everything else returns a typed result rather than throwing) · `AdsProvider`,
+`useAds` · `AdsBanner` · `usePlacementState`, `useAdsStatus`, `useAdsEvents` · `AdsError`,
+`AdsConfigError`, `isAdsError`, `isFullScreenFormat` · `DEFAULT_LOAD_TIMEOUT_MS`,
+`DEFAULT_SHOW_TIMEOUT_MS`, `DEFAULT_AD_VALIDITY_MS`, `DEFAULT_APP_OPEN_VALIDITY_MS`,
+`DEFAULT_RETRY_POLICY`, `DEFAULT_UNDECIDED_WARNING_MS`, `LOAD_TIMEOUT_BOUNDS`,
+`SHOW_TIMEOUT_BOUNDS`, `AD_VALIDITY_BOUNDS`, `APP_OPEN_VALIDITY_BOUNDS`, `RETRY_BOUNDS`,
+`UNDECIDED_WARNING_BOUNDS`, `DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS`,
+`DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS`, `MIN_REQUEST_INTERVAL_BOUNDS`,
+`defaultMinRequestIntervalMs` · `createFakeAdsEngine`, `createTestClock` from
+`@chipmobilesdk/rn-ads/testing` (test doubles only).
+
+Instance: `initialize`, `updatePrivacy`, `setEnabled`, `setEnablement`, `setAppActive`,
+`consent`, `getStatus`, `subscribeStatus`, `load`, `show`, `getPlacementState`,
+`subscribePlacement`, `subscribeEvents`, `getSubstitutedPlacements`,
+`getIgnoredConsentTools`, `dispose`.
+
+Consent namespace (`ads.consent.*`, opt-in — untouched, nothing starts):
+`requestInfoUpdate`, `showFormIfRequired`, `getState`, `subscribe`, `reset`.
+
+Types: `AdsInstance`, `AdsConfig`, `PlacementDefinition`, `PrivacyOptions`, `AdFormat`,
+`FullScreenFormat`, `Environment`, `Enablement`, `EnablementResult`, `ConsentApi`,
+`ConsentState`, `ConsentSnapshot`, `ConsentTestingOptions`, `RetryPolicy`, `InitStatus`,
+`PlacementState`, `InitResult`, `LoadResult`, `ShowResult`, `PrivacyUpdateResult`,
+`Reward`, `AdEvent`, `AdEventType`, `AdEventListener`, `ConfigWarning`, `ImpressionSource`,
+`AdsErrorCode`, `AdsOperation`, `TimeoutConfig`, `AdContentRating`, `PrivacyBlockReason`,
+`UnavailableReason`, `Unsubscribe`, `AdsBannerProps`, `AdsProviderProps`.
+
+Call `dispose()` when the owning screen unmounts; it is idempotent, and so is every
+`Unsubscribe`.
+
+## Upgrading 0.2.x → 0.3.0
+
+One compile-time change and one behaviour change.
+
+| Union | New member |
+|---|---|
+| `PlacementState` | `'throttled'` |
+| `LoadResult` | `{ status: 'throttled', retryAfterMs }` |
+| `AdEventType` | `'request_throttled'` |
+
+**The behaviour change:** banner placements now have a 60s floor between requests. If your
+banner lives inside a list row, a tab, or a view the user swipes between, it will report
+`throttled` after a quick navigation where 0.2.x silently issued another request. That was
+the bug; this is the fix. Read the throttle section above before setting
+`minRequestIntervalMs: 0`.
+
+Full-screen formats are unchanged — their default floor is `0`.
+
+## Upgrading 0.1.0 → 0.2.0
+
+One required change, compile-time only: five unions gained members, so an exhaustive
+`switch` over any of them needs the new cases or a `default`.
+
+| Union | New members |
+|---|---|
+| `AdFormat` | `'app_open'` |
+| `InitStatus` | `'undecided'` |
+| `PlacementState` | `'undecided'` |
+| `PrivacyBlockReason` | `'consent_flow_required'`, `'consent_flow_error'` |
+| `AdsErrorCode` | `'undecided'`, `'ad_originated_return'`, `'consent_flow_required'`, `'consent_flow_failed'`, `'retry_out_of_bounds'` |
+
+Everything else is opt-in: consent, `'undecided'`, app-open and retry are all off or absent
+until configured. One behavior change needs no action — on an unavailable platform with
+ads also disabled, the reason is now `unsupported_platform` where 0.1.0 said `disabled`.
+
+## Where the detail lives
+
+Read one section of `node_modules/@chipmobilesdk/rn-ads/README.md`:
+
+| Need | Section |
+|---|---|
+| First integration | `## Install`, `## Configure` |
+| Consent ordering | `## Initialize — consent comes first` |
+| Running the consent flow | `## Consent` |
+| Rendering a banner | `## Banner` |
+| Full-screen formats | `## Interstitial and rewarded` |
+| App-open and ad-originated return | `## App open` |
+| Turning ads off, undecided, re-enabling | `## Turning ads off — three states` |
+| Retry and reconciling it against a bill | `## Retry` |
+| Request throttling, banners in lists | `## Request throttling` |
+| Why a request was refused | `## Why an ad did not show` |
+| Results, events, errors, timeouts, cleanup | `## State, events, and errors` |
+| Tests without a device | `## Testing` |
+| Permissions, Data safety, families | `## Install`, `## Release checklists` |
+| Build failure after a bridge upgrade | `## Compatibility` |
+| Migration detail | `## Versioning` |
+| What is deferred | `## Known limitations`, `## Extending to iOS` |

package/src/config/types.ts

@@ -65,6 +65,18 @@ export interface PlacementDefinition {
 	 * override can narrow behavior but never exceed a ceiling (FR-136a).
 	 */
 	readonly retry?: RetryPolicy | false;
+	/**
+	 * Minimum milliseconds between two provider requests for this placement
+	 * (FR-140), added in 0.3.0.
+	 *
+	 * Absent takes the format-aware default: 60s for a banner, off for full-screen
+	 * formats. `0` turns it off here while leaving it on elsewhere.
+	 *
+	 * This is an **account-safety** floor, not a frequency cap: it limits how often
+	 * a placement may *ask* for an ad, never how often the app may *show* one. If
+	 * you are reaching for this to pace interstitials, that belongs in the app.
+	 */
+	readonly minRequestIntervalMs?: number;
 }
 
 /**
@@ -269,6 +281,16 @@ export type PlacementState =
 	| 'failed'
 	/** Mirrors `InitStatus.undecided` so the banner host can report it directly. */
 	| 'undecided'
+	/**
+	 * Refused by the per-placement request throttle (FR-140), added in 0.3.0.
+	 *
+	 * Deliberately distinct from `failed` and from a no-fill: nothing is wrong,
+	 * nothing was requested, and the same placement will work again shortly. An
+	 * app that collapses its ad slot on `failed` will usually want to collapse on
+	 * this too, but it must be able to tell the two apart when diagnosing why a
+	 * banner is absent.
+	 */
+	| 'throttled'
 	| 'unavailable';
 
 /** FR-047. The provider's reward descriptor, normalized. */