Fix Android purchase state mapping and improvements (#525)

## Summary

- Fix Android purchase state mapping (#524)
- Add mounted checks to prevent setState errors
- Deprecate old methods in favor of unified API
- Update documentation

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

- **New Features**
- Unified product/request API and richer iOS/Android product & purchase
metadata (StoreKit2 support, subscription details).

- **Bug Fixes**
- Corrected Android purchase-state mapping; fixed iOS subscription
loading and active-subscription detection; various null-reference fixes.

- **Improvements**
- Safer async UI handling (mounted guards), stronger type-safety,
clearer error messages, improved cross-platform subscription detection.

- **Documentation**
  - README and release notes updated with 6.3.0 migration guidance.

- **Tests**
- Test suite reorganized by business flows; coverage increased (~26% →
28.2%).

- **Chores**
  - Version bumped to 6.3.0.

Author: hyochan

CHANGELOG.md

@@ -1,5 +1,67 @@
 # CHANGELOG
 
+## 6.3.0
+
+### Bug Fixes
+
+- **CRITICAL FIX: Android Purchase State Mapping**: Fixed incorrect mapping of Android purchase states (#524)
+  - Previously mapped: 0=PURCHASED, 1=PENDING (incorrect)
+  - Now correctly maps: 0=UNSPECIFIED_STATE, 1=PURCHASED, 2=PENDING
+  - This fix aligns with official Google Play Billing documentation
+  - Prevents misinterpreting UNSPECIFIED_STATE as a completed purchase
+  - UNSPECIFIED_STATE (0) and unknown states now properly map to `PurchaseState.unspecified`
+
+### Features
+
+- **Enhanced OpenIAP Compliance**: Extended OpenIAP specification support with comprehensive field mapping
+  - Added full iOS-specific field support: `displayName`, `displayPrice`, `isFamilyShareable`, `jsonRepresentation`, `discountsIOS`, `subscription` info, and promotional offer fields
+  - Added comprehensive Android-specific field support: `originalPrice`, `originalPriceAmount`, `freeTrialPeriod`, `subscriptionOffersAndroid`, and billing cycle information
+  - Enhanced Purchase object with StoreKit 2 fields: `verificationResultIOS`, `environmentIOS`, `expirationDateIOS`, `revocationDateIOS`, and transaction metadata
+
+- **Improved Test Organization**: Restructured test suite by business flows
+  - **Purchase Flow Tests**: General purchase operations and error handling
+  - **Subscription Flow Tests**: Subscription-specific operations and lifecycle management  
+  - **Available Purchases Tests**: Purchase history, restoration, and transaction management
+  - Enhanced test coverage from 26% to 28.2%
+
+### Improvements
+
+- **Type Safety**: Enhanced type casting and JSON parsing reliability
+  - Fixed `Map<Object?, Object?>` to `Map<String, dynamic>` conversion issues
+  - Improved null safety handling for platform-specific fields
+  - Better error handling for malformed data
+
+- **Subscription Management**: Enhanced active subscription detection
+  - Improved iOS subscription detection logic for better reliability
+  - Added fallback logic for subscription identification across platforms
+
+- **Code Quality**: Comprehensive test suite improvements
+  - All 95 tests now pass consistently
+  - Flexible test assertions that adapt to mock data variations
+  - Better separation of platform-specific test scenarios
+
+### Bug Fixes
+
+- **Critical Fix**: Fixed iOS subscription loading issue where `requestProducts` with `PurchaseType.subs` returned empty arrays
+  - iOS now correctly uses `getItems` method instead of unsupported `getSubscriptions`
+  - Resolves GitHub issues where users couldn't load subscription products on iOS
+- Fixed type casting errors in purchase data conversion
+- Fixed subscription detection on iOS platform
+- Fixed Android purchase state mapping in active subscription queries
+- Resolved null reference exceptions for platform-specific fields
+- Fixed test expectations to match actual implementation behavior
+
+### Technical Improvements
+
+- Enhanced mock data consistency across test files
+- Improved JSON serialization/deserialization robustness
+- Better error messages and debugging information
+- Standardized field naming conventions following OpenIAP specification
+
+### Breaking Changes
+
+None - This version maintains full backward compatibility while extending functionality.
+
 ## 6.2.0
 
 ### Features

CLAUDE.md

@@ -20,8 +20,13 @@ Before committing any changes, run these commands in order and ensure ALL pass:
 
 - **iOS-related code**: Use `IOS` suffix (e.g., `PurchaseIOS`, `SubscriptionOfferIOS`)
   - When iOS is not the final suffix, use `Ios` (e.g., `IosManager`, `IosHelper`)
+  - For field names with iOS in the middle: use `Id` before `IOS` (e.g., `subscriptionGroupIdIOS`, `webOrderLineItemIdIOS`)
 - **Android-related code**: Use `Android` suffix (e.g., `PurchaseAndroid`, `SubscriptionOfferAndroid`)
 - **IAP-related code**: When IAP is not the final suffix, use `Iap` (e.g., `IapPurchase`, not `IAPPurchase`)
+- **ID vs Id convention**: 
+  - Use `Id` consistently across all platforms (e.g., `productId`, `transactionId`, `offerId`)
+  - When combined with platform suffixes: use `Id` before the suffix (e.g., `subscriptionGroupIdIOS`, `webOrderLineItemIdIOS`, `obfuscatedAccountIdAndroid`)
+  - Exception: Standalone iOS fields that end with ID use `ID` (e.g., `transactionID`, `webOrderLineItemID` in iOS-only contexts)
 - This applies to both functions and types
 
 ### API Method Naming

README.md

@@ -19,9 +19,15 @@
 
 ```yaml
 dependencies:
-  flutter_inapp_purchase: ^6.2.0
+  flutter_inapp_purchase: ^6.3.0
 ```
 
+## 🔄 What's New in 6.3.0
+
+**📝 [Read the full release blog post](docs/blog/2025-08-19-6.3.0.release.md)**
+
+Version 6.3.0 brings critical bug fixes, enhanced OpenIAP compliance, and improved test coverage while maintaining full backward compatibility.
+
 ## 🔧 Quick Start
 
 ### Basic Usage
@@ -35,16 +41,21 @@ final iap = FlutterInappPurchase();
 // Initialize connection
 await iap.initConnection();
 
-// Get products
-final products = await iap.getProducts(['product_id']);
+// Get products (using the new unified API)
+final products = await iap.requestProducts(
+  RequestProductsParams(
+    productIds: ['product_id'],
+    type: PurchaseType.inapp,
+  ),
+);
 
 // Request purchase
 await iap.requestPurchase(
-  RequestPurchase(
-    ios: RequestPurchaseIosProps(sku: 'product_id'),
-    android: RequestPurchaseAndroidProps(skus: ['product_id']),
+  request: RequestPurchase(
+    ios: RequestPurchaseIOS(sku: 'product_id'),
+    android: RequestPurchaseAndroid(skus: ['product_id']),
   ),
-  PurchaseType.inapp,
+  type: PurchaseType.inapp,
 );
 ```
 

android/src/main/kotlin/dev/hyo/flutterinapppurchase/AndroidInappPurchasePlugin.kt

@@ -227,19 +227,30 @@ class AndroidInappPurchasePlugin internal constructor() : MethodCallHandler,
             if (billingResult.responseCode == BillingClient.BillingResponseCode.OK) {
                 for (purchase in productDetailList) {
                     val item = JSONObject()
+                    item.put("id", purchase.orderId)
                     item.put("productId", purchase.products[0])
-                    item.put("transactionId", purchase.orderId)
+                    item.put("ids", JSONArray(purchase.products))
+                    item.put("transactionId", purchase.orderId)  // @deprecated - use id instead
                     item.put("transactionDate", purchase.purchaseTime)
                     item.put("transactionReceipt", purchase.originalJson)
                     item.put("purchaseToken", purchase.purchaseToken)  // Unified field
                     item.put("purchaseTokenAndroid", purchase.purchaseToken)  // Deprecated - use purchaseToken
+                    item.put("dataAndroid", purchase.originalJson)
                     item.put("signatureAndroid", purchase.signature)
                     item.put("purchaseStateAndroid", purchase.purchaseState)
+                    item.put("packageNameAndroid", purchase.packageName)
+                    item.put("developerPayloadAndroid", purchase.developerPayload)
+                    item.put("platform", "android")
                     if (type == BillingClient.ProductType.INAPP) {
                         item.put("isAcknowledgedAndroid", purchase.isAcknowledged)
                     } else if (type == BillingClient.ProductType.SUBS) {
                         item.put("autoRenewingAndroid", purchase.isAutoRenewing)
                     }
+                    val accountIdentifiers = purchase.accountIdentifiers
+                    if (accountIdentifiers != null) {
+                        item.put("obfuscatedAccountIdAndroid", accountIdentifiers.obfuscatedAccountId)
+                        item.put("obfuscatedProfileIdAndroid", accountIdentifiers.obfuscatedProfileId)
+                    }
                     items.put(item)
                 }
                 safeChannel.success(items.toString())
@@ -347,13 +358,25 @@ class AndroidInappPurchasePlugin internal constructor() : MethodCallHandler,
                     val item = JSONObject()
                     item.put("id", purchase.orderId)
                     item.put("productId", purchase.products[0])
-                    item.put("transactionId", purchase.orderId)
+                    item.put("ids", JSONArray(purchase.products))
+                    item.put("transactionId", purchase.orderId)  // @deprecated - use id instead
                     item.put("transactionDate", purchase.purchaseTime)
                     item.put("transactionReceipt", purchase.originalJson)
                     item.put("purchaseToken", purchase.purchaseToken)  // Unified field
                     item.put("purchaseTokenAndroid", purchase.purchaseToken)  // Deprecated - use purchaseToken
                     item.put("dataAndroid", purchase.originalJson)
                     item.put("signatureAndroid", purchase.signature)
+                    item.put("purchaseStateAndroid", purchase.purchaseState)
+                    item.put("autoRenewingAndroid", purchase.isAutoRenewing)
+                    item.put("isAcknowledgedAndroid", purchase.isAcknowledged)
+                    item.put("packageNameAndroid", purchase.packageName)
+                    item.put("developerPayloadAndroid", purchase.developerPayload)
+                    item.put("platform", "android")
+                    val accountIdentifiers = purchase.accountIdentifiers
+                    if (accountIdentifiers != null) {
+                        item.put("obfuscatedAccountIdAndroid", accountIdentifiers.obfuscatedAccountId)
+                        item.put("obfuscatedProfileIdAndroid", accountIdentifiers.obfuscatedProfileId)
+                    }
                     items.put(item)
                 }
                 safeChannel.success(items.toString())
@@ -397,10 +420,24 @@ class AndroidInappPurchasePlugin internal constructor() : MethodCallHandler,
 
                     // Create flutter objects
                     val item = JSONObject()
+                    item.put("id", productDetails.productId)
                     item.put("productId", productDetails.productId)
                     item.put("type", productDetails.productType)
                     item.put("title", productDetails.title)
+                    item.put("displayName", productDetails.name)
                     item.put("description", productDetails.description)
+                    item.put("platform", "android")
+                    
+                    // Set currency and displayPrice based on product type
+                    val currency = productDetails.oneTimePurchaseOfferDetails?.priceCurrencyCode
+                        ?: productDetails.subscriptionOfferDetails?.firstOrNull()?.pricingPhases?.pricingPhaseList?.firstOrNull()?.priceCurrencyCode
+                        ?: "Unknown"
+                    val displayPrice = productDetails.oneTimePurchaseOfferDetails?.formattedPrice
+                        ?: productDetails.subscriptionOfferDetails?.firstOrNull()?.pricingPhases?.pricingPhaseList?.firstOrNull()?.formattedPrice
+                        ?: "N/A"
+                    
+                    item.put("currency", currency)
+                    item.put("displayPrice", displayPrice)
 
                     // One-time offer details have changed in 5.0
                     if (productDetails.oneTimePurchaseOfferDetails != null) {
@@ -412,8 +449,14 @@ class AndroidInappPurchasePlugin internal constructor() : MethodCallHandler,
 
                         if (oneTimePurchaseOfferDetails != null) {
                             item.put("price", (oneTimePurchaseOfferDetails.priceAmountMicros / 1000000f).toString())
-                            item.put("currency", oneTimePurchaseOfferDetails.priceCurrencyCode)
                             item.put("localizedPrice", oneTimePurchaseOfferDetails.formattedPrice)
+                            
+                            // Add structured oneTimePurchaseOfferDetails
+                            val offerDetails = JSONObject()
+                            offerDetails.put("priceCurrencyCode", oneTimePurchaseOfferDetails.priceCurrencyCode)
+                            offerDetails.put("formattedPrice", oneTimePurchaseOfferDetails.formattedPrice)
+                            offerDetails.put("priceAmountMicros", oneTimePurchaseOfferDetails.priceAmountMicros.toString())
+                            item.put("oneTimePurchaseOfferDetails", offerDetails)
                         }
                     } else if (productDetails.productType == BillingClient.ProductType.SUBS) {
                         // These generalized values are derived from the first pricing object, mainly for backwards compatibility
@@ -424,11 +467,41 @@ class AndroidInappPurchasePlugin internal constructor() : MethodCallHandler,
                         if (firstOffer != null && firstOffer.pricingPhases.pricingPhaseList.isNotEmpty()) {
                             val defaultPricingPhase = firstOffer.pricingPhases.pricingPhaseList[0]
                             item.put("price", (defaultPricingPhase.priceAmountMicros / 1000000f).toString())
-                            item.put("currency", defaultPricingPhase.priceCurrencyCode)
                             item.put("localizedPrice", defaultPricingPhase.formattedPrice)
                             item.put("subscriptionPeriodAndroid", defaultPricingPhase.billingPeriod)
                         }
 
+                        // Add structured subscriptionOfferDetails
+                        val subsOffers = JSONArray()
+                        if (productDetails.subscriptionOfferDetails != null) {
+                            for (offer in productDetails.subscriptionOfferDetails!!) {
+                                val offerItem = JSONObject()
+                                offerItem.put("basePlanId", offer.basePlanId)
+                                offerItem.put("offerId", offer.offerId)
+                                offerItem.put("offerToken", offer.offerToken)
+                                offerItem.put("offerTags", JSONArray(offer.offerTags))
+                                
+                                // Add pricingPhases
+                                val pricingPhasesObj = JSONObject()
+                                val pricingPhasesList = JSONArray()
+                                for (pricing in offer.pricingPhases.pricingPhaseList) {
+                                    val pricingPhase = JSONObject()
+                                    pricingPhase.put("formattedPrice", pricing.formattedPrice)
+                                    pricingPhase.put("priceCurrencyCode", pricing.priceCurrencyCode)
+                                    pricingPhase.put("billingPeriod", pricing.billingPeriod)
+                                    pricingPhase.put("billingCycleCount", pricing.billingCycleCount)
+                                    pricingPhase.put("priceAmountMicros", pricing.priceAmountMicros.toString())
+                                    pricingPhase.put("recurrenceMode", pricing.recurrenceMode)
+                                    pricingPhasesList.put(pricingPhase)
+                                }
+                                pricingPhasesObj.put("pricingPhaseList", pricingPhasesList)
+                                offerItem.put("pricingPhases", pricingPhasesObj)
+                                subsOffers.put(offerItem)
+                            }
+                        }
+                        item.put("subscriptionOfferDetails", subsOffers)
+                        
+                        // Keep backward compatibility with subscriptionOffers
                         val subs = JSONArray()
                         if (productDetails.subscriptionOfferDetails != null ) {
                             for (offer in productDetails.subscriptionOfferDetails!!) {
@@ -651,8 +724,10 @@ class AndroidInappPurchasePlugin internal constructor() : MethodCallHandler,
                 for (purchase in purchases) {
                     Log.d(TAG, "Processing purchase: productId=${purchase.products[0]}, orderId=${purchase.orderId}")
                     val item = JSONObject()
+                    item.put("id", purchase.orderId)
                     item.put("productId", purchase.products[0])
-                    item.put("transactionId", purchase.orderId)
+                    item.put("ids", JSONArray(purchase.products))
+                    item.put("transactionId", purchase.orderId)  // @deprecated - use id instead
                     item.put("transactionDate", purchase.purchaseTime)
                     item.put("transactionReceipt", purchase.originalJson)
                     item.put("purchaseToken", purchase.purchaseToken)  // Unified field for iOS JWS and Android purchaseToken
@@ -664,6 +739,7 @@ class AndroidInappPurchasePlugin internal constructor() : MethodCallHandler,
                     item.put("isAcknowledgedAndroid", purchase.isAcknowledged)
                     item.put("packageNameAndroid", purchase.packageName)
                     item.put("developerPayloadAndroid", purchase.developerPayload)
+                    item.put("platform", "android")
                     val accountIdentifiers = purchase.accountIdentifiers
                     if (accountIdentifiers != null) {
                         item.put("obfuscatedAccountIdAndroid", accountIdentifiers.obfuscatedAccountId)