novvy-ads-react-native-admob 0.0.0-stage → 1.2.1-stable.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+## 1.2.1-stable.0
+
+Unreleased — not yet published to npm.
+
+Initial release. Delivers the native AdMob mediation adapter — rewarded,
+interstitial and banner served to an existing AdMob waterfall as a custom
+event — on both platforms:
+
+- **Android**: `ai.novvy.android:admob-adapter:1.2.0.0` from Maven Central,
+  as a single `implementation` line. The AAR carries its own
+  `consumer-rules.pro`, so R8 keeps the adapter class even though nothing
+  references it at compile time.
+- **iOS**: the adapter's Swift sources, compiled into this package's pod and
+  linked against the `NovvyAds.xcframework` that `novvy-ads-react-native`
+  vendors. `pod install` fetches them from the `admob-v1.2.1.0` tag of
+  `novvy-ads-cocoapods` — always from the tag, never from a local checkout —
+  and the pod adds `-ObjC` to the app's link flags itself, which a stock React
+  Native `Podfile` does not supply.
+
+No JavaScript API. The package exports four version constants for diagnostics
+(`NOVVY_ADMOB_ADAPTER_VERSION_ANDROID` / `_IOS`,
+`NOVVY_ADS_CORE_VERSION_ANDROID` / `_IOS`) and nothing else; adding the
+dependency is the entire integration, and autolinking finds both native halves
+without a `react-native.config.js`.
+
+Requires:
+
+- `novvy-ads-react-native` **exactly `1.2.1`**. Each native half is compiled
+  against one core; a range risks two SDK instances in the process, which is a
+  permanent silent no-fill. `1.2.1` is the first GA core — it carries the
+  banner placement that `1.2.0-beta.1` introduced as a prerelease, with the
+  native SDKs split onto independent version lines (iOS 1.2.1, Android 1.2.0).
+- `react-native-google-mobile-ads` **`>=15.0.0 <16.1.0`**. The iOS adapter needs
+  Google Mobile Ads SDK 12.x, and RNGMA pins GMA to an exact version, so the
+  usable window is narrow. A 16.1+ host fails at `pod install`.
+- React Native 0.76+ with the New Architecture, Android `minSdk` 24, iOS 13.0.
+
+Android places no constraint on the Google Mobile Ads version: the adapter
+compiles against `play-services-ads` as `compileOnly`, so the host keeps
+ownership of it and this package declares no Gradle dependency on it.
+
+> Versions: this package's version names the `novvy-ads-react-native` version it
+> is built against (`1.2.1`) plus a release counter (`-stable.0`). The native
+> adapters it delivers are versioned separately, per platform, as the core each
+> was compiled against plus a revision — Android `1.2.0.0`, iOS `1.2.1.0`. The
+> three lines spell three different strings at this release and that is the
+> scheme working, not drift: the npm line follows the core npm package, the
+> native lines follow their own platforms' SDKs. See the README.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) NovvyAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NovvyAdsReactNativeAdMob.podspec

