@chipmobilesdk/rn-ads 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,183 @@
 # @chipmobilesdk/rn-ads
 
+## 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
+
+- One diagnostic stream: install a sink with `installSdkSink` from
+  `@chipmobilesdk/rn-core` and it receives what every package observes (events,
+  failures, warnings) as `SdkDiagnostic`s, redacted. Listeners are notified through
+  rn-core, so a listener that throws no longer stops the others nor fails the call that
+  notified, and its error is reported rather than swallowed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a banner's auto-refresh is a new cycle, so its `loaded` and `impression`
+    events are no longer deduplicated away; the dedupe memory is bounded. A throwing
+    status, consent or placement listener is reported as an `internal_error` event.
+  - rn-i18n: new `onDiagnostic` config receives every diagnostic (`I18nDiagnostic`,
+    with a stable `code`); without it, warnings go to `console.warn` in development
+    builds only. The warn-once memory is bounded.
+  - rn-chart: now depends on rn-core for its diagnostics.
+  - rn-payment: status, entitlement and pending listeners report a throw to the logger
+    instead of swallowing it.
+
+- The package's errors extend `SdkError` from the new `@chipmobilesdk/rn-core`
+  dependency: `isSdkError` recognises them alongside every other package's, and each
+  carries `pkg`, `code` and `retryable`. Names and codes are unchanged. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ai and rn-camera: `retryable` is the new name of `recoverable`, which stays as a
+    deprecated alias.
+  - rn-auth: `retryable` is true for `network-unavailable`. `redact` also removes URLs,
+    e-mail addresses and UUIDs.
+  - rn-ads: `redact` also removes JWTs and e-mail addresses, and reduces an `AdsError`
+    to its code.
+  - rn-ai: an error message quoted from the gateway is pattern-redacted.
+  - rn-camera: `redact` also removes JWTs, e-mail addresses and UUIDs.
+  - rn-theme: `ThemeConfigError` has `code: 'invalid_config'` and `ThemeContrastError`
+    `code: 'contrast'` (new `ThemeErrorCode` type).
+  - rn-i18n: `I18nConfigError` has `code: 'invalid_config'` and `UnitConversionError`
+    `code: 'unit_conversion'` (new `I18nErrorCode` type).
+
+- Timers, retries and bounds now come from `@chipmobilesdk/rn-core`, and the drift
+  between the copies is fixed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a retry policy out of bounds throws `retry_out_of_bounds`, as documented,
+    instead of `timeout_out_of_bounds`; a placement's `minRequestIntervalMs` out of
+    bounds throws `invalid_config`.
+  - rn-payment: backoff validates `initialDelayMs` (100 ms to 60 s, not above
+    `maxDelayMs`) and `factor` (1 to 10); `factor: 0` used to retry at once, forever.
+    Every timeout, backoff or interval out of bounds now throws the new
+    `PAYMENT_INVALID_CONFIG` instead of `PAYMENT_INVALID_CATALOG`, which is about
+    products.
+  - rn-ai: concurrent calls share one behavior-config request, so a cold start makes
+    one instead of one per call. A silent retry after a config reload waits
+    `recovery.retryBackoffMs`, which was parsed but never applied.
+
+- Native peers load through `lazyPeer` from `@chipmobilesdk/rn-core`, on first use,
+  and a missing one is each package's own typed error. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: creating `auth` no longer loads react-native-app-auth or
+    react-native-keychain; each loads on first use. New entrypoints
+    `@chipmobilesdk/rn-auth/app-auth` and `/keychain`. The default platform comes from
+    rn-core.
+  - rn-camera: a preview whose VisionCamera feed cannot load fails the session with
+    `cameraUnavailable` (new `controller.reportSurfaceUnavailable()`), instead of
+    showing black with no error. A missing VisionCamera module is `cameraUnavailable`.
+  - rn-notification: `createMmkvStore` reports a fallback to memory as
+    `STATE_STORE_DEGRADED` (to the SDK sinks and a new `onDegraded` option) and
+    exposes `durable`.
+  - rn-payment: an iOS app validates its catalog against the iOS product ids; the
+    default platform used to be Android everywhere. A missing react-native-iap is
+    `PAYMENT_UNAVAILABLE`.
+  - rn-theme: `buildThemes` runs without React Native (new `hairlineWidth` option) and
+    importing the package no longer loads Unistyles; `applyThemeMode` loads it on
+    first use.
+  - rn-ads, rn-local-db: the same loading, with the same error codes as before.
+
+- Hooks read through `useSyncExternalStore` (rn-core's `useExternalStore`) and
+  re-render only when what they return changes. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: `useProfile` and `useAccessTier` no longer re-render for a status change,
+    and the provider's context no longer changes on every transition. New
+    `useAuthSelector`. `auth.getState()` returns the same frozen object until the state
+    changes, instead of a copy per call.
+  - rn-payment: `useEntitlement` re-renders only when its own entitlement changes; the
+    engine keeps unchanged entitlement objects across syncs and does not notify for a
+    sync that changed nothing.
+  - rn-ads: `usePlacementState` and `useAdsStatus` read tear-free; `useAdsEvents` keeps
+    one subscription when given an inline listener.
+  - rn-i18n: `useTranslation` returns the same `t` until the locale changes, and
+    `useLocale`'s `setLocale` is stable.
+  - rn-ai: new `useAiBehaviorState`, with `client.subscribe` and a stable
+    `client.getBehaviorState()`.
+
+- Port conformance suites: one list of checks that a package's fake and its real adapter
+  both pass, so a test written against the fake proves something about the device. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-core: `@chipmobilesdk/rn-core/testing` adds `runChecks`, `expectConformance`,
+    `ensure` and `createFaultRegistry` (deterministic fault injection by named point).
+  - rn-camera: a `./testing` entrypoint with `runPermissionPortConformance`,
+    `runCameraEngineConformance` and the test adapter, which stays on the main
+    entrypoint too until the next major. `createTestCamera(...).prompts()` counts system
+    prompts.
+  - rn-payment: `runProviderPortConformance` in `./testing`, passed by the fake store and
+    the Play adapter.
+  - rn-ads: `runAdsEngineConformance` in `./testing`, passed by the fake engine and the
+    AdMob adapter.
+  - rn-auth: a `./testing` entrypoint with `createMemorySecureStore`,
+    `runSecureTokenStoreConformance` and `runOidcAuthClientConformance`, passed by the
+    in-memory doubles and the keychain and app-auth adapters.
+
+### Patch Changes
+
+- One app-lifecycle source, and a startup that needs no extra frame. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-core: `appLifecycle()`, a shared, reference-counted `AppState` subscription that
+    reports changes only (`active`, `inactive`, `background`), with `onForeground` for a
+    return from the background and `createManualLifecycle` in `./testing`.
+  - rn-camera, rn-ads and rn-notification hear the lifecycle through it instead of
+    subscribing to `AppState` each, so an app holds one native listener. The camera
+    controller's core layer no longer imports `react-native`.
+  - rn-payment: `syncOnForeground(engine)` and `<PaymentProvider syncOnForeground>` call
+    `handleForeground()` on each return from the background. Off by default; calling
+    `handleForeground()` yourself works as before.
+  - rn-i18n: `i18n.initSync()` resolves the locale before the first render when the
+    storage adapter has the new optional `getItemSync`, and returns false otherwise.
+    `localeStorageFromKeyValue(port)` builds such an adapter from rn-core's
+    `KeyValuePort` (MMKV).
+- Updated dependencies ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17)):
+  - @chipmobilesdk/rn-core@0.1.0
+
 ## 0.5.1
 
 ### Patch Changes

