@superwall/cli 2.2.0 → 2.3.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 (113) hide show
  1. package/README.md +26 -11
  2. package/dist/{apple-Bcr_PteR.js → apple-D79LBw5E.js} +13 -13
  3. package/dist/assets-Diivv88t.js +89 -0
  4. package/dist/auth.d.ts +1 -1
  5. package/dist/auth.js +3 -3
  6. package/dist/{billing-CWM1ds3K.js → billing-CCuMv6mh.js} +3 -3
  7. package/dist/{bind-DEYxsnZD.js → bind-CVRlFlRo.js} +4 -4
  8. package/dist/{build--oQKfZU6.js → build-BCq0cGh-.js} +7 -6
  9. package/dist/{client-CimFymxG.js → client-CYtQvWJR.js} +3 -3
  10. package/dist/{create-BG9n4fvs.js → create-BZyUW60x.js} +28 -226
  11. package/dist/{create-DTAyHkxb.js → create-BaP6hoQ1.js} +6 -6
  12. package/dist/create-DNfuZ9os.js +19 -0
  13. package/dist/{doctor-BkygMUe2.js → doctor-kx01VvQX.js} +6 -6
  14. package/dist/{drivers-C6eXj5-r.js → drivers-D0818zGc.js} +3 -3
  15. package/dist/entry.js +19 -19
  16. package/dist/{environment-CQn323uB.js → environment-a7W-0wg0.js} +1 -1
  17. package/dist/{existing-CvOluc9U.js → existing-B7qxYiUX.js} +2 -2
  18. package/dist/held-C4BiAQ_X.js +16 -0
  19. package/dist/{held-QM7yfrXq.js → held-CEyXc1SI.js} +6 -6
  20. package/dist/{integrate-Ci_MLkQG.js → integrate-RK5U0GTQ.js} +22 -22
  21. package/dist/login-DV70XgZO.js +16 -0
  22. package/dist/{login-BIAWgdzM.js → login-DrMLxlF4.js} +6 -6
  23. package/dist/{login-DLi71nJq.js → login-NxCl2WuU.js} +1 -1
  24. package/dist/{lookup-DZFrfzO0.js → lookup-Dor6ch5A.js} +2 -2
  25. package/dist/{migrate-BKF1WckS.js → migrate-CjSpcnNu.js} +25 -22
  26. package/dist/{open-BjvGVwJf.js → migration-MlzZHGP-.js} +22 -56
  27. package/dist/{notification-url-erXQ1edb.js → notification-url-C_QXtljc.js} +2 -2
  28. package/dist/open-CBW0Cuog.js +41 -0
  29. package/dist/{org-CvPGVSBF.js → org-BJCyaL1b.js} +2 -2
  30. package/dist/{paths-oRuC18Kt.js → paths-Cp_lgyWO.js} +1 -1
  31. package/dist/{playbook-CtTj1HBK.js → playbook-VqV7546k.js} +10 -10
  32. package/dist/{promote-BkJYISza.js → promote-BSckFPwZ.js} +18 -16
  33. package/dist/pull-DEumBwvc.js +303 -0
  34. package/dist/{push-Ul2SW87i.js → push-D-dewDd1.js} +8 -6
  35. package/dist/push-YEPqa6hs.js +24 -0
  36. package/dist/{registry-OmPZ6dj0.js → registry-D6M1JxYC.js} +236 -142
  37. package/dist/{resources-FIrK7pE9.js → resources-DKn4itf3.js} +21 -7
  38. package/dist/{run-CwEY1eu5.js → run-Ccv5egCC.js} +2 -2
  39. package/dist/{scan-CpbfZ2ju.js → scan-Be17rMcQ.js} +1 -1
  40. package/dist/scan-CocGVPe0.js +4 -0
  41. package/dist/{scope-BSqVfZvy.js → scope-92neiQ2q.js} +5 -4
  42. package/dist/{selection-CHnVk8uw.js → selection-C5ZY23dQ.js} +16 -96
  43. package/dist/server-1pOxW1GJ.js +24 -0
  44. package/dist/{server-D5xl5iKO.js → server-DZ7L28w4.js} +9 -7
  45. package/dist/{session-BFwasPVq.js → session-CdnUL4zt.js} +444 -243
  46. package/dist/session-Cm0U68t3.js +6 -0
  47. package/dist/{session-6lnJ0shD.js → session-gTuw2_8i.js} +1 -1
  48. package/dist/setup-esb3_a7N.js +216 -0
  49. package/dist/skills/animate-onboarding/SKILL.md +2 -2
  50. package/dist/skills/index.json +18 -18
  51. package/dist/skills/mobile-design/SKILL.md +2 -2
  52. package/dist/skills/onboarding-questions/SKILL.md +2 -2
  53. package/dist/skills/superwall/SKILL.md +104 -20
  54. package/dist/skills/superwall/references/api.md +21 -5
  55. package/dist/skills/superwall/workflows/dashboard/playbook.md +6 -4
  56. package/dist/skills/superwall/workflows/dashboard/setup.md +10 -5
  57. package/dist/skills/superwall/workflows/integrate/playbook.md +4 -2
  58. package/dist/skills/superwall/workflows/migrate/adapty.md +7 -6
  59. package/dist/skills/superwall/workflows/migrate/playbook.md +4 -3
  60. package/dist/skills/superwall/workflows/migrate/qonversion.md +7 -6
  61. package/dist/skills/superwall/workflows/migrate/revenuecat.md +8 -7
  62. package/dist/skills/superwall-editor/SKILL.md +52 -1
  63. package/dist/skills/superwall-framework/SKILL.md +90 -15
  64. package/dist/skills/superwall-framework/references/cli.md +92 -21
  65. package/dist/skills/superwall-framework/references/migrate-from-editor.md +6 -2
  66. package/dist/skills/superwall-framework/references/mobile-design.md +1 -1
  67. package/dist/{skills-B8uSuanf.js → skills-B_oH2dYK.js} +8 -8
  68. package/dist/{skills-D7sG0xom.js → skills-miJDcjQ2.js} +4 -4
  69. package/dist/source-push-NVrs53Uo.js +205 -0
  70. package/dist/{spinner-TZeZEeVv.js → spinner-D6phP4Af.js} +3 -3
  71. package/dist/{storage-DqKJe13V.js → storage-BcvKhvzZ.js} +1 -1
  72. package/dist/storekit-D1A5VHT1.js +16 -0
  73. package/dist/{storekit-uyT3DWo4.js → storekit-Di3BkafX.js} +3 -3
  74. package/dist/{telemetry-D_uIIuSk.js → telemetry-BpYXL-z3.js} +1 -1
  75. package/dist/{token-BJsLGoSX.js → token-4dQOfOaK.js} +1 -1
  76. package/dist/tools-skills/animate-onboarding/SKILL.md +1 -1
  77. package/dist/tools-skills/mobile-design/SKILL.md +1 -1
  78. package/dist/tools-skills/onboarding-questions/SKILL.md +1 -1
  79. package/dist/tools-skills/superwall/SKILL.md +80 -8
  80. package/dist/tools-skills/superwall/references/api.md +116 -24
  81. package/dist/tools-skills/superwall/references/apple-setup.md +316 -0
  82. package/dist/tools-skills/superwall/references/asc.md +74 -38
  83. package/dist/tools-skills/superwall/references/data-analytics.md +62 -29
  84. package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +3 -3
  85. package/dist/tools-skills/superwall/workflows/dashboard/setup.md +8 -8
  86. package/dist/tools-skills/superwall/workflows/migrate/adapty.md +6 -6
  87. package/dist/tools-skills/superwall/workflows/migrate/playbook.md +4 -4
  88. package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +5 -5
  89. package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +6 -6
  90. package/dist/tools-skills/superwall/workflows/placements/android.md +2 -2
  91. package/dist/tools-skills/superwall/workflows/placements/expo.md +2 -2
  92. package/dist/tools-skills/superwall/workflows/placements/flutter.md +2 -2
  93. package/dist/tools-skills/superwall/workflows/placements/ios.md +2 -2
  94. package/dist/tools-skills/superwall/workflows/placements/playbook.md +2 -2
  95. package/dist/tools-skills/superwall/workflows/placements/react-native.md +2 -2
  96. package/dist/tools-skills/superwall/workflows/placements/strategy.md +2 -2
  97. package/dist/tools-skills/superwall/workflows/review/playbook.md +1 -1
  98. package/dist/tools-skills/superwall-editor/SKILL.md +2 -2
  99. package/dist/tools.d.ts +1 -1
  100. package/dist/tools.js +222 -109
  101. package/dist/{upgrade-DV_rmhyV.js → upgrade-BnOq32zn.js} +2 -2
  102. package/dist/{upgrade-BRM51As6.js → upgrade-Cb6f4S_c.js} +1 -1
  103. package/package.json +2 -2
  104. package/dist/create-kT2C9k4h.js +0 -19
  105. package/dist/held-Bwkhufdj.js +0 -16
  106. package/dist/login-Dy9N5ZDH.js +0 -16
  107. package/dist/push-BIizJJOn.js +0 -22
  108. package/dist/scan-DjyvuWel.js +0 -4
  109. package/dist/server-BTveynqC.js +0 -22
  110. package/dist/session-Ds6tLC19.js +0 -6
  111. package/dist/storekit-C_LFh8qy.js +0 -16
  112. /package/dist/{reports-D_qbl7_u.js → reports-CwwKLUh0.js} +0 -0
  113. /package/dist/{storage-BbJF7z3l.d.ts → storage-gRyQetN9.d.ts} +0 -0
