@dodopayments/opencode-plugin 0.5.1 → 0.6.1

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
@@ -86,12 +86,13 @@ switch (result.status) {
     showFailure();
     break;
   case 'cancelled':
-    // User cancelled. Dismiss checkout.
-    dismiss();
+    // 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':
-    // Payment is pending (e.g., awaiting 3D Secure). Show waiting state.
-    showPending();
+    // Settles later (status=processing / requires_*), or status was missing.
+    await reconcileAbandonedSession();
     break;
   case 'expired':
     // Checkout session expired. Prompt user to start a new checkout.
@@ -102,16 +103,24 @@ switch (result.status) {
 
 ### Abandoned session recovery
 
-If the app crashes or is backgrounded during checkout, recover the session:
+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';
 
-const abandoned = await DodoCheckout.getAbandonedSession();
-if (abandoned) {
-  // Reconcile abandoned.sessionId with your backend
-  // Decide whether to resume or start fresh
-  await DodoCheckout.clearAbandonedSession();
+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();
+  }
 }
 ```
 
@@ -176,10 +185,10 @@ switch (result.status) {
     showFailure();
     break;
   case CheckoutStatus.cancelled:
-    dismiss();
-    break;
   case CheckoutStatus.pending:
-    showPending();
+    // 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();
@@ -218,111 +227,136 @@ On iOS, register the same scheme in `ios/Runner/Info.plist`:
 
 ## iOS (native)
 
-### Setup
+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+.
 
-Use `SFSafariViewController` to open the checkout URL:
+### 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
-import SafariServices
+.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`.
 
-let checkoutURL = URL(string: "https://checkout.dodopayments.com/...")!
-let safariVC = SFSafariViewController(url: checkoutURL)
-present(safariVC, animated: true)
+### 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()
+}
 ```
 
-### Deep-link handling
+### Forwarding the return URL
 
-Register your custom URL scheme in `Info.plist`:
+`SFSafariViewController` cannot catch its own return URL, so forward every incoming URL to the SDK:
 
-```xml
-<key>CFBundleURLTypes</key>
-<array>
-  <dict>
-    <key>CFBundleURLSchemes</key>
-    <array>
-      <string>myapp</string>
-    </array>
-  </dict>
-</array>
+```swift
+// SwiftUI
+.onOpenURL { url in
+    DodoCheckout.handleOpenURL(url)
+}
 ```
 
-Handle the return in your app delegate:
+`handleOpenURL` returns `true` only for the in-progress checkout's return URL; handle other URLs yourself.
+
+### Abandoned sessions
 
 ```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()
+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:
-      break
+        showPending() // still pending - keep the record and check again later
     }
-    return true
-  }
-  return false
 }
 ```
 
 ## Android (native)
 
-### Setup
+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.
 
-Use Chrome Custom Tabs to open the checkout URL:
+### Installation
 
 ```kotlin
-import androidx.browser.customtabs.CustomTabsIntent
-import android.net.Uri
+// app/build.gradle.kts
+dependencies {
+    implementation("com.dodopayments.api:checkout-android:1.1.0")
+}
 
-val checkoutUri = Uri.parse("https://checkout.dodopayments.com/...")
-val customTabsIntent = CustomTabsIntent.Builder().build()
-customTabsIntent.launchUrl(context, checkoutUri)
+android {
+    defaultConfig {
+        // The SDK's manifest uses this placeholder; do not add an intent filter yourself.
+        manifestPlaceholders["dodoCallbackScheme"] = "myapp"
+    }
+}
 ```
 
-### Deep-link handling
+### Starting checkout
 
-Register your custom URL scheme in `AndroidManifest.xml`:
+```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()
+        }
+    }
 
-```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>
+checkoutLauncher.launch(
+    CheckoutParams(
+        checkoutUrl = checkoutUrl, // from your backend's checkout session
+        returnUrl = "myapp://checkout/return"
+    )
+)
 ```
 
-Handle the return in your activity:
+### Abandoned sessions
 
 ```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()
+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
     }
-  }
 }
 ```
 
@@ -372,23 +406,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 +459,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 +511,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 +533,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 +551,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 the React Native section above
 ```
 
 ## Package names
@@ -516,6 +564,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/product-catalog-management/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: product-catalog-management
-description: Guide for creating and managing products, pricing, add-ons, product collections, images, and digital product delivery
+description: Dodo Payments product catalog management, covering products with one_time_price, recurring_price, or usage_based_price, add-ons, product collections, product images, and digital file delivery. Use when creating or updating products, plans, or prices, building a storefront, uploading images, attaching downloadable files, or debugging a failed product update.
 ---
 
 # Product Catalog Management
@@ -13,7 +13,7 @@ This skill covers the full product lifecycle: creating products with pricing mod
 - You're building a product collection or storefront.
 - You need to upload product images or deliver digital files to customers.
 - You're managing add-ons or product variants.
-- You need to understand why a product update failed or why pricing can't be changed.
+- You need to understand why a product update failed or how to change a product's pricing.
 
 ## Core concepts
 
@@ -36,7 +36,7 @@ Pricing is nested inside the product object. There is no separate top-level Pric
 
 **Lifecycle:** Products support `list`, `retrieve`, `update`, and `archive`/`unarchive`. There is no delete endpoint. Archived products remain in your history but don't appear in new checkouts.
 
