@superwall/cli 2.6.0-beta.2 → 2.6.1

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 (152) hide show
  1. package/README.md +47 -16
  2. package/dist/{apple-Dc5pOPms.js → apple-BE1GBJFP.js} +17 -19
  3. package/dist/{approve-BSbdmOez.js → approve-yRZmvkCj.js} +9 -11
  4. package/dist/{assets-C_RjojkK.js → assets-DTAgbWw0.js} +3 -3
  5. package/dist/auth.d.ts +11 -4
  6. package/dist/auth.js +4 -5
  7. package/dist/base-zc1wl_9b.js +82 -0
  8. package/dist/{billing-B6HK-F_a.js → billing-C1LV4-BN.js} +3 -3
  9. package/dist/{build-DK88pTMW.js → build-CQd-pf7O.js} +35 -16
  10. package/dist/{client-x08fpvay.js → config-DCqRQTJ4.js} +162 -15
  11. package/dist/create-CSHGZDfB.js +18 -0
  12. package/dist/{create-kpqEhqkk.js → create-Costu6UT.js} +9 -9
  13. package/dist/{create-B6-Dr3GZ.js → create-wlCp83IH.js} +41 -41
  14. package/dist/{doctor-DYbm8IKQ.js → doctor-Bd9ffg51.js} +50 -10
  15. package/dist/entry.js +45 -40
  16. package/dist/{environment-BFNzLLPN.js → environment-Dn7irhZr.js} +1 -1
  17. package/dist/{drivers-Dyi-y9Jn.js → existing-BQMB_2AG.js} +305 -8
  18. package/dist/framework-DW5fqjh4.js +65 -0
  19. package/dist/{source-BccdO4aL.js → git-Hf9Wc7Hp.js} +34 -92
  20. package/dist/{held-sKq3xrsT.js → held-D5wSX2Mf.js} +9 -9
  21. package/dist/held-Dmf5SR3p.js +15 -0
  22. package/dist/{install-DsIsif39.js → install-CxyqfKFe.js} +15 -17
  23. package/dist/{integrate-B8eA676b.js → integrate-MkyDDzI5.js} +33 -38
  24. package/dist/{login-BlpfYapG.js → login-B7IqDafm.js} +3 -3
  25. package/dist/{login-Blhxi20A.js → login-BMHDhxAx.js} +8 -9
  26. package/dist/login-Cp0-BgDZ.js +13 -0
  27. package/dist/{lookup-Dg55W9S7.js → lookup-DkcT4E-5.js} +28 -4
  28. package/dist/{migrate-DoRb9jmA.js → migrate-CdFoZipj.js} +66 -45
  29. package/dist/{notification-url-D82msWF5.js → notification-url-D6KKeXnk.js} +4 -4
  30. package/dist/{open-BAqLpTSI.js → open-COJE6ryI.js} +2 -2
  31. package/dist/{org-C4G7WjTV.js → org-BV8wwxwc.js} +4 -4
  32. package/dist/{organization-CmuQwcKN.js → organization-9R_1PJKk.js} +4 -4
  33. package/dist/{orgs-1OzwUtpT.js → orgs-ltP8H0Nl.js} +1 -2
  34. package/dist/{paths-gBbqgkS7.js → paths-Cb1RfjaX.js} +1 -1
  35. package/dist/{playbook-BKqlv77S.js → playbook-CVGolez9.js} +10 -14
  36. package/dist/{products-Cqq59DBQ.js → products-CJq_iXv5.js} +1 -1
  37. package/dist/{promote-D0i8A0CO.js → promote-B_HnFEbX.js} +27 -28
  38. package/dist/{pull-DgQ_UmGv.js → pull-DF4KYVcP.js} +72 -26
  39. package/dist/pull-JxiMyRwY.js +30 -0
  40. package/dist/{pull-CiIrJ5ik.js → pull-lYRULo4v.js} +33 -39
  41. package/dist/push-B5py7h5y.js +29 -0
  42. package/dist/{push-7N4XIVtg.js → push-BZN1Qpkq.js} +23 -12
  43. package/dist/{push-BWsXO7FN.js → push-BnllH2Rd.js} +8 -7
  44. package/dist/push-DHlUMkbf.js +21 -0
  45. package/dist/registry-BGEYCWyD.js +22 -0
  46. package/dist/{registry-aAR_8VOw.js → registry-CqePfigB.js} +1287 -902
  47. package/dist/{resolve-CcOpO_5s.js → resolve-B4bd3Qjl.js} +4 -4
  48. package/dist/{resources-DNwvf8rg.js → resources-BaURbSpY.js} +15 -2
  49. package/dist/{run-tVYJ3V5j.js → run-Bme4Egyl.js} +15 -17
  50. package/dist/{scan-dv0rrY4C.js → scan-DugxddUU.js} +1 -1
  51. package/dist/scan-J2DILUNE.js +4 -0
  52. package/dist/{scope-ehZ7L1nj.js → scope-Cg1AdAfO.js} +33 -3
  53. package/dist/{scope-BXoQo30_.js → scope-DDYLQeZw.js} +24 -18
  54. package/dist/screenshot-file-Dix2Qynm.js +127 -0
  55. package/dist/{sdk-DEfQttek.js → sdk-BFunw4Hc.js} +1 -1
  56. package/dist/{framework-JFLjmD5Y.js → selection-C439nEhn.js} +4 -54
  57. package/dist/{series-D2ZpZ8cx.js → series-B8NJK4yS.js} +1 -1
  58. package/dist/{server-CcZGdYjE.js → server-C_aMxzvS.js} +40 -18
  59. package/dist/server-Cif9w5lM.js +33 -0
  60. package/dist/{session-dHBtgSN0.js → session-B7frlXXQ.js} +1 -1
  61. package/dist/{base-83ZTv6up.js → session-CfG3gzko.js} +8 -83
  62. package/dist/session-DvaPyOuH.js +5 -0
  63. package/dist/{migration-BUedsREQ.js → setup-DQEasPhx.js} +290 -28
  64. package/dist/skills/index.json +5 -0
  65. package/dist/skills/superwall/SKILL.md +37 -10
  66. package/dist/skills/superwall/references/api.md +66 -21
  67. package/dist/skills/superwall/references/asa.md +109 -64
  68. package/dist/skills/superwall/references/dashboard-links.md +65 -28
  69. package/dist/skills/superwall/references/data-analytics.md +1 -1
  70. package/dist/skills/superwall/workflows/dashboard/setup.md +15 -5
  71. package/dist/skills/superwall/workflows/integrate/flutter.md +9 -7
  72. package/dist/skills/superwall-framework/SKILL.md +248 -36
  73. package/dist/skills/superwall-framework/references/cli.md +98 -7
  74. package/dist/skills/superwall-framework/references/examples.md +2 -2
  75. package/dist/skills/superwall-framework/references/layout.md +30 -2
  76. package/dist/skills/superwall-framework/references/migrate-from-editor.md +5 -0
  77. package/dist/skills/superwall-framework/references/migrate-from-native.md +5 -0
  78. package/dist/skills/teleport/SKILL.md +154 -0
  79. package/dist/skills/teleport/references/experiments.md +328 -0
  80. package/dist/skills/teleport/references/setup.md +157 -0
  81. package/dist/{skills-Q7xB784d.js → skills-DnegE1A6.js} +139 -9
  82. package/dist/{skills-Bqz2l_bx.js → skills-MmF7IyTg.js} +8 -12
  83. package/dist/source-DQs6iLtC.js +82 -0
  84. package/dist/{source-push-CG948HrX.js → source-push-MbJjh4Ki.js} +38 -14
  85. package/dist/{spinner-IA6hV8nI.js → spinner-Dcr-Dqdi.js} +7 -5
  86. package/dist/{starter-BtUUQWhd.js → starter-BlJ_InZJ.js} +2 -2
  87. package/dist/{status-CB_MrFu5.js → status-DHRxg1ZA.js} +9 -11
  88. package/dist/{output-Ggzq5_-t.js → storage-DdIAHolY.js} +40 -1
  89. package/dist/storekit-De998QOt.js +203 -0
  90. package/dist/storekit-iBCWmeKn.js +15 -0
  91. package/dist/{bind-DcWIIPgk.js → theme-BrUrye-c.js} +29 -6
  92. package/dist/token-CKCBQ4I8.js +100 -0
  93. package/dist/tools-skills/animate-onboarding/SKILL.md +1 -1
  94. package/dist/tools-skills/mobile-design/SKILL.md +1 -1
  95. package/dist/tools-skills/onboarding-questions/SKILL.md +1 -1
  96. package/dist/tools-skills/superwall/SKILL.md +43 -17
  97. package/dist/tools-skills/superwall/references/api.md +74 -24
  98. package/dist/tools-skills/superwall/references/asa.md +109 -64
  99. package/dist/tools-skills/superwall/references/dashboard-links.md +65 -28
  100. package/dist/tools-skills/superwall/references/data-analytics.md +1 -1
  101. package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +4 -3
  102. package/dist/tools-skills/superwall/workflows/dashboard/setup.md +21 -8
  103. package/dist/tools-skills/superwall/workflows/integrate/flutter.md +9 -7
  104. package/dist/tools-skills/superwall/workflows/migrate/adapty.md +4 -3
  105. package/dist/tools-skills/superwall/workflows/migrate/playbook.md +2 -2
  106. package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +4 -3
  107. package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +4 -3
  108. package/dist/tools-skills/superwall-editor/SKILL.md +2 -3
  109. package/dist/tools-skills/teleport/SKILL.md +154 -0
  110. package/dist/tools-skills/teleport/references/experiments.md +328 -0
  111. package/dist/tools-skills/teleport/references/setup.md +157 -0
  112. package/dist/tools.d.ts +1 -1
  113. package/dist/tools.js +1232 -746
  114. package/dist/{try-CS3jLyoP.js → try-C8QQbG0b.js} +17 -19
  115. package/dist/{lock-DgSx-p8Y.js → types-Dc9U_4kp.js} +86 -80
  116. package/dist/upgrade-CYFdpVpi.js +27 -0
  117. package/dist/upgrade-D0thxCA4.js +348 -0
  118. package/package.json +11 -3
  119. package/dist/config-CGcG7GOt.js +0 -113
  120. package/dist/create-Du8Fx7W5.js +0 -20
  121. package/dist/existing-WQ3pz94o.js +0 -97
  122. package/dist/held-DmOhszHR.js +0 -17
  123. package/dist/log-C0MDCfA2.js +0 -62
  124. package/dist/login-D9jfRO8w.js +0 -17
  125. package/dist/pull-CO5HlqBe.js +0 -36
  126. package/dist/push-BIhGDNpL.js +0 -30
  127. package/dist/push-BgqTddLA.js +0 -22
  128. package/dist/run-B-YoyB-a.js +0 -100
  129. package/dist/scan-BU41gcQY.js +0 -4
  130. package/dist/screenshot-file-XAS0Xy0e.js +0 -16
  131. package/dist/server-BemmM1FV.js +0 -29
  132. package/dist/session-4aITGsF1.js +0 -6
  133. package/dist/setup-m94dpT3t.js +0 -217
  134. package/dist/spawn-DmmmHIP-.js +0 -71
  135. package/dist/storage-pR0Wb0d9.js +0 -41
  136. package/dist/storekit-BMxyYAHj.js +0 -17
  137. package/dist/storekit-CQnwlpKV.js +0 -47
  138. package/dist/telemetry-DU56L7Cy.js +0 -56
  139. package/dist/theme-DUsCh-Vd.js +0 -25
  140. package/dist/token-BbUeExGJ.js +0 -70
  141. package/dist/upgrade-CKn88PZD.js +0 -206
  142. package/dist/upgrade-DfD3-ClG.js +0 -7
  143. /package/dist/{browser-Bp3yRKlU.js → browser-BVjaf98V.js} +0 -0
  144. /package/dist/{client-BJQXl62Q.js → client-BwYhzITp.js} +0 -0
  145. /package/dist/{design-lint-CiFc78aM.js → design-lint-mgO-2SGS.js} +0 -0
  146. /package/dist/{devtools-ByZ6XYnn.js → devtools-B6Vp6HMy.js} +0 -0
  147. /package/dist/{input-MDd67UIp.js → input-DOT_2Zvb.js} +0 -0
  148. /package/dist/{project-NoMtbMyl.js → project-BomArwSj.js} +0 -0
  149. /package/dist/{reports-HYVp169R.js → reports-hbxsd3Zo.js} +0 -0
  150. /package/dist/{storage-Bdz5AmqS.d.ts → storage-Bh3wT1Rn.d.ts} +0 -0
  151. /package/dist/{timing-Ca0TXY-A.js → timing-BKEEIBij.js} +0 -0
  152. /package/dist/{ui-D_qf3Gvw.js → ui-hFgji1e8.js} +0 -0
