expo-iap 2.4.3 → 2.4.5-rc.1

package/{iap.md → docs/IAP.md}

@@ -4,11 +4,11 @@
 
 ## Overview
 
-`expo-iap` is an Expo module for handling in-app purchases (IAP) on iOS (StoreKit 2) and Android (Google Play Billing). It supports consumables, non-consumables, and subscriptions. Unlike [`react-native-iap`](https://github.com/hyochan/react-native-iap), which requires native setup, `expo-iap` integrates seamlessly into Expo's [managed workflow](https://docs.expo.dev/archive/managed-vs-bare)—no ejecting needed! However, you’ll need a [development client](https://docs.expo.dev/development/introduction/) instead of Expo Go for full functionality. Starting from version 2.2.8, most features of `react-native-iap` have been ported.
+`expo-iap` is an Expo module for handling in-app purchases (IAP) on iOS (StoreKit 2) and Android (Google Play Billing). It supports consumables, non-consumables, and subscriptions. Unlike [`react-native-iap`](https://github.com/hyochan/react-native-iap), which requires native setup, `expo-iap` integrates seamlessly into Expo's managed workflow! However, you’ll need a [development client](https://docs.expo.dev/development/introduction/) instead of Expo Go for full functionality. Starting from version 2.2.8, most features of `react-native-iap` have been ported.
 
 ## Installation
 
-`expo-iap` is compatible with [Expo SDK](https://expo.dev) 51+ and supports both managed workflows and React Native CLI projects. Official documentation is in progress for SDK inclusion (see [Expo IAP Documentation](link-to-docs)).
+`expo-iap` is compatible with [Expo SDK](https://expo.dev) 51+ and supports both managed workflows and React Native CLI projects. Official documentation is in progress for SDK inclusion (see [Expo IAP Documentation](https://github.com/hyochan/expo-iap/blob/main/docs/IAP.md#expo-iap-documentation)).
 
 ### Add the Package
 
@@ -91,16 +91,6 @@ Manually apply the following changes:
 
    If there’s no `ext` block, append it at the end.
 
-2. **Update `android/app/src/main/AndroidManifest.xml`**  
-   Add the BILLING permission:
-
-   ```xml
-   <manifest ...>
-       <uses-permission android:name="com.android.vending.BILLING" />
-       <!-- Other manifest content... -->
-   </manifest>
-   ```
-
 ## Current State & Feedback
 
 Updates are in progress to improve reliability and address remaining edge cases. For production apps, test thoroughly. Contributions (docs, code, or bug reports) are welcome—especially detailed error logs or use cases!
@@ -272,43 +262,49 @@ export default function SimpleIAP() {
 }
 ```
 
-## Using useIAP Hook
+## Using `useIAP` Hook
+
+The `useIAP` hook from `expo-iap` lets you manage in-app purchases in functional React components. This example reflects a **real-world production use case** with:
+
+- Consumable & subscription support
+- Purchase lifecycle management
+- Platform-specific `requestPurchase` formats
+- UX alerts and loading states
+- Optional receipt validation before finishing the transaction
+
+### 🧭 Flow Overview
 
-The `useIAP` hook simplifies managing in-app purchases. Below is an example updated to use the new `requestPurchase` signature:
+| Step | Description |
+| --- | --- |
+| 1️⃣ | Wait for `connected === true` before fetching products and subscriptions |
+| 2️⃣ | Render UI with products/subscriptions dynamically from store |
+| 3️⃣ | Trigger purchases via `requestPurchase()` (with Android/iOS handling) |
+| 4️⃣ | When `currentPurchase` updates, validate & finish the transaction |
+| 5️⃣ | Handle `currentPurchaseError` for graceful UX |
+
+### ✅ Realistic Example with `useIAP`
 
 ```tsx
-import {useEffect, useState} from 'react';
+import {useEffect, useState, useCallback} from 'react';
 import {
-  SafeAreaView,
-  ScrollView,
-  StyleSheet,
-  Text,
   View,
-  Pressable,
+  Text,
+  ScrollView,
   Button,
-  InteractionManager,
   Alert,
+  Platform,
+  InteractionManager,
 } from 'react-native';
 import {useIAP} from 'expo-iap';
-import type {ProductPurchase, SubscriptionProduct} from 'expo-iap';
-
-// Define SKUs
-const productSkus = [
-  'cpk.points.1000',
-  'cpk.points.5000',
-  'cpk.points.10000',
-  'cpk.points.30000',
-];
-const subscriptionSkus = [
-  'cpk.membership.monthly.bronze',
-  'cpk.membership.monthly.silver',
-];
-
-// Define operations
-const operations = ['getProducts', 'getSubscriptions'] as const;
-type Operation = (typeof operations)[number];
-
-export default function IAPWithHook() {
+import type {
+  ProductAndroid,
+  ProductPurchaseAndroid,
+} from 'expo-iap/build/types/ExpoIapAndroid.types';
+
+const productSkus = ['dev.hyo.luent.10bulbs', 'dev.hyo.luent.30bulbs'];
+const subscriptionSkus = ['dev.hyo.luent.premium'];
+
+export default function PurchaseScreen() {
   const {
     connected,
     products,
@@ -317,195 +313,188 @@ export default function IAPWithHook() {
     currentPurchaseError,
     getProducts,
     getSubscriptions,
-    finishTransaction,
     requestPurchase,
+    finishTransaction,
+    validateReceipt,
   } = useIAP();
 
   const [isReady, setIsReady] = useState(false);
+  const [isLoading, setIsLoading] = useState(false);
 
-  // Fetch products and subscriptions only when connected
+  // 1️⃣ Initialize products & subscriptions
   useEffect(() => {
     if (!connected) return;
 
-    const initializeIAP = async () => {
+    const loadStoreItems = async () => {
       try {
-        await Promise.all([
-          getProducts(productSkus),
-          getSubscriptions(subscriptionSkus),
-        ]);
+        await getProducts(productSkus);
+        await getSubscriptions(subscriptionSkus);
         setIsReady(true);
-      } catch (error) {
-        console.error('Error initializing IAP:', error);
+      } catch (e) {
+        console.error('IAP init error:', e);
       }
     };
-    initializeIAP();
-  }, [connected, getProducts, getSubscriptions]);
 
-  // Handle purchase updates and errors
+    loadStoreItems();
+  }, [connected]);
+
+  // 2️⃣ Purchase handler when currentPurchase updates
   useEffect(() => {
-    if (currentPurchase) {
-      InteractionManager.runAfterInteractions(async () => {
-        try {
-          await finishTransaction({
-            purchase: currentPurchase,
-            isConsumable: currentPurchase.productType === 'inapp',
+    if (!currentPurchase) return;
+
+    const handlePurchase = async () => {
+      try {
+        setIsLoading(true);
+
+        const productId = currentPurchase.id;
+        const isConsumable = productSkus.includes(productId);
+
+        // ✅ Optionally validate receipt before finishing
+        let isValid = true;
+        if (Platform.OS === 'ios') {
+          const result = await validateReceipt(productId);
+          isValid = result?.isValid ?? true;
+        } else if (Platform.OS === 'android') {
+          const token = (currentPurchase as ProductPurchaseAndroid)
+            .purchaseTokenAndroid;
+          const packageName = 'your.android.package.name';
+
+          const result = await validateReceipt(productId, {
+            productToken: token,
+            packageName,
+            isSub: subscriptionSkus.includes(productId),
           });
-          Alert.alert('Purchase Successful', JSON.stringify(currentPurchase));
-        } catch (error) {
-          console.error('Error finishing transaction:', error);
-          Alert.alert('Transaction Error', String(error));
+          isValid = result?.isValid ?? true;
         }
-      });
-    }
 
+        if (!isValid) {
+          Alert.alert('Invalid purchase', 'Receipt validation failed');
+          return;
+        }
+
+        // 🧾 Finish transaction (important!)
+        await finishTransaction({
+          purchase: currentPurchase,
+          isConsumable,
+        });
+
+        // ✅ Grant item or unlock feature
+        Alert.alert(
+          'Thank you!',
+          isConsumable
+            ? 'Bulbs added to your account!'
+            : 'Premium subscription activated.',
+        );
+      } catch (err) {
+        console.error('Finish transaction error:', err);
+      } finally {
+        setIsLoading(false);
+      }
+    };
+
+    handlePurchase();
+  }, [currentPurchase]);
+
+  // 3️⃣ Error handling
+  useEffect(() => {
     if (currentPurchaseError) {
       InteractionManager.runAfterInteractions(() => {
-        Alert.alert('Purchase Error', JSON.stringify(currentPurchaseError));
+        Alert.alert('Purchase error', currentPurchaseError.message);
       });
+      setIsLoading(false);
     }
-  }, [currentPurchase, currentPurchaseError, finishTransaction]);
+  }, [currentPurchaseError]);
 
-  // Handle operation buttons
-  const handleOperation = async (operation: Operation) => {
-    if (!connected) {
-      Alert.alert('Not Connected', 'Please wait for IAP to connect.');
-      return;
-    }
+  // 4️⃣ Purchase trigger
+  const handleBuy = useCallback(
+    async (productId: string, type?: 'subs') => {
+      try {
+        setIsLoading(true);
 
-    try {
-      switch (operation) {
-        case 'getProducts':
-          await getProducts(productSkus);
-          break;
-        case 'getSubscriptions':
-          await getSubscriptions(subscriptionSkus);
-          break;
+        if (Platform.OS === 'ios') {
+          await requestPurchase({
+            request: {sku: productId},
+            type,
+          });
+        } else {
+          const request: any = {skus: [productId]};
+
+          if (type === 'subs') {
+            const sub = subscriptions.find(
+              (s) => s.id === productId,
+            ) as ProductAndroid;
+            const offers =
+              sub?.subscriptionOfferDetails?.map((offer) => ({
+                sku: productId,
+                offerToken: offer.offerToken,
+              })) || [];
+
+            request.subscriptionOffers = offers;
+          }
+
+          await requestPurchase({request, type});
+        }
+      } catch (err) {
+        console.error('Purchase request failed:', err);
+        Alert.alert(
+          'Error',
+          err instanceof Error ? err.message : 'Purchase failed',
+        );
+        setIsLoading(false);
       }
-    } catch (error) {
-      console.error(`Error in ${operation}:`, error);
-    }
-  };
+    },
+    [subscriptions],
+  );
 
-  if (!connected) {
-    return (
-      <SafeAreaView style={styles.container}>
-        <Text style={styles.title}>Connecting to IAP...</Text>
-      </SafeAreaView>
-    );
-  }
+  if (!connected) return <Text>Connecting to store...</Text>;
+  if (!isReady) return <Text>Loading products...</Text>;
 
   return (
-    <SafeAreaView style={styles.container}>
-      <Text style={styles.title}>Expo IAP with useIAP Hook</Text>
-      <View style={styles.buttons}>
-        <ScrollView contentContainerStyle={styles.buttonsWrapper} horizontal>
-          {operations.map((operation) => (
-            <Pressable
-              key={operation}
-              onPress={() => handleOperation(operation)}
-            >
-              <View style={styles.buttonView}>
-                <Text>{operation}</Text>
-              </View>
-            </Pressable>
-          ))}
-        </ScrollView>
-      </View>
-      <View style={styles.content}>
-        {!isReady ? (
-          <Text>Loading...</Text>
-        ) : (
-          <View style={{gap: 12}}>
-            <Text style={{fontSize: 20}}>Products</Text>
-            {products.map((item) => (
-              <View key={item.id} style={{gap: 12}}>
-                <Text>
-                  {item.title} -{' '}
-                  {item.platform === 'android'
-                    ? item.oneTimePurchaseOfferDetails?.formattedPrice
-                    : item.displayPrice}
-                </Text>
-                <Button
-                  title="Buy"
-                  onPress={() =>
-                    requestPurchase({
-                      request:
-                        item.platform === 'android'
-                          ? {skus: [item.id]}
-                          : {sku: item.id},
-                    })
-                  }
-                />
-              </View>
-            ))}
-
-            <Text style={{fontSize: 20}}>Subscriptions</Text>
-            {subscriptions.map((item) => (
-              <View key={item.id} style={{gap: 12}}>
-                <Text>
-                  {item.title || item.displayName} -{' '}
-                  {item.platform === 'android' && item.subscriptionOfferDetails
-                    ? item.subscriptionOfferDetails[0]?.pricingPhases
-                        .pricingPhaseList[0].formattedPrice
-                    : item.displayPrice}
-                </Text>
-                <Button
-                  title="Subscribe"
-                  onPress={() =>
-                    requestPurchase({
-                      request:
-                        item.platform === 'android'
-                          ? {
-                              skus: [item.id],
-                              subscriptionOffers:
-                                item.subscriptionOfferDetails?.map((offer) => ({
-                                  sku: item.id,
-                                  offerToken: offer.offerToken,
-                                })) || [],
-                            }
-                          : {sku: item.id},
-                      type: 'subs',
-                    })
-                  }
-                />
-              </View>
-            ))}
-          </View>
-        )}
-      </View>
-    </SafeAreaView>
+    <ScrollView contentContainerStyle={{padding: 20}}>
+      <Text style={{fontSize: 18, fontWeight: 'bold'}}>💡 Bulb Packs</Text>
+      {products.map((p) => (
+        <View key={p.id} style={{marginVertical: 10}}>
+          <Text>
+            {p.title} - {p.displayPrice}
+          </Text>
+          <Button
+            title={isLoading ? 'Processing...' : 'Buy'}
+            onPress={() => handleBuy(p.id)}
+            disabled={isLoading}
+          />
+        </View>
+      ))}
+
+      <Text style={{fontSize: 18, fontWeight: 'bold', marginTop: 30}}>
+        ⭐ Subscription
+      </Text>
+      {subscriptions.map((s) => (
+        <View key={s.id} style={{marginVertical: 10}}>
+          <Text>
+            {s.title} - {s.displayPrice}
+          </Text>
+          <Button
+            title={isLoading ? 'Processing...' : 'Subscribe'}
+            onPress={() => handleBuy(s.id, 'subs')}
+            disabled={isLoading}
+          />
+        </View>
+      ))}
+    </ScrollView>
   );
 }
-
-const styles = StyleSheet.create({
-  container: {
-    flex: 1,
-    backgroundColor: '#fff',
-    alignItems: 'center',
-  },
-  title: {
-    marginTop: 24,
-    fontSize: 20,
-    fontWeight: 'bold',
-  },
-  buttons: {
-    height: 90,
-  },
-  buttonsWrapper: {
-    padding: 24,
-    gap: 8,
-  },
-  buttonView: {
-    borderRadius: 8,
-    borderWidth: 1,
-    borderColor: '#000',
-    padding: 8,
-  },
-  content: {
-    flex: 1,
-    alignSelf: 'stretch',
-    padding: 24,
-    gap: 12,
-  },
-});
 ```
+
+---
+
+물론입니다. 아래는 보다 자연스럽고 요약된 느낌으로 다듬은 영어 버전입니다:
+
+---
+
+### 🔎 Key Benefits of This Approach
+
+- ✅ Supports **both Android and iOS**, with platform-aware purchase handling
+- ✅ Covers **both consumable items and subscriptions**
+- ✅ Includes a **receipt validation flow** using `validateReceipt` (server-ready)
+- ✅ Handles iOS cases where **auto-finishing transactions is disabled**
+- ✅ Provides **user-friendly error and loading state management**

package/docs/README.md

@@ -0,0 +1,30 @@
+# Documentation
+
+This directory contains detailed documentation for expo-iap.
+
+## Available Documents
+
+- **[API Documentation](./IAP.md)** - Complete API reference and usage examples
+- **[Error Code Management](./ERROR_CODES.md)** - Centralized error handling system documentation
+
+## Quick Links
+
+- [Main README](../README.md) - Project overview and quick start
+- [Example App](../example/) - Sample implementation
+- [GitHub Issues](https://github.com/hyochan/expo-iap/issues) - Bug reports and feature requests
+
+## Contributing
+
+If you find any documentation errors or have suggestions for improvements, please:
+
+1. Check existing [issues](https://github.com/hyochan/expo-iap/issues)
+2. Create a new issue with the `documentation` label
+3. Submit a pull request with your improvements
+
+## Support
+
+For questions and support:
+
+- 📚 Read the documentation in this folder
+- 🐛 Report bugs via [GitHub Issues](https://github.com/hyochan/expo-iap/issues)
+- 💬 Join discussions in [GitHub Discussions](https://github.com/hyochan/expo-iap/discussions)