@superwall/cli 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +201 -0
  3. package/dist/actions-MB-eBY64.js +140 -0
  4. package/dist/api-BF7-toqM.js +151 -0
  5. package/dist/api-output-B5hh0q4V.js +20 -0
  6. package/dist/app-K6j9Es7h.js +189 -0
  7. package/dist/asc-CArSwo5D.js +539 -0
  8. package/dist/asc-products-YQ6Oc6YO.js +93 -0
  9. package/dist/auth-CY2cO_NF.js +139 -0
  10. package/dist/auth.d.ts +30 -0
  11. package/dist/auth.js +4 -0
  12. package/dist/billing-DWyfEQ6l.js +80 -0
  13. package/dist/bind-hslFhcTR.js +213 -0
  14. package/dist/chunk-DQxbwPpZ.js +30 -0
  15. package/dist/command-Kwx4ekbo.js +283 -0
  16. package/dist/create-Bbi8BOO1.js +410 -0
  17. package/dist/dev-D0lQDCQI.js +397 -0
  18. package/dist/devtools-8EgLo86w.js +3638 -0
  19. package/dist/doctor-ByeRdMcl.js +88 -0
  20. package/dist/drivers-DVAZgone.js +413 -0
  21. package/dist/entry.d.ts +9 -0
  22. package/dist/entry.js +495 -0
  23. package/dist/existing-CcJrIIAU.js +88 -0
  24. package/dist/feedback-Z0Wk7VC5.js +73 -0
  25. package/dist/git-3OX9u3xE.js +433 -0
  26. package/dist/hosted-CHwaUqLd.js +32 -0
  27. package/dist/integrate-DqOAqK7J.js +863 -0
  28. package/dist/json-C3hPIMkI.js +7 -0
  29. package/dist/login-Dr8UN_Gx.js +290 -0
  30. package/dist/migrate-D92bJTg6.js +114 -0
  31. package/dist/org-B2gy9Pmu.js +40 -0
  32. package/dist/params-Bvq0iqQK.js +52 -0
  33. package/dist/pipeline-CHHIg6BU.js +1056 -0
  34. package/dist/print-skill-BnZAk7dV.js +74 -0
  35. package/dist/promote-CRe9170G.js +88 -0
  36. package/dist/publish-DsODvrOD.js +35 -0
  37. package/dist/push-BDkZUC0v.js +35 -0
  38. package/dist/query-DIllrSnk.js +53 -0
  39. package/dist/resource-CdP1MDla.js +483 -0
  40. package/dist/resources-CVrWwA1K.js +233 -0
  41. package/dist/run-cGGBUMs5.js +89 -0
  42. package/dist/scan-BQexuUPO.js +236 -0
  43. package/dist/skills-DhuUs28u.js +64 -0
  44. package/dist/skills-xrfXt9u0.js +205 -0
  45. package/dist/spawn-DSoTXy_j.js +69 -0
  46. package/dist/spinner-gOxIMz-V.js +18 -0
  47. package/dist/storekit-Ddvs4Ynw.js +29 -0
  48. package/dist/telemetry-CcfrtXdf.js +204 -0
  49. package/dist/token-DHRH8cxi.js +102 -0
  50. package/dist/ui-C4ncRJqd.js +27703 -0
  51. package/dist/update-BiVeR024.js +137 -0
  52. package/dist/upgrade-DYWspApv.js +72 -0
  53. package/package.json +87 -0
  54. package/prompts/actions/dashboard-setup.xml +10 -0
  55. package/prompts/actions/integrate.xml +5 -0
  56. package/prompts/actions/migrate.xml +11 -0
  57. package/prompts/actions/placements-implement.xml +20 -0
  58. package/prompts/actions/placements-review.xml +18 -0
  59. package/prompts/actions/review-fix.xml +18 -0
  60. package/prompts/actions/review.xml +18 -0
  61. package/prompts/commandments.xml +17 -0
  62. package/prompts/context.xml +9 -0
  63. package/skills/README.md +118 -0
  64. package/skills/superwall-dashboard/SKILL.md +81 -0
  65. package/skills/superwall-dashboard/references/setup.md +101 -0
  66. package/skills/superwall-integrate/SKILL.md +76 -0
  67. package/skills/superwall-integrate/references/expo.md +269 -0
  68. package/skills/superwall-integrate/references/flutter.md +285 -0
  69. package/skills/superwall-integrate/references/ios.md +314 -0
  70. package/skills/superwall-integrate/references/react-native.md +245 -0
  71. package/skills/superwall-migrate/SKILL.md +83 -0
  72. package/skills/superwall-migrate/references/adapty.md +229 -0
  73. package/skills/superwall-migrate/references/qonversion.md +227 -0
  74. package/skills/superwall-migrate/references/revenuecat.md +414 -0
  75. package/skills/superwall-placements/SKILL.md +73 -0
  76. package/skills/superwall-placements/references/expo.md +161 -0
  77. package/skills/superwall-placements/references/flutter.md +139 -0
  78. package/skills/superwall-placements/references/ios.md +165 -0
  79. package/skills/superwall-placements/references/react-native.md +145 -0
  80. package/skills/superwall-placements/references/strategy.md +221 -0
  81. package/skills/superwall-review/SKILL.md +75 -0
  82. package/skills/superwall-review/references/expo.md +100 -0
  83. package/skills/superwall-review/references/flutter.md +99 -0
  84. package/skills/superwall-review/references/ios.md +108 -0
  85. package/skills/superwall-review/references/react-native.md +100 -0
