fix: add onError callback to useIAP and pass subscriptionProductReplacementParams (#3128)

## Summary
- Add `onError` callback to `UseIapOptions` for handling non-purchase
errors (fetchProducts, getAvailablePurchases, getActiveSubscriptions,
restorePurchases)
- Fix `subscriptionProductReplacementParams` not being passed to native
module in `requestPurchase` for Android subscription replacements
- Add comprehensive tests for both fixes
- Update documentation (use-iap.md, llms.txt, llms-full.txt)
- Remove unused `shouldAutoSyncPurchases` from docs

## Test plan
- [x] Run `yarn typecheck` - passes
- [x] Run `yarn lint` - passes
- [x] Run `yarn test` - all 187 tests pass
- [x] Added tests for `onError` callback (7 new tests)
- [x] Added tests for `subscriptionProductReplacementParams` (3 new
tests)

## Related Issues
Fixes related to expo-iap#303 and expo-iap#304

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* **New Features**
* Added an onError callback option to surface non-purchase operation
errors (e.g., product fetches, availability checks).
* Added support for Android subscription replacement parameters to
enable custom upgrade/downgrade behavior in purchase requests.

* **Documentation**
* API docs updated with the new onError option, examples showing onError
and purchase-error handling, and guidance for the Android subscription
replacement parameter.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: hyochan

docs/docs/api/use-iap.md

@@ -62,7 +62,7 @@ const {
 interface UseIAPOptions {
   onPurchaseSuccess?: (purchase: Purchase) => void;
   onPurchaseError?: (error: PurchaseError) => void;
-  shouldAutoSyncPurchases?: boolean; // Controls auto sync behavior inside the hook
+  onError?: (error: Error) => void; // Non-purchase errors (fetchProducts, getAvailablePurchases, etc.)
   onPromotedProductIOS?: (product: Product) => void; // iOS promoted products
 }
 ```
@@ -96,6 +96,41 @@ interface UseIAPOptions {
   };
   ```
 
+#### onError
+
+- **Type**: `(error: Error) => void`
+- **Description**: Called when non-purchase operations fail (e.g., `fetchProducts`, `getAvailablePurchases`, `getActiveSubscriptions`, `restorePurchases`). Use this callback to handle errors from query operations that are not related to the purchase flow itself.
+- **Example**:
+
+  ```tsx
+  onError: (error) => {
+    // Handle non-purchase errors (network issues, query failures, etc.)
+    console.error('IAP operation failed:', error.message);
+    Alert.alert('Error', 'Failed to load products. Please check your connection.');
+  };
+  ```
+
+- **Full Example with Both Error Callbacks**:
+
+  ```tsx
+  const {fetchProducts, requestPurchase} = useIAP({
+    onPurchaseSuccess: (purchase) => {
+      console.log('Purchase successful:', purchase.productId);
+    },
+    onPurchaseError: (error) => {
+      // Purchase-specific errors (user cancelled, payment failed, etc.)
+      if (error.code !== ErrorCode.UserCancelled) {
+        Alert.alert('Purchase Failed', error.message);
+      }
+    },
+    onError: (error) => {
+      // Non-purchase errors (fetchProducts failed, network issues, etc.)
+      console.error('Operation failed:', error.message);
+      Alert.alert('Error', 'Something went wrong. Please try again.');
+    },
+  });
+  ```
+
 #### autoFinishTransactions
 
 - **Type**: `boolean`

docs/static/llms-full.txt

@@ -95,7 +95,7 @@ function useIAP(options?: UseIAPOptions): UseIAPReturn;
 interface UseIAPOptions {
   onPurchaseSuccess?: (purchase: Purchase) => void;
   onPurchaseError?: (error: PurchaseError) => void;
-  shouldAutoSyncPurchases?: boolean;
+  onError?: (error: Error) => void; // Non-purchase errors (fetchProducts, getAvailablePurchases, etc.)
   onPromotedProductIOS?: (product: Product) => void;
 }
 ```
@@ -136,6 +136,7 @@ interface UseIAPReturn {
 - **Auto-connects**: Calls `initConnection()` on mount, `endConnection()` on unmount
 - **Void-returning methods**: `fetchProducts`, `requestPurchase`, `getAvailablePurchases` return `Promise<void>` and update internal state
 - **Use callbacks**: Always handle purchases via `onPurchaseSuccess` and `onPurchaseError`
+- **Error handling**: Use `onPurchaseError` for purchase-related errors and `onError` for non-purchase errors (fetchProducts, getAvailablePurchases, etc.)
 
 ### Basic Example
 
@@ -170,6 +171,11 @@ function Store() {
         Alert.alert('Purchase Failed', error.message);
       }
     },
+    onError: (error) => {
+      // Handle non-purchase errors (fetchProducts, getAvailablePurchases, etc.)
+      console.error('IAP operation failed:', error.message);
+      Alert.alert('Error', 'Failed to load products. Please try again.');
+    },
   });
 
   useEffect(() => {

docs/static/llms.txt

@@ -108,7 +108,8 @@ const purchases = await getAvailablePurchases(); // purchases is void!
 
 **Options:**
 - `onPurchaseSuccess?: (purchase: Purchase) => void` - Success callback
-- `onPurchaseError?: (error: PurchaseError) => void` - Error callback
+- `onPurchaseError?: (error: PurchaseError) => void` - Purchase error callback
+- `onError?: (error: Error) => void` - Non-purchase error callback (fetchProducts, getAvailablePurchases, etc.)
 
 ### Direct API Functions
 

docs/versioned_docs/version-14.4/api/use-iap.md

@@ -62,7 +62,6 @@ const {
 interface UseIAPOptions {
   onPurchaseSuccess?: (purchase: Purchase) => void;
   onPurchaseError?: (error: PurchaseError) => void;
-  shouldAutoSyncPurchases?: boolean; // Controls auto sync behavior inside the hook
   onPromotedProductIOS?: (product: Product) => void; // iOS promoted products
 }
 ```

docs/versioned_docs/version-14.5/api/use-iap.md

@@ -62,7 +62,6 @@ const {
 interface UseIAPOptions {
   onPurchaseSuccess?: (purchase: Purchase) => void;
   onPurchaseError?: (error: PurchaseError) => void;
-  shouldAutoSyncPurchases?: boolean; // Controls auto sync behavior inside the hook
   onPromotedProductIOS?: (product: Product) => void; // iOS promoted products
 }
 ```

docs/versioned_docs/version-14.6/api/use-iap.md

@@ -62,7 +62,6 @@ const {
 interface UseIAPOptions {
   onPurchaseSuccess?: (purchase: Purchase) => void;
   onPurchaseError?: (error: PurchaseError) => void;
-  shouldAutoSyncPurchases?: boolean; // Controls auto sync behavior inside the hook
   onPromotedProductIOS?: (product: Product) => void; // iOS promoted products
 }
 ```

src/__tests__/hooks/useIAP.test.ts

@@ -40,13 +40,30 @@ describe('hooks/useIAP (renderer)', () => {
   });
 
   let capturedPurchaseListener: any;
+  let mockFetchProducts: jest.SpyInstance;
+  let mockGetAvailablePurchases: jest.SpyInstance;
+  let mockGetActiveSubscriptions: jest.SpyInstance;
+  let mockHasActiveSubscriptions: jest.SpyInstance;
+  let mockRestorePurchases: jest.SpyInstance;
 
   beforeEach(() => {
     jest.spyOn(IAP, 'initConnection').mockResolvedValue(true as any);
-    jest.spyOn(IAP, 'getAvailablePurchases').mockResolvedValue([] as any);
-    jest.spyOn(IAP, 'getActiveSubscriptions').mockResolvedValue([] as any);
-    jest.spyOn(IAP, 'hasActiveSubscriptions').mockResolvedValue(false as any);
+    mockGetAvailablePurchases = jest
+      .spyOn(IAP, 'getAvailablePurchases')
+      .mockResolvedValue([] as any);
+    mockGetActiveSubscriptions = jest
+      .spyOn(IAP, 'getActiveSubscriptions')
+      .mockResolvedValue([] as any);
+    mockHasActiveSubscriptions = jest
+      .spyOn(IAP, 'hasActiveSubscriptions')
+      .mockResolvedValue(false as any);
     jest.spyOn(IAP, 'finishTransaction').mockResolvedValue(undefined as any);
+    mockFetchProducts = jest
+      .spyOn(IAP, 'fetchProducts')
+      .mockResolvedValue([] as any);
+    mockRestorePurchases = jest
+      .spyOn(IAP, 'restorePurchases')
+      .mockResolvedValue(undefined as any);
     jest.spyOn(IAP, 'purchaseUpdatedListener').mockImplementation((cb: any) => {
       capturedPurchaseListener = cb;
       return {remove: jest.fn()};
@@ -100,4 +117,173 @@ describe('hooks/useIAP (renderer)', () => {
     });
     expect(IAP.finishTransaction).toBeDefined();
   });
+
+  describe('onError callback', () => {
+    it('calls onError when fetchProducts fails', async () => {
+      const fetchError = new Error('Network error fetching products');
+      mockFetchProducts.mockRejectedValueOnce(fetchError);
+
+      let api: any;
+      const onError = jest.fn();
+      const Harness = () => {
+        api = useIAP({onError});
+        return null;
+      };
+
+      await act(async () => {
+        TestRenderer.create(React.createElement(Harness));
+      });
+      await act(async () => {});
+
+      // Call fetchProducts which should trigger onError
+      await act(async () => {
+        await api.fetchProducts({skus: ['product1']});
+      });
+
+      expect(onError).toHaveBeenCalledWith(fetchError);
+    });
+
+    it('calls onError when getAvailablePurchases fails', async () => {
+      const purchaseError = new Error('Failed to get purchases');
+      mockGetAvailablePurchases.mockRejectedValueOnce(purchaseError);
+
+      let api: any;
+      const onError = jest.fn();
+      const Harness = () => {
+        api = useIAP({onError});
+        return null;
+      };
+
+      await act(async () => {
+        TestRenderer.create(React.createElement(Harness));
+      });
+      await act(async () => {});
+
+      await act(async () => {
+        await api.getAvailablePurchases();
+      });
+
+      expect(onError).toHaveBeenCalledWith(purchaseError);
+    });
+
+    it('calls onError when getActiveSubscriptions fails', async () => {
+      const subscriptionError = new Error('Failed to get subscriptions');
+      mockGetActiveSubscriptions.mockRejectedValueOnce(subscriptionError);
+
+      let api: any;
+      const onError = jest.fn();
+      const Harness = () => {
+        api = useIAP({onError});
+        return null;
+      };
+
+      await act(async () => {
+        TestRenderer.create(React.createElement(Harness));
+      });
+      await act(async () => {});
+
+      await act(async () => {
+        const result = await api.getActiveSubscriptions();
+        // Should return empty array on error
+        expect(result).toEqual([]);
+      });
+
+      expect(onError).toHaveBeenCalledWith(subscriptionError);
+    });
+
+    it('calls onError when hasActiveSubscriptions fails', async () => {
+      const hasSubsError = new Error('Failed to check subscriptions');
+      mockHasActiveSubscriptions.mockRejectedValueOnce(hasSubsError);
+
+      let api: any;
+      const onError = jest.fn();
+      const Harness = () => {
+        api = useIAP({onError});
+        return null;
+      };
+
+      await act(async () => {
+        TestRenderer.create(React.createElement(Harness));
+      });
+      await act(async () => {});
+
+      await act(async () => {
+        const result = await api.hasActiveSubscriptions();
+        // Should return false on error
+        expect(result).toBe(false);
+      });
+
+      expect(onError).toHaveBeenCalledWith(hasSubsError);
+    });
+
+    it('calls onError when restorePurchases fails', async () => {
+      const restoreError = new Error('Failed to restore');
+      mockRestorePurchases.mockRejectedValueOnce(restoreError);
+
+      let api: any;
+      const onError = jest.fn();
+      const Harness = () => {
+        api = useIAP({onError});
+        return null;
+      };
+
+      await act(async () => {
+        TestRenderer.create(React.createElement(Harness));
+      });
+      await act(async () => {});
+
+      await act(async () => {
+        await api.restorePurchases();
+      });
+
+      expect(onError).toHaveBeenCalledWith(restoreError);
+    });
+
+    it('does not call onError when operations succeed', async () => {
+      let api: any;
+      const onError = jest.fn();
+      const Harness = () => {
+        api = useIAP({onError});
+        return null;
+      };
+
+      await act(async () => {
+        TestRenderer.create(React.createElement(Harness));
+      });
+      await act(async () => {});
+
+      await act(async () => {
+        await api.fetchProducts({skus: ['product1']});
+        await api.getAvailablePurchases();
+        await api.getActiveSubscriptions();
+        await api.hasActiveSubscriptions();
+      });
+
+      expect(onError).not.toHaveBeenCalled();
+    });
+
+    it('converts non-Error objects to Error in onError callback', async () => {
+      const stringError = 'String error message';
+      mockFetchProducts.mockRejectedValueOnce(stringError);
+
+      let api: any;
+      const onError = jest.fn();
+      const Harness = () => {
+        api = useIAP({onError});
+        return null;
+      };
+
+      await act(async () => {
+        TestRenderer.create(React.createElement(Harness));
+      });
+      await act(async () => {});
+
+      await act(async () => {
+        await api.fetchProducts({skus: ['product1']});
+      });
+
+      expect(onError).toHaveBeenCalledWith(expect.any(Error));
+      expect(onError.mock.calls[0][0].message).toBe(stringError);
+    });
+  });
 });