@@ -44,9 +44,32 @@ Entry points: `superwall` (SuperwallProvider — mounted for you),
44
44
  `superwall/assets`.
45
45
 
46
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.
47
+ and the rebuild forms of `migrate` by default. An `Unknown command` (such as
48
+ `Unknown command: create`, or `Unknown command: pull` before 2.3.0) means the
49
+ CLI that ran is older than that command; `superwall --version` shows which one
50
+ ran. Inside a project, the project's own `superwall` dependency is the CLI that
51
+ runs, whichever copy was started, and a newer CLI prints the command that
52
+ updates it on stderr, e.g. `cd superwall && npm i superwall@latest`. A missing
53
+ `pull` is never a reason to use `--overwrite-source`.
54
+
55
+ When a newer release is out, every command (`dev` at start, the rest at the
56
+ end) also prints an upgrade prompt on stderr, even under `--json`:
57
+
58
+ - `Update available 2.5.2 → 2.6.0 · run cd superwall && pnpm add superwall@latest`
59
+ is a patch or minor: tell the user in one line, run that command, then
60
+ carry on (or retry the command that failed).
61
+ - `Major update available 2.5.2 → 3.0.0`, followed by a release-notes link and
62
+ `Update: <command>`, is a major: tell the user, link the notes and ask
63
+ before running it, since a major can break paywalls. If they decline, keep
64
+ working on the pinned version.
65
+
66
+ Run the command exactly as printed: the project bump when the project pins
67
+ `superwall`, `superwall upgrade` when it doesn't. A beta pin follows npm's
68
+ `next` tag, so its command says `superwall@next`; never change it to
69
+ `@latest`. The older-pin notice above follows the same rule: run it when
70
+ only the minor or patch differs, ask first when the major does. The dev
71
+ studio shows the same update as a banner whose Copy prompt hands you these
72
+ steps.
50
73
 