package/README.md

@@ -268,10 +268,14 @@ ads.subscribeEvents(event => {
 
 **Ordering and exactly-once** are documented and tested. Within one `correlationId`, `loaded` / `display_started` / `impression` / `dismissed` / `reward_earned` occur at most once; `click` may repeat. After `dispose()`, zero events are emitted — a late provider callback is dropped.
 
-**Errors** carry a stable `code`, a log-safe `message`, the `operation`, a `retryable` flag, and a redacted `cause`. Codes are public API; renaming one is a breaking change.
+**Errors** carry a stable `code`, a log-safe `message`, the `operation`, a `retryable` flag, and a redacted `cause`. Codes are public API; renaming one is a breaking change. `AdsError` extends `SdkError` from `@chipmobilesdk/rn-core`, so `isSdkError(error)` recognises it alongside every other package's errors, `error.pkg` names this package, and `error.redactedCause` (when present) is the underlying failure reduced to log-safe text.
+
+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` `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:
 
@@ -741,6 +745,11 @@ engine.failConsentInfoRead();                   // the re-read after a failure r
 engine.consentCalls                             // includes 'showPrivacyOptionsForm'
 ```
 
+`runAdsEngineConformance(harness)` from `./testing` holds the checks every `AdsEngine`
+must pass — initialization, `loaded` reaching a subscriber and nothing after it
+unsubscribes, a reward and a dismissal, one handle per ad, and a dispose that is safe
+twice. The package runs it against the fake engine and the AdMob adapter.
+
 On device, verify with Google's official test ads only. `npm run android`, then exercise each `Ads · …` screen in the demo app.
 
 ---
@@ -797,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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-ads",
-	"version": "0.5.1",
+	"version": "0.7.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",
@@ -31,9 +31,12 @@
 	],
 	"sideEffects": false,
 	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
 		"pack:check": "npm pack --dry-run"
 	},
+	"dependencies": {
+		"@chipmobilesdk/rn-core": "^0.1.0"
+	},
 	"peerDependencies": {
 		"react": ">=19",
 		"react-native": ">=0.85",

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

@@ -173,8 +173,9 @@ policy; everything else returns a typed result rather than throwing) · `AdsProv
 `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).
+`defaultMinRequestIntervalMs` · `createFakeAdsEngine`, `createTestClock`,
+`runAdsEngineConformance`, `allTestAdUnits` from `@chipmobilesdk/rn-ads/testing` (test
+doubles only).
 
 Instance: `initialize`, `updatePrivacy`, `setEnabled`, `setEnablement`, `setAppActive`,
 `consent`, `getStatus`, `subscribeStatus`, `load`, `show`, `getPlacementState`,

package/src/config/validate.ts

@@ -146,10 +146,12 @@ export function validateConfig(config: AdsConfig, options: ValidateOptions): Res
 			key,
 			placement.minRequestIntervalMs === undefined
 				? defaultMinRequestIntervalMs(placement.format)
-				: checkBand(
+				: // A request floor, not a timeout: its own code (ADS-16).
+					checkBand(
 						`placements["${key}"].minRequestIntervalMs`,
 						placement.minRequestIntervalMs,
 						MIN_REQUEST_INTERVAL_BOUNDS,
+						'invalid_config',
 					),
 		);
 	}