admanagekit-mcp-server 1.2.2 → 1.2.3

package/content/README.md

@@ -5,7 +5,11 @@
 
 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.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).
+**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).
 
@@ -195,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.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: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.3'
+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.3'
+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).
@@ -777,6 +781,7 @@ 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)

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.3
+# 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.3
+# 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.3
+**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.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: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.3
+# 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.3
+**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.3'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.3'
+    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.3'
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.3'
+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

package/content/wiki/Configuration.md

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

package/content/wiki/Home.md

@@ -6,12 +6,22 @@
 
 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.3`**
+**Latest Version: `4.4.4`**
+
+## What's New in 4.4.4
+
+Critical billing hotfix, no API changes. **If you ship the billing module on 4.4.3, upgrade.**
+
+- **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`
 
 ## 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
@@ -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.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: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.3'
+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.3'
+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.3
+# 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.3
+**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.3'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.3'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.3'
+    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.3'
+    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.3
+# 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.3
+**Library Version**: v4.4.4
 
 ## Installation
 
 ```groovy
 dependencies {
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit: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: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.3"
-    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.3"
+    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.3"
+    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.3
+# 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.3
+**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.3'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.3'
+    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.3"
-    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.3"
-    implementation "com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v4.4.3"
+    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.2",
+  "version": "1.2.3",
   "description": "MCP server for AdManageKit Android library - documentation lookup and code generation",
   "main": "dist/index.js",
   "bin": {