@superwall/cli 2.6.0-beta.2 → 2.6.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 (144) hide show
  1. package/README.md +47 -16
  2. package/dist/{apple-Dc5pOPms.js → apple-D-rfsuDA.js} +17 -19
  3. package/dist/{approve-BSbdmOez.js → approve-aPc5RoXB.js} +9 -11
  4. package/dist/{assets-C_RjojkK.js → assets-PyuXe45Y.js} +3 -3
  5. package/dist/auth.d.ts +11 -4
  6. package/dist/auth.js +4 -5
  7. package/dist/base-CAU0hWoI.js +82 -0
  8. package/dist/{billing-B6HK-F_a.js → billing-Dt6L_l9R.js} +3 -3
  9. package/dist/{build-DK88pTMW.js → build-CY5FnMNY.js} +35 -16
  10. package/dist/{client-x08fpvay.js → config-DOp5oChe.js} +162 -15
  11. package/dist/{create-B6-Dr3GZ.js → create-BZL5VH4L.js} +41 -41
  12. package/dist/{create-kpqEhqkk.js → create-D6w3UL0m.js} +9 -9
  13. package/dist/create-DM5Y1Pyk.js +18 -0
  14. package/dist/{doctor-DYbm8IKQ.js → doctor-C9FR0qw3.js} +50 -10
  15. package/dist/entry.js +45 -40
  16. package/dist/{environment-BFNzLLPN.js → environment-sE2wZYdg.js} +1 -1
  17. package/dist/{drivers-Dyi-y9Jn.js → existing--peXpOZj.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-CUBCOCGP.js} +8 -8
  21. package/dist/held-DVxvPMSG.js +15 -0
  22. package/dist/{install-DsIsif39.js → install-C5d82gZF.js} +15 -17
  23. package/dist/{integrate-B8eA676b.js → integrate-D8J_X1bj.js} +33 -38
  24. package/dist/{login-Blhxi20A.js → login-C6X7JrhM.js} +8 -9
  25. package/dist/{login-BlpfYapG.js → login-DXhm9L0F.js} +3 -3
  26. package/dist/login-et319ESO.js +13 -0
  27. package/dist/{lookup-Dg55W9S7.js → lookup-DqmIbUkv.js} +28 -4
  28. package/dist/{migrate-DoRb9jmA.js → migrate-BYF6hKZ2.js} +66 -45
  29. package/dist/{notification-url-D82msWF5.js → notification-url-Bo54nkXv.js} +4 -4
  30. package/dist/{open-BAqLpTSI.js → open-xdgXUzaF.js} +2 -2
  31. package/dist/{org-C4G7WjTV.js → org-BD8U3D1_.js} +4 -4
  32. package/dist/{organization-CmuQwcKN.js → organization-D-ZlB3qU.js} +4 -4
  33. package/dist/{orgs-1OzwUtpT.js → orgs-DQQJ3sw_.js} +1 -2
  34. package/dist/{paths-gBbqgkS7.js → paths-CIlyzF2I.js} +1 -1
  35. package/dist/{playbook-BKqlv77S.js → playbook-ecggWGFi.js} +10 -14
  36. package/dist/{products-Cqq59DBQ.js → products-CJq_iXv5.js} +1 -1
  37. package/dist/{promote-D0i8A0CO.js → promote-QVMLGYlU.js} +27 -28
  38. package/dist/{pull-DgQ_UmGv.js → pull-CCXhb2a7.js} +72 -26
  39. package/dist/{pull-CiIrJ5ik.js → pull-CrdsfsAl.js} +33 -39
  40. package/dist/pull-h71pL3r_.js +30 -0
  41. package/dist/push-BIq6R8Ro.js +29 -0
  42. package/dist/push-D6pJM_vv.js +21 -0
  43. package/dist/{push-7N4XIVtg.js → push-DJMGG7zW.js} +23 -12
  44. package/dist/{push-BWsXO7FN.js → push-DiMDwGfe.js} +8 -7
  45. package/dist/{registry-aAR_8VOw.js → registry-BSnQXft4.js} +1286 -901
  46. package/dist/registry-YwzTfCNc.js +22 -0
  47. package/dist/{resolve-CcOpO_5s.js → resolve-DO7bPota.js} +4 -4
  48. package/dist/{resources-DNwvf8rg.js → resources-XwvXA20E.js} +15 -2
  49. package/dist/{run-tVYJ3V5j.js → run-B-YvxfRc.js} +15 -17
  50. package/dist/scan-B36wkZmI.js +4 -0
  51. package/dist/{scan-dv0rrY4C.js → scan-ViBhmrB7.js} +1 -1
  52. package/dist/{scope-BXoQo30_.js → scope-BLLUxbrA.js} +24 -18
  53. package/dist/{scope-ehZ7L1nj.js → scope-Cg1AdAfO.js} +33 -3
  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-C07e_GGY.js} +4 -54
  57. package/dist/{series-D2ZpZ8cx.js → series-B8NJK4yS.js} +1 -1
  58. package/dist/{server-CcZGdYjE.js → server-CBtHzl9y.js} +40 -18
  59. package/dist/server-CZwSfzKe.js +33 -0
  60. package/dist/{base-83ZTv6up.js → session-BfVx50iA.js} +8 -83
  61. package/dist/{session-dHBtgSN0.js → session-BlrwAdGN.js} +1 -1
  62. package/dist/session-Cip4j99n.js +5 -0
  63. package/dist/{migration-BUedsREQ.js → setup-a4B72xJ8.js} +290 -28
  64. package/dist/skills/superwall/SKILL.md +37 -10
  65. package/dist/skills/superwall/references/api.md +66 -21
  66. package/dist/skills/superwall/references/asa.md +109 -64
  67. package/dist/skills/superwall/references/dashboard-links.md +65 -28
  68. package/dist/skills/superwall/references/data-analytics.md +1 -1
  69. package/dist/skills/superwall/workflows/dashboard/setup.md +15 -5
  70. package/dist/skills/superwall/workflows/integrate/flutter.md +9 -7
  71. package/dist/skills/superwall-framework/SKILL.md +197 -14
  72. package/dist/skills/superwall-framework/references/cli.md +98 -7
  73. package/dist/skills/superwall-framework/references/examples.md +2 -2
  74. package/dist/skills/superwall-framework/references/migrate-from-editor.md +5 -0
  75. package/dist/skills/superwall-framework/references/migrate-from-native.md +5 -0
  76. package/dist/{skills-Q7xB784d.js → skills-BB1uIt8t.js} +139 -9
  77. package/dist/{skills-Bqz2l_bx.js → skills-SnxFa2in.js} +8 -12
  78. package/dist/source-DQs6iLtC.js +82 -0
  79. package/dist/{source-push-CG948HrX.js → source-push-w7miTr6m.js} +38 -14
  80. package/dist/{spinner-IA6hV8nI.js → spinner-BQp7fQvK.js} +7 -5
  81. package/dist/{starter-BtUUQWhd.js → starter-BlJ_InZJ.js} +2 -2
  82. package/dist/{status-CB_MrFu5.js → status-DxsIw9zq.js} +9 -11
  83. package/dist/{output-Ggzq5_-t.js → storage-BR6imSqm.js} +40 -1
  84. package/dist/storekit-BqyujKQ_.js +203 -0
  85. package/dist/storekit-ELVCMF0X.js +15 -0
  86. package/dist/{bind-DcWIIPgk.js → theme-Ed0gz6hr.js} +29 -6
  87. package/dist/token-CWQ6tdva.js +100 -0
  88. package/dist/tools-skills/animate-onboarding/SKILL.md +1 -1
  89. package/dist/tools-skills/mobile-design/SKILL.md +1 -1
  90. package/dist/tools-skills/onboarding-questions/SKILL.md +1 -1
  91. package/dist/tools-skills/superwall/SKILL.md +43 -17
  92. package/dist/tools-skills/superwall/references/api.md +74 -24
  93. package/dist/tools-skills/superwall/references/asa.md +109 -64
  94. package/dist/tools-skills/superwall/references/dashboard-links.md +65 -28
  95. package/dist/tools-skills/superwall/references/data-analytics.md +1 -1
  96. package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +4 -3
  97. package/dist/tools-skills/superwall/workflows/dashboard/setup.md +21 -8
  98. package/dist/tools-skills/superwall/workflows/integrate/flutter.md +9 -7
  99. package/dist/tools-skills/superwall/workflows/migrate/adapty.md +4 -3
  100. package/dist/tools-skills/superwall/workflows/migrate/playbook.md +2 -2
  101. package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +4 -3
  102. package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +4 -3
  103. package/dist/tools-skills/superwall-editor/SKILL.md +2 -3
  104. package/dist/tools.d.ts +1 -1
  105. package/dist/tools.js +1230 -745
  106. package/dist/{try-CS3jLyoP.js → try-C3HW3hPZ.js} +17 -19
  107. package/dist/{lock-DgSx-p8Y.js → types-Dc9U_4kp.js} +86 -80
  108. package/dist/upgrade-Cw9jVt-r.js +348 -0
  109. package/dist/upgrade-DVsonzDF.js +27 -0
  110. package/package.json +11 -3
  111. package/dist/config-CGcG7GOt.js +0 -113
  112. package/dist/create-Du8Fx7W5.js +0 -20
  113. package/dist/existing-WQ3pz94o.js +0 -97
  114. package/dist/held-DmOhszHR.js +0 -17
  115. package/dist/log-C0MDCfA2.js +0 -62
  116. package/dist/login-D9jfRO8w.js +0 -17
  117. package/dist/pull-CO5HlqBe.js +0 -36
  118. package/dist/push-BIhGDNpL.js +0 -30
  119. package/dist/push-BgqTddLA.js +0 -22
  120. package/dist/run-B-YoyB-a.js +0 -100
  121. package/dist/scan-BU41gcQY.js +0 -4
  122. package/dist/screenshot-file-XAS0Xy0e.js +0 -16
  123. package/dist/server-BemmM1FV.js +0 -29
  124. package/dist/session-4aITGsF1.js +0 -6
  125. package/dist/setup-m94dpT3t.js +0 -217
  126. package/dist/spawn-DmmmHIP-.js +0 -71
  127. package/dist/storage-pR0Wb0d9.js +0 -41
  128. package/dist/storekit-BMxyYAHj.js +0 -17
  129. package/dist/storekit-CQnwlpKV.js +0 -47
  130. package/dist/telemetry-DU56L7Cy.js +0 -56
  131. package/dist/theme-DUsCh-Vd.js +0 -25
  132. package/dist/token-BbUeExGJ.js +0 -70
  133. package/dist/upgrade-CKn88PZD.js +0 -206
  134. package/dist/upgrade-DfD3-ClG.js +0 -7
  135. /package/dist/{browser-Bp3yRKlU.js → browser-BVjaf98V.js} +0 -0
  136. /package/dist/{client-BJQXl62Q.js → client-BwYhzITp.js} +0 -0
  137. /package/dist/{design-lint-CiFc78aM.js → design-lint-mgO-2SGS.js} +0 -0
  138. /package/dist/{devtools-ByZ6XYnn.js → devtools-B6Vp6HMy.js} +0 -0
  139. /package/dist/{input-MDd67UIp.js → input-DOT_2Zvb.js} +0 -0
  140. /package/dist/{project-NoMtbMyl.js → project-BomArwSj.js} +0 -0
  141. /package/dist/{reports-HYVp169R.js → reports-hbxsd3Zo.js} +0 -0
  142. /package/dist/{storage-Bdz5AmqS.d.ts → storage-Bh3wT1Rn.d.ts} +0 -0
  143. /package/dist/{timing-Ca0TXY-A.js → timing-BKEEIBij.js} +0 -0
  144. /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
 