@@ -26,7 +26,7 @@ superwall products create --identifier <identifier> \
26
26
  --trial-days 7 \ # optional free-trial length
27
27
  --entitlement pro \ # entitlement(s) to grant; repeat --entitlement for more
28
28
  --name "Pro Yearly" \ # optional display name
29
- --project <id> --json
29
+ --app <id> --json # the app the entitlement is on
30
30
  ```
31
31
 
32
32
  Use the **real store product identifiers** (the ones in App Store Connect / Google Play), e.g.
@@ -53,7 +53,7 @@ superwall asc products com.app.bundle --json # everything
53
53
  superwall asc apps --json # list ASC apps if unsure of the id
54
54
 
55
55
  # create each returned productId, granting your entitlement
56
- superwall products create --identifier com.app.pro.yearly --entitlement pro --project <id> --json
56
+ superwall products create --identifier com.app.pro.yearly --entitlement pro --app <id> --json
57
57
  ```
58
58
 
59
59
  Products imported this way carry only the identifier (and reference name); Xcode/StoreKit and
@@ -71,11 +71,14 @@ Seeds product identifiers into a StoreKit configuration file; Xcode refines pric
71
71
 
72
72
  ```bash
73
73
  superwall entitlements list --project <id> --json
74
- superwall entitlements create --identifier pro --project <id> --json
74
+ superwall entitlements create --identifier pro --app <id> --json
75
75
  ```
76
76
 
77
77
  Default to a single coarse `pro` entitlement. Add more only for genuine tiers (e.g. `pro`,
78
- `team`). Products grant entitlements via `--entitlement` at create time.
78
+ `team`). Products grant entitlements via `--entitlement` (id or identifier) at create time.
79
+ Pass the same `--app <id>` to the entitlement and the product: a native product only grants
80
+ entitlements on its own app. CLI 2.2.1 and older take only the numeric id from
81
+ `superwall entitlements list --json`; run `superwall upgrade` once a newer CLI is out.
79
82
 
80
83
  ## Campaigns + placements
81
84
 
@@ -91,7 +94,9 @@ superwall campaigns placements create <campaignId> --event-name another_placemen
91
94
 
92
95
  ## What the CLI cannot do (leave manual)
93
96
 
