admanagekit-mcp-server 1.2.1 → 1.2.3

package/content/README.md

@@ -5,7 +5,13 @@
 
 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 `4.4.2`** is a bug-fix release. No API changed, but several fixes are user-visible and two affect revenue: rewarded ads could **crash the app** (every show-path callback, including `onRewardEarned`, was delivered on a background thread), a **completed purchase could fail to disable ads** until the next launch, **blank gaps** were left where banner/native slots should have collapsed for premium users and after failed loads (in both XML and Compose), and app open ads could appear over screens excluded via `disableAppOpenAdsTemporarily()`. Also fixes a `BannerAdView` leak that kept requesting ads after detach. Two deliberate behavior changes: an account-hold subscription no longer disables ads, and premium users no longer reserve ad space in Compose. See [Release Notes v4.4.2](docs/release-notes/RELEASE_NOTES_v4.4.2.md).
+**Latest Version `4.4.4`** is a **critical billing hotfix**. No API changed. It repairs a regression introduced in 4.4.3, where the Play Billing connection was never started at all: `connectToGooglePlayBilling()` guarded on `billingClient.isReady()`, which reports `true` the instant a client is built, so `startConnection(...)` was skipped on every fresh client. Setup never ran, no product details or entitlement were ever fetched, and there was **no failure callback and no error log** to explain it. **If you ship the billing module on 4.4.3, upgrade.** Also fixes a long-standing bug where a timed-out setup reported itself as initialized — permanently suppressing the host app's `if (!initBillingFinish) initBilling()` retry — and adds `DEBUG` logging across the billing connection lifecycle. See [Release Notes v4.4.4](docs/release-notes/RELEASE_NOTES_v4.4.4.md).
+
+> ⚠️ **4.4.3 is superseded.** Its billing regression makes purchases unusable; use 4.4.4.
+
+**Version `4.4.3`** is a bug-fix and dependency release. No API changed. Two silent-failure bugs are fixed, both of which cost money: a **rewarded load the manager had given up on could sabotage the load that replaced it** — discarding an ad a newer load had just delivered, and clearing the "loading" flag out from under a request still in flight — and **billing could stop acknowledging purchases for the rest of the process**, which lets Play auto-refund a completed purchase on day 3. Acknowledgment also no longer requires the purchase to match a configured product id. Picks up the Next-Gen GMA SDK **1.3.1**, Yandex Mobile Ads **8.3.0**, and refreshed AndroidX/Firebase/Compose BOMs. See [Release Notes v4.4.3](docs/release-notes/RELEASE_NOTES_v4.4.3.md).
+
+**Version `4.4.2`** is a bug-fix release. No API changed, but several fixes are user-visible and two affect revenue: rewarded ads could **crash the app** (every show-path callback, including `onRewardEarned`, was delivered on a background thread), a **completed purchase could fail to disable ads** until the next launch, **blank gaps** were left where banner/native slots should have collapsed for premium users and after failed loads (in both XML and Compose), and app open ads could appear over screens excluded via `disableAppOpenAdsTemporarily()`. Also fixes a `BannerAdView` leak that kept requesting ads after detach. Two deliberate behavior changes: an account-hold subscription no longer disables ads, and premium users no longer reserve ad space in Compose. See [Release Notes v4.4.2](docs/release-notes/RELEASE_NOTES_v4.4.2.md).
 
 **Version `4.4.1`** is a patch release that updates the Google Mobile Ads Next-Gen SDK to **1.3.0** (from 1.2.1) and repairs three documentation-delivery channels that had silently gone stale: the API docs build had failed on every release since the Dokka 2.x upgrade, leaving [the published KDoc](https://i2hammad.github.io/AdManageKit/) without any 4.x types; MCP server npm publishing had been broken since January 2026; and the MCP tool schemas hardcoded which versions and classes existed, so they rejected `4.4.0` as an unknown version. No AdManageKit API changed. See [Release Notes v4.4.1](docs/release-notes/RELEASE_NOTES_v4.4.1.md).
 
@@ -29,7 +35,7 @@ Since **4.2.0** the library runs on the Google Mobile Ads **Next-Gen SDK** (`ads
 
 ## Next-Gen GMA SDK
 
-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.3.0` as of 4.4.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.
+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.3.1` as of 4.4.3) 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.
 
 ### Why the move
 
@@ -193,15 +199,15 @@ dependencyResolutionManagement {
 **Step 2:** Add dependencies to your app's `build.gradle`:
 
 ```groovy
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.2'
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.2'
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.2'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.4'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.4'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.4'
 
 // For Jetpack Compose support
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v4.4.2'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v4.4.4'
 
 // For Yandex Ads multi-provider support
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v4.4.2'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v4.4.4'
 ```
 
 **Step 3:** Ensure your app's `compileSdk` is **37 or higher** (required transitively as of 4.2.0).
@@ -775,6 +781,8 @@ Register it **before** `initBilling`. Products land in `unfetched` when the id i
 - [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.4](docs/release-notes/RELEASE_NOTES_v4.4.4.md)
+- [Release Notes v4.4.3](docs/release-notes/RELEASE_NOTES_v4.4.3.md)
 - [Release Notes v4.4.2](docs/release-notes/RELEASE_NOTES_v4.4.2.md)
 - [Release Notes v4.4.1](docs/release-notes/RELEASE_NOTES_v4.4.1.md)
 - [Release Notes v4.4.0](docs/release-notes/RELEASE_NOTES_v4.4.0.md)

package/content/docs/APP_PURCHASE_GUIDE.md

@@ -128,6 +128,24 @@ PurchaseItem("premium_yearly", null, TYPE_IAP.SUBSCRIPTION)
 > call `consumePurchase(productId)` after granting items — consuming both lets
 > the item be bought again and satisfies Play's acknowledgment requirement.
 
+> **Pending purchases need one thing from you.** A pending order (cash, bank
+> transfer, parental approval) can complete hours or days later, while your app
+> is closed. `onPurchasesUpdated` only fires if the app happens to be running,
+> so Play requires apps to re-query owned purchases on every foreground.
+> `AppPurchase` queries on billing init; if your process stays alive across the
+> transition, that never runs again — so call `refreshPurchases()` from your
+> main activity's `onResume()`:
+>
+> ```kotlin
+> override fun onResume() {
+>     super.onResume()
+>     AppPurchase.getInstance().refreshPurchases()
+> }
+> ```
+>
+> It acknowledges every unacknowledged `PURCHASED` purchase it finds, which is
+> what stops a completed pending order from being auto-cancelled on day 3.
+
 ### In-App Products
 
 ```kotlin

package/content/docs/release-notes/RELEASE_NOTES_v4.4.3.md

@@ -0,0 +1,121 @@
+# Release Notes — v4.4.3
+
+**Release Date:** 2026-08-15
+
+## Overview
+
+v4.4.3 is a bug-fix and dependency release. No API was added, removed or changed. Two of the fixes are silent-failure bugs that cost real money:
+
+- **A rewarded load the manager had given up on could sabotage the load that replaced it** — throwing away an ad that had just arrived, and clearing the "loading" flag out from under a request that was still running.
+- **Billing could stop acknowledging purchases for the rest of the process**, which lets Play auto-refund a completed purchase on day 3.
+
+It also picks up the Next-Gen GMA SDK **1.3.1**, Yandex Mobile Ads **8.3.0**, and refreshed AndroidX/Firebase/Compose BOMs.
+
+Upgrading is a drop-in from 4.4.x.
+
+---
+
+## Fixed
+
+### A timed-out rewarded load could sabotage the one that replaced it
+
+`RewardedAdManager.loadRewardedAdWithTimeout(...)` stops waiting for a load once its timeout elapses — but a request handed to the SDK **cannot be cancelled**, so it keeps running and reports back whenever it finishes. Its callbacks then ran the full success/failure path as though they still spoke for the manager, even though a replacement load had started in the meantime.
+
+Concretely, a late callback from an abandoned request could:
+
+- **Throw away a perfectly good ad.** The failure path ran `rewardedAd = null` unconditionally, so a stale failure discarded an ad a *later* load had just delivered. The next `showAd()` found nothing and skipped the reward.
+- **Clear `isLoading` out from under the load that was still running**, so the manager reported itself idle while a request was in flight — letting a duplicate load start and burning an extra ad request.
+- **Fail callers queued behind a load that had not finished yet**, via `notifyPendingLoadFailure`.
+- **Schedule a retry for a request nobody was waiting on.**
+
+Every load path now claims a generation token and checks it before touching anything shared — the same mechanism `RewardedWaterfall` already used internally. A stale callback answers *its own* caller (which is still owed a result and has no other source of one) and otherwise leaves shared state alone.
+
+A late ad is **kept rather than dropped**: it is real and showable no matter which request produced it, so it is adopted for the next show whenever nothing better is already in hand. This applies to both the AdMob path and the waterfall path.
+
+Two related unconditional writes were tightened at the same time:
+
+- The direct load's failure path no longer does `rewardedAd = null` at all. A failed request means *this* request produced nothing — not that an ad obtained elsewhere has stopped being showable.
+- The waterfall failure path now clears `rewardedWaterfall` only when the chain being reported on is still the one it installed (`if (rewardedWaterfall === waterfall)`), so a newer load's chain — or a late chain adopted in the meantime — is not discarded by an older failure.
+
+> This is the same class of bug as the v4.4.2 `AdManager` duplicate-callback fix, in the one manager that still resolved in-flight state with plain flags.
+
+### Billing could stop acknowledging purchases for the rest of the process
+
+`AppPurchase` gated every re-query on `isServiceConnected`, an `AtomicBoolean` written **only** by `onBillingSetupFinished` and cleared by `onBillingServiceDisconnected`.
+
+The library enables `enableAutoServiceReconnection()`, and the SDK restores the connection on its own without necessarily re-firing `onBillingSetupFinished`. So after a single disconnect the flag could stay `false` permanently — while the client itself was perfectly ready — silently disabling:
+
+- `verifyPurchased(...)` and `updatePurchaseStatus()` — entitlement re-checks
+- `refreshPurchases(...)` — including **the acknowledgment retry**
+- `consumePurchase(...)`, `queryProductDetails(...)`
+- `connectToGooglePlayBilling()`, which skipped reconnecting because it believed it was still connected
+
+That last one matters most: **Play auto-refunds any purchase left unacknowledged for 3 days.** A user who bought while the flag was stuck could be charged, granted the entitlement, and then silently refunded — with the app still treating them as a paying customer.
+
+All of these now consult the client's own live state (`billingClient.isReady()`) instead of the latched flag. `onBillingServiceDisconnected` also stops clearing `isBillingAvailable`: the client *was* set up successfully, and `isAvailable()` ANDs that fact with the live readiness check, so it now reports `false` only while the service is actually down rather than latching `false` for the rest of the process.
+
+### Acknowledgment required the purchase to match a configured product id
+
+In both `verifyPurchased(...)` and `updatePurchaseStatus()`, `acknowledgePurchaseIfNeeded(purchase)` was called *inside* the loop that matched the purchase against `inAppProductIdList` / `subProductIdList`. A `PURCHASED` order whose id the current build does not list was never acknowledged — and so was auto-refunded on day 3.
+
+That is not a hypothetical set: promo-code grants, products dropped from a newer release, a Play Console id typo, and a user who purchased on a build that configured more ids than the one they are running now all land here.
+
+Acknowledgment now happens **before** the id match, unconditionally for every `PURCHASED` purchase. Entitlement still requires a configured id — only the acknowledgment was decoupled, since the 3-day clock does not care whether your build recognises the product.
+
+---
+
+## Dependencies
+
+| Dependency | 4.4.2 | 4.4.3 |
+| --- | --- | --- |
+| Google Mobile Ads Next-Gen SDK | 1.3.0 | **1.3.1** |
+| Yandex Mobile Ads | 8.2.0 | **8.3.0** |
+| Compose BOM | 2026.06.01 | **2026.08.00** |
+| Firebase BOM | 34.15.0 | **34.17.0** |
+| AndroidX AppCompat | 1.7.1 | **1.8.0** |
+| ConstraintLayout | 2.2.1 | **2.2.2** |
+| org.json (test only) | 20250517 | **20260719** |
+
+Google Play Billing stays at **9.1.0** and Kotlin at **2.2.10**.
+
+### Sample app now compiles at JVM 17
+
+The `app` sample module was the only module still pinned to `jvmTarget = "1.8"`, while all five published modules use 17. Compose BOM 2026.08.00 ships artifacts compiled at JVM 11+, which cannot be inlined into 1.8 bytecode — so the bump broke `assembleDebug` on the sample with `Cannot inline bytecode built with JVM target 11 into bytecode that is being built with JVM target 1.8`.
+
+The sample now uses `VERSION_17` / `jvmTarget = "17"`, matching the library modules. **This does not affect the published artifacts** — their compile options were already 17 and are unchanged. It is noted here only because anyone building the repo from source would otherwise hit it.
+
+---
+
+## Documentation
+
+`docs/APP_PURCHASE_GUIDE.md` now documents what pending purchases require from the host app. A pending order (cash, bank transfer, parental approval) can complete hours or days later while the app is closed; `onPurchasesUpdated` only fires if the app happens to be running, so Play requires apps to re-query owned purchases on every foreground. `AppPurchase` queries on billing init, and if the process survives the transition that never runs again — so the guide now shows calling `refreshPurchases()` from the main activity's `onResume()`, and explains that this is what stops a completed pending order from being auto-cancelled on day 3.
+
+---
+
+## Verification
+
+`assembleDebug` succeeds and `testDebugUnitTest --rerun-tasks` passes **176 tests, 0 failures** — 173 existing plus 3 new `RewardedAdManagerStaleLoadTest` cases pinning down the stale-load contract:
+
+- an abandoned load's failure must not discard an ad another load produced
+- an abandoned load's failure must not clear the replacement's `isLoading`
+- an ad arriving after the timeout is kept for the next show rather than dropped
+
+The tests drive the waterfall path, whose providers are fakes the test can complete by hand; the AdMob path runs the same generation checks over a static SDK entry point.
+
+The billing changes are **not** covered by automated tests — both depend on `BillingClient` connection-state transitions that the existing `ProductDetailsFactory`-based harness cannot drive. They were verified by reading every call site of `isServiceConnected` and every `acknowledgePurchaseIfNeeded` path; on-device verification against a Play test track is recommended.
+
+---
+
+## Upgrading
+
+Drop-in from 4.4.x. No source changes required.
+
+If your app relies on pending purchases, add the `onResume()` refresh described under [Documentation](#documentation) — the library cannot do this for you, since it does not own your activity lifecycle.
+
+```groovy
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.3'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.3'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.3'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v4.4.3'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v4.4.3'
+```

package/content/docs/release-notes/RELEASE_NOTES_v4.4.4.md

@@ -0,0 +1,85 @@
+# Release Notes — v4.4.4
+
+**Release Date:** 2026-08-15
+
+## Overview
+
+v4.4.4 is a **critical billing hotfix**. No API was added, removed or changed.
+
+It repairs a regression introduced in **v4.4.3**: on that version the Play Billing connection is never started at all, so billing is dead for the life of the process — no product details, no offers, no entitlement, and no error anywhere to explain it. **Anyone on 4.4.3 who ships the billing module should upgrade immediately.**
+
+It also fixes a long-standing bug where a billing setup that *timed out* reported itself as initialized, which permanently suppressed the host app's retry.
+
+Upgrading is a drop-in from 4.4.x.
+
+---
+
+## Fixed
+
+### Billing never connected on 4.4.3 (regression)
+
+v4.4.3 replaced the latched `isServiceConnected` flag with the client's own `billingClient.isReady()` everywhere, to stop `enableAutoServiceReconnection()` from leaving re-queries permanently disabled. That was right for the *re-query* paths — but it was also applied to `connectToGooglePlayBilling()`, which is the path that starts the connection in the first place:
+
+```java
+// 4.4.3
+if (!isClientReady()) {           // isReady() is already true on a fresh client
+    billingClient.startConnection(...);
+}
+```
+
+Since `enableAutoServiceReconnection()` was added, a `BillingClient` reports `isReady() == true` **the instant it is built**, before any setup has run. So the guard was false on every fresh client and `startConnection(...)` was skipped:
+
+- setup never began, so **neither branch of `onBillingSetupFinished` ever fired**
+- `isBillingAvailable` and `isBillingInitialized` stayed `false`
+- `queryProductDetails(...)` and `verifyPurchased(...)` — both invoked from the success branch — never ran, so `productDetailsMap` stayed empty
+- `isAvailable()` returned `false` forever, and `setBillingListener(...)` only ever reported `SERVICE_TIMEOUT`
+
+The user-visible result is a paywall that renders no prices and a purchase flow that cannot be launched, with **no failure callback and no error log** to point at the cause.
+
+`connectToGooglePlayBilling()` now guards on `isServiceConnected` — our own flag, written only by `onBillingSetupFinished` and cleared by `onBillingServiceDisconnected` — which is the right question for "has setup run?", as distinct from "can the client serve a call right now?" that `isClientReady()` answers for the re-query paths. Those paths are unchanged from 4.4.3 and keep the acknowledgment fix intact.
+
+> Both flags are load-bearing and they are not interchangeable: `isServiceConnected` guards *starting* the connection, `isClientReady()` guards *using* it.
+
+### A timed-out billing setup reported itself as initialized
+
+In `setBillingListener(listener, timeout)`, the timeout runnable set `isBillingInitialized = TRUE` before delivering `SERVICE_TIMEOUT`:
+
+```java
+// before
+this.isBillingInitialized = Boolean.TRUE;
+billingListener.onInitBillingFinished(BillingClient.BillingResponseCode.SERVICE_TIMEOUT);
+```
+
+That path means Play did **not** answer in time — setup did not finish. It is the same outcome the `onBillingSetupFinished` failure branch reports, and that branch sets `FALSE`.
+
+Reporting `TRUE` told every caller billing was up when it was not. The common host-app guard —
+
+```kotlin
+if (!AppPurchase.getInstance().initBillingFinish) { /* retry init */ }
+```
+
+— went permanently quiet, so a connection that timed out once could never be retried for the life of the process, and screens rendered "no offers" for what was really a dead client. It now sets `FALSE`. The listener still receives `SERVICE_TIMEOUT` either way, so callers that only wait on the callback are unaffected.
+
+This bug predates 4.4.3 (it dates to the June 2026 billing listener work) but was largely masked until the regression above made timeouts the normal outcome.
+
+## Changed
+
+- **Billing connection lifecycle logging.** `initBilling`, `connectToGooglePlayBilling`, `onBillingSetupFinished` and `onBillingServiceDisconnected` now log their state at `DEBUG` (`Log.d`) under the existing `AppPurchase` tag — client built/null, `isReady()`, `isServiceConnected`, and the setup response code plus debug message. The failure above produced complete silence; this class of problem is now visible in `logcat` without attaching a debugger. No behavior depends on it, and it costs nothing beyond the log calls.
+
+---
+
+## Upgrading
+
+```gradle
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.4'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.4'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.4'
+```
+
+No code changes are required. Nothing else in the library changed — no dependency updates, no ad-side changes.
+
+To confirm the fix on device, filter `logcat` for the `AppPurchase` tag: you should see `connectToGooglePlayBilling: ... serviceConnected=false` followed by `onBillingSetupFinished: code=0`.
+
+## Notes
+
+- Neither fix is covered by an automated test — both depend on `BillingClient` connection-state transitions the current harness cannot drive (the same limitation noted for the 4.4.3 billing changes), so on-device verification against a Play test track is recommended. The existing 176 tests are unaffected and still pass

package/content/wiki/Ad-Loading-Strategies.md

@@ -1,4 +1,4 @@
-# Ad Loading Strategies - AdManageKit v4.4.2
+# Ad Loading Strategies - AdManageKit v4.4.4
 
 ## Overview
 

package/content/wiki/App-Open-Ads.md

@@ -1,10 +1,10 @@
-# App Open Ads - AdManageKit v4.4.2
+# App Open Ads - AdManageKit v4.4.4
 
 ## Overview
 
 AdManageKit provides lifecycle-aware app open ad management through `AppOpenManager`. App open ads display when users launch or return to your app, with support for loading strategies, ad freshness enforcement, welcome dialogs, activity/screen exclusion, and the multi-provider waterfall.
 
-**Library Version**: v4.4.2
+**Library Version**: v4.4.4
 
 ## Features
 
@@ -23,9 +23,9 @@ AdManageKit provides lifecycle-aware app open ad management through `AppOpenMana
 
 ```groovy
 dependencies {
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.2'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.2'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.2'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.4'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.4'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.4'
 }
 ```
 

package/content/wiki/Banner-Ads.md

@@ -1,10 +1,10 @@
-# Banner Ads - AdManageKit v4.4.2
+# Banner Ads - AdManageKit v4.4.4
 
 ## Overview
 
 AdManageKit provides `BannerAdView` for banner ad integration with every standard AdMob size, adaptive banners, collapsible banners, a size-aware loading shimmer, auto-refresh, and smart retry logic.
 
-**Library Version**: v4.4.2
+**Library Version**: v4.4.4
 
 ## Features
 
@@ -23,8 +23,8 @@ AdManageKit provides `BannerAdView` for banner ad integration with every standar
 
 ```groovy
 dependencies {
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.2'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.2'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.4'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.4'
 }
 ```
 

package/content/wiki/Billing-Integration.md

@@ -7,8 +7,8 @@ AdManageKit provides a comprehensive billing integration module (`admanagekit-bi
 ### 1. Add Dependency
 
 ```groovy
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.2'
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.2'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.4'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.4'
 ```
 
 ### 2. Define Products
@@ -52,6 +52,24 @@ class MyApp : Application() {
 > Only `PurchaseState.PURCHASED` grants entitlement (pending purchases do not).
 > Consumables still require a manual `consumePurchase(productId)` after granting.
 
+> **Pending purchases need one thing from you (v4.4.3).** A pending order (cash,
+> bank transfer, parental approval) can complete hours or days later, while your
+> app is closed. `onPurchasesUpdated` only fires if the app happens to be
+> running, so Play requires apps to re-query owned purchases on every foreground.
+> `AppPurchase` queries on billing init; if your process stays alive across the
+> transition, that never runs again — so call `refreshPurchases()` from your main
+> activity's `onResume()`:
+>
+> ```kotlin
+> override fun onResume() {
+>     super.onResume()
+>     AppPurchase.getInstance().refreshPurchases()
+> }
+> ```
+>
+> It acknowledges every unacknowledged `PURCHASED` purchase it finds, which is
+> what stops a completed pending order from being auto-cancelled on day 3.
+
 ### 4. Make Purchases
 
 ```kotlin

package/content/wiki/Configuration.md

@@ -1,4 +1,4 @@
-# Configuration - AdManageKit v4.4.2
+# Configuration - AdManageKit v4.4.4
 
 ## Overview
 

package/content/wiki/Home.md

@@ -6,22 +6,32 @@
 
 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: `4.4.2`**
+**Latest Version: `4.4.4`**
 
-## What's New in 4.4.2
+## What's New in 4.4.4
 
-Bug-fix release, no API changes. Two deliberate behavior changes are noted below.
+Critical billing hotfix, no API changes. **If you ship the billing module on 4.4.3, upgrade.**
 
-- **Rewarded ads could crash** — every show-path callback, including `onRewardEarned`, was delivered on a background thread
-- **A completed purchase could fail to disable ads** until the next app launch
-- **Blank gaps** where banner/native slots should have collapsed, for premium users and after a failed load, in both XML and Compose
-- **App open ads could appear over excluded screens**, including flows protected by `disableAppOpenAdsTemporarily()`
-- **`BannerAdView` leaked its Activity** and kept requesting ads after being detached
+- **Billing never connected on 4.4.3** — `connectToGooglePlayBilling()` guarded on `billingClient.isReady()`, which reports `true` the instant a client is built, so `startConnection(...)` was skipped on every fresh client. Setup never ran, no product details or entitlement were fetched, and there was no failure callback and no error log to explain it. The guard is back on `isServiceConnected`; the re-query paths keep the 4.4.3 `isReady()` fix
+- **A timed-out setup reported itself as initialized** — the `setBillingListener(listener, timeout)` timeout path set `isBillingInitialized = true` before delivering `SERVICE_TIMEOUT`, so host-app guards of the form `if (!initBillingFinish) initBilling()` went permanently quiet and the connection could never be retried. It now sets `false`
+- **Billing connection lifecycle logging** — `initBilling`, `connectToGooglePlayBilling` and both `BillingClientStateListener` callbacks now log their state at `DEBUG` under the `AppPurchase` tag, so this class of failure is visible in `logcat`
 
-> **Behavior changes:** an account-hold subscription no longer disables ads (it already reported `ON_HOLD` and failed `isSubscriptionActive()`), and premium users no longer reserve ad space in Compose.
+## What's New in 4.4.3
+
+Bug-fix and dependency release, no API changes. Two silent-failure bugs, both of which cost money.
+
+> ⚠️ 4.4.3's billing regression makes purchases unusable — use 4.4.4.
+
+- **A timed-out rewarded load could sabotage the one that replaced it** — a request handed to the SDK cannot be cancelled, and when it finally reported back it could discard an ad a *newer* load had just delivered, clear the loading flag out from under a request still in flight, and fail callers waiting on a load that had not finished. Every load path now carries a generation token, and a late ad is kept for the next show instead of dropped
+- **Billing could stop acknowledging purchases for the rest of the process** — the connection flag could latch `false` after one disconnect while the client was actually ready, disabling every purchase re-query including the acknowledgment retry. Play auto-refunds an unacknowledged purchase after 3 days
+- **Acknowledgment no longer requires a configured product id** — a `PURCHASED` order the current build does not list (promo grants, dropped products, a Console typo) was never acknowledged, and so was auto-refunded on day 3
+- **Dependencies** — Next-Gen GMA SDK 1.3.1, Yandex Mobile Ads 8.3.0, Compose BOM 2026.08.00, Firebase BOM 34.17.0, AppCompat 1.8.0
+
+> **Pending purchases need one thing from your app:** call `refreshPurchases()` from your main activity's `onResume()`. See [[Billing Integration]].
 
 ## Recent Highlights
 
+- **4.4.2** — Rewarded callbacks marshalled to the main thread (they could crash the app), a completed purchase could fail to disable ads, blank gaps where banner/native slots should have collapsed, and a `BannerAdView` Activity leak. Behavior changes: an account-hold subscription no longer disables ads, and premium users no longer reserve ad space in Compose
 - **4.4.1** — Google Mobile Ads Next-Gen SDK 1.3.0 (from 1.2.1), plus repairs to API doc generation and the MCP documentation server
 - **4.4.0** — Subscription offers can be **purchased individually** (`subscribe(activity, offer)`), offer lookup by id/base plan/tag, cross-cadence price normalization (`BillingPeriod`, `getSavingsPercent`), trial eligibility, Play Billing 9 one-time product offers, and client-side **account hold** detection. See [[Subscription Offers]]
 - **4.3.x** — All standard banner sizes (`BannerAdSize`), custom native templates, and app-open ad freshness enforcement
@@ -84,15 +94,15 @@ dependencyResolutionManagement {
 **Step 2:** Add dependencies to your app's `build.gradle`:
 
 ```groovy
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.2'
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.2'
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.2'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.4'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.4'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.4'
 
 // For Jetpack Compose support
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v4.4.2'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v4.4.4'
 
 // For Yandex Ads multi-provider support
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v4.4.2'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v4.4.4'
 ```
 
 **Step 3:** Ensure your app's `compileSdk` is **37 or higher** (required transitively as of 4.2.0).

package/content/wiki/Interstitial-Ads.md

@@ -1,10 +1,10 @@
-# Interstitial Ads - AdManageKit v4.4.2
+# Interstitial Ads - AdManageKit v4.4.4
 
 ## Overview
 
 AdManageKit provides a complete interstitial ad stack with `AdManager` and the fluent `InterstitialAdBuilder`. Features include loading strategies, automatic retry, frequency controls, splash screen support, and Jetpack Compose utilities.
 
-**Library Version**: v4.4.2
+**Library Version**: v4.4.4
 
 ## What's New
 
@@ -23,11 +23,11 @@ AdManageKit provides a complete interstitial ad stack with `AdManager` and the f
 
 ```groovy
 dependencies {
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.2'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.2'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.2'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.4'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.4'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.4'
     // Optional - Jetpack Compose
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v4.4.2'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v4.4.4'
 }
 ```
 

package/content/wiki/Jetpack-Compose.md

@@ -1,18 +1,18 @@
-# Jetpack Compose Integration - AdManageKit v4.4.2
+# Jetpack Compose Integration - AdManageKit v4.4.4
 
 ## Overview
 
 AdManageKit provides first-class Jetpack Compose support with composable functions for all ad types, state management helpers, and programmatic native ad loading.
 
-**Library Version**: v4.4.2
+**Library Version**: v4.4.4
 
 ## Installation
 
 ```groovy
 dependencies {
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.2'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.2'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v4.4.2'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.4'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.4'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v4.4.4'
 }
 ```
 

package/content/wiki/Multi-Provider-Waterfall.md

@@ -38,11 +38,11 @@ This is fully backward compatible -- if no provider chains are configured, all e
 
 ```groovy
 dependencies {
-    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.2"
-    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.2"
+    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.4"
+    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.4"
 
     // Add Yandex provider
-    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v4.4.2"
+    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v4.4.4"
 }
 ```
 

package/content/wiki/NativeAdManager.md

@@ -1,10 +1,10 @@
-# Native Ads - AdManageKit v4.4.2
+# Native Ads - AdManageKit v4.4.4
 
 ## Overview
 
 AdManageKit provides comprehensive native ad support with caching, multiple formats, and the new `NativeTemplateView` (v2.6.0+). Native ads blend seamlessly with your app's content while maximizing engagement.
 
-**Library Version**: v4.4.2
+**Library Version**: v4.4.4
 
 ## Features
 
@@ -19,8 +19,8 @@ AdManageKit provides comprehensive native ad support with caching, multiple form
 
 ```groovy
 dependencies {
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.2'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.2'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.4'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.4'
 }
 ```
 

package/content/wiki/Yandex-Integration.md

@@ -10,9 +10,9 @@ The `admanagekit-yandex` module provides Yandex Ads SDK providers for the multi-
 
 ```groovy
 dependencies {
-    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.2"
-    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.2"
-    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v4.4.2"
+    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.4"
+    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.4"
+    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v4.4.4"
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "admanagekit-mcp-server",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "MCP server for AdManageKit Android library - documentation lookup and code generation",
   "main": "dist/index.js",
   "bin": {