@@ -89,8 +112,8 @@ curl -sL https://superwall.com/docs/framework/{page}.md # one page
89
112
  | `purchase()` outcomes, restore, the two channels | `purchases` |
90
113
  | Introductory-offer eligibility forking (`useIntroductoryOffer`), reminder notifications | `trials` |
91
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`), 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` |
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 })`, 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` |
94
117
  | Web funnels — answers in the URL (`useQueryState`), resume after a browser hand-off, `shift` | `web-funnels` |
95
118
  | Multi-page flows, router, cross-page state, shared chrome | `navigation` |
96
119
  | Built-in + custom transitions, bottom sheets | `transitions` |
@@ -121,11 +144,23 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
121
144
  2. **`purchase()` never throws for flow outcomes** — it resolves
122
145
  `completed | abandoned | failed`. React to the awaited result; treat
123
146
  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
147
+ A store purchase through the SDK resolves `failed` with
148
+ `reason: "unknown"` (or `"superseded"` when a newer purchase replaced it)
149
+ on iOS only: Android reports no purchase failures, so there a failed purchase stays pending until the user
126
150
  abandons or completes. The paywall runs no timer of its own; design the
127
151
  pending state to be survivable and never gate irreversible UI on
128
- `failed` on Android. What happens *after* a completed purchase is
152
+ `failed` on Android. On a hosted web paywall (`*.superwall.app`),
153
+ `purchase()` of a custom store product (`custom|…`) opens the store's
154
+ checkout itself in the same tab; never POST
155
+ `/v1/checkout/custom-store/session` yourself. It resolves `abandoned`
156
+ once the tab navigates (a second tap while the first is in flight also
157
+ resolves `abandoned` and opens nothing), and `failed` only when the
158
+ backend refuses the buyer's id (a placeholder such as `null`), no web
159
+ checkout is configured, or the network fails. A buyer without
160
+ `app_user_id` still gets the checkout as an anonymous buyer and a
161
+ redemption code after paying. Under the Web SDK custom store products
162
+ resolve `failed` as unsupported; inside an app they go to the SDK's
163
+ purchase. What happens *after* a completed purchase is
129
164
  `postPurchase` in config (or per call): `"dismiss"` (default), `"stay"`
