feat(ios): add ExternalPurchaseCustomLink API support (iOS 18.1+) (#311)

## Summary

- Sync with OpenIAP v1.3.16 (gql: 1.3.16, apple: 1.3.14, google: 1.3.27)
- Add 3 new ExternalPurchaseCustomLink APIs for iOS 18.1+:
  - `isEligibleForExternalPurchaseCustomLinkIOS()` - Check eligibility
- `getExternalPurchaseCustomLinkTokenIOS(tokenType)` - Get token for
Apple reporting
- `showExternalPurchaseCustomLinkNoticeIOS(noticeType)` - Show
disclosure notice
- Update `presentExternalPurchaseNoticeSheetIOS` to return
`externalPurchaseToken`

## Changes

| File | Description |
|------|-------------|
| openiap-versions.json | Update to gql 1.3.16, apple 1.3.14, google
1.3.27 |
| src/types.ts | Regenerated types with new ExternalPurchaseCustomLink
types |
| ios/ExpoIapModule.swift | Add 3 new AsyncFunctions |
| src/modules/ios.ts | Add TypeScript API wrappers |
| docs/blog/2026-01-26-3.4.7-external-purchase-custom-link.md | Release
notes |
| docs/static/llms.txt | Update AI reference |
| docs/static/llms-full.txt | Update AI reference |

## Test plan

- [x] `bun run lint:ci` passes
- [x] `bun run test` passes (186 tests)
- [x] TypeScript types compile correctly

## References

- [Apple ExternalPurchaseCustomLink
Documentation](https://developer.apple.com/documentation/storekit/externalpurchasecustomlink)
- [OpenIAP Release
Notes](https://www.openiap.dev/docs/updates/notes#gql-1-3-16-apple-1-3-14)

🤖 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**
* iOS 18.1+ External Purchase Custom Link flow: eligibility check,
disclosure notice flow, token retrieval for Apple reporting.
* External purchase notice flow now returns a reporting token when the
user continues.

* **Documentation**
* Added detailed release notes, usage example, and installation/version
guidance for the new flow.

* **Tests**
* Added comprehensive tests covering the new iOS external purchase APIs
and flows.

<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/blog/2026-01-26-3.4.7-external-purchase-custom-link.md

@@ -0,0 +1,194 @@
+---
+slug: 3.4.7
+title: 3.4.7 - ExternalPurchaseCustomLink API (iOS 18.1+)
+authors: [hyochan]
+tags: [release, ios, storekit, external-purchase, ios-18]
+date: 2026-01-26
+---
+
+# 3.4.7 Release Notes
+
+Expo IAP 3.4.7 adds support for Apple's **ExternalPurchaseCustomLink** API (iOS 18.1+) for apps using custom external purchase links.
+
+<!-- truncate -->
+
+## New Features
+
+### ExternalPurchaseCustomLink API (iOS 18.1+)
+
+The ExternalPurchaseCustomLink API enables apps to use custom external purchase links with token-based reporting to Apple. This is for apps that have been granted an entitlement to link out to external purchases.
+
+Reference: [ExternalPurchaseCustomLink Documentation](https://developer.apple.com/documentation/storekit/externalpurchasecustomlink)
+
+### New APIs
+
+#### `isEligibleForExternalPurchaseCustomLinkIOS()`
+
+Check if your app is eligible to use the ExternalPurchaseCustomLink API.
+
+```tsx
+import {isEligibleForExternalPurchaseCustomLinkIOS} from 'expo-iap';
+
+const isEligible = await isEligibleForExternalPurchaseCustomLinkIOS();
+if (isEligible) {
+  // App can use custom external purchase links
+}
+```
+
+#### `getExternalPurchaseCustomLinkTokenIOS(tokenType)`
+
+Get an external purchase token for reporting to Apple's External Purchase Server API.
+
+```tsx
+import {getExternalPurchaseCustomLinkTokenIOS} from 'expo-iap';
+
+// For new customer acquisition
+const acquisitionResult = await getExternalPurchaseCustomLinkTokenIOS('acquisition');
+if (acquisitionResult.token) {
+  // Report to Apple's External Purchase Server API
+  await reportToApple(acquisitionResult.token);
+}
+
+// For existing customer services
+const servicesResult = await getExternalPurchaseCustomLinkTokenIOS('services');
+if (servicesResult.token) {
+  await reportToApple(servicesResult.token);
+}
+```
+
+#### `showExternalPurchaseCustomLinkNoticeIOS(noticeType)`
+
+Display the system disclosure notice sheet before linking out to external purchases.
+
+```tsx
+import {showExternalPurchaseCustomLinkNoticeIOS} from 'expo-iap';
+
+const result = await showExternalPurchaseCustomLinkNoticeIOS('browser');
+if (result.continued) {
+  // User agreed to continue to external purchase
+  // Now open your external purchase link
+  await Linking.openURL('https://your-store.com/checkout');
+} else {
+  // User cancelled
+}
+```
+
+### Updated: `presentExternalPurchaseNoticeSheetIOS()`
+
+Now returns `externalPurchaseToken` when user continues to external purchase.
+
+```tsx
+import {presentExternalPurchaseNoticeSheetIOS} from 'expo-iap';
+
+const result = await presentExternalPurchaseNoticeSheetIOS();
+if (result.result === 'continue') {
+  console.log('Token:', result.externalPurchaseToken);
+  // Report this token to Apple's External Purchase Server API
+}
+```
+
+### New Types
+
+```ts
+// Token types for getExternalPurchaseCustomLinkTokenIOS
+type ExternalPurchaseCustomLinkTokenTypeIOS = 'acquisition' | 'services';
+
+// Notice types for showExternalPurchaseCustomLinkNoticeIOS
+type ExternalPurchaseCustomLinkNoticeTypeIOS = 'browser';
+
+// Result of token retrieval
+interface ExternalPurchaseCustomLinkTokenResultIOS {
+  token?: string | null;
+  error?: string | null;
+}
+
+// Result of showing notice
+interface ExternalPurchaseCustomLinkNoticeResultIOS {
+  continued: boolean;
+  error?: string | null;
+}
+
+// Updated ExternalPurchaseNoticeResultIOS
+interface ExternalPurchaseNoticeResultIOS {
+  result: 'continue' | 'dismissed';
+  externalPurchaseToken?: string | null; // New field
+  error?: string | null;
+}
+```
+
+### Complete External Purchase Custom Link Flow
+
+```tsx
+import {useEffect, useState} from 'react';
+import {Button, Linking, Platform} from 'react-native';
+import {
+  isEligibleForExternalPurchaseCustomLinkIOS,
+  getExternalPurchaseCustomLinkTokenIOS,
+  showExternalPurchaseCustomLinkNoticeIOS,
+} from 'expo-iap';
+
+export function ExternalPurchaseCustomLink() {
+  const [isEligible, setIsEligible] = useState(false);
+
+  useEffect(() => {
+    if (Platform.OS !== 'ios') return;
+
+    isEligibleForExternalPurchaseCustomLinkIOS().then(setIsEligible);
+  }, []);
+
+  const handleExternalPurchase = async () => {
+    // Step 1: Show disclosure notice
+    const noticeResult = await showExternalPurchaseCustomLinkNoticeIOS('browser');
+    if (!noticeResult.continued) {
+      console.log('User cancelled');
+      return;
+    }
+
+    // Step 2: Get token for reporting
+    const tokenResult = await getExternalPurchaseCustomLinkTokenIOS('acquisition');
+    if (tokenResult.error) {
+      console.error('Failed to get token:', tokenResult.error);
+      return;
+    }
+
+    // Step 3: Open external purchase link
+    await Linking.openURL('https://your-store.com/checkout');
+
+    // Step 4: After purchase completes, report to Apple
+    if (tokenResult.token) {
+      await reportExternalPurchaseToApple(tokenResult.token);
+    }
+  };
+
+  if (!isEligible) return null;
+
+  return (
+    <Button title="Purchase on Web" onPress={handleExternalPurchase} />
+  );
+}
+```
+
+## OpenIAP Updates
+
+| Package | Version |
+|---------|---------|
+| openiap-gql | 1.3.16 |
+| openiap-apple | 1.3.14 |
+| openiap-google | 1.3.27 |
+
+## Installation
+
+```bash
+bun add expo-iap@3.4.7
+# or
+npm install expo-iap@3.4.7
+# or
+yarn add expo-iap@3.4.7
+```
+
+## References
+
+- [Apple ExternalPurchaseCustomLink Documentation](https://developer.apple.com/documentation/storekit/externalpurchasecustomlink)
+- [OpenIAP Release Notes](https://www.openiap.dev/docs/updates/notes#gql-1-3-16-apple-1-3-14)
+
+Questions or feedback? Reach out via [GitHub issues](https://github.com/hyochan/expo-iap/issues).

docs/static/llms-full.txt

@@ -742,10 +742,14 @@ import {
   currentEntitlementIOS,
   showManageSubscriptionsIOS,
   beginRefundRequestIOS,
-  // Alternative Billing (iOS 16+)
+  // External Purchase (iOS 15.4+)
   canPresentExternalPurchaseNoticeIOS,
   presentExternalPurchaseNoticeSheetIOS,
   presentExternalPurchaseLinkIOS,
+  // ExternalPurchaseCustomLink (iOS 18.1+)
+  isEligibleForExternalPurchaseCustomLinkIOS,
+  getExternalPurchaseCustomLinkTokenIOS,
+  showExternalPurchaseCustomLinkNoticeIOS,
 } from 'expo-iap';
 
 // Clear pending transactions
@@ -759,6 +763,25 @@ await beginRefundRequestIOS(transactionId);
 
 // Show subscription management
 await showManageSubscriptionsIOS();
+
+// ExternalPurchaseCustomLink (iOS 18.1+)
+// Check if eligible for custom external purchase links
+const isEligible = await isEligibleForExternalPurchaseCustomLinkIOS();
+
+if (isEligible) {
+  // Show disclosure notice before external link
+  const noticeResult = await showExternalPurchaseCustomLinkNoticeIOS('browser');
+  if (noticeResult.continued) {
+    // Get token for reporting to Apple
+    const tokenResult = await getExternalPurchaseCustomLinkTokenIOS('acquisition');
+    // tokenResult.token - report to Apple's External Purchase Server API
+    // tokenResult.error - error message if failed
+  }
+}
+
+// presentExternalPurchaseNoticeSheetIOS now returns token
+const result = await presentExternalPurchaseNoticeSheetIOS();
+// result.externalPurchaseToken - token to report to Apple
 ```
 
 ### Android-Specific

docs/static/llms.txt

@@ -337,6 +337,33 @@ const restore = async () => {
 await getAvailablePurchases({includeSuspendedAndroid: true});
 ```
 
+### iOS External Purchase Custom Link (iOS 18.1+)
+
+For apps with custom external purchase links entitlement:
+
+```tsx
+import {
+  isEligibleForExternalPurchaseCustomLinkIOS,
+  getExternalPurchaseCustomLinkTokenIOS,
+  showExternalPurchaseCustomLinkNoticeIOS,
+} from 'expo-iap';
+
+// Check eligibility
+const isEligible = await isEligibleForExternalPurchaseCustomLinkIOS();
+
+if (isEligible) {
+  // Show disclosure notice
+  const notice = await showExternalPurchaseCustomLinkNoticeIOS('browser');
+  if (notice.continued) {
+    // Get token for reporting to Apple
+    const result = await getExternalPurchaseCustomLinkTokenIOS('acquisition');
+    if (result.token) {
+      // Open external link and report to Apple's External Purchase Server API
+    }
+  }
+}
+```
+
 ### Check Active Subscriptions
 
 ```tsx

ios/ExpoIapModule.swift

@@ -415,5 +415,42 @@ public final class ExpoIapModule: Module {
             ExpoIapLog.result("getAppTransactionIOS", value: nil)
             return nil
         }
+
+        // MARK: - ExternalPurchaseCustomLink (iOS 18.1+)
+
+        AsyncFunction("isEligibleForExternalPurchaseCustomLinkIOS") { () async throws -> Bool in
+            ExpoIapLog.payload("isEligibleForExternalPurchaseCustomLinkIOS", payload: nil)
+            let isEligible = try await OpenIapModule.shared.isEligibleForExternalPurchaseCustomLinkIOS()
+            ExpoIapLog.result("isEligibleForExternalPurchaseCustomLinkIOS", value: isEligible)
+            return isEligible
+        }
+
+        AsyncFunction("getExternalPurchaseCustomLinkTokenIOS") { (tokenType: String) async throws -> [String: Any] in
+            ExpoIapLog.payload("getExternalPurchaseCustomLinkTokenIOS", payload: ["tokenType": tokenType])
+            guard let type = ExternalPurchaseCustomLinkTokenTypeIOS(rawValue: tokenType) else {
+                throw IapException.from(PurchaseError.make(
+                    code: .developerError,
+                    message: "Invalid token type: \(tokenType). Must be 'acquisition' or 'services'"
+                ))
+            }
+            let result = try await OpenIapModule.shared.getExternalPurchaseCustomLinkTokenIOS(type)
+            let sanitized = ExpoIapHelper.sanitizeDictionary(OpenIapSerialization.encode(result))
+            ExpoIapLog.result("getExternalPurchaseCustomLinkTokenIOS", value: sanitized)
+            return sanitized
+        }
+
+        AsyncFunction("showExternalPurchaseCustomLinkNoticeIOS") { (noticeType: String) async throws -> [String: Any] in
+            ExpoIapLog.payload("showExternalPurchaseCustomLinkNoticeIOS", payload: ["noticeType": noticeType])
+            guard let type = ExternalPurchaseCustomLinkNoticeTypeIOS(rawValue: noticeType) else {
+                throw IapException.from(PurchaseError.make(
+                    code: .developerError,
+                    message: "Invalid notice type: \(noticeType). Must be 'browser'"
+                ))
+            }
+            let result = try await OpenIapModule.shared.showExternalPurchaseCustomLinkNoticeIOS(type)
+            let sanitized = ExpoIapHelper.sanitizeDictionary(OpenIapSerialization.encode(result))
+            ExpoIapLog.result("showExternalPurchaseCustomLinkNoticeIOS", value: sanitized)
+            return sanitized
+        }
     }
 }

openiap-versions.json

@@ -1,5 +1,5 @@
 {
-  "apple": "1.3.13",
+  "apple": "1.3.14",
   "google": "1.3.27",
-  "gql": "1.3.15"
+  "gql": "1.3.16"
 }