feat: update to OpenIAP v1.3.11 (#298)

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

* **Breaking Changes**
* PurchaseState simplified: removed 'failed', 'restored', and 'deferred'
in v3.4.0.
* Old alternative-billing APIs deprecated; migrate to Billing Programs.

* **New Features**
* Android Billing Programs expanded (including user-choice-billing and
external-payments) and new enableBillingProgramAndroid option; updated
Android flows and UI examples.

* **Documentation**
* Large docs update: migration guide, API reference, guides, examples,
blog release notes, and versioning.

* **Chores**
  * Pre-commit adjusted to stop auto-re-adding files after linting.

<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

.husky/pre-commit

@@ -10,9 +10,6 @@ else
   npm run lint:ci || { echo "Lint failed. Aborting commit." >&2; exit 1; }
 fi
 
-# Re-add files that were modified by linting
-git add -u
-
 # Run tests with coverage before committing to reduce CI failures
 echo "Running test coverage (pre-commit)…"
 if command -v bun >/dev/null 2>&1; then

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

@@ -58,7 +58,9 @@ class ExpoIapModule : Module() {
         get() = appContext.activityProvider?.currentActivity ?: throw Exceptions.MissingActivity()
 
     private val openIap: OpenIapModule by lazy { OpenIapModule(context) }
-    private val openIapStore: OpenIapStore by lazy { OpenIapStore(context) }
+
+    // Pass openIap directly to OpenIapStore to avoid reflection-based module loading
+    private val openIapStore: OpenIapStore by lazy { OpenIapStore(openIap) }
     private var listenersAttached = false
     private val pendingEvents = ConcurrentLinkedQueue<Pair<String, Map<String, Any?>>>()
     private val connectionReady = AtomicBoolean(false)
@@ -388,6 +390,7 @@ class ExpoIapModule : Module() {
                 }
             }
 
+            @Suppress("DEPRECATION")
             AsyncFunction("checkAlternativeBillingAvailabilityAndroid") { promise: Promise ->
                 ExpoIapLog.payload("checkAlternativeBillingAvailabilityAndroid", null)
                 scope.launch {
@@ -402,6 +405,7 @@ class ExpoIapModule : Module() {
                 }
             }
 
+            @Suppress("DEPRECATION")
             AsyncFunction("showAlternativeBillingDialogAndroid") { promise: Promise ->
                 ExpoIapLog.payload("showAlternativeBillingDialogAndroid", null)
                 scope.launch {
@@ -425,6 +429,7 @@ class ExpoIapModule : Module() {
                 }
             }
 
+            @Suppress("DEPRECATION")
             AsyncFunction("createAlternativeBillingTokenAndroid") { sku: String?, promise: Promise ->
                 ExpoIapLog.payload("createAlternativeBillingTokenAndroid", mapOf("sku" to sku))
                 scope.launch {
@@ -441,6 +446,7 @@ class ExpoIapModule : Module() {
                 }
             }
 
+            @Suppress("UNCHECKED_CAST")
             AsyncFunction("verifyPurchase") { params: Map<String, Any?>, promise: Promise ->
                 ExpoIapLog.payload("verifyPurchase", params)
                 scope.launch {
@@ -639,6 +645,7 @@ class ExpoIapModule : Module() {
             "external-offer" -> OpenIapBillingProgram.ExternalOffer
             "external-content-link" -> OpenIapBillingProgram.ExternalContentLink
             "external-payments" -> OpenIapBillingProgram.ExternalPayments
+            "user-choice-billing" -> OpenIapBillingProgram.UserChoiceBilling
             else -> OpenIapBillingProgram.Unspecified
         }
 

docs/blog/2025-12-29-3.4.0-purchasestate-cleanup.md

@@ -0,0 +1,45 @@
+---
+slug: v3.4.0-purchasestate-cleanup
+title: v3.4.0 - PurchaseState Cleanup & API Consolidation
+authors: [hyochan]
+tags: [release, openiap, android, billing, breaking-change]
+---
+
+## v3.4.0 Release Notes
+
+This release reflects [OpenIAP v1.3.11 updates](https://www.openiap.dev/docs/updates/notes#gql-1-3-11-google-1-3-21-apple-1-3-9), simplifying the `PurchaseState` enum and consolidating the Android billing API.
+
+### Breaking Changes
+
+- **PurchaseState**: Removed `failed`, `restored`, `deferred` (now only `pending`, `purchased`, `unknown`)
+- **AlternativeBillingModeAndroid**: Deprecated in favor of `BillingProgramAndroid`
+- **useAlternativeBilling**: Deprecated (only logged debug info, had no effect on purchase flow)
+
+### Migration Guide
+
+| Before (Deprecated) | After (Recommended) |
+|---------------------|---------------------|
+| `alternativeBillingModeAndroid: 'user-choice'` | `enableBillingProgramAndroid: 'user-choice-billing'` |
+| `alternativeBillingModeAndroid: 'alternative-only'` | `enableBillingProgramAndroid: 'external-offer'` |
+
+```typescript
+// Before
+const {connected} = useIAP({
+  alternativeBillingModeAndroid: 'user-choice',
+});
+
+// After
+const {connected} = useIAP({
+  enableBillingProgramAndroid: 'user-choice-billing',
+});
+```
+
+### OpenIAP Versions
+
+| Package | Version |
+|---------|---------|
+| openiap-gql | 1.3.11 |
+| openiap-google | 1.3.21 |
+| openiap-apple | 1.3.9 |
+
+For detailed changes, see the [OpenIAP Release Notes](https://www.openiap.dev/docs/updates/notes#gql-1-3-11-google-1-3-21-apple-1-3-9).

docs/docs/api/error-codes.md

@@ -17,7 +17,7 @@ React Native IAP provides a centralized error handling system with platform-spec
 The `ErrorCode` enum provides standardized error codes that map to platform-specific errors:
 
 ```tsx
-import {ErrorCode} from 'react-native-iap';
+import {ErrorCode} from 'expo-iap';
 
 export enum ErrorCode {
   Unknown = 'unknown',

docs/docs/api/error-handling.md

@@ -19,10 +19,15 @@ import {
   isNetworkError,
   getUserFriendlyErrorMessage,
   ErrorCode,
-} from 'react-native-iap';
+} from 'expo-iap';
 
 try {
-  await requestPurchase({request: {sku: 'product_id'}});
+  await requestPurchase({
+    request: {
+      apple: {sku: 'product_id'},
+      google: {skus: ['product_id']},
+    },
+  });
 } catch (error) {
   // Check for user cancellation
   if (isUserCancelledError(error)) {
@@ -68,7 +73,7 @@ interface PurchaseError extends Error {
 Use the `ErrorCode` enum for type-safe error code comparisons:
 
 ```ts
-import {ErrorCode} from 'react-native-iap';
+import {ErrorCode} from 'expo-iap';
 
 if (error instanceof PurchaseError && error.code === ErrorCode.UserCancelled) {
   // Handle user cancellation

docs/docs/api/methods/unified-apis.md

@@ -154,7 +154,7 @@ const buySubscription = (subscriptionId: string, subscription?: any) => {
       google: {
         skus: [subscriptionId],
         subscriptionOffers:
-          subscription?.subscriptionOfferDetails?.map((offer) => ({
+          subscription?.subscriptionOfferDetailsAndroid?.map((offer) => ({
             sku: subscriptionId,
             offerToken: offer.offerToken,
           })) || [],
@@ -175,9 +175,11 @@ const buySubscription = (subscriptionId: string, subscription?: any) => {
 ```tsx
 await requestPurchase({
   request: {
-    sku: productId,
-    quantity: 1,
-    appAccountToken: 'user-account-token',
+    apple: {
+      sku: productId,
+      quantity: 1,
+      appAccountToken: 'user-account-token',
+    },
   },
   type: 'in-app',
 });
@@ -693,7 +695,7 @@ interface Purchase {
   // Android-specific properties
   dataAndroid?: string;
   signatureAndroid?: string;
-  purchaseStateAndroid?: number;
+  purchaseState?: 'pending' | 'purchased' | 'unknown';
   isAcknowledgedAndroid?: boolean;
   packageNameAndroid?: string;
   developerPayloadAndroid?: string;

docs/docs/api/types.md

@@ -24,12 +24,14 @@ export type IapStore = 'unknown' | 'apple' | 'google' | 'horizon';
 export type ProductType = 'in-app' | 'subs';
 
 export type PurchaseState =
-  | 'deferred'
-  | 'failed'
   | 'pending'
   | 'purchased'
-  | 'restored'
   | 'unknown';
+
+// Note: 'failed', 'restored', and 'deferred' were removed in v3.4.0
+// - Failed: Both platforms return errors instead of Purchase objects on failure
+// - Restored: Restored purchases return as 'purchased' state
+// - Deferred: iOS StoreKit 2 has no transaction state; Android uses 'pending'
 ```
 
 The `ErrorCode` enum now mirrors the OpenIAP schema without the legacy `E_` prefix:
@@ -214,7 +216,13 @@ New types for the Google Play Billing Programs API:
 
 ```ts
 // Billing program types
-type BillingProgramAndroid = 'unspecified' | 'external-content-link' | 'external-offer';
+// USER_CHOICE_BILLING added in v3.4.0 (available in Google Play Billing 7.0+)
+type BillingProgramAndroid =
+  | 'unspecified'
+  | 'external-content-link'
+  | 'external-offer'
+  | 'external-payments'
+  | 'user-choice-billing';
 
 // Launch mode for external links
 type ExternalLinkLaunchModeAndroid =

docs/docs/api/use-iap.md

@@ -371,7 +371,7 @@ const buySubscriptionWithOffer = async (
     try {
       // Updates `availablePurchases` state; do not expect a return value
       await getAvailablePurchases();
-      // Read from state afterwards
+      // Read from state afterward
       console.log('Available purchases count:', availablePurchases.length);
     } catch (error) {
       console.error('Failed to fetch available purchases:', error);

docs/docs/examples/subscription-flow.md

@@ -200,12 +200,12 @@ function useSubscriptionStatus() {
 
         // Platform-specific status checks
         if (Platform.OS === 'ios') {
-          // iOS provides expirationDateIos
-          const isExpired = subscription.expirationDateIos < Date.now();
+          // iOS provides expirationDateIOS
+          const isExpired = subscription.expirationDateIOS < Date.now();
           setSubscriptionDetails({
             productId: subscription.productId,
             isActive: !isExpired,
-            expiresAt: new Date(subscription.expirationDateIos),
+            expiresAt: new Date(subscription.expirationDateIOS),
             environment: subscription.environmentIOS, // 'Production' or 'Sandbox'
           });
         } else {
@@ -214,7 +214,7 @@ function useSubscriptionStatus() {
             productId: subscription.productId,
             isActive: subscription.autoRenewingAndroid,
             willAutoRenew: subscription.autoRenewingAndroid,
-            purchaseState: subscription.purchaseStateAndroid, // 0 = purchased, 1 = canceled
+            purchaseState: subscription.purchaseState, // 'pending' | 'purchased' | 'unknown'
           });
         }
       } else {
@@ -281,7 +281,7 @@ async function getUserSubscriptionTier() {
 **Android:**
 
 - `autoRenewingAndroid`: Boolean for auto-renewal status
-- `purchaseStateAndroid`: Purchase state (0 = purchased, 1 = canceled)
+- `purchaseState`: Purchase state ('pending' | 'purchased' | 'unknown')
 
 ⚠️ **Always validate on your server.** Client-side checks are for UI only.
 
@@ -656,7 +656,7 @@ function SubscriptionPlanManager() {
 | **Parameters** | Just new `sku` | `purchaseTokenAndroid` + `replacementModeAndroid` |
 | **Timing** | OS-determined | Specified via `replacementModeAndroid` |
 | **Plan Changes** | Use subscription groups with ranks | Use base plans and offers |
-| **Status Check** | Check `expirationDateIos` | Check `autoRenewingAndroid` |
+| **Status Check** | Check `expirationDateIOS` | Check `autoRenewingAndroid` |
 | **Cancellation Detection** | User manages in Settings | Check `autoRenewingAndroid === false` |
 | **Proration** | Handled by App Store | Configurable via `replacementModeAndroid` |
 

docs/docs/getting-started/setup-android.md

@@ -91,7 +91,9 @@ const AndroidProductItem = ({product}: {product: Product}) => {
   const handlePurchase = () => {
     if (product.platform === 'android') {
       requestPurchase({
-        request: {skus: [product.id]},
+        request: {
+          google: {skus: [product.id]},
+        },
         type: 'in-app',
       });
     }
@@ -142,7 +144,7 @@ const AndroidSubscriptionItem = ({
   return (
     <View>
       <Text>{subscription.title}</Text>
-      {subscription.subscriptionOfferDetails?.map((offer) => (
+      {subscription.subscriptionOfferDetailsAndroid?.map((offer) => (
         <TouchableOpacity
           key={offer.offerId}
           onPress={() => handleSubscribe(offer)}