Docs: add Expo integration and purchase/subscription guidance

skills/qonversion-react-native/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: qonversion-react-native
+description: Integrate, debug, or migrate Qonversion SDK in React Native and Expo apps, including setup, initialization, offerings/products fetch, purchase/restore flows, entitlement checks, user identify/logout mapping, and major-version API migration handling. Use when tasks mention @qonversion/react-native-sdk, react-native-qonversion, subscriptions, entitlements, paywalls, App Store/Google Play purchases, or Expo prebuild/dev-client requirements.
+---
+
+# Qonversion React Native
+
+## Overview
+
+Use this skill to implement or fix Qonversion subscription flows in React Native and Expo projects.
+
+Read `references/react-native-expo.md` first, then apply only the sections required by the user request.
+
+## Workflow
+
+1. Detect project mode
+- Confirm if app is Expo managed, Expo prebuild + dev client, or bare React Native.
+- If Expo Go is being used for native purchase testing, move to dev client / native build path.
+
+2. Confirm SDK and version
+- Check `package.json` for `@qonversion/react-native-sdk` (or older `react-native-qonversion`).
+- If API usage does not match installed major version, use migration guidance from the references file.
+
+3. Initialize SDK early
+- Initialize Qonversion once during app bootstrap.
+- Use subscription-management launch mode.
+- Keep project key outside hardcoded literals when possible.
+
+4. Bind identity lifecycle
+- On login: call `identify(userId)`.
+- On logout/account switch: call `logout()`.
+- Keep backend and Qonversion identity mapping consistent.
+
+5. Implement commerce flow
+- Fetch offerings/products.
+- Trigger purchase with explicit product model/options.
+- Handle user-cancel path separately from real errors.
+- Support restore flow for reinstalls/device changes.
+
+6. Resolve access by entitlements
+- Use `checkEntitlements()` to gate premium features client-side.
+- Treat server state as source of truth for protected backend access.
+
+7. Validate on devices
+- Test with sandbox testers on iOS/Android.
+- Verify success, cancellation, restore, expired, billing issue, and offline fallback behaviors.
+
+## Implementation Rules
+
+- Prefer typed wrappers in `services/` instead of using SDK calls directly in UI screens.
+- Centralize purchase/restore/error handling in a single service module.
+- Keep entitlement keys and product IDs as constants.
+- Add telemetry around purchase start/success/failure/cancel/restore.
+- For Expo projects, document whether feature needs prebuild/dev client.
+
+## Output Expectations
+
+When completing a task with this skill, deliver:
+- Exact files changed.
+- Version assumptions and migration notes.
+- Test checklist for iOS and Android sandbox.
+- Any Expo-specific constraints (Expo Go vs dev client/prebuild).
+
+## References
+
+- Core guide: `references/react-native-expo.md`

skills/qonversion-react-native/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Qonversion RN + Expo"
+  short_description: "Integrate and troubleshoot Qonversion SDK in React Native and Expo"
+  default_prompt: "Implement or fix Qonversion SDK in React Native/Expo with setup, identify/logout, offerings, purchases, restore, and entitlements"

skills/qonversion-react-native/references/react-native-expo.md

@@ -0,0 +1,150 @@
+# Qonversion + React Native + Expo Reference
+
+## 1) Install and bootstrap
+
+Primary package (current docs):
+
+```bash
+npm install @qonversion/react-native-sdk
+```
+
+Initialize once at app startup:
+
+```ts
+import Qonversion, { QonversionConfigBuilder, LaunchMode } from '@qonversion/react-native-sdk';
+
+const config = new QonversionConfigBuilder(
+  process.env.EXPO_PUBLIC_QONVERSION_PROJECT_KEY ?? '',
+  LaunchMode.SUBSCRIPTION_MANAGEMENT
+).build();
+
+Qonversion.initialize(config);
+```
+
+If using custom networking route:
+
+```ts
+const config = new QonversionConfigBuilder(
+  process.env.EXPO_PUBLIC_QONVERSION_PROJECT_KEY ?? '',
+  LaunchMode.SUBSCRIPTION_MANAGEMENT
+)
+  .setProxyURL('https://your-proxy.example.com')
+  .build();
+```
+
+## 2) Expo integration notes
+
+- Qonversion React Native SDK is a native module; do not rely on Expo Go for full purchase testing.
+- Use Expo prebuild + dev client or EAS builds for iOS/Android purchase validation.
+- Re-run native build after dependency or native config changes.
+
+Practical commands:
+
+```bash
+npx expo prebuild
+npx expo run:ios
+npx expo run:android
+```
+
+or EAS:
+
+```bash
+eas build --platform ios --profile development
+eas build --platform android --profile development
+```
+
+## 3) Identity lifecycle
+
+Call after login:
+
+```ts
+await Qonversion.getSharedInstance().identify(userSub);
+```
+
+Call at logout/account switch:
+
+```ts
+await Qonversion.getSharedInstance().logout();
+```
+
+Optionally map Qonversion id for backend correlation:
+
+```ts
+const userInfo = await Qonversion.getSharedInstance().userInfo();
+const qonversionId = userInfo.qonversionId;
+```
+
+## 4) Offerings, products, purchases, restore
+
+Load offerings/products:
+
+```ts
+const offerings = await Qonversion.getSharedInstance().offerings();
+const products = await Qonversion.getSharedInstance().products();
+```
+
+Purchase:
+
+```ts
+try {
+  const entitlements = await Qonversion.getSharedInstance().purchaseProduct(product);
+} catch (e: any) {
+  if (e?.userCanceled) {
+    // user canceled
+  } else {
+    // real error
+  }
+}
+```
+
+Restore:
+
+```ts
+const entitlements = await Qonversion.getSharedInstance().restore();
+```
+
+## 5) Entitlement checks
+
+Client-side gate:
+
+```ts
+const entitlements = await Qonversion.getSharedInstance().checkEntitlements();
+```
+
+Use entitlement renew-state data when available to branch UX for:
+- will renew
+- canceled but still active
+- billing issue / grace period
+
+## 6) Version and migration cautions
+
+Qonversion docs include multiple React Native migration guides (4+, 6+, 6->7, 7->8 and later). Validate API names against installed major version before editing code.
+
+Examples of migration-sensitive areas:
+- `purchaseProduct(...)` vs newer `purchase(purchaseModel)` patterns
+- `updatePurchase(...)` signatures
+- permission naming transitions to entitlement naming
+- user property API renames
+
+When code and package major are mismatched:
+1. Pin target major version.
+2. Refactor to that API shape.
+3. Smoke-test purchase, restore, and entitlement-check flows.
+
+## 7) Recommended production checks
+
+- iOS and Android sandbox tester flows pass.
+- Cancel path does not show fatal error UX.
+- Restore path reactivates access.
+- Entitlement-based UI unlocks immediately after purchase.
+- Backend protected routes still enforce server truth.
+- Logs include purchase lifecycle events.
+
+## 8) Sources
+
+- Qonversion React Native SDK docs: https://documentation.qonversion.io/docs/docs/react-native-sdk
+- Purchase and restore patterns: https://documentation.qonversion.io/docs/docs/making-purchases
+- React Native migration guides: https://documentation.qonversion.io/docs/docs/react-native-8-migration-guide
+- Entitlement checks: https://documentation.qonversion.io/docs/docs/check-permissions
+- User identifiers: https://documentation.qonversion.io/docs/user-identifiers
+- Offline mode: https://documentation.qonversion.io/docs/offline-sdk-mode