admanagekit-mcp-server 1.0.0 → 1.1.1

package/content/README.md

@@ -1,203 +1,162 @@
 # AdManageKit
 [![JitPack](https://jitpack.io/v/i2hammad/AdManageKit.svg)](https://jitpack.io/#i2hammad/AdManageKit)
-![API](https://img.shields.io/badge/API-21%2B-brightgreen.svg?style=flat)
+![API](https://img.shields.io/badge/API-24%2B-brightgreen.svg?style=flat)
 ![License](https://img.shields.io/badge/License-MIT-blue.svg)
 
 AdManageKit is a comprehensive Android library designed to simplify the integration and management of Google AdMob ads, Google Play Billing, and User Messaging Platform (UMP) consent.
 
-**Latest Version `3.3.5`** adds **App Open Loading Strategies** - proper loading strategy support (ON_DEMAND, ONLY_CACHE, HYBRID) with ad freshness tracking and auto-reload configuration.
+**Latest Version `4.4.0`** is a minor release focused on the billing module. Subscription offers can now be **purchased individually** — `subscribe(activity, offer)` buys exactly the plan the user tapped, where previously the library always resolved the token itself and could charge for whichever offer Play listed last. It also adds offer lookup by id/base plan/tag, cross-cadence price normalization (`BillingPeriod`, `getSavingsPercent`, `getFormattedPricePerMonth`), trial-eligibility checks, Play Billing 9 one-time product offers (discounts, rentals, pre-orders, limited quantity), client-side **account hold** detection, Play payment-recovery messaging, and product-details diagnostics. Purely additive, with one behavior change: an on-hold subscription now reports `ON_HOLD` and is no longer `isSubscriptionActive()`. See [Release Notes v4.4.0](docs/release-notes/RELEASE_NOTES_v4.4.0.md).
 
----
+**Version `4.3.5`** is a patch release that makes `appOpenAdFreshnessThreshold` (default 4 hours) actually enforced on every app open show path. Previously only `ON_DEMAND` consulted it — `HYBRID`, `ONLY_CACHE`, and the multi-provider waterfall checked only whether an ad object existed and could show a day-old cached ad. Stale ads are now discarded and replaced instead of shown. It also settles the `appOpenAdTimeout` default at **10 seconds** (the property said 4s while `resetToDefaults()` said 10s — 4s was too short for the fetch-with-dialog paths). No API changes. See [Release Notes v4.3.5](docs/release-notes/RELEASE_NOTES_v4.3.5.md).
 
-## Next-Gen GMA SDK Version
+**Version `4.3.4`** is a patch release that restores the pre-4.2.0 default adaptive banner height: `ADAPTIVE` again requests the standard anchored adaptive size (~50-90dp) instead of the taller *large anchored adaptive* format the Next-Gen migration had switched to. The taller format is now opt-in via `BannerAdSize.ADAPTIVE_LARGE` (`app:bannerAdSize="adaptive_large"` in XML). See [Release Notes v4.3.4](docs/release-notes/RELEASE_NOTES_v4.3.4.md).
 
-> **Beta Notice:** The Next-Gen GMA SDK (`com.google.android.libraries.ads.mobile.sdk`) is currently in **beta by Google**, and AdManageKit's nextgen branch is also in **beta**. The underlying Google SDK may receive breaking changes until it reaches stable release. For production use, the **main branch** is the stable option.
+**Version `4.3.3`** is a patch release that improves native ad media quality: every native request now sends a media-aspect-ratio hint matched to each template's `MediaView` slot shape and carries global `VideoOptions` (start-muted by default). New `AdManageKitConfig` fields and a per-view `NativeTemplateView.setMediaAspect(...)` override expose the behavior; all defaults preserve prior request behavior. See [Release Notes v4.3.3](docs/release-notes/RELEASE_NOTES_v4.3.3.md).
 
-AdManageKit offers a **Next-Gen GMA SDK** version on the `nextgen` branch, featuring Google's modern preloader-based ad loading system.
+**Version `4.3.2`** is a patch release that fixes banner shimmer sizing — the placeholder now reserves the real adaptive-banner height from the first frame and in the layout preview instead of collapsing to ~50dp — and stops the Compose native ad from clipping its call-to-action button. Also bumps the Android Gradle Plugin to 9.3.0. See [Release Notes v4.3.2](docs/release-notes/RELEASE_NOTES_v4.3.2.md).
 
-### Why Next-Gen?
+**Version `4.3.1`** is a patch release fixing crashes from Next-Gen SDK callbacks delivered on background threads — interstitial `onNextAction`, banner/native waterfall chains, and `NativeTemplateView.onFailedToLoad` are now marshalled to the main thread — plus a load-site guard for app open ads. See [Release Notes v4.3.1](docs/release-notes/RELEASE_NOTES_v4.3.1.md).
 
-| Feature | Main Branch (GMS SDK) | Next-Gen Branch |
-|---------|----------------------|-----------------|
-| SDK | `play-services-ads` (stable) | `ads-mobile-sdk` (beta) |
-| Ad Loading | Traditional load/show | Preloader-based with auto-refill |
-| Threading | Manual main thread dispatch | Automatic background thread safety |
-| Buffer System | N/A | Configurable ad buffers per type |
-| Background Handling | Basic | Smart pending ad queue |
+**Version `4.3.0`** adds all standard AdMob banner sizes (`BannerAdSize`), fully custom native ad templates on `NativeTemplateView`, and a redesigned size-adaptive banner shimmer with night-mode support. See [What's New in 4.3.0](#whats-new-in-430).
 
-### Next-Gen Features
+Since **4.2.0** the library runs on the Google Mobile Ads **Next-Gen SDK** (`ads-mobile-sdk`, stable) and Google Play Billing Library **9.1.0** — see [Next-Gen GMA SDK](#next-gen-gma-sdk) below and [Migrating to 4.2.0](#migrating-to-420) if you're upgrading from 3.x/4.1.
 
-- **Preloader System**: SDK automatically loads next ad after one is consumed
-- **Background-Aware Ads**: App open ads won't show when app is in background
-- **Pending Ad Queue**: Ads that load while backgrounded are saved for return
-- **Configurable Buffers**: Set how many ads to keep ready per type
+---
 
-```kotlin
-// Next-Gen preloader configuration
-AdManageKitConfig.apply {
-    enableInterstitialPreloader = true
-    enableAppOpenPreloader = true
-    interstitialPreloaderBufferSize = 2
-}
-```
+## Next-Gen GMA SDK
 
-### Migration Compatibility
+As of v4.2.0, AdManageKit runs on Google's **Next-Gen Google Mobile Ads SDK** (`com.google.android.libraries.ads.mobile.sdk`, stable `1.2.1`) instead of the legacy `com.google.android.gms:play-services-ads`. This isn't a branch or an opt-in — it's the only version of AdManageKit going forward.
 
-Both branches use the same callback signatures via type aliases:
-- `AdKitError` → resolves to appropriate SDK error type
-- `AdKitLoadError` → resolves to appropriate SDK load error type
-- `AdKitValue` → resolves to appropriate SDK value type
+### Why the move
 
-Your callback implementations work on both branches without changes.
+The legacy Google Mobile Ads SDK is in maintenance mode; new AdMob features (Ad Inspector improvements, mediation updates, in-app price-increase messaging, etc.) land on the Next-Gen SDK first, and Google's own guidance is to move new integrations there. AdManageKit had a separate `nextgen` branch exploring this since it was in beta and diverging from `main`'s waterfall/Yandex/billing work — now that the SDK is stable, that split is gone.
 
-### Which Version Should I Use?
+### What's different under the hood
 
-| Use Case | Recommended |
-|----------|-------------|
-| Production apps (stable) | **Main branch** (v3.3.5) |
-| New projects wanting latest features | **Nextgen branch** (v4.1.1) |
-| Testing preloader system | **Nextgen branch** |
-| Risk-averse production | **Main branch** |
+- **Threading**: Next-Gen SDK callbacks fire on a background thread (the legacy SDK guaranteed main thread). Every ad manager, provider, and view in this library already wraps its callback bodies in `Handler(Looper.getMainLooper()).post {}` — this is transparent to you as a consumer.
+- **Initialization**: `MobileAds.initialize()` must be called explicitly once, before any ad request — the legacy SDK's silent lazy-init on first use no longer exists. AdManageKit doesn't call this for you (it doesn't own your app's consent flow); see the sample app's `MyApplication.kt` for the recommended pattern.
+- **Callback types**: Where AdManageKit exposes ad-network error/value types through `AdKitError`, `AdKitLoadError`, and `AdKitValue` (used by `AdManagerCallback`, `AdLoadCallback`, `AdCallback`, and friends), those aliases now resolve to Next-Gen SDK types instead of legacy ones. Your callback *implementations* (`onFailedToLoad(error)`, `onPaidEvent(value)`, etc.) don't need to change — only code that reads legacy-only members of those objects does. See [Migrating to 4.2.0](#migrating-to-420).
 
----
+## What's New in 4.4.0
+
+A billing-focused minor release. Everything is additive — no existing method signature changed — with one deliberate behavior change around account hold.
 
-## What's New in 3.3.5
+### Buy the Offer the User Actually Tapped
 
-### App Open Loading Strategies
-- **Proper Loading Strategy Support**: AppOpenManager now fully supports `AdLoadingStrategy` (ON_DEMAND, ONLY_CACHE, HYBRID)
-- **Ad Freshness Tracking**: Cached ads track load time to prevent showing stale ads
-- **Smart Cache Usage**: ON_DEMAND strategy uses cached ads if still fresh (within `appOpenAdFreshnessThreshold`)
-- **Auto-Reload Config**: New `appOpenAutoReload` setting to control automatic reloading after ad dismissal
-- **Deprecated**: `appOpenFetchFreshAd` - migrate to `appOpenLoadingStrategy`
+`AppPurchase` could already *describe* subscription offers (`getOffers`, `getTrialOffer`, `getBaseOffer` since 3.5.7), but it could not *act* on them. `subscribe(activity, subsId)` always resolved the offer token itself — the configured `trialId`, and failing that **whichever offer Play listed last**. On a product with three plans, a user tapping "Yearly" could be charged for monthly, purely because of list order.
 
 ```kotlin
-AdManageKitConfig.apply {
-    // Loading strategy (ON_DEMAND, ONLY_CACHE, HYBRID)
-    appOpenLoadingStrategy = AdLoadingStrategy.HYBRID
+val offers = AppPurchase.getInstance().getOffers("premium_sub")
+// …render them, then buy exactly what the user chose:
+AppPurchase.getInstance().subscribe(activity, offers[selectedIndex])
+```
 
-    // Freshness threshold for cached ads (default: 4 hours)
-    appOpenAdFreshnessThreshold = 4.hours
+The same applies to one-time products (`purchase(activity, offer)`) and upgrades (`updateSubscription(activity, newSubsId, offerToken, oldToken, mode)`). The original no-token overloads are unchanged.
 
-    // Auto-reload after ad dismissal (default: true)
-    appOpenAutoReload = true
-}
+### Offer Lookup by Id, Base Plan or Tag
+
+```kotlin
+billing.getIntroOffer("premium_sub")                   // first with an intro price
+billing.getOfferByBasePlanId("premium_sub", "yearly")
+billing.getOfferByTag("premium_sub", "popular")        // Play Console offer tag
+billing.getBestValueOffer("premium_sub")               // lowest cost per month
+billing.getCheapestFirstCycleOffer("premium_sub")      // cheapest way in
 ```
 
-## What's New in 3.3.4
+Offer **tags** are the useful one here: tag offers in the Play Console and select them by tag, and a paywall can be re-targeted without shipping an app update.
 
-### Subscription Expiry Verification
-- **Server-Side Verification**: New API to verify subscriptions and get accurate expiry dates from your backend
-- **Expiry Methods**: `getExpiryTimeFormatted()`, `getRemainingDays()`, `isExpired()` on PurchaseResult
-- **AppPurchase Helpers**: `getSubscriptionExpiryTime()`, `getSubscriptionRemainingDays()`, `isSubscriptionExpired()`
+### Price Comparison Without Parsing ISO-8601
+
+Play returns billing periods as raw strings (`"P1M"`, `"P1Y"`). The new `BillingPeriod` parses them and normalizes prices so plans of different cadences compare fairly:
 
 ```kotlin
-// Set up verification callback
-AppPurchase.getInstance().setSubscriptionVerificationCallback { packageName, subscriptionId, purchaseToken, listener ->
-    yourApi.verifySubscription(purchaseToken) { expiryMillis ->
-        val details = SubscriptionVerificationCallback.SubscriptionDetails.Builder()
-            .setExpiryTimeMillis(expiryMillis)
-            .build()
-        listener.onVerified(details)
-    }
-}
+val period = BillingPeriod.parse("P1Y")!!
+period.unit          // Unit.YEAR
+period.count         // 1 → getQuantityString(R.plurals.years, count, count)
+period.totalMonths   // 12.0
 
-// Verify and get expiry
-AppPurchase.getInstance().verifySubscription("premium_monthly",
-    object : AppPurchase.SubscriptionVerificationListener {
-        override fun onVerified(subscription: PurchaseResult) {
-            val expiryDate = subscription.getExpiryTimeFormatted("dd MMM yyyy")
-            val daysLeft = subscription.getRemainingDays()
-        }
-        override fun onVerificationFailed(error: String?) { }
-    }
-)
+billing.getSavingsPercent("premium_monthly", "premium_yearly")  // 50 → "Save 50%"
+billing.getFormattedPricePerMonth("premium_yearly")             // "$5.00"
 ```
 
-## What's New in 3.3.3
+`OfferInfo` also gained `firstCyclePrice` (what the user pays *today* — "Free", "$1.99" or "$9.99"), `pricePerMonthMicros`, `introDiscountPercent`, `trialDays`, `introTotalDays`, `isBaseOffer` and `hasTag(...)`.
 
-### SDK-Agnostic Type Aliases
-- **Migration Compatibility**: Callbacks use `AdKitError`, `AdKitLoadError`, `AdKitValue` type aliases
-- **Same Signatures**: Your callback implementations work across both SDK versions
-- **Easy Migration**: Switch between main (GMS SDK) and nextgen (Next-Gen SDK) branches without code changes
+### Trial Eligibility
+
+Google Play filters offers per account — a user who already used a trial simply doesn't receive that offer. So offer presence *is* the eligibility signal, now named explicitly:
 
 ```kotlin
-// Callbacks now use type aliases that resolve to the appropriate SDK types
-object : AdLoadCallback() {
-    override fun onFailedToLoad(error: AdKitError?) {  // Works on both branches
-        Log.e("Ads", "Failed: ${error?.message}")
-    }
-    override fun onPaidEvent(adValue: AdKitValue) {    // Works on both branches
-        trackRevenue(adValue.valueMicros)
-    }
-}
+button.text = if (billing.isEligibleForFreeTrial("premium_sub")) "Start free trial" else "Subscribe"
 ```
 
-## What's New in 3.3.2
+This stops a paywall promising a trial the user cannot claim and then having Play charge them immediately.
 
-### InterstitialAdBuilder Fixes
-- **Ad Unit Assignment**: Fixed ad unit not being assigned to AdManager on first HYBRID fetch
-- **Immediate Availability**: `adUnit()` now sets AdManager.adUnitId immediately for first-call reliability
+### Play Billing 9 Features That Were Unused
 
-### everyNthTime Feature Fix
-- **Counter Persistence**: Call counter now persists across builder instances in AdManager
-- **Counter API**: New methods to manage counters: `getCallCount()`, `resetCallCount()`, `resetAllCallCounts()`
+- **One-time product offers** — a single INAPP product can carry several offers (a full price plus a launch discount, a rental, a pre-order, a limited-quantity drop). New `OneTimeOfferInfo` + `getOneTimeOffers()` / `getBestOneTimeOffer()`; the legacy `getOneTimePurchaseOfferDetails()` exposes only one of them
+- **Payment recovery** — `showInAppMessages(activity, listener)` shows Play's fix-your-payment flow for declined subscriptions
+- **Product-details diagnostics** — `setProductDetailsListener(...)` and `getUnfetchedProducts()` report *which* ids Play declined and why, so an empty paywall is no longer silent
+- **Installment plans** — `OfferInfo.isInstallmentPlan` and commitment payment counts
+- **Fraud prevention & EU disclosure** — `setObfuscatedAccountId()`, `setObfuscatedProfileId()`, `setOfferPersonalized()`, applied to every flow the library launches
 
-```kotlin
-// everyNthTime now works correctly
-InterstitialAdBuilder.with(activity)
-    .adUnit(adUnitId)
-    .everyNthTime(3)  // Shows on 3rd, 6th, 9th calls, etc.
-    .show { navigateNext() }
+### Account Hold Detected Client-Side (behavior change)
 
-// Reset counters when user upgrades
-AdManager.getInstance().resetAllCallCounts()
-```
+When Play cannot charge a subscriber, the subscription enters **account hold**. This previously required server-side verification; Play Billing 9 reports it client-side, so `PurchaseResult.isSuspended()` is now populated and `getSubscriptionState()` returns `ON_HOLD`.
 
-### New Native Templates
-- **flexible**: Adaptive layout that adjusts to available space
-- **icon_left**: Icon on left side with MediaView at top for GridView display
-- **top_icon_media**: Icon at top, MediaView in middle, CTA at bottom
+> **`isSubscriptionActive()` therefore returns `false` during account hold.** That matches Google's requirement — the user's payment was declined and they must not keep premium access. If your app deliberately keeps serving on-hold users, check `isSuspended()` explicitly.
 
 ```kotlin
-nativeTemplateView.setTemplate(NativeAdTemplate.FLEXIBLE)
-nativeTemplateView.setTemplate(NativeAdTemplate.ICON_LEFT)
-nativeTemplateView.setTemplate(NativeAdTemplate.TOP_ICON_MEDIA)
+if (billing.hasSubscriptionOnHold()) {
+    billing.showInAppMessages(activity, object : InAppMessageListener {
+        override fun onSubscriptionRecovered(purchaseToken: String) { refreshPremiumUi() }
+        override fun onNoActionNeeded() { }
+    })
+}
 ```
 
-## What's New in 3.1.0
+See [Release Notes v4.4.0](docs/release-notes/RELEASE_NOTES_v4.4.0.md) and the [Subscription Offers wiki page](https://github.com/i2hammad/AdManageKit/wiki/Subscription-Offers) for full details.
+
+## What's New in 4.3.0
+
+### All Standard Banner Sizes
+`BannerAdView` and `BannerAdCompose` now support every standard AdMob banner size via the new `BannerAdSize` enum — `ADAPTIVE` (default, unchanged behavior), `BANNER` (320x50), `LARGE_BANNER` (320x100), `MEDIUM_RECTANGLE` (300x250), `FULL_BANNER` (468x60), `LEADERBOARD` (728x90). Select programmatically (`loadBanner(activity, adUnitId, BannerAdSize.MEDIUM_RECTANGLE)`), in XML (`app:bannerAdSize="medium_rectangle"`), or in Compose (`adSize = BannerAdSize.MEDIUM_RECTANGLE`). The size carries through retries, auto-refresh, and the multi-provider waterfall. See the [Banner Ad Guide](docs/BANNER_AD_IMPROVEMENTS.md).
+
+### Custom Native Ad Templates
+If none of the 37 built-in `NativeTemplateView` presets fit your design, supply your own layout: `setCustomTemplate(layoutResId, shimmerResId, sizeHint)` programmatically, `app:customAdLayout`/`app:customAdShimmerLayout` in XML, or `customLayoutResId` on `NativeTemplateCompose`. The layout's root must be a Next-Gen SDK `NativeAdView` reusing the standard asset ids. See the [NativeTemplateView guide](docs/NATIVE_TEMPLATE_VIEW.md#custom-templates).
+
+### Redesigned Banner Shimmer + Night Mode
+The banner loading placeholder now adapts to the requested size (a 300x250 request shows a proper media-block placeholder, not a lone 50dp row), reserves the exact ad size on every path including waterfalls (no layout jump), centers to match the loaded ad, and follows the system dark theme instead of rendering a hardcoded white card.
+
+### App Open Ads: Late MobileAds Initialization Support
+`AppOpenManager` no longer crashes if constructed before `MobileAds.initialize()` completes: every load path is guarded, callback-driven flows (splash screens) wait for the SDK within their existing timeout and always receive a terminal callback, and the new `isMobileAdsReady()` confirms the SDK can accept requests. See the [App Open Ads guide](docs/app-open-ads.md#initialization-order--late-initialization).
+
+> **Compatibility:** source-compatible; `ADAPTIVE` keeps pre-4.3.0 behavior everywhere. Recompile against 4.3.0 rather than hot-swapping the AAR (Compose composables gained default parameters).
 
-### FRESH_WITH_CACHE_FALLBACK Strategy Fix
-- **Auto-Caching**: Successfully loaded ads are now properly cached for future fallback
-- **RecyclerView Optimized**: Fresh ads build up the cache over time for better fallback availability
-- **Complete Implementation**: Strategy now works as documented
+See [Release Notes v4.3.0](docs/release-notes/RELEASE_NOTES_v4.3.0.md) for full details.
 
-### New Native Template
-- **MEDIUM_HORIZONTAL**: 55% media (left) / 45% content (right) horizontal split layout
-- **27 Total Templates**: 21 standard + 6 video templates
+## What's New in 4.2.0
 
-## What's New in 3.0.0
+### Google Mobile Ads Next-Gen SDK
+`com.google.android.gms:play-services-ads` is replaced by the stable **Next-Gen SDK** (`ads-mobile-sdk:1.2.1`) across every ad manager, provider, native view, and the Compose module. This is the change described in [Next-Gen GMA SDK](#next-gen-gma-sdk) above — read that section first if you're upgrading.
 
-### Ad Pool System
-- **Multiple Ad Units**: Load multiple interstitial ad units into a pool for maximum show rate
-- **Auto-Selection**: Shows ANY available ad from the pool when requested
-- **Duplicate Prevention**: Automatically skips duplicate load requests
+### Google Play Billing Library 9.1.0
+Upgraded from 8.3.0. No code changes were needed in `AppPurchase` — the wrapper was already on v8+ patterns. Source- and behavior-compatible.
 
-### Smart Splash Ads
-- **showOrWaitForAd()**: Single method handles all splash scenarios automatically
-- **Intelligent Behavior**: Shows cached ad immediately, waits if loading, or fetches fresh
+### compileSdk 37
+Required transitively by `androidx-core-ktx` 1.19.0+. Bump your app's `compileSdk` to 37+.
 
-### App Open Ad Prefetching
-- **prefetchNextAd()**: Prefetch ads before external intents for instant display on return
-- **isAdLoading()**: Check if ad is currently being fetched
+### Fixes
+- Native ad `MediaView` rendering blank in `NativeTemplateView` and the programmatic native provider (a leftover legacy-SDK pattern was interfering with the Next-Gen SDK's automatic media rendering)
+- `NativeAdView.mediaView` returning `null` for dynamically-inflated templates (the getter's auto-discovery needs the view to be window-attached; affected views now use `findViewById()` directly)
+- A Native Validator false-positive risk on deeply-nested templates like `CARD_MODERN`, caused by registering the ad before the view had been through a layout pass
 
-### Enhanced Analytics
-- **Session Tracking**: Fill rate, show rate, and impression tracking
-- **getAdStats()**: Access session-level ad performance metrics
+> **Compatibility:** **not** fully source-compatible — see [Migrating to 4.2.0](#migrating-to-420). Most consumers (anyone who only calls methods on AdManageKit's own callback types, without custom native XML layouts) are unaffected.
 
-### Technical Improvements
-- Modern `WindowInsetsController` API (replaces deprecated systemUiVisibility)
-- Thread-safe ad pool with `ConcurrentHashMap`
-- Cross-ad-unit fallback for native ads
+See [Release Notes v4.2.0](docs/release-notes/RELEASE_NOTES_v4.2.0.md) for full details.
+
+For the 3.6.0 release (Yandex template matching, waterfall-aware programmatic loader), see [Release Notes v3.6.0](docs/release-notes/RELEASE_NOTES_v3.6.0.md).
+
+For previous versions, see the [Changelog](CHANGELOG.md) or individual [release notes](docs/release-notes/).
 
 ## Screenshots
 
@@ -229,40 +188,21 @@ dependencyResolutionManagement {
 
 **Step 2:** Add dependencies to your app's `build.gradle`:
 
-<table>
-<tr>
-<th>Main Branch (Stable GMS SDK)</th>
-<th>Next-Gen Branch (Beta GMA SDK)</th>
-</tr>
-<tr>
-<td>
-
 ```groovy
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v3.3.5'
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v3.3.5'
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v3.3.5'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.0'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.0'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.0'
 
 // For Jetpack Compose support
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v3.3.5'
-```
-
-</td>
-<td>
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v4.4.0'
 
-```groovy
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-nextgen:v4.1.1'
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing-nextgen:v4.1.1'
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core-nextgen:v4.1.1'
-
-// For Jetpack Compose support
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose-nextgen:v4.1.1'
+// For Yandex Ads multi-provider support
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v4.4.0'
 ```
 
-</td>
-</tr>
-</table>
+**Step 3:** Ensure your app's `compileSdk` is **37 or higher** (required transitively as of 4.2.0).
 
-**Step 3:** Sync your project with Gradle.
+**Step 4:** Sync your project with Gradle.
 
 ## Features
 
@@ -286,7 +226,7 @@ implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose-nextgen:v4
 - ConditionalAd, CacheWarmingEffect utilities
 
 ### AdMob Ads Management
-- **Banner Ads**: Auto-refresh, collapsible banners, smart retry
+- **Banner Ads**: All standard sizes (adaptive, 320x50, 320x100, 300x250, 468x60, 728x90), auto-refresh, collapsible banners, smart retry
 - **Native Ads**: Small, Medium, Large formats with caching
 - **Interstitial Ads**: Time/count-based triggers, dialog support
 - **App Open Ads**: Lifecycle-aware with activity exclusion
@@ -306,14 +246,32 @@ implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose-nextgen:v4
 - Circuit breaker for failing ad units
 - Memory leak prevention with WeakReference
 
+### Billing & Monetization
+- **Subscriptions & One-Time Products**: Categories (consumable, feature unlock, remove ads, lifetime premium) with automatic acknowledgment
+- **Offers**: Enumerate every trial / introductory / base offer and purchase a *specific* one (v4.4.0+)
+- **Price Comparison**: ISO-8601 period parsing, per-month normalization, "Save 40%" badges (v4.4.0+)
+- **Trial Eligibility**: Ask whether *this* account can still claim a trial before promising one (v4.4.0+)
+- **Payment Recovery**: Client-side account-hold detection plus Play's in-app recovery flow (v4.4.0+)
+- [In-App Purchase Guide](docs/APP_PURCHASE_GUIDE.md)
+
 ### Privacy & Compliance
 - UMP consent management (GDPR/CCPA)
 - Automatic ad hiding for purchased users
+- Obfuscated account/profile identifiers and EU personalized-pricing disclosure (v4.4.0+)
+
+### Multi-Provider Waterfall (New)
+- **Multiple Ad Networks**: Load ads from AdMob, Yandex, and more with automatic fallback
+- **Zero Code Changes**: Configure provider chains once; all existing API calls use waterfall automatically
+- **Per-Ad-Type Chains**: Configure different provider orders for each ad format
+- **Region-Based**: Prioritize providers by user locale (e.g., Yandex first for Russia)
+- [View Waterfall Documentation](docs/MULTI_PROVIDER_WATERFALL.md)
+- [Yandex Integration Guide](docs/YANDEX_INTEGRATION.md)
 
 ### Multi-Module Architecture
 - **Core Module**: Shared interfaces and configuration
 - **Compose Module**: Jetpack Compose integration
-- **Billing Module**: Google Play Billing Library v8
+- **Billing Module**: Google Play Billing Library v9
+- **Yandex Module**: Yandex Ads SDK provider
 
 ---
 
@@ -356,6 +314,33 @@ class MyApp : Application() {
 }
 ```
 
+### Multi-Provider Waterfall (Optional)
+
+Add Yandex (or other providers) as fallback ad networks with zero changes to your existing ad loading code:
+
+```groovy
+// Add Yandex module
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v3.6.0'
+```
+
+```kotlin
+// In Application.onCreate(), after AdManageKitConfig setup:
+YandexProviderRegistration.initialize(this)
+val admob = AdMobProviderRegistration.create()
+val yandex = YandexProviderRegistration.create()
+
+// Map your AdMob ad unit IDs to Yandex equivalents
+AdUnitMapping.register("ca-app-pub-xxx/your-interstitial", mapOf("yandex" to "R-M-XXXXXX-Y"))
+AdUnitMapping.register("ca-app-pub-xxx/your-native", mapOf("yandex" to "R-M-XXXXXX-Y"))
+
+// Set provider chains (order = priority)
+AdProviderConfig.setInterstitialChain(listOf(admob.interstitialProvider, yandex.interstitialProvider))
+AdProviderConfig.setNativeChain(listOf(admob.nativeProvider, yandex.nativeProvider))
+// ... same for banner, app open, rewarded
+```
+
+See [Multi-Provider Waterfall](docs/MULTI_PROVIDER_WATERFALL.md) and [Yandex Integration](docs/YANDEX_INTEGRATION.md) for the full guide.
+
 ### NativeTemplateView (v2.6.0+)
 
 #### XML Usage
@@ -417,15 +402,24 @@ nativeTemplateView.loadNativeAd(activity, adUnitId, callback, AdLoadingStrategy.
 <com.i2hammad.admanagekit.admob.BannerAdView
     android:id="@+id/bannerAdView"
     android:layout_width="match_parent"
-    android:layout_height="wrap_content" />
+    android:layout_height="wrap_content"
+    app:bannerAdSize="adaptive" />
 ```
 
 ```kotlin
 bannerAdView.loadBanner(this, "ca-app-pub-xxx/yyy")
-// Collapsible banner
+// Fixed size (BANNER, LARGE_BANNER, MEDIUM_RECTANGLE, FULL_BANNER, LEADERBOARD)
+bannerAdView.loadBanner(this, "ca-app-pub-xxx/yyy", BannerAdSize.MEDIUM_RECTANGLE)
+// Collapsible banner (adaptive size only)
 bannerAdView.loadCollapsibleBanner(this, "ca-app-pub-xxx/yyy", true)
 ```
 
+All standard AdMob banner sizes are supported via `BannerAdSize` (v4.3.0); the
+default `ADAPTIVE` is the Google-recommended full-width anchored adaptive banner
+(~50-90dp), and `ADAPTIVE_LARGE` (v4.3.4) opts into the taller Next-Gen *large
+anchored adaptive* format.
+See [Banner Ad Guide](docs/BANNER_AD_IMPROVEMENTS.md) for the full size table.
+
 ### Native Ads (Traditional Views)
 
 ```xml
@@ -645,6 +639,62 @@ AppPurchase.getInstance().setPurchaseHistoryListener(object : PurchaseHistoryLis
 })
 ```
 
+#### Subscription Offers & Paywalls (v4.4.0+)
+
+A single subscription product usually carries several offers — a base plan, a free trial, an introductory discount. Play returns only the ones this account is eligible for.
+
+```kotlin
+val billing = AppPurchase.getInstance()
+
+// Enumerate every offer, then buy exactly the one the user tapped.
+// (subscribe(activity, subsId) picks for you, and may not pick what they chose.)
+val offers = billing.getOffers("premium_sub")
+billing.subscribe(activity, offers[selectedIndex])
+
+// Or find a specific one
+billing.getIntroOffer("premium_sub")                   // first with an intro price
+billing.getOfferByBasePlanId("premium_sub", "yearly")
+billing.getOfferByTag("premium_sub", "popular")        // Play Console offer tag
+billing.getBestValueOffer("premium_sub")               // lowest cost per month
+```
+
+Render an offer without hand-parsing `ProductDetails` or ISO-8601 periods:
+
+```kotlin
+val offer = billing.getBaseOffer("premium_yearly") ?: return
+
+priceLabel.text    = offer.basePrice                   // "$59.99"
+cycleLabel.text    = BillingPeriod.formatOf(offer.billingPeriod)   // "1 year"
+perMonthLabel.text = AppPurchase.formatPrice(offer.pricePerMonthMicros, offer.currencyCode)
+todayLabel.text    = offer.firstCyclePrice             // "Free", "$1.99" or "$59.99"
+
+// "Save 50%" badge — compares base offers, so trials don't distort it
+val savings = billing.getSavingsPercent("premium_monthly", "premium_yearly")
+savingsBadge.isVisible = savings > 0
+savingsBadge.text = "Save $savings%"
+
+// Only promise a trial the user can actually claim
+subscribeButton.text = if (billing.isEligibleForFreeTrial("premium_sub")) {
+    "Start free trial"
+} else {
+    "Subscribe"
+}
+```
+
+> **Localization:** `BillingPeriod.formatOf()` is an English convenience. For shipped UI use `BillingPeriod.parse(iso)` and pair `unit` + `count` with your own plurals resources.
+
+One-time products can carry multiple offers too (discounts, rentals, pre-orders, limited quantity):
+
+```kotlin
+billing.getBestOneTimeOffer("remove_ads")?.let { offer ->
+    price.text = offer.formattedPrice
+    badge.isVisible = offer.isDiscounted
+    badge.text = "-${offer.effectiveDiscountPercent}%"
+    buyButton.isEnabled = !offer.isSoldOut && offer.isValidAt()
+    buyButton.setOnClickListener { billing.purchase(activity, offer) }
+}
+```
+
 #### Subscription Management (v2.9.0+)
 
 ```kotlin
@@ -652,7 +702,8 @@ AppPurchase.getInstance().setPurchaseHistoryListener(object : PurchaseHistoryLis
 val state = AppPurchase.getInstance().getSubscriptionState("premium_monthly")
 when (state) {
     SubscriptionState.ACTIVE -> showPremiumUI()
-    SubscriptionState.CANCELLED -> showRenewalPrompt() // Still has access
+    SubscriptionState.CANCELLED -> showRenewalPrompt()   // Still has access
+    SubscriptionState.ON_HOLD -> showFixPaymentPrompt()  // Payment declined — no access (v4.4.0+)
     SubscriptionState.EXPIRED -> showSubscribeButton()
 }
 
@@ -671,6 +722,41 @@ AppPurchase.getInstance().changeSubscription(
 )
 ```
 
+#### Account Hold & Payment Recovery (v4.4.0+)
+
+When Play cannot charge a subscriber, the subscription enters **account hold**. As of 4.4.0 this is detected client-side — earlier versions needed a server round-trip.
+
+```kotlin
+if (billing.hasSubscriptionOnHold()) {
+    // Let Play walk the user through fixing their payment method.
+    billing.showInAppMessages(activity, object : InAppMessageListener {
+        override fun onSubscriptionRecovered(purchaseToken: String) {
+            refreshPremiumUi()   // isPurchased() is already up to date here
+        }
+        override fun onNoActionNeeded() { }
+    })
+}
+```
+
+> **Behavior change:** `isSubscriptionActive()` returns `false` during account hold, matching Google's requirement. If your app deliberately keeps serving these users, check `isSuspended()` explicitly.
+
+#### Debugging an Empty Paywall (v4.4.0+)
+
+```kotlin
+billing.setProductDetailsListener(object : ProductDetailsListener {
+    override fun onProductDetailsLoaded(
+        productType: String,
+        loaded: List<ProductDetails>,
+        unfetched: List<UnfetchedProduct>,
+    ) {
+        unfetched.forEach { Log.e("Billing", "${it.productId}: status ${it.statusCode}") }
+    }
+    override fun onProductDetailsFailed(productType: String, responseCode: Int, debugMessage: String?) { }
+})
+```
+
+Register it **before** `initBilling`. Products land in `unfetched` when the id is misspelled, the product is inactive in Play Console, or the account can't see the release track.
+
 ---
 
 ## Documentation
@@ -682,7 +768,32 @@ AppPurchase.getInstance().changeSubscription(
 - [Interstitial Ads](docs/interstitial-ads.md)
 - [Rewarded Ads](docs/rewarded-ads.md)
 - [App Open Ads](docs/app-open-ads.md)
+- [Multi-Provider Waterfall](docs/MULTI_PROVIDER_WATERFALL.md)
+- [Yandex Integration](docs/YANDEX_INTEGRATION.md)
 - [Billing Integration Guide](docs/APP_PURCHASE_GUIDE.md)
+- [Release Notes v4.4.0](docs/release-notes/RELEASE_NOTES_v4.4.0.md)
+- [Release Notes v4.3.5](docs/release-notes/RELEASE_NOTES_v4.3.5.md)
+- [Release Notes v4.3.4](docs/release-notes/RELEASE_NOTES_v4.3.4.md)
+- [Release Notes v4.3.3](docs/release-notes/RELEASE_NOTES_v4.3.3.md)
+- [Release Notes v4.3.2](docs/release-notes/RELEASE_NOTES_v4.3.2.md)
+- [Release Notes v4.3.1](docs/release-notes/RELEASE_NOTES_v4.3.1.md)
+- [Release Notes v4.3.0](docs/release-notes/RELEASE_NOTES_v4.3.0.md)
+- [Release Notes v4.2.0](docs/release-notes/RELEASE_NOTES_v4.2.0.md)
+- [Release Notes v3.6.0](docs/release-notes/RELEASE_NOTES_v3.6.0.md)
+- [Release Notes v3.5.9](docs/release-notes/RELEASE_NOTES_v3.5.9.md)
+- [Release Notes v3.5.8](docs/release-notes/RELEASE_NOTES_v3.5.8.md)
+- [Release Notes v3.5.7](docs/release-notes/RELEASE_NOTES_v3.5.7.md)
+- [Release Notes v3.4.6](docs/release-notes/RELEASE_NOTES_v3.4.6.md)
+- [Release Notes v3.4.5](docs/release-notes/RELEASE_NOTES_v3.4.5.md)
+- [Release Notes v3.4.4](docs/release-notes/RELEASE_NOTES_v3.4.4.md)
+- [Release Notes v3.4.3](docs/release-notes/RELEASE_NOTES_v3.4.3.md)
+- [Release Notes v3.4.2](docs/release-notes/RELEASE_NOTES_v3.4.2.md)
+- [Release Notes v3.4.1](docs/release-notes/RELEASE_NOTES_v3.4.1.md)
+- [Release Notes v3.4.0](docs/release-notes/RELEASE_NOTES_v3.4.0.md)
+- [Release Notes v3.3.9](docs/release-notes/RELEASE_NOTES_v3.3.9.md)
+- [Release Notes v3.3.8](docs/release-notes/RELEASE_NOTES_v3.3.8.md)
+- [Release Notes v3.3.7](docs/release-notes/RELEASE_NOTES_v3.3.7.md)
+- [Release Notes v3.3.6](docs/release-notes/RELEASE_NOTES_v3.3.6.md)
 - [Release Notes v3.3.5](docs/release-notes/RELEASE_NOTES_v3.3.5.md)
 - [Release Notes v3.3.4](docs/release-notes/RELEASE_NOTES_v3.3.4.md)
 - [Release Notes v3.3.3](docs/release-notes/RELEASE_NOTES_v3.3.3.md)
@@ -693,11 +804,14 @@ AppPurchase.getInstance().changeSubscription(
 - [API Reference](docs/API_REFERENCE.md)
 
 ### Wiki
+- [Multi-Provider Waterfall](wiki/Multi-Provider-Waterfall.md)
+- [Yandex Integration](wiki/Yandex-Integration.md)
 - [Rewarded Ads](wiki/Rewarded-Ads.md)
 - [Billing Integration](wiki/Billing-Integration.md)
 - [Purchase Categories](wiki/Purchase-Categories.md)
 - [Consumable Products](wiki/Consumable-Products.md)
 - [Subscriptions](wiki/Subscriptions.md)
+- [Subscription Offers](wiki/Subscription-Offers.md)
 - [Subscription Upgrades](wiki/Subscription-Upgrades.md)
 
 ### API Documentation (Dokka)
@@ -707,15 +821,135 @@ AppPurchase.getInstance().changeSubscription(
 Generate locally:
 
 ```bash
-./gradlew dokkaHtmlMultiModule
+./gradlew dokkaGenerateHtml
 ```
 
-Output: `build/dokka/htmlMultiModule/index.html`
+Output: `build/dokka/html/index.html`
+
+### MCP Server (AI Integration)
+
+[![npm](https://img.shields.io/npm/v/admanagekit-mcp-server)](https://www.npmjs.com/package/admanagekit-mcp-server)
+
+AdManageKit provides an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that integrates with AI tools like Claude Code, Claude Desktop, Cursor, and other MCP-compatible clients. It provides **10 tools** for documentation lookup and code generation.
+
+#### Tools
+
+| Category | Tools |
+|----------|-------|
+| **Documentation** | `search_docs`, `get_doc_by_topic`, `get_api_reference`, `get_release_notes`, `get_migration_guide`, `list_documentation` |
+| **Code Generation** | `generate_config`, `generate_ad_integration`, `generate_billing_code`, `generate_compose_code` |
+
+#### Setup
+
+**Claude Desktop / Cursor** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "admanagekit": {
+      "command": "npx",
+      "args": ["-y", "admanagekit-mcp-server"]
+    }
+  }
+}
+```
+
+**Claude Code** (auto-configured via `.mcp.json` when working in this repo):
+
+```json
+{
+  "mcpServers": {
+    "admanagekit": {
+      "command": "node",
+      "args": ["mcp-server/dist/index.js"]
+    }
+  }
+}
+```
+
+#### What It Does
+
+- **Search documentation** across all docs, wiki pages, and API references
+- **Look up API references** for any class (AdManager, AppOpenManager, NativeAdManager, etc.)
+- **Generate integration code** for any ad type with display modes, loading strategies, and callbacks
+- **Generate billing code** for purchases, subscriptions, consumables, and expiry verification
+- **Generate Compose code** for all Compose ad components
+- Supports both **Kotlin** and **Java** output
+
+See [mcp-server/](mcp-server/) for more details.
 
 ---
 
 ## Migration Guide
 
+### Migrating to 4.2.0
+
+The Next-Gen GMA SDK swap (see [Next-Gen GMA SDK](#next-gen-gma-sdk)) is **source-compatible for most consumers**. It only affects you if your code does one of the following:
+
+**1. You read specific members of an error/value object, not just call the callback method.**
+
+`AdKitError`/`AdKitLoadError` now resolve to the Next-Gen SDK's `LoadAdError`, which drops the old `domain`/`cause` fields and replaces the free-form `Int` error code with a closed `LoadAdError.ErrorCode` enum:
+
+```kotlin
+// Before (4.1.x and earlier)
+override fun onFailedToLoad(error: AdKitError?) {
+    Log.e(TAG, "Failed: ${error?.code} / ${error?.domain}")  // .domain no longer exists
+}
+
+// After (4.2.0)
+override fun onFailedToLoad(error: AdKitError?) {
+    Log.e(TAG, "Failed: ${error?.code}")  // .code is now a LoadAdError.ErrorCode enum, still fine to log
+}
+```
+
+**2. You use the raw-callback overload of `AdManager.loadInterstitialAd`.**
+
+```kotlin
+// Before
+AdManager.getInstance().loadInterstitialAd(context, adUnitId,
+    object : com.google.android.gms.ads.interstitial.InterstitialAdLoadCallback() {
+        override fun onAdLoaded(ad: com.google.android.gms.ads.interstitial.InterstitialAd) { }
+        override fun onAdFailedToLoad(error: com.google.android.gms.ads.LoadAdError) { }
+    })
+
+// After
+AdManager.getInstance().loadInterstitialAd(context, adUnitId,
+    object : com.google.android.libraries.ads.mobile.sdk.common.AdLoadCallback<
+        com.google.android.libraries.ads.mobile.sdk.interstitial.InterstitialAd> {
+        override fun onAdLoaded(ad: InterstitialAd) { }
+        override fun onAdFailedToLoad(adError: LoadAdError) { }
+    })
+```
+
+**3. You supply a custom native ad layout XML.**
+
+```xml
+<!-- Before -->
+<com.google.android.gms.ads.nativead.NativeAdView ...>
+    <com.google.android.gms.ads.nativead.MediaView android:id="@+id/ad_media" ... />
+    <com.google.android.gms.ads.nativead.AdChoicesView android:id="@+id/ad_choices_view" ... />
+</com.google.android.gms.ads.nativead.NativeAdView>
+
+<!-- After -->
+<com.google.android.libraries.ads.mobile.sdk.nativead.NativeAdView ...>
+    <com.google.android.libraries.ads.mobile.sdk.nativead.MediaView android:id="@+id/ad_media" ... />
+    <com.google.android.libraries.ads.mobile.sdk.common.AdChoicesView android:id="@+id/ad_choices_view" ... />
+</com.google.android.libraries.ads.mobile.sdk.nativead.NativeAdView>
+```
+
+**4. Your Compose callback lambdas' parameter types are explicitly typed.**
+
+If you wrote `onAdFailedToLoad: (com.google.android.gms.ads.LoadAdError?) -> Unit = { ... }` explicitly rather than letting Kotlin infer the type from the composable's signature, update the import to `com.google.android.libraries.ads.mobile.sdk.common.LoadAdError`.
+
+**Everything else:**
+
+- Call `MobileAds.initialize()` once at app startup if you haven't already — see [Next-Gen GMA SDK](#next-gen-gma-sdk). AdManageKit doesn't do this for you.
+- Bump `compileSdk` to **37+**.
+- If you relied on `BannerAdView`/`BannerAdProvider`'s `pause()`/`resume()` actually pausing ad refresh, that's now a no-op — the Next-Gen SDK's `AdView` doesn't expose it.
+- Google Play Billing 9.1.0 needs no changes if you only use `AppPurchase`/`PurchaseItem`.
+
+See [Release Notes v4.2.0](docs/release-notes/RELEASE_NOTES_v4.2.0.md) for the full technical writeup.
+
 ### Migrating to 3.0.0
 
 Version 3.0.0 is **fully backward compatible**. Optionally adopt new features: