@dodopayments/opencode-plugin 0.6.0 → 0.6.2

package/skills/mobile-checkout/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mobile-checkout
-description: Guide for implementing mobile in-app checkout with Dodo Payments across React Native, Flutter, iOS, and Android platforms.
+description: Dodo Payments in-app checkout for React Native, Flutter, native iOS, and Android using SFSafariViewController or Chrome Custom Tabs. Use when a mobile app must open a backend-created checkout session, handle deep link or custom URL scheme returns, recover abandoned checkouts, and verify payment server-side before unlocking access.
 ---
 
 # Mobile In-App Checkout
@@ -30,301 +30,47 @@ Your backend creates the checkout session and returns a URL. The mobile app open
 
 ## React Native (Turbo Module)
 
-### Installation
+Full guide: [references/react-native.md](references/react-native.md).
 
-```bash
-npm install @dodopayments/react-native-checkout
-```
-
-For Expo projects, add the plugin to `app.json`:
-
-```json
-{
-  "expo": {
-    "scheme": "myapp",
-    "plugins": [
-      [
-        "@dodopayments/react-native-checkout",
-        { "scheme": "myappcheckout" }
-      ]
-    ]
-  }
-}
-```
-
-The plugin registers a custom URL scheme (`myappcheckout://`) that the checkout flow uses to return to your app.
-
-### Setup
-
-Register the URL listener at app startup:
-
-```typescript
-import { Linking } from 'react-native';
-import { DodoCheckout } from '@dodopayments/react-native-checkout';
-
-// Required for iOS return-URL handling
-Linking.addEventListener('url', ({ url }) => DodoCheckout.handleOpenURL(url));
-```
-
-### Starting checkout
-
-```typescript
-const result = await DodoCheckout.start({
-  checkoutUrl: 'https://checkout.dodopayments.com/...',  // from your backend
-  returnUrl: 'myappcheckout://checkout/return',          // must match registered scheme
-  onEvent: (e) => console.log(e.type),                   // optional event logging
-});
-
-switch (result.status) {
-  case 'succeeded':
-    // Payment succeeded. Verify server-side before granting access.
-    await verifyPaymentOnBackend(result.paymentId);
-    showSuccess();
-    break;
-  case 'failed':
-    // Payment failed. Show error to user.
-    showFailure();
-    break;
-  case 'cancelled':
-    // User cancelled. Dismiss checkout.
-    dismiss();
-    break;
-  case 'pending':
-    // Payment is pending (e.g., awaiting 3D Secure). Show waiting state.
-    showPending();
-    break;
-  case 'expired':
-    // Checkout session expired. Prompt user to start a new checkout.
-    showExpired();
-    break;
-}
-```
-
-### Abandoned session recovery
-
-If the app crashes or is backgrounded during checkout, recover the session:
-
-```typescript
-import { DodoCheckout } from '@dodopayments/react-native-checkout';
-
-const abandoned = await DodoCheckout.getAbandonedSession();
-if (abandoned) {
-  // Reconcile abandoned.sessionId with your backend
-  // Decide whether to resume or start fresh
-  await DodoCheckout.clearAbandonedSession();
-}
-```
-
-### Android minSdk requirement
+Covers:
 
-React Native checkout requires Android minSdk 24 or higher. Note: the general mobile documentation mentions minSdk 23, but React Native specifically requires 24.
+- Installation
+- Setup
+- Starting checkout
+- Abandoned session recovery
+- Android minSdk requirement
 
 ## Flutter
 
-### Installation
-
-Add the Dodo Payments Flutter package to `pubspec.yaml`:
-
-```yaml
-dependencies:
-  dodopayments_checkout: ^1.0.2
-```
-
-### Setup
-
-The package uses `DodoCheckout.instance`. On iOS, register the return URL scheme and forward incoming links from your deep-link listener. Run `flutter pub add app_links` if you use the `app_links` approach shown here:
-
-```dart
-import 'dart:async';
-
-import 'package:app_links/app_links.dart';
-import 'package:dodopayments_checkout/dodopayments_checkout.dart';
-
-late final StreamSubscription<Uri> checkoutLinkSubscription;
-
-void listenForCheckoutReturns() {
-  checkoutLinkSubscription = AppLinks().uriLinkStream.listen((uri) {
-    unawaited(DodoCheckout.instance.handleOpenURL(uri.toString()));
-  });
-}
-```
-
-Start the listener from your root state object's `initState` and cancel `checkoutLinkSubscription` from `dispose`. `handleOpenURL` is required on iOS and safely returns `false` on Android.
+Full guide: [references/flutter.md](references/flutter.md).
 
