feat(android): support android billing client 8.2.0 (#3103)

## Summary

This release adds support for **Google Play Billing Library 8.2.0**
features, including the new **Billing Programs API** for external
billing and **one-time product discount support** from Billing Library
7.0+.

## New Features

### 1. Billing Programs API (Android 8.2.0+)

New methods for handling external billing programs:

- `isBillingProgramAvailableAndroid(program)` - Check if a billing
program is available for the user
- `createBillingProgramReportingDetailsAndroid(program)` - Get external
transaction token for reporting
- `launchExternalLinkAndroid(params)` - Launch external link for billing
programs

**Supported Programs:**
- `external-offer` - External offer programs
- `external-content-link` - External content link programs

```tsx
import {
  isBillingProgramAvailableAndroid,
  createBillingProgramReportingDetailsAndroid,
  launchExternalLinkAndroid,
} from 'react-native-iap';

// Step 1: Check availability
const result = await isBillingProgramAvailableAndroid('external-offer');
if (!result.isAvailable) return;

// Step 2: Launch external link
await launchExternalLinkAndroid({
  billingProgram: 'external-offer',
  launchMode: 'launch-in-external-browser-or-app',
  linkType: 'link-to-digital-content-offer',
  linkUri: 'https://your-payment-site.com',
});

// Step 3: Get reporting token
const details = await createBillingProgramReportingDetailsAndroid('external-offer');
// Report token to Google Play within 24 hours
```

### 2. One-Time Product Discounts (Android 7.0+)

`oneTimePurchaseOfferDetailsAndroid` is now an **array** to support
multiple offers with discounts.

**New Fields:**
- `offerId` - Unique offer identifier
- `fullPriceMicros` - Original price before discount
- `discountDisplayInfo` - Percentage and amount discount info
- `limitedQuantityInfo` - Purchase quantity limits
- `validTimeWindow` - Offer validity period
- `preorderDetailsAndroid` - Preorder release info
- `rentalDetailsAndroid` - Rental period info

### 3. Purchase Suspension Status (Android 8.1.0+)

- Added `isSuspendedAndroid` field to `PurchaseAndroid` type

## Breaking Changes

### `oneTimePurchaseOfferDetailsAndroid` Type Change

**Before (14.5.x):**
```ts
oneTimePurchaseOfferDetailsAndroid?: ProductAndroidOneTimePurchaseOfferDetail | null;
```

**After (14.6.0):**
```ts
oneTimePurchaseOfferDetailsAndroid?: ProductAndroidOneTimePurchaseOfferDetail[] | null;
```

**Migration:** Update code that accesses this field to handle arrays:
```ts
// Before
const price = product.oneTimePurchaseOfferDetailsAndroid?.formattedPrice;

// After
const offers = product.oneTimePurchaseOfferDetailsAndroid;
const price = offers?.[0]?.formattedPrice;
```

## New Types

```ts
// Billing Programs
type BillingProgramAndroid = 'unspecified' | 'external-content-link' | 'external-offer';
type ExternalLinkLaunchModeAndroid = 'unspecified' | 'launch-in-external-browser-or-app' | 'caller-will-launch-link';
type ExternalLinkTypeAndroid = 'unspecified' | 'link-to-digital-content-offer' | 'link-to-app-download';

interface LaunchExternalLinkParamsAndroid {
  billingProgram: BillingProgramAndroid;
  launchMode: ExternalLinkLaunchModeAndroid;
  linkType: ExternalLinkTypeAndroid;
  linkUri: string;
}

interface BillingProgramAvailabilityResultAndroid {
  billingProgram: BillingProgramAndroid;
  isAvailable: boolean;
}

interface BillingProgramReportingDetailsAndroid {
  billingProgram: BillingProgramAndroid;
  externalTransactionToken: string;
}

// One-Time Product Discounts
interface DiscountDisplayInfoAndroid {
  percentageDiscount?: number | null;
  discountAmount?: DiscountAmountAndroid | null;
}

interface DiscountAmountAndroid {
  discountAmountMicros: string;
  formattedDiscountAmount: string;
}

interface LimitedQuantityInfoAndroid {
  maximumQuantity: number;
  remainingQuantity: number;
}

interface ValidTimeWindowAndroid {
  startTimeMillis: string;
  endTimeMillis: string;
}

interface PreorderDetailsAndroid {
  preorderReleaseTimeMillis: string;
  preorderPresaleEndTimeMillis: string;
}

interface RentalDetailsAndroid {
  rentalPeriod: string;
  rentalExpirationPeriod?: string | null;
}
```

## OpenIAP Updates

- **openiap-google**: [1.3.10 →
1.3.12](hyodotdev/openiap@google-v1.3.10...google-v1.3.12)
- **openiap-gql**: [1.3.0 →
1.3.2](hyodotdev/openiap@1.3.0...1.3.2)

## Dependency Updates

- **Kotlin**: 2.1.20 → 2.2.0

## Documentation

- Added versioned docs for 14.5 (preserving previous API documentation)
- Updated types documentation with new Android discount fields
- Updated alternative billing guide with Billing Programs API
- Added release blog post for 14.6.0

## Files Changed

### Core Implementation
- `android/src/main/java/com/margelo/nitro/iap/HybridRnIap.kt` - Billing
Programs API implementation
- `ios/HybridRnIap.swift` - iOS stub implementations for cross-platform
API
- `src/specs/RnIap.nitro.ts` - Nitro interface definitions
- `src/types.ts` - TypeScript type definitions
- `src/index.ts` - Public API exports

### Example App
- `example/screens/AlternativeBilling.tsx` - Billing Programs API demo
with mode selector
- `example/screens/AllProducts.tsx` - One-time offer discount display
- `example/src/components/AndroidOneTimeOfferDetails.tsx` - Shared
discount component

### Documentation
- `docs/blog/2025-12-11-release-14.6.0-billing-programs.md` - Release
blog post
- `docs/docs/api/types.md` - Updated type documentation
- `docs/docs/api/methods/core-methods.md` - New method documentation
- `docs/docs/guides/alternative-billing.md` - Billing Programs guide
- `docs/docs/examples/alternative-billing.md` - Updated examples
- `docs/versioned_docs/version-14.5/` - Complete 14.5 version
documentation

## Testing

- Added tests for Android one-time purchase offer array handling
- Example app includes full Billing Programs API flow demonstration

## References

- [Google Play Billing Library 8.2.0 Release
Notes](https://developer.android.com/google/play/billing/release-notes#8-2-0)
- [Google Play Billing
Programs](https://developer.android.com/google/play/billing/billing-programs)
- [Google Play One-Time Product
Discounts](https://developer.android.com/google/play/billing/integrate#one-time-discounts)


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Google Play Billing Programs API (Android 8.2.0+) —
enable/availability/reporting and external-link launching; richer
Android one‑time offer metadata; purchase suspended flag; example app
verification UI and Android deep‑link flow.

* **Breaking Changes**
* oneTimePurchaseOfferDetailsAndroid changed from a single object to an
array.

* **Documentation**
* Extensive docs, guides and examples for Billing Programs, alternative
billing, offers, installation, error handling, and troubleshooting.

* **Chores**
* Kotlin requirement bumped to 2.2.0+ and Billing Library references
updated.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: hyochan

android/src/main/java/com/margelo/nitro/iap/HybridRnIap.kt

@@ -31,6 +31,11 @@ import dev.hyo.openiap.InitConnectionConfig as OpenIapInitConnectionConfig
 import dev.hyo.openiap.listener.OpenIapPurchaseErrorListener
 import dev.hyo.openiap.listener.OpenIapPurchaseUpdateListener
 import dev.hyo.openiap.listener.OpenIapUserChoiceBillingListener
+import dev.hyo.openiap.BillingProgramAndroid as OpenIapBillingProgramAndroid
+import dev.hyo.openiap.LaunchExternalLinkParamsAndroid as OpenIapLaunchExternalLinkParams
+import dev.hyo.openiap.ExternalLinkLaunchModeAndroid as OpenIapExternalLinkLaunchMode
+import dev.hyo.openiap.ExternalLinkTypeAndroid as OpenIapExternalLinkType
+import dev.hyo.openiap.store.OpenIapStore
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
 import kotlinx.coroutines.CompletableDeferred
@@ -815,20 +820,59 @@ class HybridRnIap : HybridRnIapSpec() {
             is ProductAndroid -> product.subscriptionOfferDetailsAndroid.orEmpty()
             else -> emptyList()
         }
-        val oneTimeOffer = when (product) {
+        val oneTimeOffers = when (product) {
             is ProductSubscriptionAndroid -> product.oneTimePurchaseOfferDetailsAndroid
             is ProductAndroid -> product.oneTimePurchaseOfferDetailsAndroid
             else -> null
         }
 
         val subscriptionOffersJson = subscriptionOffers.takeIf { it.isNotEmpty() }?.let { serializeSubscriptionOffers(it) }
-        val oneTimeOfferNitro = oneTimeOffer?.let { otp ->
+        val oneTimeOffersNitro = oneTimeOffers?.map { otp ->
             NitroOneTimePurchaseOfferDetail(
                 formattedPrice = otp.formattedPrice,
                 priceAmountMicros = otp.priceAmountMicros,
-                priceCurrencyCode = otp.priceCurrencyCode
+                priceCurrencyCode = otp.priceCurrencyCode,
+                offerId = otp.offerId,
+                offerToken = otp.offerToken,
+                offerTags = otp.offerTags.toTypedArray(),
+                fullPriceMicros = otp.fullPriceMicros,
+                discountDisplayInfo = otp.discountDisplayInfo?.let { discount ->
+                    NitroDiscountDisplayInfoAndroid(
+                        percentageDiscount = discount.percentageDiscount?.toDouble(),
+                        discountAmount = discount.discountAmount?.let { amount ->
+                            NitroDiscountAmountAndroid(
+                                discountAmountMicros = amount.discountAmountMicros,
+                                formattedDiscountAmount = amount.formattedDiscountAmount
+                            )
+                        }
+                    )
+                },
+                validTimeWindow = otp.validTimeWindow?.let { window ->
+                    NitroValidTimeWindowAndroid(
+                        startTimeMillis = window.startTimeMillis,
+                        endTimeMillis = window.endTimeMillis
+                    )
+                },
+                limitedQuantityInfo = otp.limitedQuantityInfo?.let { info ->
+                    NitroLimitedQuantityInfoAndroid(
+                        maximumQuantity = info.maximumQuantity.toDouble(),
+                        remainingQuantity = info.remainingQuantity.toDouble()
+                    )
+                },
+                preorderDetailsAndroid = otp.preorderDetailsAndroid?.let { preorder ->
+                    NitroPreorderDetailsAndroid(
+                        preorderPresaleEndTimeMillis = preorder.preorderPresaleEndTimeMillis,
+                        preorderReleaseTimeMillis = preorder.preorderReleaseTimeMillis
+                    )
+                },
+                rentalDetailsAndroid = otp.rentalDetailsAndroid?.let { rental ->
+                    NitroRentalDetailsAndroid(
+                        rentalPeriod = rental.rentalPeriod,
+                        rentalExpirationPeriod = rental.rentalExpirationPeriod
+                    )
+                }
             )
-        }
+        }?.toTypedArray()
 
         var originalPriceAndroid: String? = null
         var originalPriceAmountMicrosAndroid: Double? = null
@@ -839,7 +883,7 @@ class HybridRnIap : HybridRnIapSpec() {
         var freeTrialPeriodAndroid: String? = null
 
         if (product.type == ProductType.InApp) {
-            oneTimeOffer?.let { otp ->
+            oneTimeOffers?.firstOrNull()?.let { otp ->
                 originalPriceAndroid = otp.formattedPrice
                 originalPriceAmountMicrosAndroid = otp.priceAmountMicros.toDoubleOrNull()
             }
@@ -903,7 +947,7 @@ class HybridRnIap : HybridRnIapSpec() {
             subscriptionPeriodAndroid = subscriptionPeriodAndroid,
             freeTrialPeriodAndroid = freeTrialPeriodAndroid,
             subscriptionOfferDetailsAndroid = subscriptionOffersJson,
-            oneTimePurchaseOfferDetailsAndroid = oneTimeOfferNitro
+            oneTimePurchaseOfferDetailsAndroid = oneTimeOffersNitro
         )
     }
 
@@ -957,7 +1001,8 @@ class HybridRnIap : HybridRnIapSpec() {
             packageNameAndroid = androidPurchase?.packageNameAndroid,
             obfuscatedAccountIdAndroid = androidPurchase?.obfuscatedAccountIdAndroid,
             obfuscatedProfileIdAndroid = androidPurchase?.obfuscatedProfileIdAndroid,
-            developerPayloadAndroid = androidPurchase?.developerPayloadAndroid
+            developerPayloadAndroid = androidPurchase?.developerPayloadAndroid,
+            isSuspendedAndroid = androidPurchase?.isSuspendedAndroid
         )
     }
 
@@ -1341,6 +1386,127 @@ class HybridRnIap : HybridRnIapSpec() {
         }
     }
 
+    // -------------------------------------------------------------------------
+    // Billing Programs API (Android 8.2.0+)
+    // -------------------------------------------------------------------------
+
+    // Create OpenIapStore lazily for Billing Programs API
+    private val openIapStore: OpenIapStore by lazy { OpenIapStore(context) }
+
+    override fun enableBillingProgramAndroid(program: BillingProgramAndroid) {
+        RnIapLog.payload("enableBillingProgramAndroid", mapOf("program" to program.name))
+        try {
+            val openIapProgram = mapBillingProgram(program)
+            openIapStore.enableBillingProgram(openIapProgram)
+            RnIapLog.result("enableBillingProgramAndroid", true)
+        } catch (err: Throwable) {
+            RnIapLog.failure("enableBillingProgramAndroid", err)
+            // enableBillingProgram is void, so we just log the error
+        }
+    }
+
+    override fun isBillingProgramAvailableAndroid(program: BillingProgramAndroid): Promise<NitroBillingProgramAvailabilityResultAndroid> {
+        return Promise.async {
+            RnIapLog.payload("isBillingProgramAvailableAndroid", mapOf("program" to program.name))
+            try {
+                initConnection(null).await()
+                val openIapProgram = mapBillingProgram(program)
+                val result = openIapStore.isBillingProgramAvailable(openIapProgram)
+                val nitroResult = NitroBillingProgramAvailabilityResultAndroid(
+                    billingProgram = program,
+                    isAvailable = result.isAvailable
+                )
+                RnIapLog.result("isBillingProgramAvailableAndroid", mapOf("isAvailable" to result.isAvailable))
+                nitroResult
+            } catch (err: Throwable) {
+                RnIapLog.failure("isBillingProgramAvailableAndroid", err)
+                val errorType = parseOpenIapError(err)
+                throw OpenIapException(toErrorJson(errorType, debugMessage = err.message))
+            }
+        }
+    }
+
+    override fun createBillingProgramReportingDetailsAndroid(program: BillingProgramAndroid): Promise<NitroBillingProgramReportingDetailsAndroid> {
+        return Promise.async {
+            RnIapLog.payload("createBillingProgramReportingDetailsAndroid", mapOf("program" to program.name))
+            try {
+                initConnection(null).await()
+                val openIapProgram = mapBillingProgram(program)
+                val result = openIapStore.createBillingProgramReportingDetails(openIapProgram)
+                val nitroResult = NitroBillingProgramReportingDetailsAndroid(
+                    billingProgram = program,
+                    externalTransactionToken = result.externalTransactionToken
+                )
+                RnIapLog.result("createBillingProgramReportingDetailsAndroid", mapOf("hasToken" to true))
+                nitroResult
+            } catch (err: Throwable) {
+                RnIapLog.failure("createBillingProgramReportingDetailsAndroid", err)
+                val errorType = parseOpenIapError(err)
+                throw OpenIapException(toErrorJson(errorType, debugMessage = err.message))
+            }
+        }
+    }
+
+    override fun launchExternalLinkAndroid(params: NitroLaunchExternalLinkParamsAndroid): Promise<Boolean> {
+        return Promise.async {
+            RnIapLog.payload("launchExternalLinkAndroid", mapOf(
+                "billingProgram" to params.billingProgram.name,
+                "launchMode" to params.launchMode.name,
+                "linkType" to params.linkType.name,
+                "linkUri" to params.linkUri
+            ))
+            try {
+                initConnection(null).await()
+
+                val activity = withContext(Dispatchers.Main) {
+                    runCatching { context.currentActivity }.getOrNull()
+                } ?: throw OpenIapException(toErrorJson(OpenIAPError.DeveloperError, debugMessage = "Activity not available"))
+
+                val openIapParams = OpenIapLaunchExternalLinkParams(
+                    billingProgram = mapBillingProgram(params.billingProgram),
+                    launchMode = mapExternalLinkLaunchMode(params.launchMode),
+                    linkType = mapExternalLinkType(params.linkType),
+                    linkUri = params.linkUri
+                )
+
+                val result = withContext(Dispatchers.Main) {
+                    openIapStore.launchExternalLink(activity, openIapParams)
+                }
+                RnIapLog.result("launchExternalLinkAndroid", result)
+                result
+            } catch (err: Throwable) {
+                RnIapLog.failure("launchExternalLinkAndroid", err)
+                val errorType = parseOpenIapError(err)
+                throw OpenIapException(toErrorJson(errorType, debugMessage = err.message))
+            }
+        }
+    }
+
+    // Billing Programs helper functions
+    private fun mapBillingProgram(program: BillingProgramAndroid): OpenIapBillingProgramAndroid {
+        return when (program) {
+            BillingProgramAndroid.UNSPECIFIED -> OpenIapBillingProgramAndroid.Unspecified
+            BillingProgramAndroid.EXTERNAL_CONTENT_LINK -> OpenIapBillingProgramAndroid.ExternalContentLink
+            BillingProgramAndroid.EXTERNAL_OFFER -> OpenIapBillingProgramAndroid.ExternalOffer
+        }
+    }
+
+    private fun mapExternalLinkLaunchMode(mode: ExternalLinkLaunchModeAndroid): OpenIapExternalLinkLaunchMode {
+        return when (mode) {
+            ExternalLinkLaunchModeAndroid.UNSPECIFIED -> OpenIapExternalLinkLaunchMode.Unspecified
+            ExternalLinkLaunchModeAndroid.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP -> OpenIapExternalLinkLaunchMode.LaunchInExternalBrowserOrApp
+            ExternalLinkLaunchModeAndroid.CALLER_WILL_LAUNCH_LINK -> OpenIapExternalLinkLaunchMode.CallerWillLaunchLink
+        }
+    }
+
+    private fun mapExternalLinkType(type: ExternalLinkTypeAndroid): OpenIapExternalLinkType {
+        return when (type) {
+            ExternalLinkTypeAndroid.UNSPECIFIED -> OpenIapExternalLinkType.Unspecified
+            ExternalLinkTypeAndroid.LINK_TO_DIGITAL_CONTENT_OFFER -> OpenIapExternalLinkType.LinkToDigitalContentOffer
+            ExternalLinkTypeAndroid.LINK_TO_APP_DOWNLOAD -> OpenIapExternalLinkType.LinkToAppDownload
+        }
+    }
+
     // -------------------------------------------------------------------------
     // External Purchase (iOS) - Not supported on Android
     // -------------------------------------------------------------------------