130
165
  to keep the paywall up, and on the web `"redeem"` / `{ redirect }`;
131
166
  `"stay"` on the web is finished with `useCheckoutRedemption()`. Pass
@@ -146,6 +181,64 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
146
181
  // abandoned: the user closed the store sheet — nothing changes, nothing is said
147
182
  ```
148
183
 
184
+ **Why a payment failed.** A failed Stripe purchase resolves
185
+ `{ status: "failed", product, failure }`, and `usePurchase().failure`
186
+ holds the last failed purchase until the next one starts. `failure` is a
187
+ `CheckoutFailure`: `reason` in superwall's own words, `store: "stripe"`,
188
+ and Stripe's raw `code`, `declineCode` and `message` when Stripe gave
189
+ them. Branch on `reason`, never on Stripe's codes: the reasons stay the
190
+ same whichever store or payment method took the payment. `reason`
191
+ (`CheckoutFailureReason`) is one of:
192
+
193
+ | `reason` | Meaning |
194
+ | --- | --- |
195
+ | `card_declined` | the issuer declined and gave no more specific reason |
196
+ | `insufficient_funds` | not enough money or credit on the card |
197
+ | `expired_card` | the card has expired |
198
+ | `incorrect_card_details` | a wrong number, CVC, expiry, postal code or PIN |
199
+ | `authentication_failed` | 3D Secure or another bank check failed or was cancelled |
200
+ | `card_not_supported` | the card can't pay for this kind of purchase or in this currency |
201
+ | `limit_exceeded` | a spending, frequency or PIN-attempt limit was hit |
202
+ | `fraud_suspected` | the issuer or Stripe flagged it, or the card is lost or stolen |
203
+ | `processing_error` | the issuer or the network failed; trying again may work |
204
+ | `unknown` | nobody reported why, or the reason is one superwall doesn't know |
205
+
206
+ `unknown` means "no reason known": the purchase still failed, so never
207
+ read it as success and never guess a reason behind it. Give it the
208
+ generic copy. What each purchase path reports:
209
+
210
+ | Purchase | `failure.reason` |
211
+ | --- | --- |
212
+ | Stripe, direct Apple Pay on the web | the exact reason |
213
+ | Stripe, embedded sheet (`checkout: "sheet"`) | `unknown` until the subscriptions backend reports it; subscriptions may stay `unknown` |
214
+ | Stripe, hosted (redirect) checkout, every Stripe purchase in an iOS app | `unknown`; reasons aren't supported there |
215
+ | Stripe, teleport seen from the app | the page's exact reason when the page returned it, else as for its checkout |
216
+ | App Store or Play Store through the SDK | `reason: "unknown"` or `"superseded"` on the failure itself, no `failure` object; iOS only |
217
+ | Custom store (`custom|…`) | no reason, and no callbacks |
218
+
219
+ **Purchase callbacks.** Use superwall's callbacks, never Stripe's own
220
+ events: `usePurchase({ onStart, onSubmit, onComplete, onAbandon,
221
+ onFailure })` fires for every purchase on the paywall, whichever
222
+ component started it; `purchase(product, { onFailure, … })` takes the
223
+ same callbacks for that call only, beside the hook's. They fire on every
224
+ platform (native store purchases, the sheet, Apple Pay, hosted checkout,
225
+ teleport) except for custom store products. `onSubmit` is web checkout
226
+ only: the shopper submitted the sheet or authorized Apple Pay. The others
227
+ receive the product; `onFailure` receives the failed purchase, with
228
+ `reason` on it (and `store`, `code`, `declineCode`, `message` for a web
229
+ failure). In the embedded sheet `onFailure` fires on each decline while
230
+ the sheet stays open for another card, and `purchase()` resolves only
231
+ when the sheet is paid or closed:
232
+
233
+ ```tsx
234
+ const { purchase, failure } = usePurchase({
235
+ onFailure: (failed) => track("payment_failed", { reason: failed.reason }),
236
+ });
237
+ const result = await purchase("annual");
238
+ if (result.status === "failed" && "failure" in result && result.failure)
239
+ setNotice(t(`failure.${result.failure.reason}`)); // one string per reason, unknown included
240
+ ```
241
+
149
242
  The embedded Stripe sheet waits 10 s after a tap for Stripe's checkout
150
243
  to be ready. The wait only hides the spinner and resolves `failed`: Stripe
151
244
  keeps loading, the buyer stays on the paywall, and the next tap opens the
@@ -328,7 +421,11 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
328
421
  merchant's site vs Superwall's hosted web paywall page, the teleport
329
422
  page, the studio) branches on `useDevice().host` — `"ios-sdk" |
