ci: switch to macos-14 + Xcode 15.4, add troubleshooting docs

macOS-15 + Xcode 16.2 fails with "iOS 18.2 Platform Not Installed"
on storyboard compilation (same issue as Cordova iOS builds).

Also add TROUBLESHOOTING.md (for users) and CONTRIBUTING.md (for
contributors) documenting iOS build requirements and known issues.

Author: j3k0

.github/workflows/build-capacitor-ios.yml

@@ -8,15 +8,15 @@ on:
 
 jobs:
   build:
-    runs-on: macos-15
+    runs-on: macos-14
     strategy:
       fail-fast: false
       matrix:
         include:
           - capacitor-version: '6'
-            xcode-version: '16.2'
+            xcode-version: '15.4'
           - capacitor-version: '7'
-            xcode-version: '16.2'
+            xcode-version: '15.4'
     steps:
       - uses: actions/checkout@v4
 

capacitor/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing
+
+## Podspec naming convention
+
+Capacitor CLI derives the CocoaPods pod name from the npm package name:
+
+```
+npm: capacitor-plugin-cdv-purchase → pod: CapacitorPluginCdvPurchase
+```
+
+The podspec filename and `s.name` must match this derived name exactly. A mismatch causes "No podspec found" during `pod install`.
+
+There are two podspecs:
+- `CapacitorPluginCdvPurchase.podspec` — root-level, used by Capacitor CLI (paths relative to package root)
+- `ios/CapacitorPluginPurchase.podspec` — legacy (paths relative to `ios/`)
+
+## iOS availability guards
+
+The plugin targets iOS 15.0 but some APIs require newer versions:
+
+- `AppTransaction.shared` — requires `#available(iOS 16.0, *)`
+- `AppStore.presentOfferCodeRedeemSheet` — requires `#available(iOS 16.0, *)`
+- `Locale.region` — requires `#available(iOS 16.0, *)`
+
+Always wrap these in availability checks with a fallback.
+
+## SPM (Swift Package Manager) compatibility
+
+The plugin builds with CocoaPods. SPM support is provided via `Package.swift` but has known limitations with Capacitor's precompiled xcframework.
+
+### The problem
+
+Capacitor distributes its iOS framework as a precompiled `.xcframework` via `capacitor-swift-pm`. Swift extension methods on Objective-C types are not exported from binary frameworks. This means common Capacitor APIs are invisible when built via SPM:
+
+| API | SPM status | Workaround |
+|-----|-----------|------------|
+| `call.resolve()` | Works | (zero-arg overload) |
+| `call.resolve(data)` | Works | |
+| `call.reject(msg)` | Not available | None reliable — method is invisible |
+| `call.getString("key")` | Not available | `call.options["key"] as? String` |
+| `call.getArray("key")` | Not available | `call.options["key"] as? [Type]` |
+| `call.getBool("key")` | Not available | `call.getBool("key", false)` |
+| `CAPPluginCallError(...)` | Not available | Init is inaccessible |
+
+### Impact
+
+This is a Capacitor-level issue affecting **all** third-party plugins, not specific to this one. It needs to be resolved upstream in `ionic-team/capacitor` by either shipping source via SPM instead of precompiled binaries, or moving APIs to ObjC headers. SPM became the default in Capacitor 8.
+
+### CI strategy
+
+The CI tests against Capacitor 6 and 7 using CocoaPods (the default for those versions). Once the upstream SPM issue is resolved, Capacitor 8 can be added to the test matrix.
+
+## CI environment notes
+
+- **macOS-15 + Xcode 16.2** may report "no destinations" with `-sdk iphoneos`. Use `-destination 'generic/platform=iOS'` instead.
+- **`@capacitor/create-app`** always scaffolds the latest template (Cap 8 / SPM) regardless of CLI version. For testing older versions, scaffold manually with `npm init` + pinned deps.
+- **Ruby version conflicts** on macOS: `pod` (Homebrew) and `gem` (system) may point to different Ruby versions. Install gems with the Homebrew Ruby if needed.

capacitor/TROUBLESHOOTING.md

@@ -0,0 +1,45 @@
+# Troubleshooting
+
+## iOS requires minimum deployment target 15.0
+
+This plugin uses **StoreKit 2**, which requires **iOS 15.0**. Capacitor 6 and 7 generate Podfiles with a lower default. Open `ios/App/Podfile` and update:
+
+```ruby
+# Change this:
+platform :ios, '13.0'
+# To this:
+platform :ios, '15.0'
+```
+
+Then run `npx cap sync ios`.
+
+## "No podspec found for CapacitorPluginCdvPurchase"
+
+Make sure you're on the latest version of the plugin. If you're using a local path (`file:../path`), verify the podspec exists at the plugin package root.
+
+## Different bundle IDs on iOS and Android
+
+Capacitor does not support per-platform `appId` in `capacitor.config.json` — it's a single global value. If your iOS and Android apps have different bundle IDs, you'll need to change `appId` when switching platforms, or use Xcode schemes (iOS) / product flavors (Android) for overrides.
+
+## Testing on Mac (Catalyst)
+
+To test on your Mac without a physical device:
+
+1. `npx cap open ios`
+2. In Xcode, select your Mac as the destination ("My Mac (Designed for iPad)" or "My Mac (Mac Catalyst)")
+3. Set your signing team and build
+
+This works for testing the purchase flow with sandbox accounts.
+
+## Capacitor 8 / SPM support
+
+Capacitor 8 defaults to Swift Package Manager (SPM). There is a known upstream issue where the Capacitor precompiled xcframework does not export certain Swift extension methods to plugins. This affects all third-party Capacitor plugins, not just this one.
+
+**If you hit build errors with Capacitor 8**, use CocoaPods instead:
+
+```bash
+# Remove the iOS project and recreate with CocoaPods
+rm -rf ios
+npx cap add ios --packagemanager CocoaPods
+npx cap sync ios
+```