fix(ios): emit error on duplicate purchase instead of silent hang (#3177)

## Summary

- Fixes duplicate purchase detection silently dropping events, causing
the app to hang indefinitely
- Adds `ErrorCode.DuplicatePurchase` (`'duplicate-purchase'`) so apps
can detect and recover from this scenario
- Adds `isDuplicatePurchaseError()` public helper for convenient error
checking

Closes #3176

## Changes

### iOS Native (`ios/HybridRnIap.swift`)
- When a duplicate purchase event is detected in `sendPurchaseUpdate`,
now calls `sendPurchaseError` with code `duplicate-purchase` instead of
silently returning
- The `onPurchaseError` callback now fires, allowing apps to respond
(e.g., trigger `restorePurchases`)

### TypeScript Types (`src/types.ts`)
- Added `DuplicatePurchase = 'duplicate-purchase'` to `ErrorCode` enum

### Error Utilities (`src/utils/error.ts`)
- Added `isDuplicatePurchaseError()` public helper (exported via
`react-native-iap`)

### Error Mapping (`src/utils/errorMapping.ts`)
- Added `DuplicatePurchase` to `COMMON_ERROR_CODE_MAP`
- Added user-friendly message: `"This purchase has already been
processed. Try restoring purchases."`
- Added `DuplicatePurchase` to `isRecoverableError` list (recoverable
via `restorePurchases`)
- Added internal `isDuplicatePurchaseError()` helper

## Usage

```typescript
import { useIAP, isDuplicatePurchaseError } from 'react-native-iap';

const { requestPurchase, restorePurchases } = useIAP({
  onPurchaseError: (error) => {
    if (isDuplicatePurchaseError(error)) {
      restorePurchases();
      return;
    }
    // handle other errors
  },
});
```

## Test plan

- [x] `yarn typecheck` passes
- [x] `yarn lint` passes
- [x] `yarn test` passes (260 tests, 12 suites)

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

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

* **Bug Fixes**
* Duplicate purchase attempts are now detected and reported as a
distinct, recoverable error and surface a clear, user-friendly message
guiding recovery (restore purchases or review options).

* **New Features**
* Exposed utilities to detect duplicate-purchase errors so UI can handle
them consistently and provide targeted recovery guidance.

* **Tests**
* Added tests verifying duplicate-purchase detection, recoverability,
and the user-facing message.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyochan

ios/HybridRnIap.swift

@@ -22,6 +22,7 @@ class HybridRnIap: HybridRnIapSpec {
     private var deliveredPurchaseEventKeys: Set<String> = []
     private var deliveredPurchaseEventOrder: [String] = []
     private let purchaseEventDedupLimit = 128
+    private static let duplicatePurchaseCode = "duplicate-purchase"
     private var purchasePayloadById: [String: [String: Any]] = [:]
     // Thread safety lock for listener arrays and error dedup state
     private let listenerLock = NSLock()
@@ -1042,6 +1043,14 @@ class HybridRnIap: HybridRnIapSpec {
 
         if isDuplicate {
             RnIapLog.warn("Duplicate purchase update skipped for \(purchase.productId)")
+            let error = NitroPurchaseResult(
+                responseCode: -1,
+                debugMessage: nil,
+                code: HybridRnIap.duplicatePurchaseCode,
+                message: "Duplicate purchase update skipped for \(purchase.productId). Use restorePurchases or getAvailablePurchases to recover.",
+                purchaseToken: nil
+            )
+            sendPurchaseError(error, productId: purchase.productId)
             return
         }
 

src/__tests__/utils/error.test.ts

@@ -1,6 +1,8 @@
 import {
   parseErrorStringToJsonObj,
   isUserCancelledError,
+  isDuplicatePurchaseError,
+  DUPLICATE_PURCHASE_CODE,
 } from '../../utils/error';
 import {ErrorCode} from '../../types';
 
@@ -140,4 +142,43 @@ describe('Error utilities', () => {
       expect(isUserCancelledError(error)).toBe(false);
     });
   });
+
+  describe('isDuplicatePurchaseError', () => {
+    it('should return true for duplicate purchase error', () => {
+      const error = {
+        code: DUPLICATE_PURCHASE_CODE,
+        message: 'Duplicate purchase update skipped',
+      };
+
+      expect(isDuplicatePurchaseError(error)).toBe(true);
+    });
+
+    it('should return true for duplicate-purchase string code', () => {
+      const error = {
+        code: 'duplicate-purchase',
+        message: 'Duplicate',
+      };
+
+      expect(isDuplicatePurchaseError(error)).toBe(true);
+    });
+
+    it('should return false for other errors', () => {
+      const error = {
+        code: ErrorCode.UserCancelled,
+        message: 'User cancelled',
+      };
+
+      expect(isDuplicatePurchaseError(error)).toBe(false);
+    });
+
+    it('should return false for undefined', () => {
+      expect(isDuplicatePurchaseError(undefined)).toBe(false);
+    });
+  });
+
+  describe('DUPLICATE_PURCHASE_CODE', () => {
+    it('should equal duplicate-purchase', () => {
+      expect(DUPLICATE_PURCHASE_CODE).toBe('duplicate-purchase');
+    });
+  });
 });