51
74
  ## Local references — the agent playbooks
52
75
 
@@ -88,9 +111,10 @@ curl -sL https://superwall.com/docs/framework/{page}.md # one page
88
111
  | Declaring products, reading variables, the three price rules | `products` |
89
112
  | `purchase()` outcomes, restore, the two channels | `purchases` |
90
113
  | Introductory-offer eligibility forking (`useIntroductoryOffer`), reminder notifications | `trials` |
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` |
92
- | Custom store products (external purchase controller, custom-store Stripe products) — declared by identifier, pushed with the dashboard's store | `products` |
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` |
114
+ | 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`), Apple Pay availability on every host (`useApplePay`, `checkApplePay`, `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` |
115
+ | Custom store products (external purchase controller, custom-store Stripe products) — declared by identifier, pushed with the dashboard's store; on a hosted web paywall `purchase()` opens the store's checkout itself | `products`, `web-checkout` |
116
+ | Continuing a flow on the web (teleport: `teleport: true` or `{ route, fallbacks, completion, … }`, `router.push(route, { teleport: true })` and `{ teleport: false }` to stay in the app, the Apple Pay gate (`useApplePay().available`), prefetch, the teleport screen, `useTeleport`'s typed status, returning to the app with `returnToApp({ data })` and its `"opened" \| "cancelled" \| "no_app"` result, the page's `failure` and `data` back in the app, `onReturnData`) | `teleport` |
117
+ | Setting up an app-to-web flow or experiment end to end (start in the iOS app, pay on the web with Apple Pay): the recommended setup, the Apple Pay gate, fallbacks, A/B tests by paywall | the `teleport` skill, then `teleport` |
94
118
  | Web funnels — answers in the URL (`useQueryState`), resume after a browser hand-off, `shift` | `web-funnels` |
95
119
  | Multi-page flows, router, cross-page state, shared chrome | `navigation` |
96
120
  | Built-in + custom transitions, bottom sheets | `transitions` |
@@ -121,11 +145,23 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
121
145
  2. **`purchase()` never throws for flow outcomes** — it resolves
122
146
  `completed | abandoned | failed`. React to the awaited result; treat
123
147
  abandoned as an outcome. Never put the buy button in a loading state.
124
- `failed` with `reason: "sdk"` is iOS only: Android reports no purchase
125
- failures, so there a failed purchase stays pending until the user
148
+ A store purchase through the SDK resolves `failed` with
149
+ `reason: "unknown"` (or `"superseded"` when a newer purchase replaced it)
150
+ on iOS only: Android reports no purchase failures, so there a failed purchase stays pending until the user
126
151
  abandons or completes. The paywall runs no timer of its own; design the
127
152
  pending state to be survivable and never gate irreversible UI on
128
- `failed` on Android. What happens *after* a completed purchase is
153
+ `failed` on Android. On a hosted web paywall (`*.superwall.app`),
154
+ `purchase()` of a custom store product (`custom|…`) opens the store's
155
+ checkout itself in the same tab; never POST
156
+ `/v1/checkout/custom-store/session` yourself. It resolves `abandoned`
157
+ once the tab navigates (a second tap while the first is in flight also
158
+ resolves `abandoned` and opens nothing), and `failed` only when the
159
+ backend refuses the buyer's id (a placeholder such as `null`), no web
160
+ checkout is configured, or the network fails. A buyer without
161
+ `app_user_id` still gets the checkout as an anonymous buyer and a
162
+ redemption code after paying. Under the Web SDK custom store products
163
+ resolve `failed` as unsupported; inside an app they go to the SDK's
164
+ purchase. What happens *after* a completed purchase is
129
165
  `postPurchase` in config (or per call): `"dismiss"` (default), `"stay"`
130
166
  to keep the paywall up, and on the web `"redeem"` / `{ redirect }`;
131
167
  `"stay"` on the web is finished with `useCheckoutRedemption()`. Pass
@@ -146,6 +182,64 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
146
182
  // abandoned: the user closed the store sheet — nothing changes, nothing is said
147
183
  ```
148
184
 