330
423
  "android-sdk" | "web-sdk" | "web-paywall" | "web-teleport" | "studio" |
331
- "browser"`, never `undefined` — never on the URL or `window`. UI that
424
+ "browser"`, never `undefined` — never on the URL or `window`. It is
425
+ reliable on web pages that carry a WebKit message handler: a hosted web
426
+ paywall reads `"web-paywall"` and the Web SDK `"web-sdk"`; only a real
427
+ iOS app reads `"ios-sdk"`. Never detect a hosted page yourself through
428
+ `window.webPaywallCtrl`, `client_surface` or `window.webkit`. UI that
332
429
  depends on which browser shows the page (an "open in Safari" hint for a
333
430
  funnel opened from an Instagram ad) branches on `useDevice().browser` —
334
431
  `SuperwallBrowser | undefined`, known from the first render — never on
@@ -358,14 +455,83 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
358
455
  `useTeleport().prefetch(route)` for a route only the router teleports).
359
456
  The route opens on the web with every `useQueryState` value carried
360
457
  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
458
+ web half needs in `useQueryState`, not component state. The
459
+ `teleport.route` page is pre-rendered at `superwall push` per locale,
460
+ Stripe product (plus none) and trial, and the browser paints it before
461
+ any JS runs, so its first render draws only from the locale, the
462
+ products and prices, the trial and `useTeleport().productReference`.
463
+ Read `window`, dates, random values, dark mode and `useQueryState`
464
+ answers in an effect or below the first frame, never in that first
465
+ render, or the page redraws when it takes over. A pre-render warning in
466
+ `push` output means those pages render in the browser instead; fix what
467
+ it names. A custom teleport screen renders while
468
+ `useTeleport().status === "waiting"` and not `returned`, reopens with
469
+ `open()`, and buys the fallback with plain
364
470
  `purchase()`; count cancels and returns with `useTeleport({ onCancel,
365
471
  onReturn })`, never with your own timers (`onCancel` is the Cancel
366
472
  button only; an unpaid return shows as `purchase()` resolving
367
- `abandoned`). Fetch `teleport`; the
368
- `teleport` example is the complete flow to start from.
473
+ `abandoned`). On the web half, go back to the app only with
474
+ `useTeleport().returnToApp()` (or `close()` / `router.back()` on the
475
+ first web route) — never `openDeepLink`, `openUrl` or a hand-built scheme
476
+ or universal link. The framework picks the link: the universal link
477
+ first, the URL scheme when iOS won't follow it, which is every return
478
+ nobody tapped, such as one after Apple Pay is closed. While iOS asks
479
+ "Open in…?" it dims the page and points at Open itself; draw nothing for
480
+ it. `returnToApp()` resolves `"opened" | "cancelled" | "no_app"`
481
+ (`"cancelled"`: the shopper tapped Cancel; `"no_app"`: nothing could open
482
+ the app), and `useTeleport().returning` is true meanwhile. On anything
483
+ but `"opened"` the shopper is still on the page: leave it as it is, ready
484
+ to buy again.
485
+
486
+ ```tsx
487
+ const { returnToApp } = useTeleport();
488
+ const result = await purchase("web");
489
+ if (result.status === "completed") haptics.success();
490
+ else if (result.status === "failed") setNotice(t("purchase.failed")); // say so, keep the button
491
+ else {
492
+ // abandoned: the shopper closed the sheet without paying
493
+ const back = await returnToApp(); // "opened" | "cancelled" | "no_app"
494
+ if (back === "opened") return;
495
+ // "cancelled" or "no_app": still on this page — change nothing, the buy button stays
496
+ }
497
+ ```
498
+
499
+ **Sending a failed payment back to the app.** After a decline on the
500
+ teleport page, `returnToApp()` leaves the app the page's `failure`
501
+ without being asked (its return link carries `reason=failed`), and
502
+ `returnToApp({ data })` adds your own plain JSON, at most 16 KB: over
503
+ that the page logs a warning and leaves only the failure. Put new
504
+ fields inside `data`; never encode them in the link. In the app,
505
+ `useTeleport()` shows them as `failure` and `data` while `status ===
506
+ "waiting"`, `onFailure` fires and `usePurchase().failure` is set;
507
+ `useTeleport({ onReturnData })` fires once the data is read. You never
508
+ pass the reason yourself. Nothing is left after a paid purchase (the
509
+ teleport is closed), and no SDK change is needed: the app reads them
510
+ from the teleport's session. Until the backend reports the sheet's
511
+ reason, a sheet decline reaches the app as `unknown`; Apple Pay's is
512
+ exact. Branch on `failure.reason` in the app as anywhere else:
513
+
514
+ ```tsx
515
+ // teleport page: send a shopper short on funds back to the App Store plan
516
+ const teleport = useTeleport();
517
+ const { purchase } = usePurchase({
518
+ onFailure: (failure) => {
519
+ if (teleport.status !== "arrived") return;
520
+ const offer = failure.reason === "insufficient_funds" ? "app_store" : "retry";
521
+ void teleport.returnToApp({ data: { offer } });
522
+ },
523
+ });
524
+
525
+ // app route: offer another way to pay
526
+ const back = useTeleport({ onReturnData: (data) => console.info("back from the page", data) });
527
+ const failure = back.status === "waiting" ? back.failure : undefined;
528
+ if (failure?.reason === "insufficient_funds" || failure?.reason === "card_declined") {
529
+ // show a store product (purchase("annual")) or Apple Pay; `unknown` says only that it failed
530
+ }
531
+ ```
532
+
533
+ Fetch `teleport`; the `teleport` example is the complete flow to start
534
+ from.
369
535
  13. **Shipping includes the dashboard.** A push that fails on missing