94
- - **Design the paywall** - in the dashboard's paywall editor.
97
+ - **Design the paywall** - either as code with the superwall framework (`superwall create` scaffolds
98
+ a `superwall/` directory in the app; products are declared in the paywall's `config.ts`;
99
+ `superwall publish` ships it) or in the dashboard's paywall editor.
95
100
  `superwall paywalls list --project <id> --app <id> --json` shows what exists.
96
101
  - **Configure audiences / experiment splits** beyond the default - done in the dashboard.
97
102
 
@@ -70,8 +70,10 @@ While reading the app, note any screen the user would rather change
70
70
  without a release: a paywall or offer, onboarding, an update-required or
71
71
  force-upgrade screen, a rate-us or notifications prompt, an announcement,
72
72
  a consent change. Mention them in your closing note as candidates for a
73
- Superwall paywall or onboarding (built in the dashboard editor) behind a
74
- placement. Don't build them here; the placements step wires the triggers.
73
+ Superwall surface (`superwall create` in the app, built with the
74
+ `superwall-framework` skill) behind a placement. Don't build them here;
75
+ the placements step wires the triggers and the framework skill builds the
76
+ screens.
75
77
 
76
78
  ## Definition of done
77
79
 
@@ -15,12 +15,12 @@ This migrates the **SDK integration**, not the whole product. Checklist:
15
15
  - [ ] Swap SDK calls (activate→configure, access-level reads, present → placement, identify) (§5)
16
16
  - [ ] Build + verify each placement; Restore Purchases as an existing subscriber (§7)
17
17
  - [ ] FULL only: remove Adapty dependency once verified
18
- - [ ] Hand back to user: **rebuild paywalls** (dashboard editor), attach products, connect ASC/Play
18
+ - [ ] Hand back to user: **rebuild paywalls** (superwall framework or dashboard editor), attach products, connect ASC/Play
19
19
 
20
20
  > **Important - what does NOT migrate:**
21
21
  >
22
22
  > - **Adapty paywall designs** (Paywall Builder / remote config) cannot be imported - they are
23
- > **rebuilt** in the dashboard editor.
23
+ > **rebuilt** - as code with the superwall framework or in the dashboard editor.
24
24
  > - **Historical analytics / attribution** stays in Adapty.
25
25
  > - **Subscriber base:** there is currently no server-side subscriber migration from Adapty.