-### Starting checkout
+Covers:
 
-```dart
-import 'package:dodopayments_checkout/dodopayments_checkout.dart';
-
-final result = await DodoCheckout.instance.start(
-  CheckoutParams(
-    checkoutUrl: Uri.parse('https://checkout.dodopayments.com/...'),
-    returnUrl: Uri.parse('myapp://checkout/return'),
-    onEvent: (event) => print(event.type),
-  ),
-);
-
-switch (result.status) {
-  case CheckoutStatus.succeeded:
-    final paymentId = result.paymentId;
-    if (paymentId != null) {
-      await verifyPaymentOnBackend(paymentId);
-    }
-    showSuccess();
-    break;
-  case CheckoutStatus.failed:
-    showFailure();
-    break;
-  case CheckoutStatus.cancelled:
-    dismiss();
-    break;
-  case CheckoutStatus.pending:
-    showPending();
-    break;
-  case CheckoutStatus.expired:
-    showExpired();
-    break;
-}
-```
-
-### Return URL registration
-
-On Android, set the callback scheme in `android/app/build.gradle.kts`. The package's native checkout dependency supplies the intent filter, so do not add one manually:
-
-```kotlin
-android {
-  defaultConfig {
-    minSdk = 23
-    manifestPlaceholders["dodoCallbackScheme"] = "myapp"
-  }
-}
-```
-
-Remove an empty `android:taskAffinity=""` from `MainActivity` if the generated Flutter manifest contains it; it can prevent Custom Tabs from returning correctly on some devices.
-
-On iOS, register the same scheme in `ios/Runner/Info.plist`:
-
-```xml
-<key>CFBundleURLTypes</key>
-<array>
-  <dict>
-    <key>CFBundleURLSchemes</key>
-    <array>
-      <string>myapp</string>
-    </array>
-  </dict>
-</array>
-```
+- Installation
+- Setup
+- Starting checkout
+- Return URL registration
 
 ## iOS (native)
 
-### Setup
-
-Use `SFSafariViewController` to open the checkout URL:
-
-```swift
-import SafariServices
-
-let checkoutURL = URL(string: "https://checkout.dodopayments.com/...")!
-let safariVC = SFSafariViewController(url: checkoutURL)
-present(safariVC, animated: true)
-```
-
-### Deep-link handling
+Full guide: [references/ios.md](references/ios.md).
 
-Register your custom URL scheme in `Info.plist`:
+Covers:
 
-```xml
-<key>CFBundleURLTypes</key>
-<array>
-  <dict>
-    <key>CFBundleURLSchemes</key>
-    <array>
-      <string>myapp</string>
-    </array>
-  </dict>
-</array>
-```
-
-Handle the return in your app delegate:
-
-```swift
-func application(
-  _ app: UIApplication,
-  open url: URL,
-  options: [UIApplication.OpenURLOptionsKey: Any] = [:]
-) -> Bool {
-  if url.scheme == "myapp" && url.host == "checkout" {
-    // Parse the result from the URL query parameters
-    let components = URLComponents(url: url, resolvingAgainstBaseURL: false)
-    let status = components?.queryItems?.first(where: { $0.name == "status" })?.value
-    
-    switch status {
-    case "succeeded":
-      let paymentId = components?.queryItems?.first(where: { $0.name == "payment_id" })?.value
-      verifyPaymentOnBackend(paymentId: paymentId)
-    case "cancelled":
-      dismiss()
-    case "expired":
-      showExpired()
-    default:
-      break
-    }
-    return true
-  }
-  return false
-}
-```
+- Installation
+- Starting checkout
+- Forwarding the return URL
+- Abandoned sessions
 
 ## Android (native)
 
