docs: clarify useIAP hook state-driven design pattern in llms.txt

- Add Design Pattern section explaining void-returning methods
- Clearly separate STATE VARIABLES from METHODS
- Add Usage Pattern examples showing correct vs incorrect usage
- Note difference between hook getAvailablePurchases (void) and root API (Purchase[])
- Mark exceptions that return values (hasActiveSubscriptions, verifyPurchase, etc.)

Author: hyochan

docs/static/llms-full.txt

@@ -91,22 +91,29 @@ interface UseIAPOptions {
 
 ```tsx
 interface UseIAPReturn {
-  // State
+  // ═══════════════════════════════════════════════════════════════
+  // STATE VARIABLES (read data from these)
+  // ═══════════════════════════════════════════════════════════════
   connected: boolean;
   products: Product[];
   subscriptions: ProductSubscription[];
   availablePurchases: Purchase[];
   activeSubscriptions: ActiveSubscription[];
   promotedProductIOS?: Product;
 
-  // Methods (return void, update state)
+  // ═══════════════════════════════════════════════════════════════
+  // METHODS (return Promise<void>, update state above)
+  // ═══════════════════════════════════════════════════════════════
   fetchProducts: (params: {skus: string[]; type: 'in-app' | 'subs'}) => Promise<void>;
   requestPurchase: (props: RequestPurchaseProps) => Promise<void>;
   finishTransaction: (params: {purchase: Purchase; isConsumable?: boolean}) => Promise<void>;
   getAvailablePurchases: () => Promise<void>;
+  getActiveSubscriptions: (ids?: string[]) => Promise<void>;
+  restorePurchases: () => Promise<void>;
 
-  // Methods (return values)
-  getActiveSubscriptions: (ids?: string[]) => Promise<ActiveSubscription[]>;
+  // ═══════════════════════════════════════════════════════════════
+  // METHODS THAT RETURN VALUES (exceptions to the pattern)
+  // ═══════════════════════════════════════════════════════════════
   hasActiveSubscriptions: (ids?: string[]) => Promise<boolean>;
   verifyPurchase: (props: VerifyPurchaseProps) => Promise<VerifyPurchaseResult>;
   verifyPurchaseWithProvider: (props: VerifyPurchaseWithProviderProps) => Promise<VerifyPurchaseWithProviderResult>;
@@ -117,10 +124,29 @@ interface UseIAPReturn {
 }
 ```
 
+### Design Pattern
+
+**The hook follows React's state-driven pattern:**
+- Methods return `Promise<void>` and update internal state
+- You must read data from state variables, not from method return values
+
+```tsx
+// ✅ CORRECT: Call method, then read from state
+await fetchProducts({skus: ['product1'], type: 'in-app'});
+console.log(products); // Read from state variable
+
+await getAvailablePurchases();
+console.log(availablePurchases); // Read from state variable
+
+// ❌ WRONG: Don't expect return values from methods
+const result = await fetchProducts({...}); // result is void!
+const purchases = await getAvailablePurchases(); // purchases is void!
+```
+
 ### Important Behavior
 
 - **Auto-connects**: Calls `initConnection()` on mount, `endConnection()` on unmount
-- **Void-returning methods**: `fetchProducts`, `requestPurchase`, `getAvailablePurchases` return `Promise<void>` and update internal state
+- **Void-returning methods**: `fetchProducts`, `requestPurchase`, `getAvailablePurchases`, `getActiveSubscriptions` return `Promise<void>` and update internal state
 - **Use callbacks**: Always handle purchases via `onPurchaseSuccess` and `onPurchaseError`
 
 ### Basic Example

docs/static/llms.txt

@@ -57,31 +57,59 @@ function Store() {
 
 The main interface for in-app purchases. Auto-manages connection lifecycle.
 
+**Design Pattern:** The hook follows React's state-driven pattern. Methods return `Promise<void>` and update internal state. You must read data from the returned state variables, not from method return values.
+
 ```tsx
 const {
+  // ═══════════════════════════════════════════════════════════════
+  // STATE VARIABLES (read data from these)
+  // ═══════════════════════════════════════════════════════════════
   connected,           // boolean - IAP service ready
-  products,            // Product[] - fetched products
-  subscriptions,       // ProductSubscription[] - fetched subscriptions
-  availablePurchases,  // Purchase[] - restorable purchases
-  activeSubscriptions, // ActiveSubscription[] - active subscriptions
-  fetchProducts,       // ({skus, type}) => Promise<void>
-  requestPurchase,     // (props) => Promise<void>
-  finishTransaction,   // ({purchase, isConsumable}) => Promise<void>
+  products,            // Product[] - populated by fetchProducts()
+  subscriptions,       // ProductSubscription[] - populated by fetchProducts()
+  availablePurchases,  // Purchase[] - populated by getAvailablePurchases()
+  activeSubscriptions, // ActiveSubscription[] - populated by getActiveSubscriptions()
+
+  // ═══════════════════════════════════════════════════════════════
+  // METHODS (return Promise<void>, update state above)
+  // ═══════════════════════════════════════════════════════════════
+  fetchProducts,            // ({skus, type}) => Promise<void>
+  requestPurchase,          // (props) => Promise<void>
+  finishTransaction,        // ({purchase, isConsumable}) => Promise<void>
   getAvailablePurchases,    // () => Promise<void>
-  getActiveSubscriptions,   // (ids?) => Promise<ActiveSubscription[]>
+  getActiveSubscriptions,   // (ids?) => Promise<void>
+  restorePurchases,         // () => Promise<void>
+
+  // ═══════════════════════════════════════════════════════════════
+  // METHODS THAT RETURN VALUES (exceptions to the pattern)
+  // ═══════════════════════════════════════════════════════════════
   hasActiveSubscriptions,   // (ids?) => Promise<boolean>
   verifyPurchase,           // (props) => Promise<VerifyPurchaseResult>
   verifyPurchaseWithProvider, // (props) => Promise<result>
 } = useIAP(options);
 ```
 
+**Usage Pattern:**
+```tsx
+// ✅ CORRECT: Call method, then read from state
+await fetchProducts({skus: ['product1'], type: 'in-app'});
+console.log(products); // Read from state variable
+
+await getAvailablePurchases();
+console.log(availablePurchases); // Read from state variable
+
+// ❌ WRONG: Don't expect return values from methods
+const result = await fetchProducts({...}); // result is void!
+const purchases = await getAvailablePurchases(); // purchases is void!
+```
+
 **Options:**
 - `onPurchaseSuccess?: (purchase: Purchase) => void` - Success callback
 - `onPurchaseError?: (error: PurchaseError) => void` - Error callback
 
 ### Direct API Functions
 
-For use outside React components:
+For use outside React components. Unlike hook methods, these return data directly.
 
 ```tsx
 import {
@@ -90,14 +118,16 @@ import {
   fetchProducts,      // ({skus, type}) => Promise<Product[]>
   requestPurchase,    // (props) => Promise<Purchase | Purchase[] | void>
   finishTransaction,  // ({purchase, isConsumable}) => Promise<void>
-  getAvailablePurchases,   // () => Promise<Purchase[]>
+  getAvailablePurchases,   // (options?) => Promise<Purchase[]> - returns Purchase array directly
   getActiveSubscriptions,  // (ids?) => Promise<ActiveSubscription[]>
   hasActiveSubscriptions,  // (ids?) => Promise<boolean>
   deepLinkToSubscriptions, // ({skuAndroid?}) => Promise<void>
   getStorefront,           // () => Promise<string>
 } from 'expo-iap';
 ```
 
+**Note:** The root API `getAvailablePurchases` returns `Promise<Purchase[]>`, while the hook's `getAvailablePurchases` returns `Promise<void>` and updates internal state.
+
 ### Event Listeners
 
 ```tsx