@@ -0,0 +1,245 @@
1
+ # Integrate Superwall - React Native (bare, non-Expo)
2
+
3
+ You are integrating Superwall into a **bare** React Native app (no Expo config).
4
+ Get the SDK installed and configured. **Do not add paywall triggers** - that is the
5
+ separate **superwall-placements** skill.
6
+
7
+ > **Important - which SDK:** Superwall's recommended SDK for React Native is now
8
+ > **`expo-superwall`**, installed into bare RN via Expo modules (**Path A**). The
9
+ > standalone **`@superwall/react-native-superwall`** is **deprecated** (**Path B**,
10
+ > kept only for existing setups). Default to Path A. Use Path B only if the project
11
+ > cannot add Expo modules or is already on the legacy SDK.
12
+
13
+ **Requirements (Path A):** React Native **0.79+**, Node **18+**, iOS deployment
14
+ target **15.1+**, Android **minSdkVersion 21+**.
15
+
16
+ ## Checklist
17
+
18
+ - [ ] **0. Decide the purchase-handling path** (default / RevenueCat / custom).
19
+ - [ ] **0b. Pick the SDK** - Path A (`expo-superwall`, default) or Path B (legacy).
20
+ - [ ] **1. Install** the SDK + native deps (pods / gradle).
21
+ - [ ] **2. Configure** at launch with per-platform `pk_` keys.
22
+ - [ ] **3. API keys** branched on platform (public keys, never secrets).
23
+ - [ ] **4. Purchase handling** for the chosen path.
24
+ - [ ] **5. Native rebuild** (not just a Metro reload) - module links.
25
+ - [ ] **6. Run** - native logs show Superwall startup.
26
+ - [ ] **7. Post-integration** (identity, attributes, subscription state, deep links, analytics), then → **superwall-placements**.
27
+
28
+ ## Docs access - read the current page when baked steps aren't enough
29
+
30
+ ```bash
31
+ curl -sL https://superwall.com/docs/expo/llms.txt # Path A docs (expo-superwall) live here
32
+ curl -sL https://superwall.com/docs/react-native/llms.txt # Path B legacy SDK reference
33
+ curl -sL https://superwall.com/docs/llms-full.txt # broad context
34
+ curl -sL https://superwall.com/docs/expo/guides/using-expo-sdk-in-bare-react-native.md
35
+ ```
36
+
37
+ Pattern: fetch the index, then `https://superwall.com/docs/{sdk}/{path}.md`. Every
38
+ `curl` here is verified working. **Path A uses the Expo docs** - the hooks/provider
39
+ API (`SuperwallProvider`, `useUser`) is documented under `/docs/expo/…`. **Never
40
+ invent an API**; fetch and confirm.
41
+
42
+ ## Quickstart walk
43
+
44
+ Path A follows the **Expo** quickstart. Path B uses the (deprecated) react-native
45
+ SDK reference.
46
+
47
+ | Order | Path A slug (Expo docs) | Covered by |
48
+ | ----- | ------------------------------------------------- | --------------- |
49
+ | 1 | `expo/guides/using-expo-sdk-in-bare-react-native` | Step 1 (Path A) |
50
+ | 2 | `expo/quickstart/configure` | Step 2 |
51
+ | 3 | `expo/quickstart/setting-user-properties` | Step 7 |
52
+ | 4 | `expo/quickstart/tracking-subscription-state` | Step 7 |
53
+ | 5 | `expo/quickstart/user-management` | Step 7 |
54
+
55
+ Path B reference: `curl -sL https://superwall.com/docs/react-native/llms.txt`
56
+
57
+ ## Step 0 - Purchase-handling path (decide first)
58
+
59
+ > **Important:** Paths (b)/(c) require manual subscription-status management; (a) doesn't.
60
+
61
+ - **(a) Default - Superwall handles StoreKit/Billing.** Recommended, zero purchase code.
62
+ - **(b) RevenueCat stays the source of truth.** Keep RC purchasing; sync entitlements in.
63
+ - **(c) Custom purchase controller.** Supply a `PurchaseController`, drive status.
64
+
65
+ Full migration off another SDK → **superwall-migrate** skill.
66
+
67
+ ---
68
+
69
+ ## Path A - `expo-superwall` in bare React Native (recommended)
70
+
71
+ ### 1. Install
72
+
73
+ Add Expo modules support to the bare project (the Superwall-documented way to
74
+ consume `expo-superwall` without full Expo):
75
+
76
+ ```bash
77
+ curl -sL https://superwall.com/docs/expo/guides/using-expo-sdk-in-bare-react-native.md
78
+ npx install-expo-modules@latest
79
+ ```
80
+
81
+ Install the SDK with the project's package manager (detect from lockfile):
82
+
83
+ ```bash
84
+ npm install expo-superwall
85
+ # or: yarn add expo-superwall / pnpm add expo-superwall / bun add expo-superwall
86
+ ```
87
+
88
+ Install iOS pods, ensure Android mins:
89
+
90
+ ```bash
91
+ cd ios && pod install
92
+ ```
93
+
94
+ `android/app/build.gradle`: `minSdkVersion 21`+ (with `compileSdkVersion` /
95
+ `targetSdkVersion` 34).
96
+
97
+ ### 2. Configure
98
+
99
+ Wrap the app root in `SuperwallProvider` with per-platform public keys:
100
+
101
+ ```tsx
102
+ import { SuperwallProvider } from "expo-superwall";
103
+
104
+ export default function App() {
105
+ return (
106
+ <SuperwallProvider
107
+ apiKeys={{ ios: "pk_YOUR_IOS_PUBLIC_KEY", android: "pk_YOUR_ANDROID_PUBLIC_KEY" }}
108
+ >
109
+ {/* your existing app tree */}
110
+ </SuperwallProvider>
111
+ );
112
+ }
113
+ ```
114
+
115
+ `SuperwallProvider` configures the SDK on mount - **do not** also call a separate
116
+ `configure()`. Optional behavior goes through the `options` prop.
117
+
118
+ Path A shares the Expo API. Skip to **API key handling**, **Purchase handling**,
119
+ **Post-integration** - they apply to both paths (Path A uses the hooks form).
120
+
121
+ ---
122
+
123
+ ## Path B - legacy `@superwall/react-native-superwall`
124
+
125
+ Use only if you cannot add Expo modules, or the project already uses this SDK.
126
+
127
+ ### 1. Install
128
+
129
+ ```bash
130
+ npm install @superwall/react-native-superwall
131
+ # or: yarn add @superwall/react-native-superwall
132
+ cd ios && pod install
133
+ ```
134
+
135
+ Android autolinks - no extra native step beyond a normal build.
136
+
137
+ ### 2. Configure
138
+
139
+ Import the default export and call `Superwall.configure` once at launch (root
140
+ component's `useEffect` with empty deps). The public key is per-platform:
141
+
142
+ ```tsx
143
+ import { useEffect } from "react";
144
+ import { Platform } from "react-native";
145
+ import Superwall from "@superwall/react-native-superwall";
146
+
147
+ export default function App() {
148
+ useEffect(() => {
149
+ const apiKey = Platform.OS === "ios" ? "pk_YOUR_IOS_PUBLIC_KEY" : "pk_YOUR_ANDROID_PUBLIC_KEY";
150
+ Superwall.configure({ apiKey });
151
+ }, []);
152
+
153
+ return (/* your app */);
154
+ }
155
+ ```
156
+
157
+ Full signature: `Superwall.configure({ apiKey, options?, purchaseController?, completion? })`
158
+ (returns a Promise resolving to the configured instance, also at `Superwall.shared`).
159
+ `curl -sL https://superwall.com/docs/react-native/sdk-reference/configure.md`
160
+
161
+ ---
162
+
163
+ ## API key handling (both paths)
164
+
165
+ Use the **Public API Key(s)** (`pk_…`) from Dashboard ▸ Settings ▸ Keys - iOS and
166
+ Android apps have separate keys, so branch on platform. Public keys aren't secrets;
167
+ inline them, or read from existing config (`react-native-config`). **Never** use a
168
+ secret/server key.
169
+
170
+ ## Purchase handling (both paths - implements Step 0)
171
+
172
+ ### (a) Default
173
+
174
+ Nothing extra - Superwall manages purchases, restores, and subscription status.
175
+
176
+ ### (b) RevenueCat / (c) custom
177
+
178
+ Subclass `PurchaseController` and implement `purchaseFromAppStore(productId)`,
179
+ `purchaseFromGooglePlay(productId, basePlanId?, offerId?)`, `restorePurchases()`;
180
+ pass it at configure time. Read the page first - **do not invent method names**:
181
+
182
+ ```bash
183
+ curl -sL https://superwall.com/docs/expo/guides/advanced-configuration.md
184
+ ```
185
+
186
+ ```tsx
187
+ export class MyPurchaseController extends PurchaseController {
188
+ async purchaseFromAppStore(productId: string): Promise<PurchaseResult> { /* ... */ }
189
+ async purchaseFromGooglePlay(
190
+ productId: string, basePlanId?: string, offerId?: string
191
+ ): Promise<PurchaseResult> { /* ... */ }
192
+ async restorePurchases(): Promise<RestorationResult> { /* ... */ }
193
+ }
194
+ ```
195
+
196
+ > **Important (paths b & c):** keep subscription status synced whenever entitlements
197
+ > change. Path A (hooks): `const { setSubscriptionStatus } = useUser();
198
+ setSubscriptionStatus({ status: "ACTIVE", entitlements: [{ id: "pro" }] })`.
199
+ > Shared instance:
200
+ > `Superwall.shared.setSubscriptionStatus(SubscriptionStatus.Active([new Entitlement("pro")]))`
201
+ > / `SubscriptionStatus.Inactive()`. For (b), map RevenueCat's active entitlements in.
202
+
203
+ ## Verify (both paths)
204
+
205
+ 1. **Native rebuild** & run: `npx react-native run-ios` / `run-android`. Path A must
206
+ relink the native module - rebuild, don't just reload JS.
207
+ 2. Watch native logs on launch for Superwall SDK startup.
208
+ 3. iOS purchase testing: StoreKit testing in Xcode.
209
+
210
+ ## Post-integration (wire what the app needs, then → placements)
211
+
212
+ Path A uses the `useUser` hook; Path B uses static `Superwall` methods.
213
+
214
+ - **User identity - REQUIRED if the app has ANY auth/login system.** Not optional: without it every logged-in user is anonymous to Superwall, breaking user-scoped audiences, attribution, and cross-device status. Wire it the moment you see a login/logout flow (grep for signIn/login/logout/signOut/auth). Path A: `const { identify, signOut } = useUser()`. Path B:
215
+ `Superwall.shared.identify(userId)` / `Superwall.shared.reset()`. `userId` should
216
+ be a **UUID** (StoreKit compat), never an email/device id/guessable value.
217
+ `curl -sL https://superwall.com/docs/expo/quickstart/user-management.md`
218
+ - **User attributes** - `setUserAttributes(...)`.
219
+ `curl -sL https://superwall.com/docs/expo/quickstart/setting-user-properties.md`
220
+ - **Tracking subscription state** - Path A: `subscriptionStatus` from `useUser`
221
+ (`status` = `"ACTIVE" | "INACTIVE" | "UNKNOWN"`).
222
+ `curl -sL https://superwall.com/docs/expo/quickstart/tracking-subscription-state.md`
223
+ - **Deep links** - pass URLs to `handleDeepLink`; fires the `deepLink_open` placement.
224
+ `curl -sL https://superwall.com/docs/expo/guides/handling-deep-links.md`
225
+ - **3rd-party analytics** - forward events (Path A: `useSuperwallEvents`).
226
+ `curl -sL https://superwall.com/docs/expo/guides/3rd-party-analytics.md`
227
+
228
+ ## Pitfalls
229
+
230
+ - **iOS module not found / link errors** → `cd ios && pod install`, then a full
231
+ native rebuild (not just Metro reload).
232
+ - **Reached for the wrong SDK** → prefer Path A (`expo-superwall`); the standalone
233
+ `@superwall/react-native-superwall` is deprecated.
234
+ - **Path A native module missing** → `npx install-expo-modules@latest` must succeed
235
+ before `pod install`; rebuild afterward.
236
+ - **Configuring on every render** → Path B: wrap `configure` in `useEffect(..., [])`.
237
+ - **Secret key** → key must start with `pk_`.
238
+
239
+ ## Deeper docs
240
+
241
+ - Bare RN install guide (Path A): https://superwall.com/docs/expo/guides/using-expo-sdk-in-bare-react-native
242
+ - Migrating from the legacy SDK: https://superwall.com/docs/expo/guides/migrating-react-native
243
+ - Legacy `configure()` (Path B): https://superwall.com/docs/react-native/sdk-reference/configure
244
+ - React Native SDK reference index: `curl -sL https://superwall.com/docs/react-native/llms.txt`
245
+ - Expo docs index (applies to Path A): `curl -sL https://superwall.com/docs/expo/llms.txt`
@@ -0,0 +1,83 @@
1
+ ---
2
+ name: superwall-migrate
3
+ description: Migrate a mobile app from RevenueCat, Adapty, or Qonversion to Superwall. Replaces provider SDK calls and recreates products, entitlements, campaigns, and placements. Subscriber access carries over via the stores (RevenueCat state can also be ported server-side), and paywall designs must be rebuilt. Use when replacing another paywall or billing SDK with Superwall. Not for first-time SDK setup in an app with no provider (superwall-integrate).
4
+ ---
5
+
6
+ # Migrate to Superwall
7
+
8
+ > **Important - what does and does not migrate:**
9
+ >
10
+ > - Paywall designs are rebuilt from scratch - as code with the superwall framework
11
+ > (`superwall create`) or in the dashboard editor.
12
+ > - Historical analytics and attribution stay in the old provider.
13
+ > - Adapty/Qonversion subscribers do not currently move server-side; existing
14
+ > purchases are recovered from the store through Restore Purchases.
15
+ > - RevenueCat: Superwall provides server-side migration tooling that ports
16
+ > subscription history and entitlement state - fetch the live migration guide
17
+ > for the current process before promising specifics. Restore Purchases works
18
+ > regardless.
19
+
20
+ ## Docs access
21
+
22
+ ```bash
23
+ curl -sL https://superwall.com/docs/llms.txt
24
+ curl -sL https://superwall.com/docs/{path}.md
25
+ ```
26
+
27
+ Fetch the framework's configure, purchase-controller, subscription-state,
28
+ identity, register, and feature-gating pages before changing APIs.
29
+
30
+ ## Route to exactly one provider playbook
31
+
32
+ | Detect | Read fully |
33
+ | ------------------------------------------------------------- | -------------------------- |
34
+ | `RevenueCat`, `react-native-purchases`, `purchases_flutter` | `references/revenuecat.md` |
35
+ | `Adapty`, `react-native-adapty`, `adapty_flutter` | `references/adapty.md` |
36
+ | `Qonversion`, `react-native-qonversion`, `qonversion_flutter` | `references/qonversion.md` |
37
+
38
+ If several exist, identify which one owns purchases before proceeding.
39
+
40
+ ## Flow
41
+
42
+ 1. Inventory configure, purchase, restore, entitlement, identity, attributes,
43
+ presentation calls, and all callback side effects.
44
+ 2. Choose billing ownership: Superwall, retained custom/store billing, or the
45
+ existing provider as a purchase controller. Follow the chosen playbook.
46
+ 3. Map store product ids unchanged, provider entitlements/access levels to
47
+ Superwall entitlements, and each presentation call site to a placement.
48
+ 4. Run `superwall apps list --json`; match the code's public key or bundle id and
49
+ record explicit project/app ids. Stop on an account mismatch.
50
+ 5. Recreate only missing dashboard resources with scoped JSON commands.
51
+ 6. Add Superwall alongside the provider, replace presentation with placements,
52
+ preserve purchase/restore side effects and identity lifecycle, then build.
53
+ 7. Verify every placement and Restore Purchases as an existing subscriber.
54
+ 8. Remove the old SDK only in full-migration mode and only after verification.
55
+ 9. Hand back migrated code, created ids, evidence, and every remaining manual step.
56
+
57
+ ## Non-negotiable seams
58
+
59
+ - Exactly one purchase owner and transaction finisher.
60
+ - Purchases outside Superwall must continuously sync subscription state through
61
+ a purchase controller, observer mode, or explicit status updates.
62
+ - Preserve backend sync, analytics, attribution, cache refresh, and navigation
63
+ from old purchase/restore callbacks.
64
+ - Identify before placements can fire; reset on logout, deletion, and forced
65
+ session expiry.
66
+ - Put remotely gated work inside the placement feature callback.
67
+ - Never create dashboard resources until the logged-in app match is verified.
68
+
69
+ ## CLI contract
70
+
71
+ Agents always use `--json` and explicit scope:
72
+
73
+ ```bash
74
+ superwall whoami --json
75
+ superwall apps list --json
76
+ superwall entitlements list --project <projectId> --json
77
+ superwall entitlements create <id> --project <projectId> --json
78
+ superwall products list --project <projectId> --json
79
+ superwall products create <storeId> --project <projectId> --json
80
+ superwall campaigns list --project <projectId> --app <appId> --json
81
+ superwall campaigns create "<description>" <placement> --project <projectId> --app <appId> --json
82
+ superwall campaigns placement <campaignId> <placement> --project <projectId> --app <appId> --json
83
+ ```
@@ -0,0 +1,229 @@
1
+ # Adapty → Superwall
2
+
3
+ Definitive playbook. Read fully before editing. Superwall has no Adapty-specific
4
+ "using-adapty" guide, so PAYWALLS-ONLY mode uses the **generic** `PurchaseController`
5
+ (`/docs/ios/guides/advanced-configuration`) - mirror the RevenueCat controller shape in
6
+ `references/revenuecat.md`, swapping RC calls for Adapty calls.
7
+
8
+ ## Scope & checklist
9
+
10
+ This migrates the **SDK integration**, not the whole product. Checklist:
11
+
12
+ - [ ] Inventory Adapty SDK usage (grep §3)
13
+ - [ ] Map products / access levels / `getPaywall` call sites (§1)
14
+ - [ ] Re-create products, entitlements, campaign + placements in Superwall via CLI (§4)
15
+ - [ ] Swap SDK calls (activate→configure, access-level reads, present → placement, identify) (§5)
16
+ - [ ] Build + verify each placement; Restore Purchases as an existing subscriber (§7)
17
+ - [ ] FULL only: remove Adapty dependency once verified
18
+ - [ ] Hand back to user: **rebuild paywalls** (superwall framework or dashboard editor), attach products, connect ASC/Play
19
+
20
+ > **Important - what does NOT migrate:**
21
+ >
22
+ > - **Adapty paywall designs** (Paywall Builder / remote config) cannot be imported - they are
23
+ > **rebuilt** - as code with the superwall framework or in the dashboard editor.
24
+ > - **Historical analytics / attribution** stays in Adapty.
25
+ > - **Subscriber base:** there is currently no server-side subscriber migration from Adapty.
26
+ > Existing subscribers keep access because their purchases live with the store (StoreKit /
27
+ > Play Billing); the app reads them device-side via **Restore Purchases** and maps them to
28
+ > Superwall entitlements. No subscriber data currently moves between backends.
29
+
30
+ ## Docs access - fetch live, don't trust baked text
31
+
32
+ ```bash
33
+ curl -sL https://superwall.com/docs/llms.txt # index
34
+ curl -sL https://superwall.com/docs/ios/guides/advanced-configuration.md # PurchaseController protocol (swap ios→expo/flutter/android)
35
+ curl -sL https://superwall.com/docs/support/faq/how-to-migrate-from-another-provider-to-superwall.md
36
+ ```
37
+
38
+ ## 1. Concept mapping
39
+
40
+ | Adapty | Superwall | Notes |
41
+ | ------------------------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
42
+ | Product (store SKU) | **Product** (re-created) | Keep the SAME App Store / Play product id. |
43
+ | Paywall (Adapty Paywall Builder / remote config) | **Paywall** (rebuilt) | Design does NOT import - rebuild from scratch. |
44
+ | Placement (`main`, `onboarding`, …) | **Placement** (inside a **Campaign**) | Closest 1:1 - Adapty already hardcodes placement ids at call sites; reuse the names (as `snake_case`). |
45
+ | Access Level (e.g. `premium`) | **Entitlement** (re-created) | 1:1. Recreate each access-level id as a Superwall entitlement. |
46
+ | `profile.accessLevels["premium"].isActive` | `Superwall.shared.subscriptionStatus.isActive` (FULL) | Device-derived in FULL mode. |
47
+ | Profile (Adapty user) | Superwall user (`identify`) | |
48
+ | `Adapty.updateProfile` custom attributes | `Superwall.shared.setUserAttributes` | |
49
+
50
+ **Mental-model shift.** Adapty already uses placements - but you call `Adapty.getPaywall(placementId:)`,
51
+ fetch products, and present. In Superwall you just `register(placement:)` at the call site and the
52
+ **campaign** decides whether/which paywall shows. The decision moves from app code to the dashboard.
53
+
54
+ ## 2. Three modes - decide who owns purchases first
55
+
56
+ Once Adapty is gone, something still has to purchase, restore, and **tell Superwall who is
57
+ subscribed** - Superwall only auto-detects state when its own SDK made the purchase.
58
+
59
+ ### Mode A - FULL, Superwall owns purchases (default)
60
+
61
+ Remove Adapty. Superwall handles purchase/restore and computes entitlements from device records. No `PurchaseController`, no manual status setting.
62
+
63
+ ### Mode B - FULL, app keeps its own purchase flow (custom UI / direct StoreKit or Play Billing)
64
+
65
+ Adapty is gone, but the app still buys through its own code and uses Superwall only for paywalls.
66
+ Superwall does NOT observe purchases it didn't make.
67
+
68
+ > **Important:** From advanced-configuration, verbatim: "You **must** set
69
+ > `Superwall.shared.subscriptionStatus` every time the user's subscription status changes, otherwise
70
+ > the SDK won't know who to show a paywall to." Do exactly ONE of: (1) implement a `PurchaseController`
71
+ > that sets `subscriptionStatus`; (2) enable observer mode - `SuperwallOptions().shouldObservePurchases = true`
72
+ > (then you can't call `Superwall.shared.purchase(...)`); or (3) push status manually after every
73
+ > purchase/restore/expiry (iOS: from a `Transaction.currentEntitlements` read +
74
+ > `Transaction.updates` listener; Expo/RN/Flutter: `Superwall.shared.setSubscriptionStatus(...)`).
75
+ > Skip this and Superwall shows paywalls to paying users.
76
+
77
+ ```bash
78
+ curl -sL https://superwall.com/docs/ios/quickstart/tracking-subscription-state.md # + expo/ · flutter/ variants
79
+ curl -sL https://superwall.com/docs/ios/guides/advanced/observer-mode.md
80
+ ```
81
+
82
+ ### Mode C - PAYWALLS-ONLY, Adapty stays the purchase controller
83
+
84
+ Keep Adapty for purchases/receipts/webhooks; Superwall only shows paywalls. Implement a Superwall
85
+ `PurchaseController` whose `purchase`/`restore` call Adapty, and mirror Adapty access levels into
86
+ `Superwall.shared.subscriptionStatus` / `setSubscriptionStatus`. Confirm the exact
87
+ `PurchaseController` protocol signatures live (there is no Adapty-specific sample):
88
+
89
+ ```bash
90
+ curl -sL https://superwall.com/docs/ios/guides/advanced-configuration.md
91
+ ```
92
+
93
+ _Pure observer_ (analytics-only, Adapty owns purchases AND paywalls): `SuperwallOptions.shouldObservePurchases = true`. `curl -sL https://superwall.com/docs/ios/guides/advanced/observer-mode.md`
94
+
95
+ ## 3. Codebase inventory - grep these symbols
96
+
97
+ **iOS (Swift, `Adapty`):**
98
+
99
+ - Config: `Adapty.activate(` , `AdaptyConfiguration`, `Adapty.delegate`, `AdaptyDelegate`
100
+ - Paywall/products (→ future placements): `Adapty.getPaywall(placementId:` , `Adapty.getPaywallProducts(paywall:` , `AdaptyUI.getPaywallConfiguration`, `AdaptyPaywallController`, `paywall.remoteConfig`
101
+ - Purchase/restore: `Adapty.makePurchase(product:` , `Adapty.restorePurchases(`
102
+ - Access-level checks (→ future gates): `Adapty.getProfile(` , `profile.accessLevels[` , `.isActive`, `AdaptyDelegate.didLoadLatestProfile`
103
+ - Identity/attributes: `Adapty.identify(` , `Adapty.logout(` , `Adapty.updateProfile(` (`AdaptyProfileParameters` / `.customAttributes`)
104
+
105
+ **React Native (`react-native-adapty`):**
106
+ `adapty.activate('APP_KEY')`, `adapty.getPaywall(placementId)`, `adapty.getPaywallProducts(paywall)`,
107
+ `adapty.makePurchase(product)`, `adapty.restorePurchases()`, `adapty.getProfile()`,
108
+ `profile.accessLevels['premium'].isActive`, `adapty.identify(id)`, `adapty.logout()`,
109
+ `adapty.updateProfile({...})`, `adapty.addEventListener('onLatestProfileLoad', …)`.
110
+
111
+ **Flutter (`adapty_flutter`):**
112
+ `Adapty().activate(...)`, `Adapty().getPaywall(placementId: ...)`, `Adapty().getPaywallProducts(paywall: ...)`,
113
+ `Adapty().makePurchase(product: ...)`, `Adapty().restorePurchases()`, `Adapty().getProfile()`,
114
+ `profile.accessLevels['premium']?.isActive`, `Adapty().identify(...)`, `Adapty().logout()`,
115
+ `Adapty().updateProfile(...)`, `adaptyDelegate.didLoadLatestProfile`.
116
+
117
+ Produce: product ids, access-level ids (→ entitlements), and one row per `getPaywall`/present call site → placement (reuse Adapty's placement id, `snake_case`).
118
+
119
+ ## 4. Dashboard-side re-creation (CLI)
120
+
121
+ ```bash
122
+ superwall entitlements create premium --project <projectId> --json
123
+ superwall products create com.app.premium_monthly --name "Premium Monthly" --project <projectId> --json
124
+ superwall products create com.app.premium_yearly --name "Premium Yearly" --project <projectId> --json
125
+ superwall campaigns create "Main paywall" main --project <projectId> --app <appId> --json
126
+ superwall campaigns placement <campaignId> onboarding --project <projectId> --app <appId> --json
127
+ ```
128
+
129
+ Product ids MUST equal existing App Store / Play SKUs (import from ASC via `superwall asc keys set --help`).
130
+ Verify with the same explicit ids: `superwall entitlements list --project <projectId> --json`,
131
+ `superwall products list --project <projectId> --json`, and `superwall campaigns list --project <projectId> --app <appId> --json`.
132
+
133
+ ## 5. Code replacement
134
+
135
+ ### FULL mode
136
+
137
+ - **Configure.** Replace `Adapty.activate(...)` with `Superwall.configure(apiKey: "…")`. No purchase controller.
138
+ - **Access-level checks → subscriptionStatus.**
139
+ ```swift
140
+ // Before
141
+ let profile = try? await Adapty.getProfile()
142
+ return profile?.accessLevels["premium"]?.isActive ?? false
143
+ // After
144
+ if Superwall.shared.subscriptionStatus.isActive { /* entitled */ }
145
+ // per-entitlement: switch Superwall.shared.subscriptionStatus { case .active(let e): … ; case .inactive: … ; case .unknown: … }
146
+ ```
147
+ - **Presentation → placement.** Replace `getPaywall` + `getPaywallProducts` + present with:
148
+ ```swift
149
+ Superwall.shared.register(placement: "main") { unlockFeature() }
150
+ ```
151
+ RN: `Superwall.shared.register({ placement: "main" }, () => {...})`.
152
+ Flutter: `Superwall.shared.registerPlacement("main", feature: () {...})`.
153
+ - **Identity.** `Adapty.identify(id)` → `Superwall.shared.identify(userId: id)`; `Adapty.logout()` → `Superwall.shared.reset()`.
154
+ - **Attributes.** `Adapty.updateProfile(params)` (customAttributes) → `Superwall.shared.setUserAttributes([...])`. Call `identify` BEFORE `setUserAttributes`.
155
+ - Remove the Adapty dependency only after build + verification.
156
+
157
+ ### PAYWALLS-ONLY mode - bridge to Adapty
158
+
159
+ Build a Superwall `PurchaseController` (confirm signatures at advanced-configuration). Skeleton,
160
+ mirroring the RC pattern with Adapty calls:
161
+
162
+ ```swift
163
+ final class AdaptyPurchaseController: PurchaseController {
164
+ func syncSubscriptionStatus() {
165
+ // Adapty is the source of truth. On every profile update (AdaptyDelegate.didLoadLatestProfile
166
+ // or an initial getProfile), map active access levels → Superwall entitlements:
167
+ // let ents = profile.accessLevels.filter { $0.value.isActive }.keys.map { Entitlement(id: $0) }
168
+ // Superwall.shared.subscriptionStatus = ents.isEmpty ? .inactive : .active(Set(ents))
169
+ }
170
+ func purchase(product: SuperwallKit.StoreProduct) async -> PurchaseResult {
171
+ // Resolve the matching AdaptyPaywallProduct (or make an Adapty purchase by product id),
172
+ // call Adapty.makePurchase(product:), map its result → .purchased / .cancelled / .pending / .failed(error)
173
+ }
174
+ func restorePurchases() async -> RestorationResult {
175
+ // try await Adapty.restorePurchases(); return .restored (catch → .failed(error))
176
+ }
177
+ }
178
+ ```
179
+
180
+ Wire: `Superwall.configure(apiKey: "…", purchaseController: AdaptyPurchaseController())` then start the sync.
181
+ Set `AdaptyDelegate` so `didLoadLatestProfile` drives `Superwall.shared.subscriptionStatus` (iOS) /
182
+ `setSubscriptionStatus(...)` (RN/Flutter). Confirm the exact `PurchaseController` method signatures and
183
+ `PurchaseResult`/`RestorationResult` cases at the advanced-configuration doc before finalizing.
184
+
185
+ ## 6. Feature gating
186
+
187
+ Set per placement in the editor (**General → Feature Gating**): non-gated (closure runs on dismiss
188
+ regardless) vs gated (only when entitled). Peek: `Superwall.shared.getPresentationResult(forPlacement:)`.
189
+ `curl -sL https://superwall.com/docs/ios/quickstart/feature-gating.md`
190
+
191
+ ## 7. Order of operations + safety
192
+
193
+ 1. Re-create entitlements/products/campaign+placements (CLI); import products from ASC/Play so ids match.
194
+ 2. **Rebuild** paywalls (superwall framework or dashboard editor), attach products (hand-back to user - designs do not import).
195
+ 3. Add Superwall SDK alongside Adapty; configure it.
196
+ 4. Replace `getPaywall`/present call sites with `register(placement:)`; replace access-level reads with `subscriptionStatus`.
197
+ 5. Build, present each placement, Restore Purchases as an existing subscriber, confirm `subscriptionStatus.isActive`.
198
+ 6. FULL: remove controller + Adapty dependency. PAYWALLS-ONLY: keep Adapty + controller.
199
+ 7. Never delete Adapty dashboard/webhook config until verified in production. Existing subscribers keep access via device-side Restore Purchases (Superwall reads store records) - no server-side subscriber migration currently exists.
200
+
201
+ ## 8. Pitfalls
202
+
203
+ - **Double-finish / double-charge.** Exactly one SDK finishes transactions. PAYWALLS-ONLY: Adapty owns purchasing via the controller; never also call `Superwall.shared.purchase`. FULL: remove Adapty purchase paths.
204
+ - **StoreKit listener conflicts.** Two SDKs observing StoreKit → duplicate grants/races. One owner only.
205
+ - **Silent "everyone sees a paywall" bug (Mode B).** Removed Adapty but kept the app's own purchase
206
+ flow (custom UI / direct StoreKit / Play Billing) without syncing state → Superwall treats every user
207
+ as unsubscribed and shows paywalls to payers. Grep for `purchase(` / `Transaction.updates` /
208
+ `BillingClient` outside Superwall; if purchases happen outside Superwall, sync via controller,
209
+ observer mode, or a manual `subscriptionStatus` set (§2 Mode B).
210
+ - **Observer flag.** `shouldObservePurchases = true` disables `Superwall.shared.purchase`; observer mode only.
211
+ - **Entitlement id mismatch.** Superwall entitlement ids must equal Adapty access-level ids exactly (`premium` ≠ `Premium`).
212
+ - **Access-level nuances.** Adapty access levels also carry grace-period / lifetime / billing-issue states; when mirroring, treat `isActive` (incl. grace period per your policy) as entitled - don't silently drop grace-period users.
213
+ - **Cache during switchover.** Status may read `.unknown`/`.inactive` until the first profile load / StoreKit sync - prompt Restore Purchases if a known subscriber looks free.
214
+ - **identify order.** `identify` before `setUserAttributes`.
215
+ - **Unverified controller signatures.** The Adapty controller above is a skeleton - verify `PurchaseController` protocol + result enums at the advanced-configuration doc, since there's no official Adapty sample.
216
+
217
+ ## 9. Deeper docs (fetch live)
218
+
219
+ ```bash
220
+ curl -sL https://superwall.com/docs/support/faq/how-to-migrate-from-another-provider-to-superwall.md
221
+ curl -sL https://superwall.com/docs/ios/guides/advanced-configuration.md # PurchaseController (+ expo/flutter/android)
222
+ curl -sL https://superwall.com/docs/ios/guides/advanced/observer-mode.md
223
+ curl -sL https://superwall.com/docs/ios/quickstart/tracking-subscription-state.md
224
+ curl -sL https://superwall.com/docs/llms.txt # index
225
+ ```
226
+
227
+ - PurchaseController reference: https://superwall.com/docs/ios/sdk-reference/PurchaseController
228
+ - register/identify/setUserAttributes: https://superwall.com/docs/ios/sdk-reference/register · .../identify · .../setUserAttributes
229
+ - Adapty side: https://adapty.io/docs/ios-sdk-overview · https://adapty.io/docs/making-purchases · RN https://adapty.io/docs/react-native-making-purchases · Flutter https://adapty.io/docs/flutter-sdk-making-purchases