@@ -0,0 +1,237 @@
+# iOS half of novvy-ads-react-native-admob.
+#
+# There is no source file of our own in this pod — see the `source_files` note
+# below. Everything here exists to get the adapter's Swift sources compiled into
+# the host app and to stop the linker from throwing them away again.
+
+# The two values a release edits.
+#
+# Composed rather than written out, so the NovvyAds version this pod's sources
+# were cut against and the version encoded in the pod's own version are the same
+# string by construction. Mirrors `novvy-ads-cocoapods/NovvyAdsAdMob.podspec`
+# and the Flutter package's `novvy_ads_admob.podspec`, which compose the same
+# two values for the same reason — and the reason is worth restating:
+# `1.2.0-beta.1.0` split as core `1.2.0-beta` + revision `1.0` just as readily
+# as it split the way it was meant, and both spellings look plausible enough to
+# publish.
+#
+# ⚠️ These two are the NATIVE version line. They are not this npm package's
+# `version` field, which tracks `novvy-ads-react-native` instead and reads
+# `1.2.1-stable.0` at this release — visibly a different string from
+# `1.2.1.0`, which is the divergence the previous release's comment predicted
+# for the day the core reached GA. The two lines move independently — see the
+# "two version lines" table in docs/plan/admob-mediation.md §四, and the
+# exported constants in index.js, which are generated from nothing and must be
+# edited alongside these.
+#
+# ⚠️ The native line is per-platform since the core's 1.2.1 generation:
+# `novvy-ads-react-native` 1.2.1 vendors NovvyAds iOS 1.2.1 while resolving
+# `ai.novvy.android:sdk:1.2.0` on Android, so this pod's sources come from the
+# `admob-v1.2.1.0` tag while `android/build.gradle` pins the Android adapter at
+# `1.2.0.0`. The iOS line moved; the Android one deliberately did not — see the
+# comment on that coordinate.
+NOVVY_ADS_VERSION = '1.2.1'
+ADAPTER_REVISION  = 0
+
+# The tag in `novvy-ads-cocoapods` the adapter sources come from, and the stamp
+# value `prepare_command` writes so a second `pod install` is a no-op.
+ADAPTER_TAG = "admob-v#{NOVVY_ADS_VERSION}.#{ADAPTER_REVISION}"
+ADAPTER_TARBALL = "https://github.com/NovvyAI/novvy-ads-cocoapods/archive/refs/tags/#{ADAPTER_TAG}.tar.gz"
+
+Pod::Spec.new do |s|
+  s.name    = 'NovvyAdsReactNativeAdMob'
+  s.version = "#{NOVVY_ADS_VERSION}.#{ADAPTER_REVISION}"
+
+  s.summary     = 'AdMob mediation adapter for the Novvy Ads React Native SDK.'
+  s.description = <<-DESC
+Lets an existing AdMob waterfall call Novvy as a custom event. Carries the
+native adapter into the host build; no JavaScript API and no TurboModule.
+                  DESC
+  s.homepage = 'https://novvy.ai/'
+  # The package's own LICENSE, not the repo root's. A `:file => '../LICENSE'`
+  # would resolve in this checkout and fail for every consumer, because npm ships
+  # only what package.json's `files` whitelist names — the repo root is not in
+  # the tarball.
+  s.license  = { :type => 'MIT', :file => 'LICENSE' }
+  s.author   = { 'NovvyAI' => 'dev@novvy.ai' }
+
+  # Never fetched by CocoaPods. React Native's autolinking always declares this
+  # pod as `:path => '../node_modules/novvy-ads-react-native-admob'`, so the
+  # source is whatever npm installed. Deliberately not `:git => ..., :tag =>
+  # "#{s.version}"` like the SDK repo's podspec: s.version here is the native
+  # line (`1.2.1.0`) and no git tag by that name exists in this repo.
+  s.source   = { :path => '.' }
+  s.platform = :ios, '13.0'
+  s.swift_version = '5.0'
+
+  # The adapter sources, put there by `prepare_command` below — not in git.
+  #
+  # ⚠️ Asymmetry with the Flutter package, which also lists a `Classes/**/*`
+  # holding an empty plugin registrant: Flutter's tooling requires a registrant
+  # class per plugin, so it has a file there with nothing in it. React Native's
+  # iOS autolinking names no plugin class at all — it discovers pods from the
+  # podspec and TurboModules from codegen, neither of which this package has. So
+  # the iOS half needs zero source files of its own.
+  #
+  # This is the exact mirror image of Android, where RN is the platform that
+  # *does* demand an empty registration class (see NovvyAdsAdMobPackage.kt) and
+  # Flutter's requirement is the silent one. Neither framework is consistently
+  # stricter; each is strict on a different side.
+  s.source_files = 'ios/NovvyAdsAdMob/**/*.swift'
+
+  # Where `import NovvyAds` resolves from: NovvyAdsReactNative vendors
+  # NovvyAds.xcframework and CocoaPods propagates a dependency's
+  # FRAMEWORK_SEARCH_PATHS to dependent pod targets.
+  #
+  # No version requirement, deliberately. The coupling is real — these sources
+  # come from a tag that pins one exact core version — but it is stated once, in
+  # package.json's exact `peerDependencies` pin, where npm can act on it.
+  # Restating it here would mean two constraints to keep in agreement, and the
+  # podspec's copy would be the one nobody remembers to bump.
+  s.dependency 'NovvyAdsReactNative'
+
+  # The Google Mobile Ads SDK, which on React Native also arrives via
+  # `react-native-google-mobile-ads`. Unlike Android — where the adapter takes
+  # play-services-ads as `compileOnly` and lets the host own the version — a
+  # source pod has no compileOnly: without this dependency GMA's headers are not
+  # on the search path and the adapter does not compile.
+  #
+  # `~> 12.0` is the range the adapter sources are written against (they use the
+  # un-prefixed GMA 12.x Swift API — `MediationAdapter`, `VersionNumber`). It has
+  # to intersect whatever `react-native-google-mobile-ads` asks for, and RNGMA
+  # asks with a *bare* version string, which CocoaPods reads as `= x.y.z`
+  # (RNGoogleMobileAds.podspec:65, value from package.json's
+  # sdkVersions.ios.googleMobileAds). So the intersection is a single point, and
+  # the usable RNGMA range is narrow:
+  #
+  #   react-native-google-mobile-ads 14.2.5  ->  GMA 11.7.0   no intersection
+  #   react-native-google-mobile-ads 15.0.0  ->  GMA 12.2.0   ok  (lower bound)
+  #   react-native-google-mobile-ads 16.0.3  ->  GMA 12.14.0  ok  (upper bound)
+  #   react-native-google-mobile-ads 16.1.0  ->  GMA 13.1.0   no intersection
+  #
+  # Hence the `>=15.0.0 <16.1.0` peer range in package.json. A 16.1+ host fails
+  # during `pod install`, which is the good failure — loud, before a build.
+  #
+  # ⚠️ RNGMA offers an escape hatch that turns that good failure into a bad one:
+  # `$RNGoogleMobileAdsSDKVersion` in the Podfile overrides its GMA version
+  # (RNGoogleMobileAds.podspec:58-61). Forcing 12.14.0 on a 16.1+ host makes
+  # `pod install` succeed and then breaks RNGMA's own code, which is compiled
+  # against the GMA 13 API — compile errors, or worse, a build that links and is
+  # missing symbols at runtime. Supporting GMA 13 means new adapter sources in
+  # novvy-ads-cocoapods, not a wider range here.
+  s.dependency 'Google-Mobile-Ads-SDK', '~> 12.0'
+
+  # Deliberately NOT called: `install_modules_dependencies(s)`.
+  #
+  # The SDK repo's NovvyAdsReactNative.podspec calls it because it has
+  # Objective-C++ and Swift that include React headers and Fabric/TurboModule
+  # glue. This pod has no React Native code of any kind — pulling in React-Core,
+  # folly compiler flags and the new-architecture header search paths would be
+  # build time spent on headers nothing here includes.
+  s.prepare_command = <<-CMD
+    set -e
+    DEST="ios/NovvyAdsAdMob"
+    STAMP="$DEST/.source.version"
+
+    if [ "$(cat "$STAMP" 2>/dev/null)" != "#{ADAPTER_TAG}" ]; then
+      rm -rf "$DEST" ios/NovvyAdsAdMob.tmp
+      mkdir -p ios/NovvyAdsAdMob.tmp
+      curl -fsSL "#{ADAPTER_TARBALL}" | tar -xz -C ios/NovvyAdsAdMob.tmp --strip-components=1
+      if [ ! -d ios/NovvyAdsAdMob.tmp/Adapters/AdMob ]; then
+        echo "NovvyAdsReactNativeAdMob: tag #{ADAPTER_TAG} has no Adapters/AdMob" >&2
+        exit 1
+      fi
+      mkdir -p "$DEST"
+      cp ios/NovvyAdsAdMob.tmp/Adapters/AdMob/*.swift "$DEST/"
+      rm -rf ios/NovvyAdsAdMob.tmp
+      echo "#{ADAPTER_TAG}" > "$STAMP"
+    fi
+
+    # The pod is useless without sources. Fail loudly here rather than let
+    # source_files match nothing and ship an adapter-less build.
+    if [ -z "$(ls "$DEST"/*.swift 2>/dev/null)" ]; then
+      echo "NovvyAdsReactNativeAdMob: no adapter sources in $DEST — refusing to install" >&2
+      exit 1
+    fi
+  CMD
+
+  # Notes on the script above, in rough order of how much trouble each saves.
+  #
+  # **It runs on every `pod install`, and that is what makes this work.**
+  # CocoaPods runs `prepare_command` once for a pod it downloads into its cache,
+  # but for a local pod it runs on every install —
+  # `pod_source_installer.rb`: `PodSourcePreparer.new(...).prepare! if local?`.
+  # Every autolinked React Native package is a `:path` pod pointing into
+  # node_modules, so this is the supported way for one to acquire native
+  # sources. NovvyAdsReactNative.podspec gets NovvyAds.xcframework the same way.
+  #
+  # **One source only: the `admob-v*` tag.** The Flutter package once had a
+  # branch here that symlinked a sibling `novvy-ads-cocoapods` checkout whenever
+  # one existed. It fired on the mere presence of the directory, so the machine
+  # authoring the SDK was the one machine never testing what it shipped — an
+  # uncommitted adapter edit built fine there and did not exist for anyone else.
+  # This package has no such branch and no `NOVVY_ADS_LOCAL_*` escape hatch
+  # either, which is a deliberate asymmetry with NovvyAdsReactNative.podspec:
+  # that one needs its hatch because an unreleased *binary* core cannot be
+  # obtained any other way, whereas adapter *sources* are one `git tag` away.
+  # Editing the adapter means tagging first. `ADAPTER_TAG` is the contract.
+  #
+  # **Copy the files; never symlink the directory.** CocoaPods' `PathList` does
+  # one `Dir.glob(root + '**/*')` and matches `source_files` against that cached
+  # list, never touching the filesystem again (`sandbox/path_list.rb`). Ruby's
+  # `**` does not descend into a symlinked directory, so
+  # `ln -s <checkout>/Adapters/AdMob ios/NovvyAdsAdMob` makes every .swift inside
+  # invisible: the pattern matches zero files, the pod compiles zero adapter
+  # files, **the build succeeds**, and `NovvyAdMobMediationAdapter` is absent
+  # from the binary. AdMob cannot instantiate a class that is not there, and a
+  # missing custom event is a silent no-fill — no crash, no log.
+  #
+  # (NovvyAdsReactNative.podspec symlinks a directory under its local escape
+  # hatch and gets away with it, because `vendored_frameworks` needs only the
+  # top-level entry, which the glob does see. `source_files` needs the children.
+  # Same symlink, opposite outcome — worth knowing before copying a pattern from
+  # a podspec that survives it.)
+  #
+  # After changing anything here, check the binary rather than the build log:
+  #
+  #   nm <app>.app/<binary> | grep '_OBJC_CLASS_$_NovvyAdMobMediationAdapter'
+
+  # A static framework even under a plain dynamic `use_frameworks!`.
+  #
+  # This pod links NovvyAdsReactNative's vendored *dynamic* NovvyAds.xcframework,
+  # and CocoaPods will not build a dynamic framework that links a vendored one.
+  # React Native's default Podfile uses static libraries and never reaches this,
+  # but the SDK repo's own example flips to frameworks when USE_FRAMEWORKS is
+  # set, so the configuration is one env var away from being real.
+  s.static_framework = true
+
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+    # NovvyAds.xcframework ships ios-arm64 and ios-arm64-simulator only.
+    'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'i386 x86_64',
+  }
+
+  s.user_target_xcconfig = {
+    'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'x86_64',
+
+    # The iOS counterpart of the Android adapter's consumer ProGuard rule, and
+    # just as load-bearing.
+    #
+    # AdMob instantiates `NovvyAdMobMediationAdapter` by the class-name string
+    # typed into the dashboard, so nothing references it at compile time and the
+    # linker is free to drop the whole object file. `-ObjC` forces every member
+    # of a linked static archive in. Without it there is no build error and no
+    # log line — the ad source simply never fills.
+    #
+    # ⚠️ Unlike the Flutter package, where this flag is redundant for a host
+    # following the README (`use_frameworks! :linkage => :static` already adds
+    # it), here it is **required in the default configuration**: a stock React
+    # Native Podfile adds no `use_frameworks!` at all and no `-ObjC`, so nothing
+    # else puts the flag in the app's OTHER_LDFLAGS. This is not a belt-and-
+    # braces duplicate. Removing it silently disables the ad source.
+    #
+    # (CocoaPods warns about setting OTHER_LDFLAGS in user_target_xcconfig. The
+    # warning is by far the cheaper problem.)
+    'OTHER_LDFLAGS' => '$(inherited) -ObjC',
+  }
+end

