fix(react-native-iap): avoid iOS listener cleanup crash after unmount (#262)

## Summary

This keeps the iOS StoreKit-backed singleton native purchase and
purchase-error listeners attached for the app session while JavaScript
subscriptions are still removed normally.

`useIAP` keeps internal state updates mount-guarded during post-purchase
refresh, but still delivers `onPurchaseSuccess` for a purchase event
that already entered before unmount so apps can call
`finishTransaction`.

## Why

In a React Native app using `useIAP` from a modal-like plans screen,
dismissing the screen can unmount the hook while StoreKit/Nitro purchase
listener work is still in flight. The JS subscription cleanup removes
the JS callback, but when it is also the last callback it previously
disposed the native iOS listener immediately.

On iOS release builds this can abort during screen dismissal. Keeping
the singleton native listener attached for the app session avoids that
teardown race while still removing the JS callback, so unmounted screens
no longer receive new purchase, purchase-error, promoted-product, or
billing-issue callbacks.

For a purchase event that already entered before unmount,
`onPurchaseSuccess` remains deliverable after the pending refresh
completes. That callback is the documented `finishTransaction` site, and
dropping it would risk leaving the purchase unfinished.

Android behavior is unchanged: native listener removal still happens
when the last JS listener is removed.

## Validation

- `yarn typecheck:lib` in `libraries/react-native-iap`
- `yarn lint` in `libraries/react-native-iap`
- `yarn lint:tsc` in `libraries/react-native-iap`
- `yarn test:ci --watchman=false --silent` in
`libraries/react-native-iap`
- `git diff --check`
- Consumer app validation with a patch-package version of the same fix:
`npm run typecheck`


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

* **Bug Fixes**
* Purchase success callbacks now remain deliverable when a related
screen or component is unmounted, while preventing updates to inactive
state.
* Improved iOS purchase and error listener handling so removing a
JavaScript listener does not interrupt native purchase updates.
* Improved Android listener cleanup and re-subscription behavior after
the final JavaScript listener is removed.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Hyo <hyo@hyo.dev>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

libraries/react-native-iap/src/__tests__/hooks/useIAP.test.ts

@@ -50,6 +50,7 @@ describe('hooks/useIAP (renderer)', () => {
   let mockSyncIOS: jest.SpyInstance;
 
   beforeEach(() => {
+    capturedPurchaseListener = undefined;
     jest.spyOn(IAP, 'initConnection').mockResolvedValue(true as any);
     mockGetAvailablePurchases = jest
       .spyOn(IAP, 'getAvailablePurchases')
@@ -121,6 +122,66 @@ describe('hooks/useIAP (renderer)', () => {
     expect(IAP.finishTransaction).toBeDefined();
   });
 
+  it('still delivers purchase success when unmounted while refresh is pending', async () => {
+    let resolveActiveSubscriptions: (() => void) | undefined;
+    mockGetActiveSubscriptions.mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolveActiveSubscriptions = () => resolve([]);
+        }) as any,
+    );
+
+    const onPurchaseSuccess = jest.fn();
+    const Harness = () => {
+      useIAP({onPurchaseSuccess});
+      return null;
+    };
+
+    let renderer: ReturnType<typeof TestRenderer.create>;
+    await act(async () => {
+      renderer = TestRenderer.create(React.createElement(Harness));
+    });
+    await act(async () => {});
+
+    const purchase = {
+      id: 't1',
+      productId: 'p1',
+      transactionDate: Date.now(),
+      platform: 'ios',
+      store: 'apple',
+      quantity: 1,
+      purchaseState: 'purchased',
+      isAutoRenewing: false,
+    };
+    if (!capturedPurchaseListener) {
+      throw new Error('purchase listener was not initialized');
+    }
+
+    const purchaseUpdate = capturedPurchaseListener(purchase);
+
+    if (!resolveActiveSubscriptions) {
+      throw new Error('active subscriptions resolver was not initialized');
+    }
+    const resolvePendingActiveSubscriptions = resolveActiveSubscriptions;
+
+    await act(async () => {
+      renderer.unmount();
+    });
+
+    await act(async () => {
+      resolvePendingActiveSubscriptions();
+      await purchaseUpdate;
+    });
+
+    // The event entered while mounted, so the success callback still fires:
+    // it is where apps call finishTransaction, and a dropped event has no
+    // in-session redelivery.
+    expect(onPurchaseSuccess).toHaveBeenCalledTimes(1);
+    expect(onPurchaseSuccess).toHaveBeenCalledWith(
+      expect.objectContaining({id: 't1', productId: 'p1'}),
+    );
+  });
+
   it('requestPurchase calls root API and returns void', async () => {
     const mockRequestPurchase = jest
       .spyOn(IAP, 'requestPurchase')

libraries/react-native-iap/src/__tests__/index.test.ts

@@ -214,7 +214,7 @@ describe('Public API (src/index.ts)', () => {
       expect(duplicateListener).toHaveBeenCalledTimes(1);
     });
 
-    it('removes purchase updated native listener by token after the last JS listener is removed', () => {
+    it('removes iOS purchase updated JS listeners without removing the native listener', () => {
       const listener1 = jest.fn();
       const listener2 = jest.fn();
       const sub1 = IAP.purchaseUpdatedListener(listener1);
@@ -226,23 +226,100 @@ describe('Public API (src/index.ts)', () => {
 
       sub2.remove();
       sub2.remove();
-      expect(mockIap.removePurchaseUpdatedListener).toHaveBeenCalledTimes(1);
-      expect(mockIap.removePurchaseUpdatedListener).toHaveBeenCalledWith(1);
+      expect(mockIap.removePurchaseUpdatedListener).not.toHaveBeenCalled();
     });
 
-    it('removes non-deduping purchase updated native listener by its own token', () => {
+    it('removes iOS non-deduping purchase updated JS listener without removing the native listener', () => {
       const defaultSub = IAP.purchaseUpdatedListener(jest.fn());
-      const duplicateSub = IAP.purchaseUpdatedListener(jest.fn(), {
+      const duplicateListener = jest.fn();
+      const duplicateSub = IAP.purchaseUpdatedListener(duplicateListener, {
         dedupeTransactionIOS: false,
       });
 
       expect(mockIap.addPurchaseUpdatedListener).toHaveBeenCalledTimes(2);
+      const duplicateNativeHandler = mockIap.addPurchaseUpdatedListener.mock
+        .calls[1][0];
+      const nitroPurchase = {
+        id: 't1',
+        transactionId: 't1',
+        productId: 'p1',
+        transactionDate: Date.now(),
+        store: 'apple',
+        quantity: 1,
+        purchaseState: 'purchased',
+        isAutoRenewing: false,
+      };
+
+      duplicateNativeHandler(nitroPurchase);
+      expect(duplicateListener).toHaveBeenCalledTimes(1);
+
       duplicateSub.remove();
-      expect(mockIap.removePurchaseUpdatedListener).toHaveBeenCalledWith(2);
+      expect(mockIap.removePurchaseUpdatedListener).not.toHaveBeenCalled();
+
+      duplicateNativeHandler(nitroPurchase);
+      expect(duplicateListener).toHaveBeenCalledTimes(1);
 
       defaultSub.remove();
+      expect(mockIap.removePurchaseUpdatedListener).not.toHaveBeenCalled();
+    });
+
+    it('reuses the retained iOS native listener when re-subscribing after full removal', () => {
+      const first = jest.fn();
+      const sub = IAP.purchaseUpdatedListener(first);
+      const nativeHandler = mockIap.addPurchaseUpdatedListener.mock.calls[0][0];
+      sub.remove();
+
+      const second = jest.fn();
+      IAP.purchaseUpdatedListener(second);
+      expect(mockIap.addPurchaseUpdatedListener).toHaveBeenCalledTimes(1);
+
+      nativeHandler({
+        id: 't1',
+        transactionId: 't1',
+        productId: 'p1',
+        transactionDate: Date.now(),
+        store: 'apple',
+        quantity: 1,
+        purchaseState: 'purchased',
+        isAutoRenewing: false,
+      });
+      expect(first).not.toHaveBeenCalled();
+      expect(second).toHaveBeenCalledTimes(1);
+    });
+
+    it('removes the Android native listener by token and re-attaches on next subscribe', () => {
+      (Platform as any).OS = 'android';
+      const sub1 = IAP.purchaseUpdatedListener(jest.fn());
+      const sub2 = IAP.purchaseUpdatedListener(jest.fn());
+
+      expect(mockIap.addPurchaseUpdatedListener).toHaveBeenCalledTimes(1);
+      sub1.remove();
+      expect(mockIap.removePurchaseUpdatedListener).not.toHaveBeenCalled();
+
+      sub2.remove();
+      expect(mockIap.removePurchaseUpdatedListener).toHaveBeenCalledTimes(1);
       expect(mockIap.removePurchaseUpdatedListener).toHaveBeenCalledWith(1);
-      expect(mockIap.removePurchaseUpdatedListener).toHaveBeenCalledTimes(2);
+
+      IAP.purchaseUpdatedListener(jest.fn());
+      expect(mockIap.addPurchaseUpdatedListener).toHaveBeenCalledTimes(2);
+    });
+
+    it('keeps the iOS native purchase error listener attached across removal and re-subscribe', () => {
+      const first = jest.fn();
+      const sub = IAP.purchaseErrorListener(first);
+      expect(mockIap.addPurchaseErrorListener).toHaveBeenCalledTimes(1);
+      const nativeHandler = mockIap.addPurchaseErrorListener.mock.calls[0][0];
+
+      sub.remove();
+      expect(mockIap.removePurchaseErrorListener).not.toHaveBeenCalled();
+
+      const second = jest.fn();
+      IAP.purchaseErrorListener(second);
+      expect(mockIap.addPurchaseErrorListener).toHaveBeenCalledTimes(1);
+
+      nativeHandler({code: 'network-error', message: 'offline'});
+      expect(first).not.toHaveBeenCalled();
+      expect(second).toHaveBeenCalledTimes(1);
     });
 
     it('purchaseErrorListener forwards error objects and supports removal', () => {
@@ -435,7 +512,8 @@ describe('Public API (src/index.ts)', () => {
       expect(listener1).not.toHaveBeenCalled();
     });
 
-    it('detaches the native error listener after the last JS listener is removed', () => {
+    it('detaches the Android native error listener after the last JS listener is removed', () => {
+      (Platform as any).OS = 'android';
       const sub1 = IAP.purchaseErrorListener(jest.fn());
       const sub2 = IAP.purchaseErrorListener(jest.fn());
       const nativeHandler = mockIap.addPurchaseErrorListener.mock.calls[0][0];

libraries/react-native-iap/src/hooks/useIAP.ts

@@ -591,6 +591,11 @@ export function useIAP(options?: UseIapOptions): UseIap {
           } catch (e) {
             RnIapConsole.warn('[useIAP] post-purchase refresh failed:', e);
           }
+
+          // Deliver even if the hook unmounted while the refresh was pending:
+          // onPurchaseSuccess is where apps call finishTransaction, and a
+          // dropped event has no in-session redelivery. Internal setState is
+          // mount-guarded inside the refresh helpers.
           if (optionsRef.current?.onPurchaseSuccess) {
             optionsRef.current.onPurchaseSuccess(purchase);
           }

libraries/react-native-iap/src/index.ts

@@ -451,6 +451,13 @@ export const purchaseUpdatedListener = (
         return;
       }
 
+      // StoreKit-backed Nitro listener disposal can abort in iOS release builds
+      // when a native modal is being popped. Keep the singleton native listener
+      // attached for the app session and only remove the JS callback above.
+      if (Platform.OS === 'ios') {
+        return;
+      }
+
       const token = receiveDuplicateTransactionUpdatesIOS
         ? purchaseUpdateDuplicateNativeToken
         : purchaseUpdateNativeToken;
@@ -498,7 +505,19 @@ export const purchaseErrorListener = (
   return {
     remove: () => {
       purchaseErrorJsListeners.delete(listener);
-      if (purchaseErrorJsListeners.size === 0 && purchaseErrorNativeAttached) {
+      if (purchaseErrorJsListeners.size > 0) {
+        return;
+      }
+
+      // Same iOS policy as purchaseUpdatedListener: releasing the stored
+      // native callback from a JS unsubscribe can race an in-flight dispatch
+      // snapshot on another thread. Keep the singleton attached; endConnection
+      // owns native disposal.
+      if (Platform.OS === 'ios') {
+        return;
+      }
+
+      if (purchaseErrorNativeAttached) {
         try {
           IAP.instance.removePurchaseErrorListener(purchaseErrorNativeHandler);
           purchaseErrorNativeAttached = false;