@dodopayments/opencode-plugin 0.6.1 → 0.6.3

package/skills/mobile-checkout/SKILL.md

@@ -30,335 +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
+Covers:
 
-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':
-    // Sheet closed before the return URL arrived: the outcome is UNKNOWN and the
-    // payment may have succeeded. Do not show a failure - reconcile instead.
-    await reconcileAbandonedSession();
-    break;
-  case 'pending':
-    // Settles later (status=processing / requires_*), or status was missing.
-    await reconcileAbandonedSession();
-    break;
-  case 'expired':
-    // Checkout session expired. Prompt user to start a new checkout.
-    showExpired();
-    break;
-}
-```
-
-### Abandoned session recovery
-
-The SDK keeps a record of the session until checkout ends with `succeeded`, `failed`, or `expired`. The record survives an app kill and **stays after a `cancelled` or `pending` result**. Check it on the next launch and after every `cancelled`/`pending`:
-
-```typescript
-import { DodoCheckout } from '@dodopayments/react-native-checkout';
-
-async function reconcileAbandonedSession() {
-  const abandoned = await DodoCheckout.getAbandonedSession();
-  if (!abandoned) return;
-
-  // Your backend calls GET /checkouts/{abandoned.sessionId} and returns payment_status.
-  const outcome = await fetchCheckoutOutcome(abandoned.sessionId);
-  if (outcome === 'succeeded' || outcome === 'failed' || outcome === 'expired') {
-    showOutcome(outcome);
-    // Clear only once the outcome is final; until then treat it as pending, not failed.
-    await DodoCheckout.clearAbandonedSession();
-  } else {
-    showPending();
-  }
-}
-```
-
-### Android minSdk requirement
-
-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()));
-  });
-}
-```
+Full guide: [references/flutter.md](references/flutter.md).
 
-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.
+Covers:
 
-### 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>
-```
+- Installation
+- Setup
+- Starting checkout
+- Return URL registration
 
 ## 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)
-}
-```
+Full guide: [references/ios.md](references/ios.md).
 
-`handleOpenURL` returns `true` only for the in-progress checkout's return URL; handle other URLs yourself.
+Covers:
 
-### 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
-    }
-}
-```
+- Installation
+- Starting checkout
+- Forwarding the return URL
+- Abandoned sessions
 
 ## 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.
+Full guide: [references/android.md](references/android.md).
 
-### Installation
+Covers:
 
-```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
-    }
-}
-```
+- Installation
+- Starting checkout
+- Abandoned sessions
 
 ## Backend: Creating checkout sessions
 
@@ -553,7 +265,7 @@ If the app crashes or is backgrounded during checkout, the session is abandoned.
 
 // 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 the React Native section above
+await reconcileAbandonedSession(); // defined in references/react-native.md
 ```
 
 ## Package names

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
+    }
+}
+```

package/skills/mobile-checkout/references/react-native.md

@@ -0,0 +1,100 @@
+# Mobile In-App Checkout: React Native (Turbo Module)
+
+
+### Installation
+
+```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':
+    // Sheet closed before the return URL arrived: the outcome is UNKNOWN and the
+    // payment may have succeeded. Do not show a failure - reconcile instead.
+    await reconcileAbandonedSession();
+    break;
+  case 'pending':
+    // Settles later (status=processing / requires_*), or status was missing.
+    await reconcileAbandonedSession();
+    break;
+  case 'expired':
+    // Checkout session expired. Prompt user to start a new checkout.
+    showExpired();
+    break;
+}
+```
+
+### Abandoned session recovery
+
+The SDK keeps a record of the session until checkout ends with `succeeded`, `failed`, or `expired`. The record survives an app kill and **stays after a `cancelled` or `pending` result**. Check it on the next launch and after every `cancelled`/`pending`:
+
+```typescript
+import { DodoCheckout } from '@dodopayments/react-native-checkout';
+
+async function reconcileAbandonedSession() {
+  const abandoned = await DodoCheckout.getAbandonedSession();
+  if (!abandoned) return;
+
+  // Your backend calls GET /checkouts/{abandoned.sessionId} and returns payment_status.
+  const outcome = await fetchCheckoutOutcome(abandoned.sessionId);
+  if (outcome === 'succeeded' || outcome === 'failed' || outcome === 'expired') {
+    showOutcome(outcome);
+    // Clear only once the outcome is final; until then treat it as pending, not failed.
+    await DodoCheckout.clearAbandonedSession();
+  } else {
+    showPending();
+  }
+}
+```
+
+### Android minSdk requirement
+
+React Native checkout requires Android minSdk 24 or higher. Note: the general mobile documentation mentions minSdk 23, but React Native specifically requires 24.