185
+ **Why a payment failed.** A failed Stripe purchase resolves
186
+ `{ status: "failed", product, failure }`, and `usePurchase().failure`
187
+ holds the last failed purchase until the next one starts. `failure` is a
188
+ `CheckoutFailure`: `reason` in superwall's own words, `store: "stripe"`,
189
+ and Stripe's raw `code`, `declineCode` and `message` when Stripe gave
190
+ them. Branch on `reason`, never on Stripe's codes: the reasons stay the
191
+ same whichever store or payment method took the payment. `reason`
192
+ (`CheckoutFailureReason`) is one of:
193
+
194
+ | `reason` | Meaning |
195
+ | --- | --- |
196
+ | `card_declined` | the issuer declined and gave no more specific reason |
197
+ | `insufficient_funds` | not enough money or credit on the card |
198
+ | `expired_card` | the card has expired |
199
+ | `incorrect_card_details` | a wrong number, CVC, expiry, postal code or PIN |
200
+ | `authentication_failed` | 3D Secure or another bank check failed or was cancelled |
201
+ | `card_not_supported` | the card can't pay for this kind of purchase or in this currency |
202
+ | `limit_exceeded` | a spending, frequency or PIN-attempt limit was hit |
203
+ | `fraud_suspected` | the issuer or Stripe flagged it, or the card is lost or stolen |
204
+ | `processing_error` | the issuer or the network failed; trying again may work |
205
+ | `unknown` | nobody reported why, or the reason is one superwall doesn't know |
206
+
207
+ `unknown` means "no reason known": the purchase still failed, so never
208
+ read it as success and never guess a reason behind it. Give it the
209
+ generic copy. What each purchase path reports:
210
+
211
+ | Purchase | `failure.reason` |
212
+ | --- | --- |
213
+ | Stripe, direct Apple Pay on the web | the exact reason |
214
+ | Stripe, embedded sheet (`checkout: "sheet"`) | `unknown` until the subscriptions backend reports it; subscriptions may stay `unknown` |
215
+ | Stripe, hosted (redirect) checkout, every Stripe purchase in an iOS app | `unknown`; reasons aren't supported there |
216
+ | Stripe, teleport seen from the app | the page's exact reason when the page returned it, else as for its checkout |
217
+ | App Store or Play Store through the SDK | `reason: "unknown"` or `"superseded"` on the failure itself, no `failure` object; iOS only |
218
+ | Custom store (`custom|…`) | no reason, and no callbacks |
219
+
220
+ **Purchase callbacks.** Use superwall's callbacks, never Stripe's own
221
+ events: `usePurchase({ onStart, onSubmit, onComplete, onAbandon,
222
+ onFailure })` fires for every purchase on the paywall, whichever
223
+ component started it; `purchase(product, { onFailure, … })` takes the
224
+ same callbacks for that call only, beside the hook's. They fire on every
225
+ platform (native store purchases, the sheet, Apple Pay, hosted checkout,
226
+ teleport) except for custom store products. `onSubmit` is web checkout
227
+ only: the shopper submitted the sheet or authorized Apple Pay. The others
228
+ receive the product; `onFailure` receives the failed purchase, with
229
+ `reason` on it (and `store`, `code`, `declineCode`, `message` for a web
230
+ failure). In the embedded sheet `onFailure` fires on each decline while
231
+ the sheet stays open for another card, and `purchase()` resolves only
232
+ when the sheet is paid or closed:
233
+
234
+ ```tsx
235
+ const { purchase, failure } = usePurchase({
236
+ onFailure: (failed) => track("payment_failed", { reason: failed.reason }),
237
+ });
238
+ const result = await purchase("annual");
239
+ if (result.status === "failed" && "failure" in result && result.failure)
240
+ setNotice(t(`failure.${result.failure.reason}`)); // one string per reason, unknown included
241
+ ```
242
+
149
243
  The embedded Stripe sheet waits 10 s after a tap for Stripe's checkout
150
244
  to be ready. The wait only hides the spinner and resolves `failed`: Stripe
151
245
  keeps loading, the buyer stays on the paywall, and the next tap opens the
@@ -158,24 +252,42 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
158
252
  on `stripe_error`; read them in Safari Web Inspector or Chrome DevTools to
159
253
  debug a slow checkout before changing the paywall.
160
254
 
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`,
255
+ `useApplePay()` says whether Apple Pay is set up with a card on this
256
+ device, the same way on every host: the iOS SDK, the Web SDK, a hosted
257
+ web paywall, a teleport page and a plain browser. It is Apple's
258
+ `ApplePaySession.canMakePaymentsWithActiveCard` for the page's own Stripe
259
+ merchant; the answer follows the cards in Wallet, not the domain's Stripe
260
+ registration, and any usable card counts (Apple Cash with no balance
261
+ too), so it means Apple Pay is set up, not that a payment will succeed.
262
+ It is always defined: `{ available: true }` or
263
+ `{ available: false, reason, message, error? }`, never `undefined`, so
264
+ read `applePay.available` without `?.`. `reason`
265
+ (`ApplePayUnavailableReason`) is `checking` until Apple answers (usually
266
+ right after the first render, at most 1.5 s), `no_active_card`,
267
+ `unsupported_browser` (no Apple Pay JS: the Android SDK, desktop Chrome,
268
+ whose card sheet may still offer Apple Pay by QR code), `insecure_context`
269
+ (not HTTPS, `http://localhost` included), `cross_origin_frame`,
270
+ `check_failed` (with the browser's `error`) or `timed_out` after 1.5 s,
271
+ which Apple's late answer still replaces. `checking` is not available:
272
+ a decision made on the first render keeps the shopper in the app. Apple
273
+ is asked once per page and every `useApplePay()` shares the answer; a
274
+ check that threw or timed out is asked again, and a paywall with
275
+ `teleport` in its config asks as it opens. `checkApplePay()` from
276
+ `superwall/hooks` is the same answer as a promise for code outside
277
+ React, never `checking`. `useVariables().device.isApplePayAvailable` is
278
+ `@deprecated` (the native SDK always reports `true`); never read it.
279
+
280
+ With a product, `useApplePay(product)` adds `product: { status:
281
+ "preparing" | "ready" | "unavailable", reason?, message?, error? }`,
282
+ whether the wallet is ready to open for that product. Only Stripe's
283
+ check, made when it prepares the product, sees the domain's registration.
284
+ Its `reason` (`ApplePayProductReason`) is `unsupported_host` inside the
285
+ iOS and Android SDKs and Studio (a purchase never opens the wallet
286
+ there), the device's reason when Apple Pay is not available, else an
287
+ `ApplePayWalletReason`: `not_prepared` means nothing has prepared that
288
+ product's wallet yet, not that the device can't pay; `stripe_declined`
289
+ means no card in Wallet, an unregistered domain or Safari's Apple Pay
290
+ check setting off; the rest (`stripe_check_failed`,
179
291
  `stripe_load_failed`, `missing_public_api_key`, `session_failed`,
180
292
  `session_unsupported`, `show_failed`) name the step that failed. The
181
293
  wallet opens only for a product prepared before the tap: config
@@ -189,9 +301,9 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
189
301
  const { purchase, prefetch } = usePurchase();
190
302
  const applePay = useApplePay(reference);
191
303
  useEffect(() => {
192
- if (applePay?.available) prefetch(reference, { checkout: "applePay" });
193
- }, [applePay?.available, prefetch, reference]);
194
- return applePay?.available && applePay.product.status === "ready" ? (
304
+ if (applePay.available) prefetch(reference, { checkout: "applePay" });
305
+ }, [applePay.available, prefetch, reference]);
306
+ return applePay.product.status === "ready" ? (
195
307
  <button onClick={() => purchase(reference, { checkout: "applePay" })}>Apple Pay</button>
196
308
  ) : (
197
309
  <button onClick={() => purchase(reference, { checkout: "sheet" })}>Pay with card</button>
@@ -328,7 +440,11 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
328
440
  merchant's site vs Superwall's hosted web paywall page, the teleport
329
441
  page, the studio) branches on `useDevice().host` — `"ios-sdk" |
330
442
  "android-sdk" | "web-sdk" | "web-paywall" | "web-teleport" | "studio" |
331
- "browser"`, never `undefined` — never on the URL or `window`. UI that
443
+ "browser"`, never `undefined` — never on the URL or `window`. It is
444
+ reliable on web pages that carry a WebKit message handler: a hosted web
445
+ paywall reads `"web-paywall"` and the Web SDK `"web-sdk"`; only a real
446
+ iOS app reads `"ios-sdk"`. Never detect a hosted page yourself through
447
+ `window.webPaywallCtrl`, `client_surface` or `window.webkit`. UI that
332
448
  depends on which browser shows the page (an "open in Safari" hint for a
333
449
  funnel opened from an Instagram ad) branches on `useDevice().browser` —
334
450
  `SuperwallBrowser | undefined`, known from the first render — never on
@@ -356,16 +472,95 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
356
472
  true })`, or `teleport: { route }` so a push to it and a Stripe purchase