-### Setup
-
-Use Chrome Custom Tabs to open the checkout URL:
+Full guide: [references/android.md](references/android.md).
 
-```kotlin
-import androidx.browser.customtabs.CustomTabsIntent
-import android.net.Uri
+Covers:
 
-val checkoutUri = Uri.parse("https://checkout.dodopayments.com/...")
-val customTabsIntent = CustomTabsIntent.Builder().build()
-customTabsIntent.launchUrl(context, checkoutUri)
-```
-
-### Deep-link handling
-
-Register your custom URL scheme in `AndroidManifest.xml`:
-
-```xml
-<activity android:name=".CheckoutReturnActivity">
-  <intent-filter>
-    <action android:name="android.intent.action.VIEW" />
-    <category android:name="android.intent.category.DEFAULT" />
-    <category android:name="android.intent.category.BROWSABLE" />
-    <data android:scheme="myapp" android:host="checkout" android:path="/return" />
-  </intent-filter>
-</activity>
-```
-
-Handle the return in your activity:
-
-```kotlin
-override fun onCreate(savedInstanceState: Bundle?) {
-  super.onCreate(savedInstanceState)
-  
-  val uri = intent.data
-  if (uri?.scheme == "myapp" && uri.host == "checkout") {
-    val status = uri.getQueryParameter("status")
-    val paymentId = uri.getQueryParameter("payment_id")
-    
-    when (status) {
-      "succeeded" -> verifyPaymentOnBackend(paymentId)
-      "cancelled" -> dismiss()
-      "expired" -> showExpired()
-    }
-  }
-}
-```
+- Installation
+- Starting checkout
+- Abandoned sessions
 
 ## Backend: Creating checkout sessions
 
@@ -372,23 +118,40 @@ Never grant access based on the mobile SDK result alone. Always verify via webho
 Listen for `payment.succeeded` webhooks. Webhook signature verification is covered in the `webhook-integration` skill.
 
 ```typescript
+// Mount with express.raw({ type: 'application/json' }) so req.body is the raw Buffer.
 app.post('/webhook', async (req, res) => {
-  const event = client.webhooks.unwrap(req.body.toString(), {
-    headers: {
-      'webhook-id': req.headers['webhook-id'] as string,
-      'webhook-signature': req.headers['webhook-signature'] as string,
-      'webhook-timestamp': req.headers['webhook-timestamp'] as string,
-    },
-  });
-  
-  if (event.type === 'payment.succeeded') {
-    const paymentId = event.data.payment_id;
-    const customerId = event.data.customer.customer_id;
-    
-    // Grant access to the customer
-    await grantAccess(customerId);
+  let event;
+  try {
+    event = client.webhooks.unwrap(req.body.toString(), {
+      headers: {
+        'webhook-id': req.headers['webhook-id'] as string,
+        'webhook-signature': req.headers['webhook-signature'] as string,
+        'webhook-timestamp': req.headers['webhook-timestamp'] as string,
+      },
+    });
+  } catch {
+    return res.status(401).json({ error: 'Invalid signature' });
   }
-  
+
+  try {
+    // Dodo retries and may redeliver: claim webhook-id with a UNIQUE insert
+    // and grant in the same transaction so a duplicate is a no-op.
+    await db.$transaction(async (tx) => {
+      const claim = await tx.webhookLog.createMany({
+        data: [{ webhookId: req.headers['webhook-id'] as string, eventType: event.type }],
+        skipDuplicates: true,
+      });
+      if (claim.count === 0) return; // already processed
+
+      if (event.type === 'payment.succeeded') {
+        await grantAccess(event.data.customer.customer_id, tx);
+      }
+    });
+  } catch (error) {
+    // Non-2xx makes Dodo retry; the transaction rolled back the claim.
+    return res.status(500).json({ error: 'Processing failed' });
+  }
+
   res.json({ received: true });
 });
 ```