370
536
  products is not a blocker to report — create them with
371
537
  `superwall products create` ([references/cli.md](references/cli.md)).
@@ -447,6 +613,13 @@ superwall push # sealed version, production untouched; diagnostics har
447
613
  superwall promote # ship (or: superwall publish -m "why")
448
614
  ```
449
615
 
616
+ After a push, promote or publish, give the user the paywall's studio link:
617
+ `https://app.superwall.com/{orgId}/{applicationId}/paywalls/{paywallId}/studio`.
618
+ The app and paywall ids are in `superwall.lock`; `orgId` is
619
+ `organization_id` in `GET /v2/projects`. Never link a code-first paywall to
620
+ the legacy `superwall.com/editor` — it cannot open one. Every other
621
+ dashboard page is in the `superwall` skill's `references/dashboard-links.md`.
622
+
450
623
  Before calling a paywall done, run the audit at the end of the
451
624
  `mobile-design` skill (and the framework items in
452
625
  [references/mobile-design.md](references/mobile-design.md)) and the matrix
@@ -465,6 +638,16 @@ it, so pass it only when the user says to. In an empty folder,
465
638
  `superwall pull --app <id>` gets every paywall of an app without GitHub
466
639
  ([references/cli.md](references/cli.md)).
467
640
 
641
+ In a pnpm monorepo whose `pnpm-workspace.yaml` does not list `superwall`,
642
+ a bare `pnpm install` in `superwall/` installs the parent workspace, exits
643
+ 0 and leaves `superwall/` empty; `superwall dev` then fails with
644
+ `No superwall framework found`. Install and re-install there with
645
+ `pnpm install --ignore-workspace` and commit `superwall/pnpm-lock.yaml`, or
646
+ add `superwall` to the workspace patterns to share the root lockfile.
647
+ Never take a clean `pnpm install` exit as proof: check that
648
+ `superwall/node_modules/superwall` exists. bun and npm are not affected
649
+ ([references/cli.md](references/cli.md#installing-in-a-pnpm-monorepo)).
650
+
468
651
  ## Report what's broken
469
652
 
470
653
  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
@@ -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
@@ -13,6 +13,11 @@ superwall migrate --screen App/UpdateRequiredView.swift # in the app's root
13
13
  superwall migrate --screen # scan for likely screens and pick
14
14
  ```
15
15
 
16
+ Add `--dry-run` to preview first: it reads the screen, prints the
17
+ `paywalls/<slug>` it would create and ends with "Dry run - no changes
18
+ made." without writing a file, prompting for a screenshot or starting the
19
+ agent or the studio.
20
+
16
21
  The scan reads that one file — SwiftUI or UIKit (`.swift`), Jetpack Compose or
17
22
  Android Views (`.kt`), React Native (`.tsx`), Flutter (`.dart`) — and writes into the project it finds (or a
18
23
  new `superwall/`):