26
26
  > Existing subscribers keep access because their purchases live with the store (StoreKit /
@@ -119,13 +119,14 @@ Produce: product ids, access-level ids (→ entitlements), and one row per `getP
119
119
  ## 4. Dashboard-side re-creation (CLI)
120
120
 
121
121
  ```bash
122
- superwall entitlements create --identifier premium --project <projectId> --json
123
- superwall products create --identifier com.app.premium_monthly --name "Premium Monthly" --project <projectId> --json
124
- superwall products create --identifier com.app.premium_yearly --name "Premium Yearly" --project <projectId> --json
122
+ superwall entitlements create --identifier premium --app <appId> --json
123
+ superwall products create --identifier com.app.premium_monthly --name "Premium Monthly" --entitlement premium --app <appId> --json
124
+ superwall products create --identifier com.app.premium_yearly --name "Premium Yearly" --entitlement premium --app <appId> --json
125
125
  superwall campaigns create --description "Main paywall" --placement main --project <projectId> --app <appId> --json
126
126
  superwall campaigns placements create <campaignId> --event-name onboarding --project <projectId> --app <appId> --json
127
127
  ```
128
128
 
129
+ Each product MUST grant the entitlements it unlocked in the old provider (`--entitlement <identifier>`, repeat for several); a product with none unlocks nothing. CLI 2.2.1 and older take only the numeric id from `superwall entitlements list --json`.
129
130
  Product ids MUST equal existing App Store / Play SKUs (import from ASC via `superwall asc keys create --help`).
130
131
  Verify with the same explicit ids: `superwall entitlements list --project <projectId> --json`,
131
132
  `superwall products list --project <projectId> --json`, and `superwall campaigns list --project <projectId> --app <appId> --json`.
@@ -191,7 +192,7 @@ regardless) vs gated (only when entitled). Peek: `Superwall.shared.getPresentati
191
192
  ## 7. Order of operations + safety
192
193
 
193
194
  1. Re-create entitlements/products/campaign+placements (CLI); import products from ASC/Play so ids match.
194
- 2. **Rebuild** paywalls (dashboard editor), attach products (hand-back to user - designs do not import).
195
+ 2. **Rebuild** paywalls (superwall framework or dashboard editor), attach products (hand-back to user - designs do not import).
195
196
  3. Add Superwall SDK alongside Adapty; configure it.
196
197
  4. Replace `getPaywall`/present call sites with `register(placement:)`; replace access-level reads with `subscriptionStatus`.
197
198
  5. Build, present each placement, Restore Purchases as an existing subscriber, confirm `subscriptionStatus.isActive`.
@@ -2,7 +2,8 @@
2
2
 
3
3
  > **Important - what does and does not migrate:**
4
4
  >
5
- > - Paywall designs are rebuilt from scratch in the dashboard editor.
5
+ > - Paywall designs are rebuilt from scratch - as code with the superwall framework
6
+ > (`superwall create`) or in the dashboard editor.
6
7
  > - Historical analytics and attribution stay in the old provider.
7
8
  > - Adapty/Qonversion subscribers do not currently move server-side; existing
8
9
  > purchases are recovered from the store through Restore Purchases.
@@ -68,9 +69,9 @@ Agents always use `--json` and explicit scope:
68
69
  superwall whoami --json
69
70
  superwall apps list --json
70
71
  superwall entitlements list --project <projectId> --json
71
- superwall entitlements create --identifier <id> --project <projectId> --json
72
+ superwall entitlements create --identifier <id> --app <appId> --json
72
73
  superwall products list --project <projectId> --json
73
- superwall products create --identifier <storeId> --project <projectId> --json
74
+ superwall products create --identifier <storeId> --entitlement <id> --app <appId> --json
74
75
  superwall campaigns list --project <projectId> --app <appId> --json
75
76
  superwall campaigns create --description "<description>" --placement <placement> --project <projectId> --app <appId> --json
76
77
  superwall campaigns placements create <campaignId> --event-name <placement> --project <projectId> --app <appId> --json
@@ -15,11 +15,11 @@ This migrates the **SDK integration**, not the whole product. Checklist:
15
15
  - [ ] Swap SDK calls (init→configure, entitlement reads, present → placement, identify) (§5)
16
16
  - [ ] Build + verify each placement; Restore Purchases as an existing subscriber (§7)
17
17
  - [ ] FULL only: remove Qonversion dependency once verified
18
- - [ ] Hand back to user: **rebuild paywalls** (dashboard editor), attach products, connect ASC/Play
18
+ - [ ] Hand back to user: **rebuild paywalls** (superwall framework or dashboard editor), attach products, connect ASC/Play
19
19
 
20
20
  > **Important - what does NOT migrate:**
21
21
  >
22
- > - **Qonversion paywall UI** cannot be imported - paywalls are **rebuilt** in the dashboard editor.
22
+ > - **Qonversion paywall UI** cannot be imported - paywalls are **rebuilt** - as code with the superwall framework or in the dashboard editor.
23
23
  > - **Historical analytics / attribution** stays in Qonversion.
24
24
  > - **Subscriber base:** there is currently no server-side subscriber migration from Qonversion.
25
25
  > Existing subscribers keep access because their purchases live with the store (StoreKit /
@@ -116,12 +116,13 @@ Produce: product ids, entitlement/permission ids (→ entitlements), and one row
116
116
  ## 4. Dashboard-side re-creation (CLI)
117
117
 
118
118
  ```bash
119
- superwall entitlements create --identifier premium --project <projectId> --json
120
- superwall products create --identifier com.app.premium_monthly --name "Premium Monthly" --project <projectId> --json
121
- superwall products create --identifier com.app.premium_yearly --name "Premium Yearly" --project <projectId> --json
119
+ superwall entitlements create --identifier premium --app <appId> --json
120
+ superwall products create --identifier com.app.premium_monthly --name "Premium Monthly" --entitlement premium --app <appId> --json
121
+ superwall products create --identifier com.app.premium_yearly --name "Premium Yearly" --entitlement premium --app <appId> --json
122
122
  superwall campaigns create --description "Main paywall" --placement paywall_main --project <projectId> --app <appId> --json
123
123
  ```
124
124
 
125
+ Each product MUST grant the entitlements it unlocked in the old provider (`--entitlement <identifier>`, repeat for several); a product with none unlocks nothing. CLI 2.2.1 and older take only the numeric id from `superwall entitlements list --json`.
125
126
  Product ids MUST equal existing App Store / Play SKUs (import from ASC via `superwall asc keys create --help`).
126
127
  Verify with the same explicit ids: `superwall entitlements list --project <projectId> --json`,
127
128
  `superwall products list --project <projectId> --json`, and `superwall campaigns list --project <projectId> --app <appId> --json`.
@@ -189,7 +190,7 @@ regardless) vs gated (only when entitled). Peek: `Superwall.shared.getPresentati
189
190
  ## 7. Order of operations + safety
190
191
 
191
192
  1. Re-create entitlements/products/campaign+placements (CLI); import products from ASC/Play so ids match.
192
- 2. **Rebuild** paywalls (dashboard editor), attach products (hand-back to user - designs do not import).
193
+ 2. **Rebuild** paywalls (superwall framework or dashboard editor), attach products (hand-back to user - designs do not import).
193
194
  3. Add Superwall SDK alongside Qonversion; configure it.
194
195
  4. Replace offering-fetch/present call sites with `register(placement:)`; replace `checkEntitlements` reads with `subscriptionStatus`.
195
196
  5. Build, present each placement, Restore Purchases as an existing subscriber, confirm `subscriptionStatus.isActive`.
@@ -26,11 +26,11 @@ This migrates the **SDK integration**, not the whole product. Checklist:
26
26
  `pk_` key / bundle id BEFORE any create; wrong account → stop dashboard work loudly (§4)
27
27
  - [ ] Build + verify each placement; Restore Purchases as an existing subscriber (§7)
28
28
  - [ ] FULL only: remove RC dependency once verified
29
- - [ ] Hand back to user: **rebuild paywalls** (dashboard editor), attach products, connect ASC/Play
29
+ - [ ] Hand back to user: **rebuild paywalls** (superwall framework or dashboard editor), attach products, connect ASC/Play
30
30
 
31
31
  > **Important - what does and does NOT migrate:**
32
32
  >
33
- > - **RC paywall designs** cannot be imported - they are **rebuilt** in the dashboard editor.
33
+ > - **RC paywall designs** cannot be imported - they are **rebuilt** - as code with the superwall framework or in the dashboard editor.
34
34
  > - **Historical analytics / attribution** stays in RevenueCat.
35
35
  > - **Subscriber base:** Superwall provides server-side RevenueCat migration tooling that ports
36
36
  > subscription history and entitlement state - fetch the migration guide (Docs access below)
@@ -53,7 +53,7 @@ curl -sL https://www.revenuecat.com/docs/llms.txt
53
53
  | RevenueCat | Superwall | Notes |
54
54
  | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
55
55
  | Product (store SKU wrapped in RC dashboard) | **Product** (re-created) | Keep the SAME App Store / Play product identifier. Only the management layer moves. |
56
- | Package (`$rc_monthly`, inside an Offering) | (no direct equal) | A package is just "product + duration slot." In Superwall you attach the raw products to a paywall (in the editor). |
56
+ | Package (`$rc_monthly`, inside an Offering) | (no direct equal) | A package is just "product + duration slot." In Superwall you attach the raw products to a paywall (in its `config.ts` with the framework, or in the editor). |
57
57
  | Offering (remote set of packages) | **Paywall** + **Campaign** | RC picks products remotely via Offering; Superwall picks the whole paywall (products included) remotely via Campaign rules. |
58
58
  | Entitlement (e.g. `pro`) | **Entitlement** (re-created) | 1:1. Recreate each RC entitlement id as a Superwall entitlement. |
59
59
  | `customerInfo.entitlements.active` | `Superwall.shared.subscriptionStatus` (`.active(Set<Entitlement>)` / `.inactive` / `.unknown`) | Status is device-derived in FULL mode. |
@@ -203,11 +203,12 @@ call the migration complete with dashboard work silently skipped.
203
203
  For each entitlement and product found, use the project/app ids from the account gate:
204
204
 
205
205
  ```bash
206
- superwall entitlements create --identifier pro --project <projectId> --json
207
- superwall products create --identifier com.app.pro_monthly --name "Pro Monthly" --project <projectId> --json
208
- superwall products create --identifier com.app.pro_yearly --name "Pro Yearly" --project <projectId> --json
206
+ superwall entitlements create --identifier pro --app <appId> --json
207
+ superwall products create --identifier com.app.pro_monthly --name "Pro Monthly" --entitlement pro --app <appId> --json
208
+ superwall products create --identifier com.app.pro_yearly --name "Pro Yearly" --entitlement pro --app <appId> --json
209
209
  ```
210
210
 
211
+ Each product MUST grant the entitlements it unlocked in the old provider (`--entitlement <identifier>`, repeat for several); a product with none unlocks nothing. CLI 2.2.1 and older take only the numeric id from `superwall entitlements list --json`.
211
212
  Product ids MUST equal the existing App Store / Play SKUs (import via ASC connection instead of
212
213
  manual create when possible - `superwall asc keys create --help`). Then one campaign with
213
214
  a placement per call site:
@@ -358,7 +359,7 @@ Set per placement in the paywall editor (**General → Feature Gating**):
358
359
  ## 7. Order of operations + safety
359
360
 
360
361
  1. Re-create entitlements, products, campaign + placements in the dashboard (CLI). Import products from ASC/Play so ids match.
361
- 2. **Rebuild** paywalls (dashboard editor) and attach products (hand-back to user - designs do not import).
362
+ 2. **Rebuild** paywalls (superwall framework or dashboard editor) and attach products (hand-back to user - designs do not import).
362
363
  3. Add Superwall SDK alongside RC (don't rip RC yet). Configure it.
363
364
  4. Replace presentation call sites with `register(placement:)`; replace entitlement reads with `subscriptionStatus`.
364
365
  5. Build, run, present each placement; **Restore Purchases** as an existing subscriber and confirm `subscriptionStatus.isActive`.
@@ -1,10 +1,47 @@
1
1
  ---
2
2
  name: superwall-editor
3
- description: Build, edit, or review Superwall paywall, onboarding, and web2app flows from a local coding agent with terminal access. Launch a browser editor session through the local CLI or attach to one with a pairing code, then discover its current tools. Covers native sw-* elements, design standards, and the attach/call/release lifecycle.
3
+ description: LEGACY — drives the browser (visual) paywall editor over a pairing code. For any screen an agent builds, use superwall-framework instead (paywalls, onboarding, update-required, lifecycle prompts, announcements, offers and web flows, as React code); to move an existing editor paywall onto it, run `superwall migrate <paywall-id>`. Use this skill only when the user explicitly wants to edit inside the visual editor, or to read an editor paywall before migrating it. Covers attach/call/release, native sw-* elements and the editor tool surface.
4
4
  ---
5
5
 
6
6
  # Superwall Paywall Editor
7
7
 
8
+ > [!WARNING]
9
+ > **LEGACY. For agents, the visual editor is the second choice.** Any screen
10
+ > an agent builds (a paywall, an onboarding, an update-required screen, a
11
+ > lifecycle prompt, an announcement, an offer, a web flow) belongs in the
12
+ > **superwall framework**: a React mini-app in the user's repo, reviewed as
13
+ > code, localized from message files, previewed in the studio on every
14
+ > device, and shipped with `superwall push` / `promote`. Use the
15
+ > `superwall-framework` skill. If it isn't installed:
16
+ >
17
+ > ```bash
18
+ > npx skills add https://github.com/superwall/skills --skill superwall-framework --global --yes --agent claude-code universal --full-depth
19
+ > ```
20
+ >
21
+ > The framework is in public beta and the CLI has its commands by default
22
+ > (an `Unknown command: create` means an older CLI: ask the user to run `superwall upgrade`).
23
+ >
24
+ > **An editor paywall moves over in one command:**
25
+ >
26
+ > ```bash
27
+ > superwall migrate <paywall-id>
28
+ > ```
29
+ >
30
+ > It scaffolds the paywall as code, briefs the rebuild (the framework
31
+ > skill's `references/migrate-from-editor.md` is the playbook), and shows
32
+ > the original beside the new one in the studio (Compare › Original). The
33
+ > original keeps serving until a campaign is switched to the new one, so
34
+ > nothing changes for users until then.
35
+ >
36
+ > **What to do here:**
37
+ >
38
+ > - Asked to build any new screen: build it with the framework, not here.
39
+ > - Asked to change an editor paywall: offer the migration first, in one
40
+ > line, saying what it gains (code review, localization files, any
41
+ > component library, the same studio for every screen). If the user
42
+ > says no or wants a quick edit in place, continue with this skill.
43
+ > - Never migrate unprompted, and never refuse an explicit editor request.
44
+
8
45
  Paywalls are built in a browser editor that exposes its tools over an authenticated relay. This skill drives the same surface used by the MCP gateway, so every tool runs inside the live browser session the user has open.
9
46
 
10
47
  ## When to use
@@ -59,3 +96,17 @@ Full CLI reference: [references/cli.md](references/cli.md).
59
96
  - `session_locked`: another client is already attached. The user either attached from another MCP client, or a previous CLI attachment wasn't released. They can detach from the editor UI and you can retry.
60
97
  - `unauthorized`: the controller token is stale. Re-attach with a fresh pairing code.
61
98
  - `attach_failed: provide a valid current pairingCode`: pairing codes expire after ~10 minutes and rotate on detach. Ask the user to show you the current one.
99
+
100
+ ## Report what's broken
101
+
102
+ When you confirm an editor tool misbehaves (wrong result, a crash, a schema
103
+ that doesn't match `tools`, a doc here that's wrong), report it yourself:
104
+ write it with every ID needed to reproduce it, tell the user in one line,
105
+ send on their yes (or straight away if they've said you may). Strip secrets
106
+ and customer data.
107
+
108
+ ```bash
109
+ superwall feedback "Called X with Y; expected Z; got W." --title "..." \
110
+ --kind bug --command "sw-editor.sh call <tool>" --app <id> \
111
+ --context paywall=<id> --file error.json --json
112
+ ```
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: superwall-framework
3
- description: Author any screen an app should be able to change without a release — paywalls, offers, onboarding funnels, update-required and force-upgrade screens, lifecycle prompts, announcements, web checkout flows — as React mini-apps with the superwall framework (the `superwall` npm package). Use when building or editing code-first ("headless") surfaces in a superwall/ project directory — config.ts, app/ routes, hooks (useProducts, usePurchase, useDiscount, useActions…), navigation, localization, assets, insets and mobile layout — when running `superwall create/dev/push/promote/publish`, when rebuilding a dashboard (visual editor) paywall as code (`superwall migrate <id>`), or when a native SwiftUI / Kotlin / React Native / Flutter screen of that kind is being built and should become a Superwall surface instead. The default for any screen an agent builds that the user would rather change after shipping than release for (paywalls, onboarding, update-required, lifecycle prompts, announcements, offers, web flows); the browser visual editor (superwall-editor) is legacy and only for explicit edits inside it. NOT for general CLI/resource management (superwall).
3
+ description: Author any screen an app should be able to change without a release — paywalls, offers, onboarding funnels, update-required and force-upgrade screens, lifecycle prompts, announcements, web checkout flows — as React mini-apps with the superwall framework (the `superwall` npm package). Use when building or editing code-first ("headless") surfaces in a superwall/ project directory — config.ts, app/ routes, hooks (useProducts, usePurchase, useDiscount, useActions…), navigation, localization, assets, insets and mobile layout — when running `superwall create/dev/push/promote/publish/pull` (including pulling a teammate's paywalls or an app's source into an empty folder with `superwall pull --app`), when rebuilding a dashboard (visual editor) paywall as code (`superwall migrate <id>`), or when a native SwiftUI / Kotlin / React Native / Flutter screen of that kind is being built and should become a Superwall surface instead. The default for any screen an agent builds that the user would rather change after shipping than release for (paywalls, onboarding, update-required, lifecycle prompts, announcements, offers, web flows); the browser visual editor (superwall-editor) is legacy and only for explicit edits inside it. NOT for general CLI/resource management (superwall).
4
4
  ---
5
5
 
6
6
  # The superwall framework
@@ -43,11 +43,10 @@ Entry points: `superwall` (SuperwallProvider — mounted for you),
43
43
  `superwall/config`, `superwall/hooks`, `superwall/navigation`,
44
44
  `superwall/assets`.
45
45
 
46
- The framework ships on the `next` channel. The CLI has
47
- `create`/`dev`/`push`/`promote`/`publish` and the rebuild forms of `migrate`
48
- only while `SUPERWALL_CHANNEL=next` is set in the environment.
49
- `Unknown command: create` means the variable is missing from your
50
- environment: ask the user to set it globally (shell rc) and relaunch.
46
+ The framework is in public beta. The CLI has `create`/`dev`/`push`/`promote`/`publish`
47
+ and the rebuild forms of `migrate` by default. `Unknown command: create` means
48
+ the installed CLI is older than the framework commands: ask the user to run
49
+ `superwall upgrade`, then try again.
51
50
 
52
51
  ## Local references — the agent playbooks
53
52
 
@@ -59,11 +58,11 @@ web page inside an app.
59
58
  | --- | --- |
60
59
  | **Any onboarding, quiz, survey or multi-page funnel that asks questions — must-follow.** Every answer a typed user attribute (`useUserAttribute`) saved the moment it is given, one `next` for the buttons and `entry`, `replayStack` resuming at the first unanswered question of the user's branch, attribute naming, back and "Start over" after resuming | [references/onboarding-state.md](references/onboarding-state.md) |
61
60
  | The layout system — the DOM the framework renders, what fixed / absolute / sticky resolve against, insets (config, variables, precedence, the floor table per device and presentation), scrolling, recipes, and the debugging order for "it's under the status bar" | [references/layout.md](references/layout.md) |
62
- | Mobile design craft — press feedback, hover gating, inputs and the keyboard, motion values, type, worst-case content, dark mode, platform conventions, the pre-ship audit. **Read it for every new screen, and especially when there is no design reference: its values are then the design.** | the **`mobile-design`** skill (install: `npx skills add https://github.com/superwall/skills/tree/next --skill mobile-design --global --yes --agent claude-code universal --full-depth`); what the framework adds to it (the skeleton, insets, scrolling, its hooks) is [references/mobile-design.md](references/mobile-design.md) |
63
- | Writing the questions of an onboarding or web2app funnel — what to ask, in what order, the branching, the statements, which answers predict revenue | the **`onboarding-questions`** skill (install: `npx skills add https://github.com/superwall/skills/tree/next --skill onboarding-questions --global --yes --agent claude-code universal --full-depth`) |
61
+ | Mobile design craft — press feedback, hover gating, inputs and the keyboard, motion values, type, worst-case content, dark mode, platform conventions, the pre-ship audit. **Read it for every new screen, and especially when there is no design reference: its values are then the design.** | the **`mobile-design`** skill (install: `npx skills add https://github.com/superwall/skills --skill mobile-design --global --yes --agent claude-code universal --full-depth`); what the framework adds to it (the skeleton, insets, scrolling, its hooks) is [references/mobile-design.md](references/mobile-design.md) |
62
+ | Writing the questions of an onboarding or web2app funnel — what to ask, in what order, the branching, the statements, which answers predict revenue | the **`onboarding-questions`** skill (install: `npx skills add https://github.com/superwall/skills --skill onboarding-questions --global --yes --agent claude-code universal --full-depth`) |
64
63
  | Animating an onboarding's page hand-offs — the chosen answer becoming the progress bar or the next hero, exits and entrances tied to the copy, mapped onto the router | the **`animate-onboarding`** skill (install: `… --skill animate-onboarding …`) |
65
64
  | Responsive — 320px → tablet → desktop, short phones, landscape, dynamic type, sheets/drawers/popups, the verification matrix | `references/responsive.md` in the **`mobile-design`** skill |
66
- | dev/push/promote/publish, creating products yourself, renames, several platforms, CI | [references/cli.md](references/cli.md) |
65
+ | dev/push/promote/publish, `superwall pull` (teammates' work, conflicts, `--theirs`, `pull --app` into an empty folder), creating products yourself, renames, several platforms, CI | [references/cli.md](references/cli.md) |
67
66
  | Migrating a dashboard (visual editor) paywall to code — `superwall create --from <id>`, reading the editor's document store, the element / action / state mapping, Compare › Original, the review gate, the campaign switch, and the rebuild playbook the CLI hands its agent | [references/migrate-from-editor.md](references/migrate-from-editor.md) |
68
67
  | Migrating a native screen to a surface — `superwall migrate --screen <path>`, what the scan reads, the screenshot original, the rebuild playbook, wiring `register()` afterwards | [references/migrate-from-native.md](references/migrate-from-native.md) |
69
68
  | What each native construct becomes, per source framework, and the `register()` wiring in that SDK | [references/native/ios.md](references/native/ios.md) (SwiftUI, UIKit) · [android.md](references/native/android.md) (Compose, Views) · [react-native.md](references/native/react-native.md) · [flutter.md](references/native/flutter.md) |
@@ -89,7 +88,7 @@ curl -sL https://superwall.com/docs/framework/{page}.md # one page
89
88
  | Declaring products, reading variables, the three price rules | `products` |
90
89
  | `purchase()` outcomes, restore, the two channels | `purchases` |
91
90
  | Introductory-offer eligibility forking (`useIntroductoryOffer`), reminder notifications | `trials` |
92
- | Selling on the web — modes, prefetch, the Stripe sheet, hosted checkout, promotion codes (`useDiscount`), the shopper's email, after the purchase (`postPurchase`, `useCheckoutRedemption`), `stripeMetadata`, managed payments; a Stripe product inside an iOS app (app to web: always hosted checkout, priced from the dashboard at push) | `web-checkout`, `products` |
91
+ | Selling on the web — modes, prefetch, the Stripe sheet, hosted checkout, promotion codes (`useDiscount`), the shopper's email, after the purchase (`postPurchase`, `useCheckoutRedemption`), `stripeMetadata`, managed payments, blocking prepaid cards (`prepaidCards`), direct Apple Pay availability (`useApplePay`, `examples/apple-pay`); a Stripe product inside an iOS app (app to web: always hosted checkout, priced from the dashboard at push) | `web-checkout`, `products` |
93
92
  | Custom store products (external purchase controller, custom-store Stripe products) — declared by identifier, pushed with the dashboard's store | `products` |
94
93
  | Continuing a flow on the web (teleport: `teleport: true` or `{ route, fallbacks, completion, … }`, `router.push(route, { teleport: true })`, prefetch, the teleport screen, `useTeleport`'s typed status, returning to the app) | `teleport` |
95
94
  | Web funnels — answers in the URL (`useQueryState`), resume after a browser hand-off, `shift` | `web-funnels` |
@@ -133,6 +132,11 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
133
132
  `stripeMetadata` to `purchase()` for key/values on the Stripe subscription,
134
133
  and `checkout` to override the config's mode for one button (never past
135
134
  the iOS rule: in an iOS app a Stripe purchase always opens hosted checkout).
135
+ `prepaidCards: "block"` in `checkout: { mode, prepaidCards }` makes Stripe
136
+ refuse prepaid cards on the sheet and hosted checkout (default `"allow"`);
137
+ `purchase()` and `prefetch()` take `prepaidCards` to override it for one
138
+ product, and a teleport carries the rule to the web page. Apple Pay can't
139
+ filter card types, so in `applePay` mode only the sheet fallback enforces it.
136
140
  The shape every buy button has, all three outcomes handled:
137
141
 
138
142
  ```tsx
@@ -141,6 +145,58 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
141
145
  else if (result.status === "failed") setNotice(t("purchase.failed")); // iOS only; say so, keep the button
142
146
  // abandoned: the user closed the store sheet — nothing changes, nothing is said
143
147
  ```
148
+
149
+ The embedded Stripe sheet waits 10 s after a tap for Stripe's checkout
150
+ to be ready. The wait only hides the spinner and resolves `failed`: Stripe
151
+ keeps loading, the buyer stays on the paywall, and the next tap opens the
152
+ sheet at once, with no redirect to hosted checkout. Picking plans keeps the
153
+ checkout already prepared, so `prefetch()` on plan selection costs nothing;
154
+ only a tap on another plan swaps it. Each step of a tap is logged to the
155
+ page console as `[superwall] checkout <stage> +<ms>ms` (`tap`,
156
+ `session_ready`, `stripe_js_loaded`, `embedded_mounted`,
157
+ `checkout_rendered`, `ready_timeout`, `stripe_error`), with Stripe's error
158
+ on `stripe_error`; read them in Safari Web Inspector or Chrome DevTools to
159
+ debug a slow checkout before changing the paywall.
160
+
161
+ `useApplePay()` says whether direct Apple Pay (the wallet the browser
162
+ opens itself) is available, from `ApplePaySession.canMakePayments()`,
163
+ known on the first render. Web hosts only (Web SDK, hosted web paywall,
164
+ teleport page, plain browser): `{ available: true }` or
165
+ `{ available: false, reason, message, error? }`; `undefined` in the iOS
166
+ and Android SDKs and Studio. `reason` (`ApplePayUnavailableReason`) is
167
+ `unsupported_browser` (no Apple Pay JS, as in desktop Chrome — its card
168
+ sheet may still offer Apple Pay by QR code, which is not direct Apple
169
+ Pay), `insecure_context` (not HTTPS, `http://localhost` included),
170
+ `device_unsupported`, `cross_origin_frame` or `check_failed`; `error` is
171
+ `{ name, message }` when the check threw. Only Stripe sees the cards in
172
+ Wallet and the domain's registration: `useApplePay(product)` adds
173
+ `product: { status: "preparing" | "ready" | "unavailable", reason?,
174
+ message?, error? }`. Its `reason` is the browser's when the browser can't
175
+ pay, else an `ApplePayWalletReason`: `not_prepared` means nothing has
176
+ prepared that product's wallet yet, not that the device can't pay;
177
+ `stripe_declined` means no card in Wallet, an unregistered domain or
178
+ Safari's Apple Pay check setting off; the rest (`stripe_check_failed`,
179
+ `stripe_load_failed`, `missing_public_api_key`, `session_failed`,
180
+ `session_unsupported`, `show_failed`) name the step that failed. The
181
+ wallet opens only for a product prepared before the tap: config
182
+ `checkout: "applePay"` prepares it on its own, a `"sheet"` paywall calls
183
+ `prefetch(ref, { checkout: "applePay" })`, and an unprepared tap opens
184
+ the sheet. Any other config `checkout` sends a Stripe purchase to the
185
+ hosted page. Types come from `superwall/hooks`; `examples/apple-pay`
186
+ renders the hook.
187
+
188
+ ```tsx
189
+ const { purchase, prefetch } = usePurchase();
190
+ const applePay = useApplePay(reference);
191
+ useEffect(() => {
192
+ if (applePay?.available) prefetch(reference, { checkout: "applePay" });
193
+ }, [applePay?.available, prefetch, reference]);
194
+ return applePay?.available && applePay.product.status === "ready" ? (
195
+ <button onClick={() => purchase(reference, { checkout: "applePay" })}>Apple Pay</button>
196
+ ) : (
197
+ <button onClick={() => purchase(reference, { checkout: "sheet" })}>Pay with card</button>
198
+ );
199
+ ```
144
200
  3. **Entry animations key off `paywall_open`, never mount** — the SDK
145
201
  preloads paywalls hidden. Gate on
146
202
  `useSuperwallSnapshot().paywall !== undefined`. That includes CSS:
@@ -257,7 +313,12 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
257
313
  Store products differ per store, so a shared slot takes one id per
258
314
  platform — `annual: { ios: "…", android: "…" }` — while
259
315
  `purchase("annual")` stays the same call; the slot must name every
260
- platform the paywall ships to. UI one platform must never show
316
+ platform the paywall ships to. An App Store product that offers Apple's
317
+ monthly plan (12-month commitment, billed monthly) sells it by default;
318
+ a slot picks its plan with `billingPlan: "monthly" | "upFront"` —
319
+ `{ productId: "pro_annual", billingPlan: "upFront" }` or
320
+ `{ ios: "pro_annual", android: "pro_annual_play", billingPlan: "upFront" }`
321
+ (iOS only; details in [references/cli.md](references/cli.md)). UI one platform must never show
261
322
  (restore, sign-out, an App Store exit offer) branches on
262
323
  `useDevice().hostPlatform` — `"ios" | "android" | "web" | undefined`,
263
324
  normalized and known from the first render — never on the raw
@@ -266,7 +327,17 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
266
327
  merchant's site vs Superwall's hosted web paywall page, the teleport
267
328
  page, the studio) branches on `useDevice().host` — `"ios-sdk" |
268
329
  "android-sdk" | "web-sdk" | "web-paywall" | "web-teleport" | "studio" |
269
- "browser"`, never `undefined` — never on the URL or `window`. A
330
+ "browser"`, never `undefined` — never on the URL or `window`. UI that
331
+ depends on which browser shows the page (an "open in Safari" hint for a
332
+ funnel opened from an Instagram ad) branches on `useDevice().browser` —
333
+ `SuperwallBrowser | undefined`, known from the first render — never on
334
+ `navigator.userAgent`. It names an app's in-app browser (`"instagram"`,
335
+ `"facebook"`, `"tiktok"`, `"snapchat"`, `"pinterest"`, `"linkedin"`,
336
+ `"twitter"`, `"wechat"`, `"line"`; the `SuperwallInAppBrowser` type) or a
337
+ regular one (`"safari"`, `"chrome"`, `"firefox"`, `"edge"`, `"samsung"`,
338
+ `"opera"`), and is `undefined` inside a native SDK paywall (its web view,
339
+ Android's included) or for a browser it does not recognize; there is no
340
+ separate in-app flag, the name says it. A
270
341
  `"web"` paywall runs inside the Web SDK on the merchant's page, which
271
342
  hosts it as the web paywall app hosts editor paywalls: the SDK prices
272
343
  the Stripe products, reports the events and finishes the checkout, so
@@ -384,9 +455,13 @@ debugging order in [references/layout.md](references/layout.md) finds it
384
455
  from the devtools console in under a minute; don't guess at CSS first.
385
456
 
386
457
  Before promising a push will work, check that every product named in a
387
- `config.ts` exists on the dashboard. A push merges onto teammates' source
388
- and stops naming the files when it can't; `--overwrite-source` discards
389
- their work, so pass it only when the user says to
458
+ `config.ts` exists on the dashboard. A push writes only the pushed
459
+ paywall's folder, the shared files and its own `superwall.lock` entries;
460
+ teammates' other paywalls stay as the source repo has them. When it stops
461
+ naming files, run `superwall pull` and push again. `--overwrite-source`
462
+ replaces only the pushed paywall's source but discards teammates' edits to
463
+ it, so pass it only when the user says to. In an empty folder,
464
+ `superwall pull --app <id>` gets every paywall of an app without GitHub
390
465
  ([references/cli.md](references/cli.md)).
391
466
 
392
467
  ## Report what's broken