package/README.md

@@ -1,3 +1,314 @@
-# Temporary Holding Version
+# novvy-ads-react-native-admob
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AdMob mediation for the [Novvy Ads React Native SDK](https://www.npmjs.com/package/novvy-ads-react-native).
+Lets a publisher's existing AdMob waterfall call Novvy as a custom event.
+
+**No JavaScript API.** Android and iOS.
+
+## What this package does
+
+Nothing at runtime. It carries the native Novvy AdMob adapter into your app's
+build — which is the only way an npm package can do that without you editing
+`android/` and `ios/` yourself.
+
+A mediated ad never crosses the TurboModule boundary:
+
+```text
+JS:   react-native-google-mobile-ads (BannerAd / InterstitialAd / RewardedAd)
+        → native AdMob SDK → waterfall
+        → reflectively loads NovvyAdMobMediationAdapter
+        → NovvySDK
+```
+
+## Install
+
+```sh
+npm install novvy-ads-react-native-admob
+```
+
+Three packages have to be present, and npm will install the two peers for you if
+they are not already there:
+
+```jsonc
+{
+  "dependencies": {
+    "novvy-ads-react-native": "1.2.1",                     // exact — see Versioning
+    "react-native-google-mobile-ads": "^16.0.3",           // yours; supplies the Google Mobile Ads SDK
+    "novvy-ads-react-native-admob": "1.2.1-stable.0"       // this package
+  }
+}
+```
+
+Then `cd ios && pod install`. There is nothing to import and no
+`react-native.config.js` to write — autolinking finds both halves on its own.
+Adding the dependency is the integration.
+
+> `react-native-google-mobile-ads` **must be `>=15.0.0 <16.1.0`**. See
+> [Requirements](#requirements); a 16.1+ host fails at `pod install`.
+
+### iOS `pod install` needs network access
+
+The adapter's Swift sources are **not** in the npm tarball. The podspec's
+`prepare_command` downloads them from a tag in
+[`novvy-ads-cocoapods`](https://github.com/NovvyAI/novvy-ads-cocoapods) on every
+`pod install`, verifies they landed, and refuses to install if they did not.
+
+This is not an extra requirement so much as an existing one restated:
+`novvy-ads-react-native`'s own podspec fetches `NovvyAds.xcframework` the same
+way, so a machine that cannot reach GitHub cannot install the Novvy iOS SDK at
+all, with or without this package. Shipping a second copy of the sources in the
+tarball would not change that, and it would make the published tarball depend on
+whatever happened to be sitting in the publisher's working directory.
+
+## Two things you must still do
+
+### 1. Initialize Novvy before any AdMob ad is requested
+
+```ts
+import { NovvyAds } from 'novvy-ads-react-native';
+
+await NovvyAds.initialize({
+  appId: 'YOUR_APP_ID',
+  endpoint: 'https://bid.novvy.ai',
+  apiKey: 'YOUR_API_KEY',
+});
+```
+
+The adapter **cannot** initialize the SDK — an app id, endpoint or api key
+mistyped into a dashboard field would be a silent no-fill with no diagnostic
+anywhere, so those values are deliberately not dashboard fields. Every load
+re-checks initialization instead and reports a no-fill while it is missing.
+
+Calling this once at app start, as you would for direct integration, is
+sufficient; it does not need to be tied to AdMob's lifecycle.
+
+### 2. Configure the custom event in the AdMob dashboard
+
+One entry per platform, because the class name is not the same on both:
+
+| Platform | Class Name |
+| --- | --- |
+| Android | `ai.novvy.android.mediation.admob.NovvyAdMobMediationAdapter` |
+| iOS | `NovvyAdMobMediationAdapter` |
+
+| Field | Value |
+| --- | --- |
+| Parameter | `{"adUnitId":"<your Novvy ad unit id>"}` |
+
+The adapter is loaded reflectively from that class-name string — on Android by
+fully-qualified name, on iOS by the adapter's `@objc` name, which is why it is
+unqualified there. Nothing else triggers it, so this step is not optional, and a
+typo produces a no-fill rather than an error.
+
+## Callbacks come from react-native-google-mobile-ads
+
+Lifecycle events for a Novvy ad shown through mediation arrive on the
+`react-native-google-mobile-ads` listeners, **not** on `NovvyAdEvent`. That is
+intended: the mediation layer owns the impression count for these ads, and a
+second set of callbacks would leave you reconciling two numbers that cannot be
+made to agree.
+
+`novvy-ads-react-native`'s own listeners continue to serve direct-integration
+placements (scroll / pause / insert / banner) as usual. The two paths coexist and
+do not interact.
+
+## Supported formats
+
+Rewarded, interstitial and banner.
+
+Banner rotation is switched off on the mediated path: AdMob's `AdView` re-runs
+the whole waterfall on its own interval and hands the adapter a fresh instance
+each time, so a second rotation underneath would swap creatives the mediation
+never counted an impression for.
+
+## User and content targeting
+
+Set through `novvy-ads-react-native` as usual — `NovvyAds.setUserContext(...)` /
+`NovvyAds.setContentContext(...)`. The values are read when a bid request is
+built, so a mediated request picks up whatever is current, with no per-ad
+plumbing.
+
+One consequence worth knowing: a mediated request can be triggered by AdMob at a
+moment you do not control (a banner's own refresh timer, for instance). Keep the
+content context maintained as screen state — updated when the user enters a drama
+or advances an episode — rather than set immediately before a load.
+
+## Requirements
+
+- React Native 0.76+ with the New Architecture, Android `minSdk` 24 and iOS 13.0,
+  matching `novvy-ads-react-native`.
+- **`react-native-google-mobile-ads` `>=15.0.0 <16.1.0`.** The iOS adapter
+  sources are written against the Google Mobile Ads SDK 12.x Swift API and the
+  pod requires `~> 12.0`, which has to intersect what
+  `react-native-google-mobile-ads` asks for. Unlike its Flutter counterpart, it
+  asks with a *bare* version string, which CocoaPods reads as `= x.y.z` — so the
+  intersection is a single point and the usable range is narrow:
+
+  | `react-native-google-mobile-ads` | Google-Mobile-Ads-SDK | |
+  | --- | --- | --- |
+  | 14.2.5 | 11.7.0 | no intersection |
+  | **15.0.0** | 12.2.0 | ok — lower bound |
+  | 15.8.3 | 12.11.0 | ok |
+  | **16.0.3** | 12.14.0 | ok — upper bound |
+  | 16.1.0 | 13.1.0 | no intersection |
+  | 16.5.0 | 13.5.0 | no intersection |
+
+  A 16.1+ host fails during `pod install` — loud, and before a build.
+
+  > ⚠️ **Do not reach for `$RNGoogleMobileAdsSDKVersion`.** That Podfile global
+  > overrides the GMA version `react-native-google-mobile-ads` requests, so a
+  > 16.1+ host can force 12.14.0 and make `pod install` succeed. It then breaks
+  > `react-native-google-mobile-ads`'s own iOS code, which is compiled against
+  > the GMA 13 API — compile errors if you are lucky, a build that links and is
+  > missing symbols at runtime if you are not. Supporting GMA 13 means new
+  > adapter sources upstream, not a wider range here.
+
+  Android is unconstrained: the adapter takes `play-services-ads` as
+  `compileOnly` so the host keeps ownership of that version, which is why this
+  package declares no Gradle dependency on it.
+- Android: your app module needs
+  `freeCompilerArgs += ["-Xskip-metadata-version-check"]`, exactly as
+  `novvy-ads-react-native`'s README already requires — the Novvy native SDK is
+  built with Kotlin 2.2.20 while React Native 0.76 pins the Kotlin plugin to
+  1.9.24. This package inherits the requirement rather than adding one; if you
+  have already installed `novvy-ads-react-native`, the flag is there.
+- iOS: nothing to configure. The pod adds `-ObjC` to your app's link flags
+  itself, and needs to — a stock React Native `Podfile` uses static libraries and
+  adds no `-ObjC` of its own, and without it the linker is free to discard an
+  adapter class that nothing references at compile time. (This differs from the
+  Flutter package, where the recommended `use_frameworks! :linkage => :static`
+  already supplies the flag and the podspec's copy is redundant.) If you override
+  `OTHER_LDFLAGS` in your own build settings, keep `$(inherited)`.
+- Expo: no config plugin is needed — this package has nothing to write into the
+  native projects, unlike the AdMob app id, which
+  `react-native-google-mobile-ads` already handles. Run `npx expo prebuild` and
+  build as usual. Expo Go cannot run it; nothing native can.
+
+## Versioning
+
+This package's version names the `novvy-ads-react-native` version it is built
+against, plus a counter for releases against that version:
+
+| `novvy-ads-react-native` | this package | rule |
+| --- | --- | --- |
+| `1.2.0` (release) | `1.2.0-stable.0`, `1.2.0-stable.1`, … | append `-stable.<N>` |
+| `1.2.0-beta.1` (prerelease) | `1.2.0-beta.1.0`, `1.2.0-beta.1.1`, … | append `.<N>` |
+
+**This release is the first row**: the core it targets, `1.2.1`, is a release,
+so the version is `1.2.1-stable.0`. The core spent one generation as the
+prerelease `1.2.0-beta.1` — where the banner placement first landed — and
+reached GA with the native SDKs split onto independent version lines: iOS
+`NovvyAds` 1.2.1, Android `ai.novvy.android:sdk` 1.2.0. The banner placement
+both lines carry is the same one that prerelease introduced.
+
+The two native artifacts are versioned per platform now, and at this release
+they do not agree with each other either:
+
+| native line | value | where |
+| --- | --- | --- |
+| Android adapter | `ai.novvy.android:admob-adapter:1.2.0.0` | this package's `android/build.gradle` |
+| iOS adapter | sources from the `admob-v1.2.1.0` tag of `novvy-ads-cocoapods` | this package's podspec |
+| Android core | `1.2.0` | resolved transitively by `novvy-ads-react-native` |
+| iOS core | `1.2.1` | vendored by `novvy-ads-react-native` |
+
+The Android adapter deliberately stays on `1.2.0.0`: no `admob-adapter:1.2.1.0`
+exists, and one that pinned `sdk:1.2.1` would drag a second SDK instance into
+the process beside the one `novvy-ads-react-native` initializes — a permanent
+silent no-fill. See the comment on that coordinate in `android/build.gradle`.
+
+`novvy-ads-react-native` is pinned to an **exact** version in
+`peerDependencies`, not a range, and you should pin this package the same way.
+Each native half is built against one specific core version — the Android AAR
+pins `ai.novvy.android:sdk`, and the iOS sources come from a tag that pins
+`NovvyAds` — so if a range let your app resolve a different core, you would get
+either an ABI mismatch or two SDK instances, and the adapter's `isInitialized`
+check would be looking at the one JavaScript did not initialize. The symptom is a
+permanent silent no-fill.
+
+### Why `stable`, and why not `1.2.0-0`
+
+Because the revision has to sort *after* the core prereleases, and semver's
+ordering rules make the obvious spellings wrong.
+
+semver §11.4.3 ranks purely numeric prerelease identifiers **below**
+alphanumeric ones. So the most natural version, `1.2.0-0`, sorts before every
+beta:
+
+```text
+1.2.0-beta.2.0  >  1.2.0-0            ← backwards
+^1.2.0-0        →  1.2.0-beta.2.0     ← `npm update` moves a GA-core adapter back to a beta one
+```
+
+And a beta adapter against a GA core is exactly the mismatch above. So the
+revision must begin with a letter, and that letter has to put the word after
+every prerelease tag the core uses:
+
+| candidate | |
+| --- | --- |
+| `stable`, `rev`, `release` | sorts after `alpha` / `beta` / `rc` |
+| `ga`, `final`, `r`, `dev`, `patch` | all sort **before** `rc` |
+
+The dividing line is `rc`: `g`, `f`, `d` and `p` all precede `r`, and a bare `r`
+is a prefix of `rc` and therefore smaller. The two words that feel most natural,
+`ga` and `final`, are both wrong — which is why this is not a matter of taste.
+
+Two constraints follow, and both are frozen:
+
+1. **`novvy-ads-react-native` prerelease tags are limited to `alpha`, `beta` and
+   `rc`.** `stable` also beats `snapshot`, but `test` or `zeta` would flip the
+   order.
+2. **`stable` cannot be changed.** Any lexically smaller word would make new
+   versions sort before old ones.
+
+`scripts/check-version.js` in this package's repository enforces the
+consequences on every publish. It cannot enforce the causes — see
+[the plan document](https://github.com/NovvyAI/novvy-ads-react-native-mediation/blob/main/docs/plan/admob-mediation.md).
+
+### Two things this buys, and two it costs
+
+The scheme is self-describing: you can read the core version straight out of the
+package version. And because every version of this package is a prerelease, a
+`^` range is **structurally** confined to one core — `^1.2.0-beta.1.0` resolves
+only within `1.2.0-*` and cannot reach `1.3.0-beta.1.0` or `1.3.0-stable.0`,
+where a plain `^1.2.0` on an ordinary package would climb to `1.3.0` without
+asking. That is a stronger guarantee than `peerDependencies`, which reports the
+conflict after the fact.
+
+One thing that range *does* reach is the GA-core adapter for the same core:
+`^1.2.0-beta.1.0` matches `1.2.0-stable.0`, because both are prereleases of
+`1.2.0`. So `npm update` will carry you from a beta-core adapter to a GA-core
+one, while your `novvy-ads-react-native` is still pinned to `1.2.0-beta.1` —
+and npm will refuse the install on the peer conflict. That is the intended
+outcome, not a bug: the two must be upgraded together, and this is the loud
+version of finding out.
+
+What it costs:
+
+- **`npm install novvy-ads-react-native-admob` picks a prerelease.** Because
+  there is no non-prerelease version to fall back on, a bare install resolves
+  through the `latest` dist-tag like any other package — but what `latest` points
+  at here is always a prerelease, and a version range you write by hand will only
+  match one if it says so. `^1.2.1` matches nothing at all; `^1.2.1-stable.0` is
+  the form to write, and the `npm install` above produces it for you.
+- **The counter at the end of the version is not the native adapter revision.**
+  It counts releases of *this npm package* against one core, so a
+  documentation-only release increments it while the native artifacts stand
+  still. The native revision lives in the exported constants —
+  `NOVVY_ADMOB_ADAPTER_VERSION_ANDROID` and
+  `NOVVY_ADMOB_ADAPTER_VERSION_IOS` — which is the only place it can be read;
+  `NOVVY_ADS_CORE_VERSION_ANDROID` / `_IOS` give the core each half was
+  compiled against. There are two of each because the native lines are
+  per-platform now: at this release the npm version is `1.2.1-stable.0` while
+  the native artifacts read `1.2.0.0` (Android) and `admob-v1.2.1.0` (iOS) —
+  no two of the three lines spell the same string, which is the point. All
+  four constants are diagnostics — nothing reads them at runtime, and you
+  never need to import this package.
+- **Renovate and Dependabot ignore prerelease versions by default**, so you will
+  not get automatic upgrade PRs for this package. That is the intended behaviour
+  — it should move when you move `novvy-ads-react-native`, not on a bot's
+  schedule — but it means "no PRs" is not evidence that the package is
+  unmaintained.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/android/build.gradle

@@ -0,0 +1,158 @@
+// Android half of novvy-ads-react-native-admob.
+//
+// This module compiles to an .aar containing exactly one class: an empty
+// ReactPackage (see NovvyAdsAdMobPackage.kt). The actual payload is the single
+// `implementation` line at the bottom of this file. That is the whole point of
+// the module — RN's Gradle autolinking turns this directory into a Gradle
+// subproject of the host app, which is the only way an npm package can add an
+// Android dependency without the publisher editing their own `android/` files.
+
+buildscript {
+  ext.getExtOrDefault = { name ->
+    return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["NovvyAdsAdMob_" + name]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.6.0"
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+// Deliberately NOT applied: `com.facebook.react`.
+//
+// The SDK repo's android/build.gradle applies it under `isNewArchitectureEnabled()`
+// because it has a TurboModule spec to run codegen over. This module has no
+// spec, no generated/java, no generated/jni — it never crosses the bridge. See
+// the class doc in NovvyAdsAdMobPackage.kt for why that is structural rather
+// than a shortcut.
+
+def getExtOrIntegerDefault = { name ->
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["NovvyAdsAdMob_" + name]).toInteger()
+}
+
+android {
+  namespace "ai.novvy.reactnative.admob"
+
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = "17"
+    // React Native 0.76 pins the Kotlin Gradle plugin to 1.9.24, and a 1.9
+    // compiler reads class metadata only up to version 2.0.0. Anything on the
+    // compile classpath built with Kotlin 2.2.20 (metadata 2.2.0) is therefore
+    // unreadable without this flag.
+    //
+    // It is tempting to think this module escapes that, since it references no
+    // Novvy symbol — the adapter AAR is named as a coordinate and never
+    // imported. That reasoning is wrong, and the POM says why:
+    //
+    //   ai.novvy.android:admob-adapter:1.2.0.0
+    //     -> org.jetbrains.kotlin:kotlin-stdlib:2.2.20   scope=compile
+    //
+    // Maven `compile` scope maps to Gradle's api variant, so kotlin-stdlib
+    // 2.2.20 lands on THIS module's compile classpath transitively, and
+    // conflict resolution picks it over the 1.9.24 stdlib that KGP contributes.
+    // The trigger is not a Novvy type but the standard library, which every
+    // Kotlin file reads — the SDK repo's README records the same failure in a
+    // host app that touches no Novvy code either:
+    //
+    //   e: MainApplication.kt: Class 'kotlin.Unit' was compiled with an
+    //      incompatible version of Kotlin.
+    //
+    // Raising the Kotlin version instead is not an option on 0.76: KGP >= 2.1
+    // turns KotlinTopLevelExtension from a class into an interface, which the
+    // React Native Gradle plugin cannot load.
+    //
+    // Not yet confirmed by a Gradle run — gate B needs novvy-ads-react-native
+    // published first. The flag is added ahead of that because the asymmetry is
+    // one-sided: unnecessary here it costs nothing, missing here it fails every
+    // consumer's build.
+    freeCompilerArgs += ["-Xskip-metadata-version-check"]
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  // The entire reason this package exists.
+  //
+  // A dependency-graph island: nothing in this module references it, and nothing
+  // can. The Google Mobile Ads SDK instantiates
+  // `ai.novvy.android.mediation.admob.NovvyAdMobMediationAdapter` reflectively
+  // from the class-name string the publisher types into the AdMob dashboard, so
+  // there is no compile-time reference anywhere in the app to keep it alive.
+  //
+  // What keeps R8 from deleting it is the AAR's own `consumer-rules.pro`, which
+  // travels with the artifact and keeps the adapter plus its three loaders with
+  // `{ *; }`. Nothing here needs to restate those rules — and if that file ever
+  // stopped shipping, the release build would still succeed and the class would
+  // simply be gone. See Step 5.2 of the plan: the dex grep is the only automated
+  // check that the payload survived, and it is the first thing to run.
+  //
+  // Pinned exactly, never a dynamic version (`1.2.0.+`): the same source
+  // would otherwise build different apks on different days, and the adapter must
+  // match the core SDK the app initializes — a mismatched pair fails as a
+  // permanent silent no-fill, because the adapter's isInitialized check reads
+  // the SDK instance JS never initialized.
+  //
+  // `1.2.0.0` = core `1.2.0` + adapter revision `0`. This is the native
+  // version line and it is NOT this npm package's own version — see the
+  // "two version lines" table in §四 of the plan, and the per-platform
+  // constants in index.js.
+  //
+  // Deliberately `1.2.0.0`, not `1.2.1.0`, at this release: the native SDKs
+  // release on independent lines now, and the 1.2.1 generation moved only the
+  // iOS one. `novvy-ads-react-native` 1.2.1 itself resolves
+  // `ai.novvy.android:sdk:1.2.0`, and no `admob-adapter:1.2.1.0` exists — an
+  // adapter that pinned `sdk:1.2.1` would drag a second NovvySDK instance into
+  // the process beside the one the core package initializes, and the
+  // adapter's isInitialized check would read the wrong one. The iOS half of
+  // this package does move to the `admob-v1.2.1.0` tag this release — the
+  // asymmetry is deliberate, and mirrors the Flutter package's coordinates.
+  implementation "ai.novvy.android:admob-adapter:1.2.0.0"
+
+  // Only to compile the empty ReactPackage in NovvyAdsAdMobPackage.kt, which
+  // exists because RN 0.76's autolinking requires a non-null `packageInstance`.
+  //
+  // compileOnly, not implementation: React Native is supplied by the host app at
+  // runtime by definition, and this module has no runtime behaviour of its own.
+  // No version string — RNGP substitutes the host's React Native version across
+  // all configurations.
+  compileOnly "com.facebook.react:react-android"
+
+  // Deliberately NOT declared: com.google.android.gms:play-services-ads.
+  //
+  // The adapter compiles against it as `compileOnly` (verified:
+  // NovvyAdMobAdapter/build.gradle.kts:74 pins 23.0.0 there) precisely so the
+  // Google Mobile Ads version stays the host's to choose. On React Native the
+  // host's choice is made transitively by `react-native-google-mobile-ads`,
+  // whose 15.x/16.0.x line brings GMA Android 24.1.0–24.9.0. Declaring any
+  // version here would contend with what is already in the host's graph.
+  //
+  // ⚠️ compileOnly 23.0.0 against a 24.x runtime has no compile-time guarantee
+  // of compatibility, only Google's own API stability. This is the plan's
+  // largest unverified assumption (§九 #1) and can only be settled on a real
+  // device. If it does break, the fix is to raise the compileOnly floor in
+  // novvy-ads-android-sdk — not to add a constraint here.
+}

package/android/gradle.properties

@@ -0,0 +1,19 @@
+# Defaults for this module's Android build, read by android/build.gradle through
+# `getExtOrDefault` / `getExtOrIntegerDefault`. A host app overrides any of them
+# by setting the un-prefixed name in its root project's ext block (the usual
+# `ext { compileSdkVersion = 35 }` in android/build.gradle), which is why the
+# prefix is here: it keeps this module's fallbacks from colliding with the SDK
+# package's `NovvyAds_` ones when both are autolinked into the same build.
+#
+# Values track novvy-ads-react-native's android/gradle.properties. They differ
+# from the Flutter mediation package (compileSdk 34, no targetSdk) because that
+# one is not built against React Native.
+
+# React Native 0.76 pins the Kotlin Gradle plugin to 1.9.24 in
+# @react-native/gradle-plugin's version catalog. Raising this is not a free
+# choice: KGP >= 2.1 turns KotlinTopLevelExtension from a class into an
+# interface, which the React Native Gradle plugin cannot load.
+NovvyAdsAdMob_kotlinVersion=1.9.24
+NovvyAdsAdMob_minSdkVersion=24
+NovvyAdsAdMob_targetSdkVersion=34
+NovvyAdsAdMob_compileSdkVersion=35

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,19 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <!-- Intentionally empty.
+
+       No permissions are declared here. The ones the ad stack needs (INTERNET,
+       ACCESS_NETWORK_STATE, com.google.android.gms.permission.AD_ID) come from
+       the manifests of the artifacts that actually use them and are merged into
+       the host app automatically: ai.novvy.android:sdk, pulled in by the host's
+       novvy-ads-react-native dependency, and play-services-ads, pulled in by
+       react-native-google-mobile-ads.
+
+       Nor is there an AdMob application-id meta-data entry. That belongs to the
+       host app and react-native-google-mobile-ads already owns the mechanism for
+       it (its `react-native-google-mobile-ads` key in app.json / Expo config
+       plugin). Declaring it here would either be ignored or, worse, conflict at
+       merge time with the publisher's real one.
+
+       An AndroidManifest.xml is still required: com.android.library refuses to
+       configure without one. -->
+</manifest>

package/android/src/main/java/ai/novvy/reactnative/admob/NovvyAdsAdMobPackage.kt

@@ -0,0 +1,101 @@
+package ai.novvy.reactnative.admob
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+/**
+ * An intentionally empty [ReactPackage]. It registers no native modules and no
+ * view managers, and it never will.
+ *
+ * ## Why an empty class has to exist at all
+ *
+ * This module's only payload is the `implementation` line in `build.gradle`
+ * that pulls in the AdMob mediation adapter AAR. There is no JavaScript API
+ * here, nothing crosses the bridge, and so there is nothing for a
+ * [ReactPackage] to contain. React Native 0.76's Gradle autolinking still
+ * demands one:
+ *
+ * - `ModelAutolinkingDependenciesPlatformAndroidJson.kt:13` declares
+ *   `val packageInstance: String` — a **non-null** type.
+ * - `GeneratePackageListTask.kt:84` then does
+ *   `requireNotNull(dep.packageInstance) { "RNGP - Autolinking: Missing `packageInstance` in `config` for dependency $name..." }`.
+ *
+ * So the `packageInstance: null` trick that the Flutter mediation package's
+ * README suggests for React Native does not work here — it fails the Android
+ * build outright. The only escape hatch in `filterAndroidPackages()` is
+ * `isPureCxxDependency == true`, which is semantically wrong (it is for pure
+ * C++ TurboModules and also changes the new-architecture CMake generation
+ * path), so it is not used.
+ *
+ * Worth stating plainly, because it is the opposite of the Flutter situation:
+ * omitting the registration class on Flutter makes the toolchain **silently
+ * ignore the whole Android directory** — the payload vanishes and the build
+ * succeeds. On React Native 0.76 it is a **loud Gradle error with a precise
+ * message**. React Native is better here. The class is still required.
+ *
+ * ## No `react-native.config.js` is needed — but mind the class declaration
+ *
+ * The CLI finds this class by scanning source, so autolinking works with no
+ * config file at all (verified against
+ * `@react-native-community/cli-platform-android/build/config`):
+ *
+ * - `findPackageClassName.js` globs `**\/*Package.kt` under `android/`, reads each
+ *   match, and applies
+ *   `/class\s+(\w+[^(\s]*)[\s\w():]*(\s+implements\s+|:)[\s\w():,]*[^{]*ReactPackage/`.
+ * - `getAndroidProject.js` takes the package name from this manifest's `package`
+ *   attribute, and — since AGP 8 manifests have none — falls back to
+ *   `parseNamespaceFromBuildGradleFile`, which reads `namespace` out of
+ *   `android/build.gradle`.
+ * - `config/index.js:135` then emits
+ *   `import ai.novvy.reactnative.admob.NovvyAdsAdMobPackage;` and
+ *   `new NovvyAdsAdMobPackage()`.
+ *
+ * ⚠️ That regex runs over the **whole file, comments included**, and `String.match`
+ * returns the first hit. So a doc line that reads like a declaration — an
+ * illustrative `class <SomeName> : ReactPackage` written out in prose, say —
+ * gets picked up ahead of the real class, and autolinking then emits
+ * `new <SomeName>()`: a Gradle error at best, the wrong class at worst.
+ *
+ * Note the angle brackets above: they are what keeps that example from matching
+ * (the pattern needs `\w` straight after `class`). This was not hypothetical —
+ * the first draft of this very paragraph spelled the example out literally and
+ * made the CLI report the placeholder name instead of `NovvyAdsAdMobPackage`.
+ * After editing this doc, re-check with:
+ *
+ * ```
+ * node -e "const {matchClassName}=require('<app>/node_modules/@react-native-community/cli-platform-android/build/config/findPackageClassName.js');
+ *   console.log(matchClassName(require('fs').readFileSync('<this file>','utf8'))[1])"
+ * ```
+ *
+ * ## Do not give it work to do
+ *
+ * The temptation, once a registration class exists, is to hang something off
+ * it — an initializer, a version getter, a convenience module. Don't.
+ *
+ * Anything that needs JavaScript belongs in `novvy-ads-react-native`, whose
+ * TurboModule is already established, already versioned, and already the thing
+ * publishers depend on. A second bridge surface shipped from a mediation
+ * package would be a second place to keep in sync, on a package whose whole
+ * design is that installing it is the entire integration.
+ *
+ * Initialization in particular must stay out of here. `NovvyAds.initialize(...)`
+ * is the publisher's call to make from JavaScript, deliberately: the adapter
+ * cannot initialize the SDK on their behalf because the app id / endpoint /
+ * apiKey would then come from the AdMob dashboard's parameter field, where a
+ * typo produces a silent no-fill with no diagnostic at all.
+ */
+class NovvyAdsAdMobPackage : ReactPackage {
+  override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> =
+    emptyList()
+
+  // `ReactPackage.createViewManagers` is declared in Java as a raw
+  // `List<ViewManager>` (ReactPackage.java:53), which Kotlin sees as
+  // `List<ViewManager<*, *>>`. Spelling the type arguments out any further —
+  // `ViewManager<out View, out ReactShadowNode<*>>`, say — produces a different
+  // type and fails to override.
+  override fun createViewManagers(
+    reactContext: ReactApplicationContext
+  ): List<ViewManager<*, *>> = emptyList()
+}

package/index.d.ts

@@ -0,0 +1,47 @@
+// Hand-written to match index.js. There is no codegen and no `tsc` step in this
+// package — see the note at the top of index.js.
+
+/**
+ * Version of the native AdMob mediation adapter this package delivers on
+ * Android: the Maven coordinate `ai.novvy.android:admob-adapter:<this>`.
+ *
+ * ⚠️ **This is not the version of this npm package.** The npm version
+ * (`1.2.1-stable.0`) tracks `novvy-ads-react-native`; the native line tracks
+ * the native core plus an adapter revision — and it is per-platform since the
+ * core's 1.2.1 generation, so this constant and
+ * {@link NOVVY_ADMOB_ADAPTER_VERSION_IOS} are expected to disagree. See
+ * index.js for the table.
+ *
+ * Diagnostics only; nothing reads it at runtime.
+ */
+export declare const NOVVY_ADMOB_ADAPTER_VERSION_ANDROID: string;
+
+/**
+ * Version of the native AdMob mediation adapter this package delivers on iOS:
+ * the `admob-v<this>` tag of `novvy-ads-cocoapods` the Swift sources come
+ * from. `<NovvyAds iOS version>.<adapter revision>`.
+ *
+ * Diagnostics only; nothing reads it at runtime.
+ */
+export declare const NOVVY_ADMOB_ADAPTER_VERSION_IOS: string;
+
+/**
+ * Version of the native Novvy core SDK the Android adapter was compiled
+ * against: `ai.novvy.android:sdk:<this>`.
+ *
+ * Pinned exactly on purpose — a range risks two SDK instances in the process,
+ * which is a permanent silent no-fill. Also not this package's `version`.
+ *
+ * Diagnostics only; nothing reads it at runtime.
+ */
+export declare const NOVVY_ADS_CORE_VERSION_ANDROID: string;
+
+/**
+ * Version of the native Novvy core SDK the iOS adapter was compiled against:
+ * the `NovvyAds.xcframework` that `novvy-ads-react-native` vendors. Differs
+ * from the Android core because the two native SDKs release on their own
+ * lines.
+ *
+ * Diagnostics only; nothing reads it at runtime.
+ */
+export declare const NOVVY_ADS_CORE_VERSION_IOS: string;

package/index.js

@@ -0,0 +1,97 @@
+'use strict';
+
+// The whole JavaScript surface of this package: two strings, for diagnostics.
+//
+// There is no API here and there is not going to be one. The payload is native
+// and arrives through the build system — `android/build.gradle`'s single
+// `implementation` line and `NovvyAdsReactNativeAdMob.podspec`'s
+// `prepare_command`. Adding this package to `dependencies` is the entire
+// integration; nothing needs to be imported for the ad source to work.
+//
+// Written by hand as CommonJS, with a hand-written `index.d.ts` beside it. No
+// bob, no tsc, no `lib/` — a build pipeline for two constants would cost more
+// to maintain than it could ever save, and it would put a `prepack` step
+// between an author and a correct tarball.
+
+/**
+ * Version of the native AdMob mediation adapter this package delivers on
+ * Android: the Maven coordinate `ai.novvy.android:admob-adapter:<this>`.
+ *
+ * ⚠️ **This is not the version of this npm package.** Three version lines meet
+ * in this repository and it is a mistake to reconcile them:
+ *
+ * | Line | Tracks | Appears in |
+ * | --- | --- | --- |
+ * | npm | `novvy-ads-react-native@1.2.1` | `package.json`'s `version` (`1.2.1-stable.0`) and its peer pin |
+ * | native Android | core `1.2.0` + adapter revision `0` | the Gradle coordinate, and this constant |
+ * | native iOS | core `1.2.1` + adapter revision `0` | the podspec's tag, and {@link NOVVY_ADMOB_ADAPTER_VERSION_IOS} |
+ *
+ * There used to be one native line and one constant. They split when the two
+ * native SDKs moved onto independent release lines — `novvy-ads-react-native`
+ * 1.2.1 vendors NovvyAds iOS 1.2.1 while resolving `ai.novvy.android:sdk:1.2.0`
+ * — and each adapter generation now follows its own platform's core. The two
+ * constants below are therefore expected to disagree routinely: they are two
+ * facts, not a value and its typo. See the comment on the Gradle coordinate in
+ * `android/build.gradle` for why Android stays on 1.2.0 this generation.
+ *
+ * Nothing reads this at runtime. It exists so a version can be pasted into a
+ * bug report or logged from a host app, which is the only way to find out which
+ * native adapter build that app actually contains — `package.json`'s version
+ * cannot tell you.
+ *
+ * @type {string}
+ */
+const NOVVY_ADMOB_ADAPTER_VERSION_ANDROID = '1.2.0.0';
+
+/**
+ * Version of the native AdMob mediation adapter this package delivers on iOS:
+ * the adapter's Swift sources are fetched from the `admob-v<this>` tag of
+ * `novvy-ads-cocoapods` at `pod install` and compiled into the pod.
+ *
+ * `<NovvyAds iOS version>.<adapter revision>` — `1.2.1.0` here, because the
+ * iOS core moved to 1.2.1 this generation. Not this npm package's version; see
+ * the table on {@link NOVVY_ADMOB_ADAPTER_VERSION_ANDROID}.
+ *
+ * The adapter sources are byte-identical to the previous generation's — the
+ * tag moved because every NovvyAds release needs a matching adapter release
+ * even when nothing in the adapter changed, not because the adapter did.
+ *
+ * @type {string}
+ */
+const NOVVY_ADMOB_ADAPTER_VERSION_IOS = '1.2.1.0';
+
+/**
+ * Version of the native Novvy core SDK the Android adapter was compiled
+ * against: `ai.novvy.android:sdk:<this>`.
+ *
+ * Also not this npm package's `version` — see the table on
+ * {@link NOVVY_ADMOB_ADAPTER_VERSION_ANDROID}.
+ *
+ * The core is pinned exactly rather than to a range on purpose. Each platform
+ * compiles the adapter against one core, and a range risks either an ABI
+ * mismatch or two SDK instances in the process — in the second case the
+ * adapter's `isInitialized` check reads the instance JavaScript never
+ * initialized, and the ad source returns no fill forever, silently.
+ *
+ * @type {string}
+ */
+const NOVVY_ADS_CORE_VERSION_ANDROID = '1.2.0';
+
+/**
+ * Version of the native Novvy core SDK the iOS adapter was compiled against:
+ * the `NovvyAds.xcframework` that `novvy-ads-react-native` vendors.
+ *
+ * Differs from {@link NOVVY_ADS_CORE_VERSION_ANDROID} because the two native
+ * SDKs release on their own lines — see the table on
+ * {@link NOVVY_ADMOB_ADAPTER_VERSION_ANDROID}. Not this package's `version`.
+ *
+ * @type {string}
+ */
+const NOVVY_ADS_CORE_VERSION_IOS = '1.2.1';
+
+module.exports = {
+  NOVVY_ADMOB_ADAPTER_VERSION_ANDROID,
+  NOVVY_ADMOB_ADAPTER_VERSION_IOS,
+  NOVVY_ADS_CORE_VERSION_ANDROID,
+  NOVVY_ADS_CORE_VERSION_IOS,
+};

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "novvy-ads-react-native-admob",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.1-stable.0",
+  "description": "AdMob mediation adapter for the Novvy Ads React Native SDK — lets an existing AdMob waterfall call Novvy as a custom event. No JavaScript API: installing the package is the whole integration.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "android",
+    "ios",
+    "NovvyAdsReactNativeAdMob.podspec",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "!android/build",
+    "!android/.gradle",
+    "!ios/NovvyAdsAdMob"
+  ],
+  "scripts": {
+    "check-version": "node scripts/check-version.js",
+    "prepublishOnly": "node scripts/check-version.js"
+  },
+  "keywords": [
+    "react-native",
+    "admob",
+    "mediation",
+    "custom-event",
+    "ads",
+    "novvy",
+    "short-drama",
+    "rewarded",
+    "interstitial",
+    "android",
+    "ios"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NovvyAI/novvy-ads-react-native-mediation.git",
+    "directory": "novvy-ads-admob"
+  },
+  "author": "NovvyAI <dev@novvy.ai>",
+  "license": "MIT",
+  "homepage": "https://github.com/NovvyAI/novvy-ads-react-native-mediation/tree/main/novvy-ads-admob#readme",
+  "peerDependencies": {
+    "novvy-ads-react-native": "1.2.1",
+    "react-native-google-mobile-ads": ">=15.0.0 <16.1.0"
+  },
+  "devDependencies": {
+    "semver": "^7.6.3"
+  }
+}