357
473
  teleport on their own and it is prepared when the paywall opens (call
358
474
  `useTeleport().prefetch(route)` for a route only the router teleports).
475
+ A Stripe `purchase()` in the app teleports to `teleport.route` with the
476
+ tapped product preselected there (`useTeleport().productReference`);
477
+ without `teleport.route` it teleports the route it was tapped on, cold.
478
+ Teleport pays off only when the shopper can pay with Apple Pay on the
479
+ web page, so check `useApplePay().available` first and keep them in the
480
+ app when it is `false`: `router.push(route, { teleport: false })`
481
+ pushes even `teleport.route` in the app, or sell the store product. A
482
+ paywall with `teleport` asks Apple as it opens, so the answer is
483
+ usually there before the first tap. To set up an app-to-web flow or
484
+ experiment end to end, use the `teleport` skill.
359
485
  The route opens on the web with every `useQueryState` value carried
360
486
  along, and the app is credited when the shopper pays. Keep answers the
361
- web half needs in `useQueryState`, not component state. A custom teleport
362
- screen renders while `useTeleport().status === "waiting"` and not
363
- `returned`, reopens with `open()`, and buys the fallback with plain
487
+ web half needs in `useQueryState`, not component state. The
488
+ `teleport.route` page is pre-rendered at `superwall push` per locale,
489
+ Stripe product (plus none) and trial, and the browser paints it before
490
+ any JS runs, so its first render draws only from the locale, the
491
+ products and prices, the trial and `useTeleport().productReference`.
492
+ Read `window`, dates, random values, dark mode and `useQueryState`
493
+ answers in an effect or below the first frame, never in that first
494
+ render, or the page redraws when it takes over. A pre-render warning in
495
+ `push` output means those pages render in the browser instead; fix what
496
+ it names. A custom teleport screen renders while
497
+ `useTeleport().status === "waiting"` and not `returned`, reopens with
498
+ `open()`, and buys the fallback with plain
364
499
  `purchase()`; count cancels and returns with `useTeleport({ onCancel,
365
500
  onReturn })`, never with your own timers (`onCancel` is the Cancel
366
501
  button only; an unpaid return shows as `purchase()` resolving
367
- `abandoned`). Fetch `teleport`; the
368
- `teleport` example is the complete flow to start from.
502
+ `abandoned`). On the web half, go back to the app only with
503
+ `useTeleport().returnToApp()` (or `close()` / `router.back()` on the
504
+ first web route) — never `openDeepLink`, `openUrl` or a hand-built scheme
505
+ or universal link. The framework picks the link: the universal link
506
+ first, the URL scheme when iOS won't follow it, which is every return
507
+ nobody tapped, such as one after Apple Pay is closed. While iOS asks
508
+ "Open in…?" it dims the page and points at Open itself; draw nothing for
509
+ it. `returnToApp()` resolves `"opened" | "cancelled" | "no_app"`
510
+ (`"cancelled"`: the shopper tapped Cancel; `"no_app"`: nothing could open
511
+ the app), and `useTeleport().returning` is true meanwhile. On anything
512
+ but `"opened"` the shopper is still on the page: leave it as it is, ready
513
+ to buy again.
514
+
515
+ ```tsx
516
+ const { returnToApp } = useTeleport();
517
+ const result = await purchase("web");
518
+ if (result.status === "completed") haptics.success();
519
+ else if (result.status === "failed") setNotice(t("purchase.failed")); // say so, keep the button
520
+ else {
521
+ // abandoned: the shopper closed the sheet without paying
522
+ const back = await returnToApp(); // "opened" | "cancelled" | "no_app"
523
+ if (back === "opened") return;
524
+ // "cancelled" or "no_app": still on this page — change nothing, the buy button stays
525
+ }
526
+ ```
527
+
528
+ **Sending a failed payment back to the app.** After a decline on the
529
+ teleport page, `returnToApp()` leaves the app the page's `failure`
530
+ without being asked (its return link carries `reason=failed`), and
531
+ `returnToApp({ data })` adds your own plain JSON, at most 16 KB: over
532
+ that the page logs a warning and leaves only the failure. Put new
533
+ fields inside `data`; never encode them in the link. In the app,
534
+ `useTeleport()` shows them as `failure` and `data` while `status ===
535
+ "waiting"`, `onFailure` fires and `usePurchase().failure` is set;
536
+ `useTeleport({ onReturnData })` fires once the data is read. You never
537
+ pass the reason yourself. Nothing is left after a paid purchase (the
538
+ teleport is closed), and no SDK change is needed: the app reads them
539
+ from the teleport's session. Until the backend reports the sheet's
540
+ reason, a sheet decline reaches the app as `unknown`; Apple Pay's is
541
+ exact. Branch on `failure.reason` in the app as anywhere else:
542
+
543
+ ```tsx
544
+ // teleport page: send a shopper short on funds back to the App Store plan
545
+ const teleport = useTeleport();
546
+ const { purchase } = usePurchase({
547
+ onFailure: (failure) => {
548
+ if (teleport.status !== "arrived") return;
549
+ const offer = failure.reason === "insufficient_funds" ? "app_store" : "retry";
550
+ void teleport.returnToApp({ data: { offer } });
551
+ },
552
+ });
553
+
554
+ // app route: offer another way to pay
555
+ const back = useTeleport({ onReturnData: (data) => console.info("back from the page", data) });
556
+ const failure = back.status === "waiting" ? back.failure : undefined;
557
+ if (failure?.reason === "insufficient_funds" || failure?.reason === "card_declined") {
558
+ // show a store product (purchase("annual")) or Apple Pay; `unknown` says only that it failed
559
+ }
560
+ ```
561
+
562
+ Fetch `teleport`; the `teleport` example is the complete flow to start
563
+ from.
369
564
  13. **Shipping includes the dashboard.** A push that fails on missing
370
565
  products is not a blocker to report — create them with
371
566
  `superwall products create` ([references/cli.md](references/cli.md)).
@@ -447,6 +642,13 @@ superwall push # sealed version, production untouched; diagnostics har
447
642
  superwall promote # ship (or: superwall publish -m "why")
448
643
  ```
449
644
 
645
+ After a push, promote or publish, give the user the paywall's studio link:
646
+ `https://app.superwall.com/{orgId}/{applicationId}/paywalls/{paywallId}/studio`.
647
+ The app and paywall ids are in `superwall.lock`; `orgId` is
648
+ `organization_id` in `GET /v2/projects`. Never link a code-first paywall to
649
+ the legacy `superwall.com/editor` — it cannot open one. Every other
650
+ dashboard page is in the `superwall` skill's `references/dashboard-links.md`.
651
+
450
652
  Before calling a paywall done, run the audit at the end of the