-**Images:** Presigned upload URLs expire after 60 seconds. Download the URL immediately after requesting it.
+**Images:** Presigned upload URLs expire after 60 seconds. Upload to the URL immediately after requesting it.
 
 **Digital delivery:** Entitlements grant customers access to files. Download URLs expire after roughly 15 minutes.
 
@@ -129,7 +129,9 @@ const product = await client.products.retrieve('pdt_pro_bundle');
 
 ## Updating a product
 
-You can update the name, description, and metadata. You cannot change the pricing model or price of a live product. Create a new product instead.
+`PATCH /products/{id}` (`client.products.update`) accepts the name, description, and metadata, and also `price`, `tax_category`, and `pricing_mode`. Every field is optional; omitted fields stay unchanged.
+
+Two limits apply. The **pricing model is immutable**: you can edit the amount, but you cannot turn a one-time product into a subscription or usage-based one (or back) - create a new product instead. And a price edit only changes what **new** customers pay: existing subscriptions keep the price they were created with, so move them explicitly with Change Plan (`client.subscriptions.changePlan(...)`).
 
 ```typescript
 await client.products.update('pdt_pro_bundle', {
@@ -226,14 +228,25 @@ await client.productCollections.groups.create(collection.id, {
   ],
 });
 
-// Checkout with a collection
-const session = await client.checkoutSessions.create({
-  product_collection_id: collection.id,
-  product_cart: [], // Required: pass an empty array for collection checkout
-  return_url: 'https://yoursite.com/return',
-});
+// Server route (e.g. POST /api/checkout): create the checkout session and return its URL
+export async function POST() {
+  const session = await client.checkoutSessions.create({
+    product_collection_id: collection.id,
+    product_cart: [], // Required: pass an empty array for collection checkout
+    return_url: 'https://yoursite.com/return',
+  });
 
-window.location.href = session.checkout_url;
+  return Response.json({ checkout_url: session.checkout_url });
+}
+```
+
+Never call the SDK or expose the API key in browser code. The browser only receives the URL from your server route and redirects:
+
+```typescript
+// Browser
+const res = await fetch('/api/checkout', { method: 'POST' });
+const { checkout_url } = (await res.json()) as { checkout_url: string };
+window.location.href = checkout_url;
 ```
 
 ## Digital product delivery
@@ -241,6 +254,9 @@ window.location.href = session.checkout_url;
 Entitlements grant customers access to downloadable files. Create an entitlement, upload files, and generate download links.
 
 ```typescript
+// openAsBlob requires Node.js 20 or later
+import { openAsBlob } from 'node:fs';
+
 // Create an entitlement
 const entitlement = await client.entitlements.create({
   name: 'Pro Bundle Files',
@@ -250,10 +266,15 @@ const entitlement = await client.entitlements.create({
   },
 });
 
-// Upload and attach a file; the response identifies the attached file
-const { file_id } = await client.entitlements.files.upload(entitlement.id);
+// Upload and attach a file as multipart/form-data (append `filename` before `file`)
+const form = new FormData();
+form.append('filename', 'pro-bundle.zip');
+form.append('file', await openAsBlob('./pro-bundle.zip'), 'pro-bundle.zip');
+const { file_id } = await client.entitlements.files.upload(entitlement.id, { body: form });
 
-// Attach the entitlement to a product
+// Attach the entitlement to a product.
+// `entitlements` REPLACES every entitlement already attached to the product:
+// include all of them, send [] to remove all, or omit the field to leave them unchanged.
 await client.products.update('pdt_pro_bundle', {
   entitlements: [{ entitlement_id: entitlement.id }],
 });
@@ -290,7 +311,9 @@ For country or currency-specific pricing, use the `localized-pricing` skill. Do
 
 **Expecting a delete endpoint:** Products don't have a delete method. Archive them instead. Archived products remain in your history for reconciliation.
 
-**Trying to change the pricing model:** Once a product is created with `one_time_price`, you can't change it to `recurring_price`. Create a new product and migrate customers to it.
+**Trying to change the pricing model:** You cannot switch a product between one-time, subscription, and usage-based pricing (for example `one_time_price` to `recurring_price`). Create a new product with the model you need.
+
+**Expecting a price edit to reprice existing subscribers:** `client.products.update(...)` changes the amount for new customers only. Existing subscriptions renew at the price they were created with; move them with `client.subscriptions.changePlan(...)`.
 
 **Hardcoding prices in the client:** Always fetch the product catalog from the API. Prices change, and your client code will become stale. Read `client.products.retrieve(id)` to get the current price.
 
@@ -300,7 +323,7 @@ For country or currency-specific pricing, use the `localized-pricing` skill. Do
 
 **Passing a non-empty product_cart for collection checkout:** Collection checkout requires `product_cart: []`. The collection itself defines what's in the cart.
 
-**Confusing purchasing_power_parity with localized pricing:** The OpenAPI schema includes a `purchasing_power_parity` field in examples, but it's marked unavailable. Use the `localized-pricing` skill for country and currency pricing instead.
+**Confusing purchasing_power_parity with localized pricing:** PPP is native. Set `price.purchasing_power_parity: true` to charge a business-wide, per-country percentage of the price (default `false`). It requires Adaptive Currency to be enabled, and a matching localized price always wins over PPP. See the `localized-pricing` skill.
 
 ## Resources