refactor: add platform-specific suffixes to native functions (#182)

## Summary
- Add IOS/Android suffixes to platform-specific functions for clarity
- Deprecate getPurchaseHistories and buyPromotedProductIOS
- Maintain common names for cross-platform functions (requestProducts,
requestPurchase)
- Compliant with [Open IAP
v1.0.1](https://www.openiap.dev/docs/versions#v1-0-1)

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

- New Features
- Added unified requestProducts/requestPurchase flows, iOS
promoted-product purchase API, initConnection and validateReceiptIOS,
new purchase/history helpers.

- Refactor
- Renamed many platform exports to IOS-suffixed variants and
Android-specific finalize actions; wrappers, hooks, and mocks updated to
match while preserving deprecated aliases.

- Documentation
- Added deprecation notices and migration guidance for renamed/legacy
methods.

- Tests
- Updated mocks and tests to reflect new API names and platform-specific
variants.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude <[email protected]>

Author: hyochan

CHANGELOG.md

@@ -1,5 +1,23 @@
 # CHANGELOG
 
+## [2.8.6] - TBD
+
+### Changed
+- **BREAKING NAMING CONVENTION**: Added platform-specific suffixes to native functions for clarity
+  - iOS functions now use `IOS` suffix (e.g., `getPromotedProductIOS`, `clearTransactionIOS`)
+  - Android functions now use `Android` suffix (e.g., `acknowledgePurchaseAndroid`, `consumeProductAndroid`)
+  - Common cross-platform functions remain without suffix (`requestProducts`, `requestPurchase`)
+- Renamed `buyPromotedProductIOS` to `requestPurchaseOnPromotedProductIOS` for consistency
+
+### Added
+- Added `getPendingTransactionsIOS` function for iOS
+- Added `clearTransactionIOS` function for iOS
+
+### Deprecated
+- `getPurchaseHistories` - Use `getAvailablePurchases` instead (will be removed in v2.9.0)
+- `buyPromotedProductIOS` - Use `requestPurchaseOnPromotedProductIOS` instead (will be removed in v2.9.0)
+- `disable` function - No longer needed, observer management is automatic (will be removed in v2.9.0)
+
 ## [2.8.5] - 2025-09-03
 
 ### Fixed

android/src/main/java/expo/modules/iap/ExpoIapModule.kt

@@ -154,7 +154,7 @@ class ExpoIapModule :
                 promise.resolve(true)
             }
 
-            AsyncFunction("getItemsByType") { type: String, skuArr: Array<String>, promise: Promise ->
+            AsyncFunction("requestProducts") { type: String, skuArr: Array<String>, promise: Promise ->
                 ensureConnection(promise) { billingClient ->
                     val skuList =
                         skuArr.map { sku ->
@@ -310,7 +310,7 @@ class ExpoIapModule :
             // getPurchaseHistoryByType removed in Google Play Billing Library v8
             // Use getAvailableItemsByType instead to get active purchases
 
-            AsyncFunction("buyItemByType") { params: Map<String, Any?>, promise: Promise ->
+            AsyncFunction("requestPurchase") { params: Map<String, Any?>, promise: Promise ->
                 val type = params["type"] as String
                 val skuArr =
                     (params["skuArr"] as? List<*>)?.filterIsInstance<String>()?.toTypedArray()
@@ -475,7 +475,7 @@ class ExpoIapModule :
                 }
             }
 
-            AsyncFunction("acknowledgePurchase") {
+            AsyncFunction("acknowledgePurchaseAndroid") {
                     token: String,
                     promise: Promise,
                 ->
@@ -507,7 +507,7 @@ class ExpoIapModule :
                 }
             }
 
-            AsyncFunction("consumeProduct") {
+            AsyncFunction("consumeProductAndroid") {
                     token: String,
                     promise: Promise,
                 ->

docs/docs/api/methods/core-methods.md

@@ -592,26 +592,30 @@ const restorePurchases = async () => {
 
 **Returns:** `Promise<Purchase[]>`
 
-## getPurchaseHistories()
+## ~~getPurchaseHistories()~~ (Deprecated)
+
+:::warning Deprecated
+`getPurchaseHistories` is deprecated and will be removed in v2.9.0. Use `getAvailablePurchases()` instead.
+
+This function internally just calls `getAvailablePurchases()` on iOS and returns an empty array on Android (Google Play Billing v8 removed purchase history API).
+:::
 
 Retrieves purchase history for the user.
 
 ```tsx
-import {getPurchaseHistories} from 'expo-iap';
+import {getAvailablePurchases} from 'expo-iap'; // Use this instead
 
 const fetchPurchaseHistory = async () => {
   try {
-    const histories = await getPurchaseHistories();
-    console.log('Purchase histories:', histories);
-    return histories;
+    const purchases = await getAvailablePurchases();
+    console.log('Available purchases:', purchases);
+    return purchases;
   } catch (error) {
-    console.error('Failed to fetch purchase histories:', error);
+    console.error('Failed to fetch purchases:', error);
   }
 };
 ```
 
-**Note:** The previous `getPurchaseHistory` (singular) function is deprecated and will be removed in version 3.0.0. Please use `getPurchaseHistories` (plural) instead.
-
 **Returns:** `Promise<Purchase[]>`
 
 ## deepLinkToSubscriptions()

docs/docs/api/use-iap.md

@@ -426,16 +426,17 @@ interface UseIAPOptions {
   };
   ```
 
-#### buyPromotedProductIOS
+#### requestPurchaseOnPromotedProductIOS
 
 - **Type**: `() => Promise<void>`
 - **Description**: Complete the purchase of a promoted product (iOS only)
+- **Note**: `buyPromotedProductIOS` is deprecated, use `requestPurchaseOnPromotedProductIOS` instead
 - **Example**:
 
   ```tsx
   const completePurchase = async () => {
     try {
-      await buyPromotedProductIOS();
+      await requestPurchaseOnPromotedProductIOS();
       console.log('Promoted product purchase completed');
     } catch (error) {
       console.error('Failed to purchase promoted product:', error);
@@ -600,7 +601,7 @@ Handle App Store promoted products when users tap on them in the App Store:
 
 ```tsx
 const PromotedProductExample = () => {
-  const {promotedProductIOS, buyPromotedProductIOS} = useIAP({
+  const {promotedProductIOS, requestPurchaseOnPromotedProductIOS} = useIAP({
     onPromotedProductIOS: (product) => {
       console.log('Promoted product detected:', product);
     },
@@ -619,7 +620,7 @@ const PromotedProductExample = () => {
 
       if (confirmed) {
         // Complete the promoted purchase
-        await buyPromotedProductIOS();
+        await requestPurchaseOnPromotedProductIOS();
       }
     } catch (error) {
       console.error('Error handling promoted product:', error);

docs/docs/guides/migration-2.8.6.md

@@ -0,0 +1,164 @@
+---
+title: Migration to v2.8.6
+sidebar_label: v2.8.6 Migration
+sidebar_position: 2
+---
+
+# Migration Guide for v2.8.6
+
+This version introduces a significant naming convention change for platform-specific functions to improve code clarity and maintainability.
+
+## Breaking Changes
+
+### Platform-Specific Function Naming
+
+All platform-specific functions now have consistent suffixes:
+
+- **iOS functions**: Use `IOS` suffix
+- **Android functions**: Use `Android` suffix
+- **Common functions**: No suffix
+
+### iOS Function Changes
+
+| Old Name | New Name |
+|----------|----------|
+| `buyPromotedProduct` | `requestPurchaseOnPromotedProductIOS` |
+| `sync` | `syncIOS` |
+| `isEligibleForIntroOffer` | `isEligibleForIntroOfferIOS` |
+| `subscriptionStatus` | `subscriptionStatusIOS` |
+| `currentEntitlement` | `currentEntitlementIOS` |
+| `latestTransaction` | `latestTransactionIOS` |
+| `showManageSubscriptions` | `showManageSubscriptionsIOS` |
+| `beginRefundRequest` | `beginRefundRequestIOS` |
+| `isTransactionVerified` | `isTransactionVerifiedIOS` |
+| `getTransactionJws` | `getTransactionJwsIOS` |
+| `getReceiptData` | `getReceiptIOS` |
+| `presentCodeRedemptionSheet` | `presentCodeRedemptionSheetIOS` |
+| `getAppTransaction` | `getAppTransactionIOS` |
+
+### Android Function Changes
+
+| Old Name | New Name |
+|----------|----------|
+| `acknowledgePurchase` | `acknowledgePurchaseAndroid` |
+| `consumeProduct` | `consumeProductAndroid` |
+
+### New Functions Added
+
+- `getPendingTransactionsIOS()` - Get pending transactions on iOS
+- `clearTransactionIOS()` - Clear a specific transaction on iOS
+
+## Deprecated Functions
+
+The following functions are deprecated and will be removed in v2.9.0:
+
+### `getPurchaseHistories()`
+- **Reason**: This function just calls `getAvailablePurchases()` internally
+- **Migration**: Use `getAvailablePurchases()` instead
+
+```tsx
+// Before
+const histories = await getPurchaseHistories();
+
+// After
+const purchases = await getAvailablePurchases();
+```
+
+### `buyPromotedProductIOS()`
+- **Reason**: Renamed for consistency
+- **Migration**: Use `requestPurchaseOnPromotedProductIOS()` instead
+
+```tsx
+// Before
+await buyPromotedProductIOS();
+
+// After
+await requestPurchaseOnPromotedProductIOS();
+```
+
+### `disable()`
+- **Reason**: Observer management is now automatic
+- **Migration**: Remove calls to this function - it's no longer needed
+
+## Migration Examples
+
+### Using the useIAP Hook
+
+```tsx
+// Before
+import { useIAP } from 'expo-iap';
+
+const MyComponent = () => {
+  const { 
+    buyPromotedProductIOS,
+    getPurchaseHistories 
+  } = useIAP();
+  
+  // ...
+};
+
+// After
+import { useIAP } from 'expo-iap';
+
+const MyComponent = () => {
+  const { 
+    requestPurchaseOnPromotedProductIOS,
+    getAvailablePurchases 
+  } = useIAP();
+  
+  // ...
+};
+```
+
+### Direct Function Imports
+
+```tsx
+// Before
+import { 
+  isEligibleForIntroOffer,
+  acknowledgePurchase,
+  getPurchaseHistories 
+} from 'expo-iap';
+
+// After
+import { 
+  isEligibleForIntroOfferIOS,
+  acknowledgePurchaseAndroid,
+  getAvailablePurchases 
+} from 'expo-iap';
+```
+
+### Platform-Specific Code
+
+```tsx
+import { Platform } from 'react-native';
+import { 
+  acknowledgePurchaseAndroid,
+  clearTransactionIOS 
+} from 'expo-iap';
+
+const finishPurchase = async (purchase: Purchase) => {
+  if (Platform.OS === 'ios') {
+    // iOS-specific function with IOS suffix
+    await clearTransactionIOS();
+  } else if (Platform.OS === 'android') {
+    // Android-specific function with Android suffix
+    await acknowledgePurchaseAndroid({ token: purchase.purchaseToken });
+  }
+};
+```
+
+## Benefits of the New Naming Convention
+
+1. **Clarity**: Function names immediately indicate platform compatibility
+2. **Type Safety**: Better TypeScript support with platform-specific types
+3. **Maintainability**: Easier to identify and manage platform-specific code
+4. **Consistency**: All platform-specific functions follow the same pattern
+
+## Need Help?
+
+If you encounter any issues during migration:
+
+1. Check the [API documentation](/docs/api) for updated function signatures
+2. Review the [example app](https://github.com/hyochan/expo-iap/tree/main/example) for usage patterns
+3. Open an issue on [GitHub](https://github.com/hyochan/expo-iap/issues) if you need assistance

example/__tests__/core-functions.test.tsx

@@ -37,7 +37,7 @@ describe('Core Functions Tests', () => {
       expect(typeof ExpoIap.finishTransaction).toBe('function');
     });
 
-    it('should export getPurchaseHistories function', () => {
+    it('should export deprecated getPurchaseHistories function', () => {
       expect(ExpoIap.getPurchaseHistories).toBeDefined();
       expect(typeof ExpoIap.getPurchaseHistories).toBe('function');
     });