451
653
  `mobile-design` skill (and the framework items in
452
654
  [references/mobile-design.md](references/mobile-design.md)) and the matrix
@@ -465,6 +667,16 @@ it, so pass it only when the user says to. In an empty folder,
465
667
  `superwall pull --app <id>` gets every paywall of an app without GitHub
466
668
  ([references/cli.md](references/cli.md)).
467
669
 
670
+ In a pnpm monorepo whose `pnpm-workspace.yaml` does not list `superwall`,
671
+ a bare `pnpm install` in `superwall/` installs the parent workspace, exits
672
+ 0 and leaves `superwall/` empty; `superwall dev` then fails with
673
+ `No superwall framework found`. Install and re-install there with
674
+ `pnpm install --ignore-workspace` and commit `superwall/pnpm-lock.yaml`, or
675
+ add `superwall` to the workspace patterns to share the root lockfile.
676
+ Never take a clean `pnpm install` exit as proof: check that
677
+ `superwall/node_modules/superwall` exists. bun and npm are not affected
678
+ ([references/cli.md](references/cli.md#installing-in-a-pnpm-monorepo)).
679
+
468
680
  ## Report what's broken
469
681
 
470
682
  When you confirm the framework, the CLI or these docs don't behave as they
@@ -20,6 +20,15 @@ The scaffolded package scripts mirror these (`dev`, `push`, `promote`,
20
20
  `SUPERWALL_API_KEY`, which is only ever the organization's secret key
21
21
  (`sk_…`), never an app's public `pk_…` key. `dev` needs no login.
22
22
 
23
+ When a newer release is out, every command prints an upgrade prompt on
24
+ stderr, even under `--json`: at the end, or right after the intro for `dev`,
25
+ which never ends. A patch or minor reads `Update available 2.5.2 → 2.6.0 ·
26
+ run cd superwall && pnpm add superwall@latest`; a major is a
27
+ `Major update available 2.5.2 → 3.0.0` block with a release-notes link.
28
+ Run the printed command for a patch or minor; for a major, tell the user,
29
+ link the release notes and ask first. A beta project's command says
30
+ `superwall@next`; keep it. The full rule is near the top of SKILL.md.
31
+
23
32
  ## `superwall create`
24
33
 
25
34
  Inside an app that already has a `superwall/` project (or inside the
@@ -33,7 +42,10 @@ Superwall app instead of detecting one from the SDK key or asking — the
33
42
  dashboard's **Copy Prompt** button hands you this form, so use the id it
34
43
  gives rather than picking; it fails if the id isn't in the account, and it
35
44
  cannot be combined with `--no-connect`. `--yes` accepts the defaults,
36
- `--no-install` skips dependencies.
45
+ `--no-install` skips dependencies, and `--no-git` skips the git step:
46
+ outside a git repository `create` otherwise runs `git init` and commits
47
+ the scaffold along with everything else in the folder. Pass `--no-git`
48
+ whenever the user or the repository's rules forbid committing on your own.
37
49
 
38
50
  `--from <paywall-id>` rebuilds a dashboard (visual editor) paywall as
39
51
  code: it scaffolds `paywalls/<slug>/config.ts` from the paywall's
@@ -47,10 +59,49 @@ The rebuild itself is
47
59
  [migrate-from-editor.md](migrate-from-editor.md). After the scaffold the
48
60
  CLI asks whether to run the rebuild headless with the user's agent, copy
49
61
  the prompt, or stop; `superwall migrate <paywall-id>` asks the same later
50
- (and scaffolds first if needed), `--skill` prints the prompt. When *you*
62
+ (and scaffolds first if needed), `--skill` prints the prompt.
63
+ `superwall migrate <paywall-id> --dry-run` reads the paywall and its
64
+ served document, runs the same refusals, prints the `paywalls/<slug>` it
65
+ would create and the paywall and app ids it would save in `superwall.lock`,
66
+ and ends with "Dry run - no changes made." It writes no files and skips
67
+ the agent / copy / stop choice and the studio; it still needs a login, and
68
+ fails like the real run when the paywall has no served document. When *you*
51
69
  are the agent driving it, read the playbook and do the inventory step with
52
70
  the user rather than running the headless path.
53
71
 
72
+ ### Installing in a pnpm monorepo
73
+
74
+ `superwall/` owns its own `package.json`, lockfile and `node_modules`. In a
75
+ pnpm monorepo whose `pnpm-workspace.yaml` patterns don't list `superwall`
76
+ (say `apps/*` and `packages/*`), a bare `pnpm install` inside `superwall/`
77
+ installs the parent workspace instead, exits 0, and leaves `superwall/`
78
+ without `node_modules`; `superwall dev` then fails with `No superwall
79
+ framework found`. bun and npm are not affected.
80
+
81
+ `create` checks that `superwall` resolves from `superwall/` after the
82
+ install instead of trusting the exit code. For pnpm it retries once with
83
+ `pnpm install --ignore-workspace` and says so:
84
+ ``Dependencies installed with `pnpm install --ignore-workspace` — superwall/ is outside the pnpm workspace``.
85
+ If the framework still doesn't resolve, with any manager, it says
86
+ ``` `<command>` finished, but superwall is still not installed for superwall/ — install it there before `superwall dev` ```
87
+ and keeps that command in the next steps. With `--no-install` under a
88
+ pnpm workspace, the next steps add
89
+ ``Not listed in the pnpm workspace? Use `pnpm install --ignore-workspace` instead``.
90
+
91
+ Pick one setup and keep to it:
92
+
93
+ - **Standalone (what the CLI does):** install and re-install with
94
+ `pnpm install --ignore-workspace` inside `superwall/`, every time: a
95
+ later bare `pnpm install` there is again a silent no-op. It writes
96
+ `superwall/pnpm-lock.yaml`; commit it.
97
+ - **Workspace member:** add `superwall` to the patterns in
98
+ `pnpm-workspace.yaml`. A bare `pnpm install` then works and the project
99
+ shares the root lockfile. Don't run `--ignore-workspace` there: it
100
+ would give a member its own lockfile.
101
+
102
+ Never treat a clean `pnpm install` exit as proof: check that
103
+ `superwall/node_modules/superwall` exists before running `superwall dev`.
104
+
54
105
  ## `superwall migrate --screen <path>`
55
106
 
56
107
  Rebuilds a native screen — SwiftUI or UIKit (`.swift`), Jetpack Compose or
@@ -61,7 +112,12 @@ hooks, the placement to register) and an `origins` entry in
61
112
  `superwall.lock`, then offers the same agent / copy / stop choice. No
62
113
  path: it lists likely screens in the app and asks. `--screenshot <file>`
63
114
  saves the original for **Compare › Original**; with a booted iOS simulator
64
- it offers to capture one. `--skill` prints the prompt. The rebuild and the
115
+ it offers to capture one. `--skill` prints the prompt. `--dry-run` reads
116
+ the screen, runs the same refusals, prints the `paywalls/<slug>` it would
117
+ create and ends with "Dry run - no changes made." It writes no files and
118
+ skips the screenshot prompt, the agent / copy / stop choice and the
119
+ studio. When the screen is already scaffolded, either dry run says so and
120
+ stops. The rebuild and the
65
121
  wiring are [migrate-from-native.md](migrate-from-native.md).
66
122
 
67
123
  ## `superwall dev`
@@ -90,7 +146,8 @@ Three consequences for you, not the user:
90
146
  1290 x 2796 render, the App Store size Apple takes for a product page and
91
147
  for subscription review attachments, so it uploads without resizing.
92
148
  - **It previews; only chat edits.** The dashboard hosts the same studio for a
93
- code-first paywall (its live snapshot plus every pushed version). Nothing
149
+ code-first paywall (its live snapshot plus every pushed version), at
150
+ `https://app.superwall.com/{orgId}/{applicationId}/paywalls/{paywallId}/studio`. Nothing
94
151
  there is point-and-click editable, so never tell the user to drag a headless
95
152
  paywall into shape — changes ship through `push`/`promote`/`publish`. Its
96
153
  **Chat** panel is the one exception: it edits the source in a sandbox and
@@ -100,7 +157,9 @@ Three consequences for you, not the user:
100
157
  preview is a `superwall build` snapshot taken when a turn ends, not a live
101
158
  server. So edits may have arrived that a local checkout has never seen —
102
159
  `main` carries the source commit of the last published version; run
103
- `superwall pull` to bring them into the local project.
160
+ `superwall pull` to bring them into the local project. A chat's edits that
161
+ were never published stay on `studio/<paywallId>`, and `pull` doesn't bring
162
+ them in.
104
163
 
105
164
  The mechanism behind both (the envelope, the `ping` reply, hosting a paywall
106
165
  yourself) is `curl -sL superwall.com/docs/framework/host-protocol.md`.
@@ -394,6 +453,23 @@ Promote never rebuilds — it only moves the live pointer.
394
453
  Push + promote in one step. Also warns about other paywalls that are
395
454
  pushed-but-not-live, so nothing ships half-forgotten.
396
455
 
456
+ ## The studio link after shipping
457
+
458
+ None of `push`, `promote` or `publish` prints a dashboard link, so end each
459
+ with the paywall's studio link yourself:
460
+
461
+ ```
462
+ https://app.superwall.com/{orgId}/{applicationId}/paywalls/{paywallId}/studio
463
+ ```
464
+
465
+ `applicationId` and `paywallId` are in `superwall.lock`
466
+ (`apps.<platform>`, `paywalls.<name>.<platform>.paywallId`); `orgId` is
467
+ `organization_id` of the project holding the app in `GET /v2/projects`.
468
+ On several platforms, give one link per platform. A paywall never pushed
469
+ has no studio page yet; the builder for a new one is
470
+ `…/paywalls/new/studio`. Never give a code-first paywall the legacy
471
+ `superwall.com/editor/#/…` link.
472
+
397
473
  ## `superwall pull`
398
474
 
399
475
  Merges the app's source repo into this project: teammates' paywalls and
@@ -401,6 +477,16 @@ shared files, their `superwall.lock` bindings, and the sync point the next
401
477
  push merges from. Run it inside a project; it pulls the repo of every app
402
478
  `superwall.lock` binds (`--platform <p>` limits it to those platforms).
403
479
 
480
+ `pull` needs superwall 2.3.0 or later. Inside a project, the project's own
481
+ `superwall` dependency is the CLI that runs, whichever copy was started
482
+ (global, `npx superwall@…`), and `superwall --version` prints its version.
483
+ When that copy is older than the one started, the CLI says so on stderr
484
+ (`Running superwall 2.0.0 pinned by superwall/package.json, not 2.6.0.
485
+ Update it: cd superwall && npm i superwall@latest`). So `Unknown command:
486
+ pull` means the project pins a version older than 2.3.0: run the update
487
+ command it printed, then pull again. Never fall back to `--overwrite-source`
488
+ because `pull` is missing.
489
+
404
490
  - **Local edits stay.** Uncommitted changes in the project are merged with
405
491
  the repo's, and only the files that changed are written.
406
492
  - **A conflict changes nothing.** If both sides changed a file (with no
@@ -423,7 +509,10 @@ clones the app's source into an empty `<dir>/superwall/` (default: the
423
509
  current directory), with its `superwall.lock` bindings, `superwall.d.ts`
424
510
  and sync point — the way to work on an app's paywalls without its codebase
425
511
  or GitHub. It installs nothing; it prints the next step, `cd superwall &&
426
- <manager> install && <dev>`. It refuses a directory that is already a
512
+ <manager> install && <dev>`; under a pnpm workspace it adds the
513
+ `Not listed in the pnpm workspace?` line, and when the workspace doesn't
514
+ list `superwall` that install must be `pnpm install --ignore-workspace`
515
+ ([above](#installing-in-a-pnpm-monorepo)). It refuses a directory that is already a
427
516
  superwall project (run `superwall pull` there instead) or one that already
428
517
  has files, and an app with no code paywall or an empty source repo (start
429
518
  one with `superwall create --app <id>`).
@@ -460,7 +549,8 @@ than listing none.
460
549
  | --- | --- |
461
550
  | `Not a superwall project` | Run inside the app (or `superwall/`); the project's `package.json` must depend on `superwall` |
462
551
  | `…package.json is named "superwall"` | Rename the package — that name shadows the framework |
463
- | `No superwall framework found` | `bun add superwall` (or npm) inside the project |
552
+ | `No superwall framework found` | `bun add superwall` (or npm) inside the project. In a pnpm monorepo the message adds `A pnpm workspace above … skips a project it does not list`: run `pnpm install --ignore-workspace` in `superwall/`, or add `superwall` to `pnpm-workspace.yaml` ([above](#installing-in-a-pnpm-monorepo)) |
553
+ | ``… finished, but superwall is still not installed for superwall/`` | The install exited 0 without installing the framework. Run the named command in `superwall/` and check `superwall/node_modules/superwall` exists ([above](#installing-in-a-pnpm-monorepo)) |
464
554
  | `These N products do not exist on Superwall` | Create them with `superwall products create` (above) — don't just report it — or fix the identifiers in `config.ts` |
465
555
  | `Superwall for Agents is in private beta and isn't enabled for this app yet` | Enabled per app on Superwall's side; contact support@superwall.com. Nothing in the CLI can set it |
466
556
  | `You can open N projects - pass --app <id\|dashboard link> or --project <id>` | Add `--app <id\|dashboard link>` to the resource command |
@@ -473,6 +563,7 @@ than listing none.
473
563
  | `paywall x has never been pushed` (promote) | Push first |
474
564
  | `superwall publish requires git` | Install git — the source snapshot is part of every publish |
475
565
  | `… version N has no source yet` (promote) | Run `superwall push` to finish that version's source, then promote |
566
+ | `Unknown command: pull` | The project's own `superwall` is older than 2.3.0 and is the CLI that runs (`superwall --version`). Run the update command it prints on stderr, e.g. `cd superwall && npm i superwall@latest`, then pull again ([above](#superwall-pull)) |
476
567
  | `Someone else published changes to …` | Run `superwall pull`, then publish again; `--overwrite-source` (this paywall only) only on the user's say-so |
477
568
  | `The source repo differs from this project in …` | Run `superwall pull`, then publish again; `--overwrite-source` (this paywall only) only on the user's say-so |
478
569
  | `Your project and the source repo both changed …, so nothing was pulled` | Ask the user which copy wins; to take the repo's, copy their edits aside if wanted, then `superwall pull --theirs` |
@@ -55,12 +55,12 @@ number.
55
55
 
56
56
  | Example | The one idea |
57
57
  | --- | --- |
58
- | `purchase-states` | The two channels: what your `purchase()` call resolves vs what the SDK reports on its own (restore arrives as `transaction_complete` with no purchase in sight) |
58
+ | `purchase-states` | The two channels: what your `purchase()` call resolves vs what the SDK reports on its own (restore arrives as `transaction_complete` with no purchase in sight); a failed purchase shows one string per `result.failure.reason` and `usePurchase({ onFailure })` logs each failure. Its `annual` is a store product, so in the studio it shows the generic notice; `apple-pay` sells Stripe test prices and logs `onFailure`, `onComplete` and `usePurchase().failure` for a real reason |
59
59
  | `trial-eligibility` | Two paywalls in one, chosen by the store — every string forks and both states read as intentional |
60
60
  | `abandonment-offer` | `purchase()` resolving `abandoned` is a signal only this paywall can act on — push a last-chance offer (a second product, not a second design) with a custom `sheet` transition |
61
61
  | `trial-reminders` | A local notification declared in config, scheduled by the SDK when the trial starts — the paywall needn't be open when it fires |
62
62
  | `web-funnel` | Selling on the web: steps as routes on `shift`, the answer kept in the URL with `useQueryState` (the rule for every web-funnel answer), then `checkout: "sheet"` — `purchase()` unchanged; `prefetch(reference)` on selection so the sheet opens instantly |
63
- | `teleport` | Finishing an app flow on the web: `teleport: { route: "plan" }` makes `router.push("plan")` open the plan in the browser with the app's `useQueryState` answer carried along; `fallbacks: { monthly: "annual" }` offers the App Store plan on the teleport screen; the plan page reads `useTeleport().status === "arrived"` |
63
+ | `teleport` | Finishing an app flow on the web: `teleport: { route: "plan" }` makes `router.push("plan")` open the plan in the browser with the app's `useQueryState` answer carried along; `fallbacks: { monthly: "annual" }` offers the App Store plan on the teleport screen; the plan page reads `useTeleport().status === "arrived"`; its `onFailure` calls `returnToApp({ data: { offer, plan } })`, and back in the app the goal route reads `useTeleport().failure` and `.data` (with `onReturnData`) to offer the App Store plan to a shopper short on funds |
64
64
 
65
65
  `purchase-states` is the only example showing the full haptic vocabulary
66
66
  (`success()` / `error()` keyed to outcomes). `abandonment-offer` contains
@@ -171,7 +171,7 @@ the attributes the framework stamps on `<html>`:
171
171
  | android · fullscreen | 24 (drawn under the status bar) | 0 (the SDK margins the webview above the nav bar) | 0 |
172
172
  | android · modal or drawer | 0 (sheet starts below the bar) | 0 (SDK pads it) | 0 |
173
173
  | any · popup | 0 | 0 | 0 (the SDK insets it) |
174
- | web | 0 | 0 | 0 (the browser owns its chrome) |
174
+ | web, including a page an app teleported to (`host` `"web-teleport"`) | 0 | 0 | 0 (the browser owns its chrome) |
175
175
 
176
176
  A **simulator** reports its host architecture (`arm64`) as `deviceModel`,
177
177
  not an `iPhone17,1`. SDKs that know it also report the simulated phone as
@@ -198,7 +198,35 @@ the insets can't make.
198
198
  `device.safeAreaInsets` (`{ top, right, bottom, left }`); the framework
199
199
  writes those as the `--sw-safe-area-floor-*`, so they stand in where
200
200
  `env()` reads 0. The studio's iPhone Duo (Closed) and (Open) presets do
201
- this with the insets measured in Apple's Duo simulator.
201
+ this with the insets measured in Apple's Duo simulator. Not on a page an
202
+ app teleported to: it runs in the shopper's browser, below the browser's
203
+ own bar, so the framework describes the browser there rather than the
204
+ app's phone. `<html>` gets `data-sw-platform="web"`, no `data-sw-idiom` or
205
+ `data-sw-cutout`, and `device.safeAreaInsets` is not written as floors, so
206
+ only the browser's `env()` applies, as on the pre-rendered first paint.
207
+
208
+ **Branch logic on `useDevice()`, not on `data-sw-platform`.** On a
209
+ teleported page `useDevice().hostPlatform` still reports the app's platform
210
+ (`"ios"`) and `useDevice().host` is `"web-teleport"`; only the attributes the
211
+ CSS reads say `web`. Key styles on `data-sw-platform`; key behaviour (copy,
212
+ which store, whether to show a step) on `hostPlatform` and `host`.
213
+
214
+ **No padding in the browser at all.** Zero the insets for every web host,
215
+ a teleported page included, and leave the in-app safe area as it is:
216
+
217
+ ```css
218
+ :root[data-sw-platform="web"] {
219
+ --sw-inset-top: 0px;
220
+ --sw-inset-right: 0px;
221
+ --sw-inset-bottom: 0px;
222
+ --sw-inset-left: 0px;
223
+ }
224
+ ```
225
+
226
+ It applies once the page takes over: the pre-rendered first paint has no
227
+ `data-sw-platform` yet and keeps the browser's own `env()` (0 at the top in
228
+ Safari), so a page with a bottom `env()` can still move by that much. An
229
+ edge `insets` sets in `config.ts` is written inline and wins over this rule.
202
230
 
203
231
  `push` and `noAnimation` are fullscreen. The attributes come from the
204
232
  device the host reports and are absent, never guessed, until the host's
@@ -19,6 +19,11 @@ screenshot, product table and an inventory, records the source in
19
19
  `superwall.lock` under `origins`, and connects the project to the same
20
20
  app. Read the brief first; every step below refers to it.
21
21
 
22
+ To preview first, run `superwall migrate <paywall-id> --dry-run`: it
23
+ needs a login, reads the paywall and its served document, prints the
24
+ `paywalls/<slug>` and `superwall.lock` entries it would write, and ends
25
+ with "Dry run - no changes made." without writing a file.
26
+
22
27
  ## What you are migrating from
23
28
 
24
29
  The served document (the brief's "Served document" URL) is a rendered