@@ -408,13 +171,14 @@ if (session.payment_status === 'succeeded' && session.payment_id) {
 
 ## Selling digital goods on iOS
 
-If you're selling digital goods (software, in-app features, subscriptions) on iOS, Apple requires you to use in-app purchase APIs for certain categories. Dodo Payments can handle the payment processing, but you must comply with App Store guidelines:
+Dodo Payments hosted checkout can sell digital goods (subscriptions, courses, downloads, SaaS plans) in an iOS app **only on App Store storefronts where Apple allows external purchases**:
 
-- Digital content (ebooks, music, software) must use in-app purchase.
-- Physical goods and services can use alternative payment methods.
-- Subscriptions for digital content must use in-app purchase.
+- **United States:** Guideline 3.1.1(a) allows buttons and links to other purchase methods without an entitlement (subject to the Epic v. Apple proceedings).
+- **European Union:** requires Apple's EU external purchase entitlement (the StoreKit External Purchases or Offers Entitlement from October 1, 2026) and DMA compliance.
+- **Japan:** allowed under the Mobile Software Competition Act, following Apple's Japan-specific entitlement requirements.
+- **South Korea is not supported** (Apple requires a native, non-web-view flow through an approved Korean PSP).
 
-Consult Apple's App Store Review Guidelines and consider whether your product category requires in-app purchase. If it does, integrate StoreKit 2 alongside Dodo Payments for compliance.
+On other storefronts, digital goods sold inside the iOS app must use Apple in-app purchase (StoreKit). Review Apple's region-specific entitlements before enabling Dodo checkout for a storefront; unsupported flows can get the app rejected.
 
 ## Common mistakes
 
@@ -459,8 +223,8 @@ If you don't register the custom URL scheme, the app won't receive the return ca
 
 - React Native: Use the Expo plugin or manually register in `Info.plist` and `AndroidManifest.xml`.
 - Flutter: Register in both `Info.plist` and `AndroidManifest.xml`.
-- iOS: Add `CFBundleURLTypes` to `Info.plist`.
-- Android: Add an intent filter with the scheme in `AndroidManifest.xml`.
+- iOS: Add `CFBundleURLTypes` to `Info.plist` and forward URLs to `DodoCheckout.handleOpenURL`.
+- Android: Set `manifestPlaceholders["dodoCallbackScheme"]`; the SDK supplies the intent filter.
 
 ### Not handling all result statuses
 
@@ -481,10 +245,9 @@ switch (result.status) {
     showFailure();
     break;
   case 'cancelled':
-    dismiss();
-    break;
   case 'pending':
-    showPending();
+    // Unknown outcome - reconcile, never show a failure
+    reconcileAbandonedSession();
     break;
   case 'expired':
     showExpired();
@@ -500,12 +263,9 @@ If the app crashes or is backgrounded during checkout, the session is abandoned.
 // WRONG
 // No recovery logic
 
-// CORRECT
-const abandoned = await DodoCheckout.getAbandonedSession();
-if (abandoned) {
-  // Reconcile and clear
-  await DodoCheckout.clearAbandonedSession();
-}
+// CORRECT: reconcile on launch and after every cancelled/pending result,
+// and clear the record only once the backend reports a final outcome.
+await reconcileAbandonedSession(); // defined in references/react-native.md
 ```
 
 ## Package names
@@ -516,6 +276,8 @@ Use `@dodopayments/react-native-checkout` for React Native and `dodopayments_che
 
 - [Mobile Integration](https://docs.dodopayments.com/developer-resources/mobile-integration)
 - [React Native SDK](https://docs.dodopayments.com/developer-resources/sdks/react-native)
+- [iOS SDK](https://docs.dodopayments.com/developer-resources/sdks/ios)
+- [Android SDK](https://docs.dodopayments.com/developer-resources/sdks/android)
 - [Flutter SDK](https://pub.dev/packages/dodopayments_checkout)
 - [Selling Digital Goods on iOS](https://docs.dodopayments.com/features/appstore-digital-goods)
 - [Webhook Integration](https://docs.dodopayments.com/developer-resources/webhooks/intents) (for payment verification)

package/skills/mobile-checkout/references/android.md

@@ -0,0 +1,69 @@
+# Mobile In-App Checkout: Android (native)
+
+
+Use the official Android checkout SDK (`minSdk` 23, Kotlin, Java 17). It opens Chrome Custom Tabs, declares the redirect intent filter itself, and returns a typed result.
+
+### Installation
+
+```kotlin
+// app/build.gradle.kts
+dependencies {
+    implementation("com.dodopayments.api:checkout-android:1.1.0")
+}
+
+android {
+    defaultConfig {
+        // The SDK's manifest uses this placeholder; do not add an intent filter yourself.
+        manifestPlaceholders["dodoCallbackScheme"] = "myapp"
+    }
+}
+```
+
+### Starting checkout
+
+```kotlin
+import com.dodopayments.checkout.CheckoutParams
+import com.dodopayments.checkout.CheckoutStatus
+import com.dodopayments.checkout.DodoCheckout
+import androidx.lifecycle.lifecycleScope
+import kotlinx.coroutines.launch
+
+// The activity-result launcher survives process death.
+private val checkoutLauncher =
+    registerForActivityResult(DodoCheckout.contract()) { result ->
+        when (result.status) {
+            CheckoutStatus.SUCCEEDED -> showSuccess(result.paymentId) // UI hint only; verify on the backend
+            CheckoutStatus.FAILED -> showFailure()
+            // Outcome unknown, not a failure. reconcileAbandonedSession() suspends
+            // (it calls your backend), so launch it from the lifecycle scope.
+            CheckoutStatus.CANCELLED, CheckoutStatus.PENDING ->
+                lifecycleScope.launch { reconcileAbandonedSession() }
+            CheckoutStatus.EXPIRED -> showExpired()
+        }
+    }
+
+checkoutLauncher.launch(
+    CheckoutParams(
+        checkoutUrl = checkoutUrl, // from your backend's checkout session
+        returnUrl = "myapp://checkout/return"
+    )
+)
+```
+
+### Abandoned sessions
+
+```kotlin
+suspend fun reconcileAbandonedSession() {
+    val abandoned = DodoCheckout.getAbandonedSession(context) ?: return
+
+    // Your backend calls GET /checkouts/{sessionId} and returns payment_status.
+    when (val outcome = fetchCheckoutOutcome(abandoned.sessionId)) {
+        "succeeded", "failed", "expired" -> {
+            showOutcome(outcome)
+            // Clear only once the outcome is final.
+            DodoCheckout.clearAbandonedSession(context)
+        }
+        else -> showPending() // still pending - keep the record and check again later
+    }
+}
+```

package/skills/mobile-checkout/references/flutter.md

@@ -0,0 +1,97 @@
+# Mobile In-App Checkout: Flutter
+
+
+### Installation
+
+Add the Dodo Payments Flutter package to `pubspec.yaml`:
+
+```yaml
+dependencies:
+  dodopayments_checkout: ^1.0.2
+```
+
+### Setup
+
+The package uses `DodoCheckout.instance`. On iOS, register the return URL scheme and forward incoming links from your deep-link listener. Run `flutter pub add app_links` if you use the `app_links` approach shown here:
+
+```dart
+import 'dart:async';
+
+import 'package:app_links/app_links.dart';
+import 'package:dodopayments_checkout/dodopayments_checkout.dart';
+
+late final StreamSubscription<Uri> checkoutLinkSubscription;
+
+void listenForCheckoutReturns() {
+  checkoutLinkSubscription = AppLinks().uriLinkStream.listen((uri) {
+    unawaited(DodoCheckout.instance.handleOpenURL(uri.toString()));
+  });
+}
+```
+
+Start the listener from your root state object's `initState` and cancel `checkoutLinkSubscription` from `dispose`. `handleOpenURL` is required on iOS and safely returns `false` on Android.
+
+### Starting checkout
+
+```dart
+import 'package:dodopayments_checkout/dodopayments_checkout.dart';
+
+final result = await DodoCheckout.instance.start(
+  CheckoutParams(
+    checkoutUrl: Uri.parse('https://checkout.dodopayments.com/...'),
+    returnUrl: Uri.parse('myapp://checkout/return'),
+    onEvent: (event) => print(event.type),
+  ),
+);
+
+switch (result.status) {
+  case CheckoutStatus.succeeded:
+    final paymentId = result.paymentId;
+    if (paymentId != null) {
+      await verifyPaymentOnBackend(paymentId);
+    }
+    showSuccess();
+    break;
+  case CheckoutStatus.failed:
+    showFailure();
+    break;
+  case CheckoutStatus.cancelled:
+  case CheckoutStatus.pending:
+    // Outcome unknown (the payment may have succeeded): reconcile the
+    // abandoned session with your backend instead of showing a failure.
+    await reconcileAbandonedSession();
+    break;
+  case CheckoutStatus.expired:
+    showExpired();
+    break;
+}
+```
+
+### Return URL registration
+
+On Android, set the callback scheme in `android/app/build.gradle.kts`. The package's native checkout dependency supplies the intent filter, so do not add one manually:
+
+```kotlin
+android {
+  defaultConfig {
+    minSdk = 23
+    manifestPlaceholders["dodoCallbackScheme"] = "myapp"
+  }
+}
+```
+
+Remove an empty `android:taskAffinity=""` from `MainActivity` if the generated Flutter manifest contains it; it can prevent Custom Tabs from returning correctly on some devices.
+
+On iOS, register the same scheme in `ios/Runner/Info.plist`:
+
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>myapp</string>
+    </array>
+  </dict>
+</array>
+```

package/skills/mobile-checkout/references/ios.md

@@ -0,0 +1,66 @@
+# Mobile In-App Checkout: iOS (native)
+
+
+Use the official Swift package rather than parsing the return URL yourself. It presents `SFSafariViewController`, matches the return URL, and maps `status` (including `active` for subscriptions and `processing`/`requires_*` as pending) into a typed result. Requires iOS 16+ and Swift 6.2+.
+
+### Installation
+
+Add `https://github.com/dodopayments/dodopayments-mobile-sdk-ios` (1.1.0 or later) in **File → Add Package Dependencies**, or in `Package.swift`:
+
+```swift
+.package(url: "https://github.com/dodopayments/dodopayments-mobile-sdk-ios", from: "1.1.0")
+```
+
+The library product is `DodoCheckout`. Register your scheme (`myapp`) under `CFBundleURLTypes` in `Info.plist`, and use the same URL as the session's `return_url`.
+
+### Starting checkout
+
+```swift
+import DodoCheckout
+
+let result = try await DodoCheckout.start(
+    checkoutUrl: checkoutUrl,   // URL from your backend's checkout session
+    returnUrl: URL(string: "myapp://checkout/return")!,
+    onEvent: { event in print(event.name) }  // logging only
+)
+
+switch result.status {
+case .succeeded: showSuccess(result.paymentId)          // UI hint only; verify on the backend
+case .failed:    showFailure()
+case .cancelled: await reconcileAbandonedSession()      // outcome unknown, not a failure
+case .pending:   await reconcileAbandonedSession()
+case .expired:   showExpired()
+}
+```
+
+### Forwarding the return URL
+
+`SFSafariViewController` cannot catch its own return URL, so forward every incoming URL to the SDK:
+
+```swift
+// SwiftUI
+.onOpenURL { url in
+    DodoCheckout.handleOpenURL(url)
+}
+```
+
+`handleOpenURL` returns `true` only for the in-progress checkout's return URL; handle other URLs yourself.
+
+### Abandoned sessions
+
+```swift
+func reconcileAbandonedSession() async {
+    guard let abandoned = DodoCheckout.getAbandonedSession() else { return }
+
+    // Your backend calls GET /checkouts/{sessionId} and returns payment_status.
+    let outcome = await fetchCheckoutOutcome(abandoned.sessionId)
+    switch outcome {
+    case "succeeded", "failed", "expired":
+        showOutcome(outcome)
+        // Clear only once the outcome is final.
+        DodoCheckout.clearAbandonedSession()
+    default:
+        showPending() // still pending - keep the record and check again later
+    }
+}
+```