src/__tests__/utils/errorMapping.test.ts

@@ -2,6 +2,8 @@ import {
   getUserFriendlyErrorMessage,
   isRecoverableError,
   isUserCancelledError,
+  isDuplicatePurchaseError,
+  DUPLICATE_PURCHASE_CODE,
 } from '../../utils/errorMapping';
 import {ErrorCode} from '../../types';
 
@@ -45,6 +47,47 @@ describe('utils/errorMapping', () => {
     ).toBe(false);
   });
 
+  test('isDuplicatePurchaseError detects duplicate purchase errors', () => {
+    expect(
+      isDuplicatePurchaseError({
+        code: DUPLICATE_PURCHASE_CODE,
+        message: 'x',
+      } as any),
+    ).toBe(true);
+    expect(
+      isDuplicatePurchaseError({
+        code: 'duplicate-purchase',
+        message: 'x',
+      } as any),
+    ).toBe(true);
+    expect(
+      isDuplicatePurchaseError({
+        code: ErrorCode.UserCancelled,
+        message: 'x',
+      } as any),
+    ).toBe(false);
+  });
+
+  test('isRecoverableError includes duplicate-purchase', () => {
+    expect(
+      isRecoverableError({
+        code: DUPLICATE_PURCHASE_CODE,
+        message: 'x',
+      } as any),
+    ).toBe(true);
+  });
+
+  test('getUserFriendlyErrorMessage returns message for duplicate-purchase', () => {
+    expect(
+      getUserFriendlyErrorMessage({
+        code: DUPLICATE_PURCHASE_CODE,
+        message: 'ignored',
+      } as any),
+    ).toBe(
+      'This purchase has already been processed. Try restoring purchases.',
+    );
+  });
+
   test('getUserFriendlyErrorMessage maps known codes and falls back to message', () => {
     expect(
       getUserFriendlyErrorMessage({

src/utils/__tests__/errorMapping.test.ts

@@ -3,10 +3,12 @@ import {
   createPurchaseErrorFromPlatform,
   ErrorCodeUtils,
   isUserCancelledError,
+  isDuplicatePurchaseError,
   isNetworkError,
   isRecoverableError,
   getUserFriendlyErrorMessage,
   ErrorCodeMapping,
+  DUPLICATE_PURCHASE_CODE,
 } from '../errorMapping';
 import {ErrorCode} from '../../types';
 
@@ -150,6 +152,19 @@ describe('errorMapping', () => {
     });
   });
 
+  describe('isDuplicatePurchaseError', () => {
+    it('should identify duplicate purchase errors', () => {
+      expect(isDuplicatePurchaseError({code: DUPLICATE_PURCHASE_CODE})).toBe(
+        true,
+      );
+      expect(isDuplicatePurchaseError({code: 'duplicate-purchase'})).toBe(true);
+      expect(isDuplicatePurchaseError({code: ErrorCode.UserCancelled})).toBe(
+        false,
+      );
+      expect(isDuplicatePurchaseError({})).toBe(false);
+    });
+  });
+
   describe('isNetworkError', () => {
     it('should identify network-related errors', () => {
       expect(isNetworkError({code: ErrorCode.NetworkError})).toBe(true);
@@ -175,6 +190,7 @@ describe('errorMapping', () => {
       );
       expect(isRecoverableError({code: ErrorCode.QueryProduct})).toBe(true);
       expect(isRecoverableError({code: ErrorCode.InitConnection})).toBe(true);
+      expect(isRecoverableError({code: DUPLICATE_PURCHASE_CODE})).toBe(true);
       expect(isRecoverableError({code: ErrorCode.UserCancelled})).toBe(false);
     });
   });
@@ -193,6 +209,9 @@ describe('errorMapping', () => {
       expect(getUserFriendlyErrorMessage({code: ErrorCode.SkuNotFound})).toBe(
         'Requested product could not be found',
       );
+      expect(getUserFriendlyErrorMessage({code: DUPLICATE_PURCHASE_CODE})).toBe(
+        'This purchase has already been processed. Try restoring purchases.',
+      );
     });
 
     it('should return custom message when provided', () => {

src/utils/error.ts

@@ -95,3 +95,9 @@ export function isUserCancelledError(
     errorObj.responseCode === 1
   ); // Android BillingClient.BillingResponseCode.USER_CANCELED
 }
+
+// Re-export from errorMapping for public API convenience
+export {
+  isDuplicatePurchaseError,
+  DUPLICATE_PURCHASE_CODE,
+} from './errorMapping';

src/utils/errorMapping.ts

@@ -6,6 +6,13 @@
 
 import {ErrorCode, type IapPlatform} from '../types';
 
+/**
+ * Error code for duplicate purchase events detected on iOS.
+ * Defined here because it originates from react-native-iap's dedup logic,
+ * not from the OpenIAP upstream that generates src/types.ts.
+ */
+export const DUPLICATE_PURCHASE_CODE = 'duplicate-purchase' as const;
+
 const ERROR_CODE_ALIASES: Record<string, ErrorCode> = {
   E_USER_CANCELED: ErrorCode.UserCancelled,
   USER_CANCELED: ErrorCode.UserCancelled,
@@ -271,6 +278,10 @@ export function isUserCancelledError(error: unknown): boolean {
   return extractCode(error) === ErrorCode.UserCancelled;
 }
 
+export function isDuplicatePurchaseError(error: unknown): boolean {
+  return extractCode(error) === DUPLICATE_PURCHASE_CODE;
+}
+
 export function isNetworkError(error: unknown): boolean {
   const networkErrors: ErrorCode[] = [
     ErrorCode.NetworkError,
@@ -296,6 +307,7 @@ export function isRecoverableError(error: unknown): boolean {
     ErrorCode.InitConnection,
     ErrorCode.SyncError,
     ErrorCode.ConnectionClosed,
+    DUPLICATE_PURCHASE_CODE,
   ];
 
   const code = extractCode(error);
@@ -326,6 +338,8 @@ export function getUserFriendlyErrorMessage(error: ErrorLike): string {
       return 'Selected offer does not match the SKU';
     case ErrorCode.DeferredPayment:
       return 'Payment is pending approval';
+    case DUPLICATE_PURCHASE_CODE:
+      return 'This purchase has already been processed. Try restoring purchases.';
     case ErrorCode.NotPrepared:
       return 'In-app purchase is not ready. Please try again later.';
     case ErrorCode.ServiceError: