@superwall/cli 2.6.1 → 2.7.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 (137) hide show
  1. package/dist/{apple-BE1GBJFP.js → apple-DfYTDEJy.js} +16 -16
  2. package/dist/{approve-yRZmvkCj.js → approve-CoQJhii4.js} +7 -7
  3. package/dist/{assets-DTAgbWw0.js → assets-BN0tFoj7.js} +3 -3
  4. package/dist/auth.d.ts +1 -1
  5. package/dist/auth.js +3 -3
  6. package/dist/{base-zc1wl_9b.js → base-DAnzMjI8.js} +2 -2
  7. package/dist/{billing-C1LV4-BN.js → billing-CFGrG-WZ.js} +3 -3
  8. package/dist/{build-CQd-pf7O.js → build-CTBvzIG8.js} +10 -10
  9. package/dist/{config-DCqRQTJ4.js → config-CJRNScT0.js} +4 -4
  10. package/dist/{create-wlCp83IH.js → create-BLs-0ETi.js} +29 -29
  11. package/dist/create-C_kjQp0N.js +18 -0
  12. package/dist/{create-Costu6UT.js → create-aWzdpjJU.js} +8 -8
  13. package/dist/{doctor-Bd9ffg51.js → doctor-ChI2Kfru.js} +21 -21
  14. package/dist/entry.js +28 -29
  15. package/dist/{environment-Dn7irhZr.js → environment-BQiaGqjB.js} +1 -1
  16. package/dist/{existing-BQMB_2AG.js → existing-Cxg_gSN1.js} +8 -8
  17. package/dist/{git-Hf9Wc7Hp.js → git-D9ooAMt7.js} +1 -1
  18. package/dist/held-CQMCqJMa.js +15 -0
  19. package/dist/{held-D5wSX2Mf.js → held-CmvNRCRD.js} +327 -22
  20. package/dist/{scope-DDYLQeZw.js → input-ApyzIzVy.js} +48 -7
  21. package/dist/{install-CxyqfKFe.js → install-DM0JBdpE.js} +12 -12
  22. package/dist/{integrate-MkyDDzI5.js → integrate-ZQUaScQ0.js} +21 -22
  23. package/dist/login-Cnt3UZKV.js +13 -0
  24. package/dist/{login-B7IqDafm.js → login-CvzBt9eM.js} +2 -2
  25. package/dist/{login-BMHDhxAx.js → login-Oo2NWLlX.js} +7 -7
  26. package/dist/{lookup-DkcT4E-5.js → lookup-CHLrO7v7.js} +3 -3
  27. package/dist/{migrate-CdFoZipj.js → migrate-mFKBset8.js} +30 -30
  28. package/dist/{notification-url-D6KKeXnk.js → notification-url-Dpx0pbYs.js} +3 -3
  29. package/dist/{open-COJE6ryI.js → open-CxgE8kLT.js} +2 -2
  30. package/dist/{org-BV8wwxwc.js → org-0KDPRSlc.js} +4 -4
  31. package/dist/{organization-9R_1PJKk.js → organization-Cg--QQtz.js} +4 -4
  32. package/dist/{orgs-ltP8H0Nl.js → orgs-Df8DzIav.js} +1 -1
  33. package/dist/{paths-Cb1RfjaX.js → paths-B4FNcaHO.js} +1 -1
  34. package/dist/{playbook-CVGolez9.js → playbook-pFhIg_0e.js} +10 -10
  35. package/dist/{promote-B_HnFEbX.js → promote-Crwz1xI0.js} +23 -23
  36. package/dist/{pull-DF4KYVcP.js → pull-BixwETu1.js} +10 -10
  37. package/dist/pull-C0gY7HGj.js +30 -0
  38. package/dist/{pull-lYRULo4v.js → pull-D8GfsKha.js} +30 -30
  39. package/dist/{push-BZN1Qpkq.js → push-BKoav_FU.js} +10 -10
  40. package/dist/{push-BnllH2Rd.js → push-BNFvZHUM.js} +8 -8
  41. package/dist/push-DOaBj8hr.js +29 -0
  42. package/dist/push-uWv5P0LA.js +21 -0
  43. package/dist/{registry-CqePfigB.js → registry-BPqRG08G.js} +268 -433
  44. package/dist/registry-DGHTk7l-.js +21 -0
  45. package/dist/{resolve-B4bd3Qjl.js → resolve-CarLrF4b.js} +3 -3
  46. package/dist/{resources-BaURbSpY.js → resources-BeXleviK.js} +15 -34
  47. package/dist/{run-Bme4Egyl.js → run-naBCXCfn.js} +14 -14
  48. package/dist/{scan-DugxddUU.js → scan-CtYVCqDS.js} +1 -1
  49. package/dist/scan-KWnscsk-.js +4 -0
  50. package/dist/{sdk-BFunw4Hc.js → sdk-BKVRAv23.js} +2 -2
  51. package/dist/{selection-C439nEhn.js → selection-CpEfqw2b.js} +1 -1
  52. package/dist/{series-B8NJK4yS.js → series-C9OU5kd7.js} +1 -1
  53. package/dist/server-DjBnyiwD.js +33 -0
  54. package/dist/{server-C_aMxzvS.js → server-Dp5Imq3v.js} +11 -11
  55. package/dist/{session-CfG3gzko.js → session-6HA1OwHe.js} +6 -6
  56. package/dist/session-BatiAUPQ.js +5 -0
  57. package/dist/{session-B7frlXXQ.js → session-BpLOLurZ.js} +1 -1
  58. package/dist/{setup-DQEasPhx.js → setup-RL-5c6SV.js} +10 -10
  59. package/dist/skills/superwall/SKILL.md +8 -1
  60. package/dist/skills/superwall/references/api.md +34 -3
  61. package/dist/skills/superwall/references/asc.md +5 -1
  62. package/dist/skills/superwall/workflows/dashboard/playbook.md +1 -1
  63. package/dist/skills/superwall/workflows/dashboard/setup.md +6 -2
  64. package/dist/skills/superwall/workflows/migrate/adapty.md +1 -1
  65. package/dist/skills/superwall/workflows/migrate/playbook.md +6 -1
  66. package/dist/skills/superwall/workflows/migrate/qonversion.md +1 -1
  67. package/dist/skills/superwall/workflows/migrate/revenuecat.md +1 -1
  68. package/dist/skills/superwall/workflows/placements/android.md +4 -1
  69. package/dist/skills/superwall/workflows/placements/expo.md +4 -1
  70. package/dist/skills/superwall/workflows/placements/flutter.md +4 -1
  71. package/dist/skills/superwall/workflows/placements/ios.md +4 -1
  72. package/dist/skills/superwall/workflows/placements/playbook.md +6 -1
  73. package/dist/skills/superwall/workflows/placements/react-native.md +4 -1
  74. package/dist/skills/superwall/workflows/placements/strategy.md +4 -1
  75. package/dist/skills/superwall-framework/SKILL.md +54 -4
  76. package/dist/skills/superwall-framework/references/cli.md +6 -0
  77. package/dist/skills/superwall-framework/references/elements-checkout.md +457 -0
  78. package/dist/skills/superwall-framework/references/examples.md +1 -0
  79. package/dist/skills/superwall-framework/references/layout.md +10 -0
  80. package/dist/skills/teleport/SKILL.md +1 -1
  81. package/dist/{skills-DnegE1A6.js → skills-C1ku2pgy.js} +5 -5
  82. package/dist/{skills-MmF7IyTg.js → skills-CkAWJveA.js} +8 -8
  83. package/dist/{source-push-MbJjh4Ki.js → source-push-D59hV02W.js} +6 -6
  84. package/dist/{spinner-Dcr-Dqdi.js → spinner-hTCJZAoJ.js} +42 -7
  85. package/dist/{starter-BlJ_InZJ.js → starter-jYb2nmlb.js} +3 -3
  86. package/dist/{status-DHRxg1ZA.js → status-DrD9CHtK.js} +7 -7
  87. package/dist/{storage-DdIAHolY.js → storage-D0Q4xBi-.js} +1 -1
  88. package/dist/storekit-CAOpa6_f.js +14 -0
  89. package/dist/{storekit-De998QOt.js → storekit-TLBxGIrN.js} +5 -5
  90. package/dist/{theme-BrUrye-c.js → theme-Bvv0yrk_.js} +5 -5
  91. package/dist/{token-CKCBQ4I8.js → token-SEWilQo9.js} +1 -1
  92. package/dist/tools-skills/superwall/SKILL.md +8 -1
  93. package/dist/tools-skills/superwall/references/api.md +34 -3
  94. package/dist/tools-skills/superwall/references/asc.md +5 -1
  95. package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +1 -1
  96. package/dist/tools-skills/superwall/workflows/dashboard/setup.md +6 -2
  97. package/dist/tools-skills/superwall/workflows/migrate/adapty.md +1 -1
  98. package/dist/tools-skills/superwall/workflows/migrate/playbook.md +6 -1
  99. package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +1 -1
  100. package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +1 -1
  101. package/dist/tools-skills/superwall/workflows/placements/android.md +4 -1
  102. package/dist/tools-skills/superwall/workflows/placements/expo.md +4 -1
  103. package/dist/tools-skills/superwall/workflows/placements/flutter.md +4 -1
  104. package/dist/tools-skills/superwall/workflows/placements/ios.md +4 -1
  105. package/dist/tools-skills/superwall/workflows/placements/playbook.md +6 -1
  106. package/dist/tools-skills/superwall/workflows/placements/react-native.md +4 -1
  107. package/dist/tools-skills/superwall/workflows/placements/strategy.md +4 -1
  108. package/dist/tools-skills/teleport/SKILL.md +1 -1
  109. package/dist/tools.d.ts +4 -2
  110. package/dist/tools.js +1352 -1187
  111. package/dist/{try-C8QQbG0b.js → try-BpMpLGCs.js} +15 -15
  112. package/dist/{ui-hFgji1e8.js → ui-Dye-QvEj.js} +26 -1
  113. package/dist/{upgrade-D0thxCA4.js → upgrade-BLFWdbGR.js} +7 -7
  114. package/dist/upgrade-BzN7PjKg.js +27 -0
  115. package/package.json +2 -2
  116. package/dist/create-CSHGZDfB.js +0 -18
  117. package/dist/held-Dmf5SR3p.js +0 -15
  118. package/dist/input-DOT_2Zvb.js +0 -42
  119. package/dist/login-Cp0-BgDZ.js +0 -13
  120. package/dist/pull-JxiMyRwY.js +0 -30
  121. package/dist/push-B5py7h5y.js +0 -29
  122. package/dist/push-DHlUMkbf.js +0 -21
  123. package/dist/registry-BGEYCWyD.js +0 -22
  124. package/dist/scan-J2DILUNE.js +0 -4
  125. package/dist/server-Cif9w5lM.js +0 -33
  126. package/dist/session-DvaPyOuH.js +0 -5
  127. package/dist/storekit-iBCWmeKn.js +0 -15
  128. package/dist/upgrade-CYFdpVpi.js +0 -27
  129. /package/dist/{design-lint-mgO-2SGS.js → design-lint-CeG3_ZWN.js} +0 -0
  130. /package/dist/{devtools-B6Vp6HMy.js → devtools-B3tCQFD-.js} +0 -0
  131. /package/dist/{download-DhGd4hOB.js → download-DVFHIwia.js} +0 -0
  132. /package/dist/{project-BomArwSj.js → project-Dml4t7jO.js} +0 -0
  133. /package/dist/{reports-hbxsd3Zo.js → reports-CJQ-8sj4.js} +0 -0
  134. /package/dist/{screenshot-file-Dix2Qynm.js → screenshot-file-CcqMLpL5.js} +0 -0
  135. /package/dist/{source-DQs6iLtC.js → source-Ct9kOCAb.js} +0 -0
  136. /package/dist/{storage-Bh3wT1Rn.d.ts → storage-BaK-MUM8.d.ts} +0 -0
  137. /package/dist/{timing-BKEEIBij.js → timing-m0ZUzYiP.js} +0 -0
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: superwall-framework
3
- description: Author any screen an app should be able to change without a release — paywalls, offers, onboarding funnels, update-required and force-upgrade screens, lifecycle prompts, announcements, web checkout flows — as React mini-apps with the superwall framework (the `superwall` npm package). Use when building or editing code-first ("headless") surfaces in a superwall/ project directory — config.ts, app/ routes, hooks (useProducts, usePurchase, useDiscount, useActions…), navigation, localization, assets, insets and mobile layout — when running `superwall create/dev/push/promote/publish/pull` (including pulling a teammate's paywalls or an app's source into an empty folder with `superwall pull --app`), when rebuilding a dashboard (visual editor) paywall as code (`superwall migrate <id>`), or when a native SwiftUI / Kotlin / React Native / Flutter screen of that kind is being built and should become a Superwall surface instead. The default for any screen an agent builds that the user would rather change after shipping than release for (paywalls, onboarding, update-required, lifecycle prompts, announcements, offers, web flows); the browser visual editor (superwall-editor) is legacy and only for explicit edits inside it. NOT for general CLI/resource management (superwall).
3
+ description: Author any screen an app should be able to change without a release — paywalls, offers, onboarding funnels, update-required and force-upgrade screens, lifecycle prompts, announcements, web checkout flows — as React mini-apps with the superwall framework (the `superwall` npm package). Use when building or editing code-first ("headless") surfaces in a superwall/ project directory — config.ts, app/ routes, hooks (useProducts, usePurchase, useDiscount, useActions…), custom checkout forms built from Stripe Elements (the elements checkout mode, `superwall/checkout`, `superwall/checkout/stripe`), navigation, localization, assets, insets and mobile layout — when running `superwall create/dev/push/promote/publish/pull` (including pulling a teammate's paywalls or an app's source into an empty folder with `superwall pull --app`), when rebuilding a dashboard (visual editor) paywall as code (`superwall migrate <id>`), or when a native SwiftUI / Kotlin / React Native / Flutter screen of that kind is being built and should become a Superwall surface instead. The default for any screen an agent builds that the user would rather change after shipping than release for (paywalls, onboarding, update-required, lifecycle prompts, announcements, offers, web flows); the browser visual editor (superwall-editor) is legacy and only for explicit edits inside it. NOT for general CLI/resource management (superwall).
4
4
  ---
5
5
 
6
6
  # The superwall framework
@@ -89,6 +89,7 @@ web page inside an app.
89
89
  | Migrating a dashboard (visual editor) paywall to code — `superwall create --from <id>`, reading the editor's document store, the element / action / state mapping, Compare › Original, the review gate, the campaign switch, and the rebuild playbook the CLI hands its agent | [references/migrate-from-editor.md](references/migrate-from-editor.md) |
90
90
  | Migrating a native screen to a surface — `superwall migrate --screen <path>`, what the scan reads, the screenshot original, the rebuild playbook, wiring `register()` afterwards | [references/migrate-from-native.md](references/migrate-from-native.md) |
91
91
  | What each native construct becomes, per source framework, and the `register()` wiring in that SDK | [references/native/ios.md](references/native/ios.md) (SwiftUI, UIKit) · [android.md](references/native/android.md) (Compose, Views) · [react-native.md](references/native/react-native.md) · [flutter.md](references/native/flutter.md) |
92
+ | **A checkout form of the paywall's own — must-follow.** `checkout: "elements"`: `<StripeCheckout>`, `useCheckout()`, `<PurchaseButton>`, which Stripe elements work, the email rule, styling from the design tokens, layout recipes (Apple Pay + Link + card), the callbacks per payment path, moving an existing Stripe checkout onto superwall | [references/elements-checkout.md](references/elements-checkout.md) |
92
93
  | Examples — using them, browsing them, what each teaches | [references/examples.md](references/examples.md) |
93
94
 
94
95
  ## Everything else — fetch the docs live
@@ -111,7 +112,7 @@ curl -sL https://superwall.com/docs/framework/{page}.md # one page
111
112
  | Declaring products, reading variables, the three price rules | `products` |
112
113
  | `purchase()` outcomes, restore, the two channels | `purchases` |
113
114
  | Introductory-offer eligibility forking (`useIntroductoryOffer`), reminder notifications | `trials` |
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
+ | Selling on the web — modes (a custom form in `elements` mode is [references/elements-checkout.md](references/elements-checkout.md)), 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
116
  | 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
117
  | 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
118
  | 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` |
@@ -145,6 +146,10 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
145
146
  2. **`purchase()` never throws for flow outcomes** — it resolves
146
147
  `completed | abandoned | failed`. React to the awaited result; treat
147
148
  abandoned as an outcome. Never put the buy button in a loading state.
149
+ The one exception is the `<PurchaseButton>` of an `elements` checkout
150
+ form (rule 22): a card payment opens no store sheet, so the button
151
+ disables itself while paying and its label says so
152
+ (`useCheckout().status === "paying"`).
148
153
  A store purchase through the SDK resolves `failed` with
149
154
  `reason: "unknown"` (or `"superseded"` when a newer purchase replaced it)
150
155
  on iOS only: Android reports no purchase failures, so there a failed purchase stays pending until the user
@@ -293,8 +298,10 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
293
298
  wallet opens only for a product prepared before the tap: config
294
299
  `checkout: "applePay"` prepares it on its own, a `"sheet"` paywall calls
295
300
  `prefetch(ref, { checkout: "applePay" })`, and an unprepared tap opens
296
- the sheet. Any other config `checkout` sends a Stripe purchase to the
297
- hosted page. Types come from `superwall/hooks`; `examples/apple-pay`
301
+ the sheet. Config `checkout: "elements"` prepares it too, from the
302
+ form's price, so a button of the paywall's own can open superwall's
303
+ Apple Pay beside the card form. Any other config `checkout` sends a
304
+ Stripe purchase to the hosted page. Types come from `superwall/hooks`; `examples/apple-pay`
298
305
  renders the hook.
299
306
 
300
307
  ```tsx
@@ -482,6 +489,10 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
482
489
  paywall with `teleport` asks Apple as it opens, so the answer is
483
490
  usually there before the first tap. To set up an app-to-web flow or
484
491
  experiment end to end, use the `teleport` skill.
492
+ In `superwall dev`, a push the studio teleports turns the preview into
493
+ the browser page (`web`, no in-app floors, ending above Safari's
494
+ toolbar on a portrait iPhone): check the web half's styling there, as in
495
+ [references/layout.md](references/layout.md).
485
496
  The route opens on the web with every `useQueryState` value carried
486
497
  along, and the app is credited when the shopper pays. Keep answers the
487
498
  web half needs in `useQueryState`, not component state. The
@@ -633,6 +644,45 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
633
644
  attribute (`useUserAttribute`), which the host persists. Use storage only for something optional, inside a
634
645
  `try`/`catch` that treats a failure as unset (docs: `troubleshooting`).
635
646
 
647
+ 22. **A checkout form of the paywall's own is `checkout: "elements"`,
648
+ built only from superwall's imports.** Read
649
+ [references/elements-checkout.md](references/elements-checkout.md)
650
+ before writing one. The CTA, the "due today" line and the failure
651
+ notice come from `useCheckout()` and `<PurchaseButton>` in
652
+ `superwall/checkout`, which work in any store's form. `<StripeCheckout>`
653
+ and Stripe's elements come from `superwall/checkout/stripe`, used only
654
+ inside the Stripe form. Never install or import `@stripe/*`: a project's
655
+ own copy has its own React context, and its elements throw "Could not
656
+ find Elements context". Every purchase needs an email (from
657
+ `LinkAuthenticationElement`, a wallet, the `email` prop or the user's
658
+ `email` attribute); without one `submit()` returns `incomplete` with
659
+ `email_required` and charges nothing. `options` must be stable: build it
660
+ with `useMemo`, or Stripe redraws every field. Inside the iOS app, in
661
+ Studio and on SDKs below 4.10.8 the form reports `unavailable` and draws
662
+ nothing, so the paywall still offers `usePurchase().purchase()` there.
663
+ `examples/elements-checkout` is the reference.
664
+
665
+ ```tsx
666
+ const Pay = ({ product }: { product: Plan }) => {
667
+ const { status, amounts } = useCheckout();
668
+ const { purchase } = usePurchase();
669
+ if (status === "unavailable")
670
+ return <button onClick={() => void purchase(product)}>{t("cta.subscribe")}</button>;
671
+ return (
672
+ <PurchaseButton>
673
+ {status === "paying" ? t("cta.paying") : amounts?.trialDays ? t("cta.trial") : t("cta.subscribe")}
674
+ </PurchaseButton>
675
+ );
676
+ };
677
+
678
+ const options = useMemo<StripeCheckoutOptions>(() => ({ appearance }), [appearance]);
679
+ <StripeCheckout product={product} options={options}>
680
+ <LinkAuthenticationElement />
681
+ <PaymentElement />
682
+ <Pay product={product} />
683
+ </StripeCheckout>;
684
+ ```
685
+
636
686
  ## Working loop
637
687
 
638
688
  ```bash
@@ -231,6 +231,12 @@ superwall products create --identifier <identifier> \
231
231
  lists them.
232
232
  - `--price` is major units (39.99); `--period` is `day|week|month|year`;
233
233
  `--trial-days` sets the intro offer. `--dry-run` confirms the target first.
234
+ - Change a trial or period later with
235
+ `superwall products update <id> --trial-days <n> --yes` (also `--period`,
236
+ `--period-count`; a one-time product needs `--period` with
237
+ `--trial-days`), never a raw `superwall patch`. It needs a CLI newer than
238
+ 2.6.1; the `superwall` skill's API reference has the details and the
239
+ fallback for older CLIs.
234
240
 
235
241
  Derive identifiers and prices from the design. Where the design shows a
236
242
  placeholder (`US$XX.xx`), pick an explicit stand-in and say so — never
@@ -0,0 +1,457 @@
1
+ # Build your own checkout form from Stripe's elements
2
+
3
+ `checkout: "elements"` lets a paywall build its own checkout form from
4
+ Stripe's own elements (wallet buttons, a card form, an email field, an
5
+ address) while superwall prices the form, takes the payment, runs 3D Secure
6
+ and the free trial, and completes the purchase with entitlements and
7
+ redemption, exactly as Apple Pay and the sheet do. The project installs
8
+ nothing from Stripe and runs no backend. The `elements-checkout` example is
9
+ the reference implementation; its chips switch between ten layouts of the
10
+ same purchase.
11
+
12
+ ## Which mode
13
+
14
+ | The paywall wants | `checkout` |
15
+ | ------------------------------------------------------------------- | ------------------------ |
16
+ | To leave for Superwall's hosted checkout page and come back | `"external"` (default) |
17
+ | Stripe's ready-made payment sheet, no design work | `"sheet"` |
18
+ | One key straight to Apple Pay, the sheet where it isn't available | `"applePay"` |
19
+ | Its own form: card fields, wallets, Link, in the paywall's design | `"elements"` |
20
+
21
+ Pick `elements` when the card form sits on the paywall itself, styled like
22
+ it, or when an existing custom Stripe checkout is being moved onto
23
+ superwall. Pick `sheet` when nobody wants to design a form, and `applePay`
24
+ when Apple Pay is the only button. In `elements` mode a plain
25
+ `purchase(product)` still opens the sheet, and superwall's Apple Pay sheet is
26
+ prepared too (see [Recipes](#recipes)).
27
+
28
+ ```ts
29
+ // config.ts
30
+ checkout: { mode: "elements", prefetch: "trial" },
31
+ products: {
32
+ trial: "test:price_1R7OiTBmoUO4I4NSACz7JoAy:3days-free",
33
+ monthly: "test:price_1RJpYPBmoUO4I4NSX0AUMLee:no-trial",
34
+ },
35
+ ```
36
+
37
+ `prefetch` names the product whose price loads as the paywall opens
38
+ (default: the first Stripe product; `false` turns it off), so the form
39
+ renders without a wait. Any other product loads when `<StripeCheckout>`
40
+ first asks for it. `prepaidCards: "block"` can't filter an `elements`
41
+ payment; only the sheet fallback refuses prepaid cards.
42
+
43
+ ## The imports
44
+
45
+ ```tsx
46
+ import { PurchaseButton, useCheckout } from "superwall/checkout";
47
+ import {
48
+ ExpressCheckoutElement,
49
+ LinkAuthenticationElement,
50
+ PaymentElement,
51
+ StripeCheckout,
52
+ } from "superwall/checkout/stripe";
53
+ ```
54
+
55
+ - **`superwall/checkout`** holds what every store's form shares:
56
+ `useCheckout()`, `<PurchaseButton>` and their types (`UseCheckoutResult`,
57
+ `CheckoutAmounts`, `CheckoutSubmitResult`, `CheckoutUnavailableReason`,
58
+ `CheckoutFailure`, `PurchaseButtonProps`). Build the CTA, the "due today"
59
+ line and the failure notice on these, so they work unchanged in another
60
+ store's form.
61
+ - **`superwall/checkout/stripe`** holds what is Stripe's: `<StripeCheckout>`,
62
+ `StripeCheckoutOptions`, `StripeCheckoutProps`, and Stripe's elements.
63
+ Import from it only inside the Stripe form. A paywall that never imports it
64
+ never ships Stripe's React bindings.
65
+ - **Never import from `@stripe/react-stripe-js` or `@stripe/stripe-js`, and
66
+ never install them.** A project's own copy of Stripe's React package has
67
+ its own context: its elements can't see `<StripeCheckout>` and throw
68
+ "Could not find Elements context".
69
+
70
+ ## A form
71
+
72
+ ```tsx
73
+ import { useMemo } from "react";
74
+ import { PurchaseButton, useCheckout } from "superwall/checkout";
75
+ import {
76
+ ExpressCheckoutElement,
77
+ LinkAuthenticationElement,
78
+ PaymentElement,
79
+ StripeCheckout,
80
+ type StripeCheckoutOptions,
81
+ } from "superwall/checkout/stripe";
82
+ import { usePurchase } from "superwall/hooks";
83
+ import { useRouter } from "superwall/navigation";
84
+
85
+ const Summary = ({ product }: { product: Plan }) => {
86
+ const { status, amounts, failure } = useCheckout();
87
+ const label = amounts?.trialDays ? "Start free trial" : "Subscribe";
88
+ if (status === "unavailable") return <PlainPurchase product={product} />;
89
+ return (
90
+ <>
91
+ {failure ? <p role="status">{failure.message ?? "Your payment was declined."}</p> : null}
92
+ <PurchaseButton className="button">
93
+ {status === "paying" ? "Paying…" : label}
94
+ </PurchaseButton>
95
+ </>
96
+ );
97
+ };
98
+
99
+ // Where the form can't take payment (inside the iOS app, Studio, an SDK
100
+ // below 4.10.8), the paywall still sells: purchase() opens hosted checkout.
101
+ const PlainPurchase = ({ product }: { product: Plan }) => {
102
+ const { purchase } = usePurchase();
103
+ return (
104
+ <button className="button" onClick={() => void purchase(product)}>
105
+ Subscribe
106
+ </button>
107
+ );
108
+ };
109
+
110
+ type Plan = "annual" | "monthly";
111
+
112
+ export function Checkout({ product }: { product: Plan }) {
113
+ const router = useRouter();
114
+ const options = useMemo<StripeCheckoutOptions>(
115
+ () => ({ appearance: { theme: "flat" } }),
116
+ [],
117
+ );
118
+ return (
119
+ <StripeCheckout product={product} options={options} onComplete={() => router.push("welcome")}>
120
+ <ExpressCheckoutElement />
121
+ <LinkAuthenticationElement />
122
+ <PaymentElement options={{ layout: "tabs" }} />
123
+ <Summary product={product} />
124
+ </StripeCheckout>
125
+ );
126
+ }
127
+ ```
128
+
129
+ The rules this follows, each one broken in real builds:
130
+
131
+ 1. **Every purchase needs an email.** It is the subscription customer's
132
+ email: the receipt, the redemption link and the billing portal hang on
133
+ it. See [The email](#the-email).
134
+ 2. **`options` is stable.** Build it with `useMemo` (or a module constant). A
135
+ new object on every render makes Stripe redraw every field.
136
+ 3. **`unavailable` is a state to design for, not an error.** Inside the iOS
137
+ app, in Studio and on SDKs below 4.10.8 the form reports `unavailable`
138
+ and Stripe's elements render nothing; offer `usePurchase().purchase()`
139
+ there, which opens hosted checkout.
140
+ 4. **The trial label reads `amounts.trialDays`**, not `dueNow === 0`: a 100%
141
+ discount makes `dueNow` `0` with no trial.
142
+ 5. **`<PurchaseButton>` says it is paying.** It disables itself while a
143
+ payment runs and its label reads "Paying…" from `status === "paying"`. This
144
+ is the one exception to "never put a purchase button in a loading state":
145
+ a card payment opens no store sheet, so the paywall is the only feedback,
146
+ and without it the shopper sees nothing for a few seconds and taps again.
147
+
148
+ ## `<StripeCheckout>`
149
+
150
+ A form for one Stripe product. It renders at once from the product's price;
151
+ nothing is created in Stripe until the shopper pays. Switching `product`
152
+ re-prices the form and Stripe's fields keep what was typed.
153
+
154
+ | Prop | What it takes |
155
+ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
156
+ | `product` | The Stripe product, by reference (`"annual"`) or as a product. Required. |
157
+ | `options` | `StripeCheckoutOptions`: Stripe's Elements options (`appearance`, `fonts`, `locale`, `loader`, `paymentMethodTypes`…), minus `mode`, `amount`, `currency`, `paymentMethodCreation` and `setupFutureUsage`, which come from the product. Default: Stripe's own. |
158
+ | `email` | The shopper's email from the paywall's own field. Pass `""` while it is empty. Default: see [The email](#the-email). |
159
+ | `stripeMetadata` | Metadata set on the Stripe subscription. Default: none. |
160
+ | `postPurchase` | What happens after the purchase, as for `purchase()`. Default: the paywall's config. |
161
+ | `onStart`, `onSubmit`, `onComplete`, `onAbandon`, `onFailure` | `usePurchase`'s callbacks, fired for this form's purchases only. See [Events](#events). |
162
+ | `children` | The form: Stripe's elements from `superwall/checkout/stripe`, a `<PurchaseButton>`, any UI of the paywall's. |
163
+
164
+ `locale` defaults to the paywall's locale, so Stripe's labels and errors
165
+ match the paywall's language. `paymentMethodTypes` defaults to
166
+ `["card", "link"]`, which covers cards, Apple Pay, Google Pay and Link; any
167
+ other type is dropped with a console warning (see [Limits](#limits)).
168
+
169
+ ## `useCheckout()`
170
+
171
+ Read it from any component inside `<StripeCheckout>`; outside one it throws.
172
+
173
+ | Field | What it holds |
174
+ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
175
+ | `status` | `"preparing"` (Stripe.js and the price are loading), `"ready"`, `"paying"`, `"unavailable"` |
176
+ | `reason` | Why it is `unavailable` (below). Set only then. |
177
+ | `message` | The reason in an English sentence, for logs and a notice. |
178
+ | `error` | What the browser or Stripe threw, when a step threw (`{ name, message }`). |
179
+ | `product` | The product the form sells. Absent when the paywall has no such product. |
180
+ | `amounts` | `CheckoutAmounts`, absent until the price loads: `currency` (lowercase ISO), `dueNow`, `recurring` (after any discount), `interval`, `intervalCount`, `trialDays?`, `discount?` |
181
+ | `canSubmit` | `status === "ready"` |
182
+ | `submit()` | Pays with what the shopper entered. Resolves a `CheckoutSubmitResult`. |
183
+ | `failure` | `CheckoutFailure` of the last payment, cleared when the next starts. |
184
+
185
+ Amounts are in the currency's minor units, and not every currency has two
186
+ decimals (yen has none). Format them with the currency's own digits:
187
+
188
+ ```ts
189
+ const formatAmount = (amount: number, currency: string) => {
190
+ const format = new Intl.NumberFormat(undefined, { style: "currency", currency });
191
+ return format.format(amount / 10 ** (format.resolvedOptions().maximumFractionDigits ?? 2));
192
+ };
193
+ ```
194
+
195
+ **`submit()` results.** `completed`, `abandoned` and `failed` are a purchase
196
+ and reach every callback. `incomplete` means no purchase started: the
197
+ fields are not filled in (they already show the shopper what is missing), the
198
+ form has no email (`error.name === "email_required"`), or Stripe refused to
199
+ read the form, such as when no `PaymentElement` is mounted. `unavailable`
200
+ carries a `reason`, which is also `"preparing"` or `"paying"` when the form
201
+ wasn't ready or is already paying.
202
+
203
+ **Unavailable reasons** (`CheckoutUnavailableReason`):
204
+
205
+ | `reason` | When | What the paywall does |
206
+ | ------------------------ | -------------------------------------------------------------------------------------------- | ----------------------------------------- |
207
+ | `unsupported_host` | Inside the iOS app, in Studio, or an SDK below 4.10.8 | Offer `usePurchase().purchase()` |
208
+ | `external_checkout` | The config's `checkout` isn't `"elements"` | Fix `config.ts` |
209
+ | `missing_public_api_key` | The host supplied no public API key | A host or setup problem; log it |
210
+ | `unknown_product` | The paywall has no product with this reference | Point the identifier at a dashboard product |
211
+ | `unsupported_product` | Not a Stripe product, such as an App Store product | Buy it with `usePurchase().purchase()` |
212
+ | `session_failed` | Fetching the price failed; `error` holds why | Show the notice; offer `purchase()` |
213
+ | `session_unsupported` | The backend can't take this product in a form, such as a one-time price | Use `purchase()` |
214
+ | `store_load_failed` | Stripe.js didn't load | Show the notice; offer `purchase()` |
215
+
216
+ **Failure reasons** are the same `CheckoutFailureReason`s as every web
217
+ purchase (`card_declined`, `insufficient_funds`, `expired_card`,
218
+ `incorrect_card_details`, `authentication_failed`, `card_not_supported`,
219
+ `limit_exceeded`, `fraud_suspected`, `processing_error`, `unknown`), with
220
+ Stripe's `code`, `declineCode` and `message`. A decline keeps the form open
221
+ for another card; show `failure.message` and let the shopper pay again. If
222
+ a promotion code or a sign-in replaces the price while the shopper is
223
+ paying, the payment is refused before any charge with `reason: "unknown"`,
224
+ `code: "quote_changed"`.
225
+
226
+ ## `<PurchaseButton>`
227
+
228
+ `useCheckout().submit` on a `<button>`: disabled until the form can pay and
229
+ while it pays, with `data-status` set to `status` and `aria-busy` while
230
+ paying, so CSS can style each state. Every other prop goes to the button;
231
+ `onClick` runs first and `event.preventDefault()` stops the payment. It
232
+ shows nothing for an `incomplete` result. A paywall with its own email box
233
+ pays from its own button instead and shows the result's `error.message`:
234
+
235
+ ```tsx
236
+ import { useState } from "react";
237
+ import { useCheckout } from "superwall/checkout";
238
+
239
+ const PayButton = ({ label }: { label: string }) => {
240
+ const { canSubmit, submit, status } = useCheckout();
241
+ const [problem, setProblem] = useState<string>();
242
+ return (
243
+ <>
244
+ {problem ? <p role="status">{problem}</p> : null}
245
+ <button
246
+ disabled={!canSubmit}
247
+ onClick={async () => {
248
+ setProblem(undefined);
249
+ const result = await submit();
250
+ if (result.status === "incomplete") setProblem(result.error.message);
251
+ }}
252
+ >
253
+ {status === "paying" ? "Paying…" : label}
254
+ </button>
255
+ </>
256
+ );
257
+ };
258
+ ```
259
+
260
+ ## The email
261
+
262
+ Every purchase needs one. The form takes the first of:
263
+
264
+ 1. the `email` prop, for a paywall that collects it in its own `<input>`
265
+ (pass `""` while empty);
266
+ 2. the email typed into `LinkAuthenticationElement`, which also signs a Link
267
+ shopper in;
268
+ 3. the email on the card's or wallet's billing details (a wallet in
269
+ `ExpressCheckoutElement` is always asked for one);
270
+ 4. the user's `email` attribute, which also pre-fills
271
+ `LinkAuthenticationElement`.
272
+
273
+ With none of these, the form logs a warning once it is ready, and a card
274
+ payment returns `incomplete` with `email_required` and charges nothing. So
275
+ render `LinkAuthenticationElement` above the card form, pass your own
276
+ field's value as `email`, or set the `email` attribute before the paywall
277
+ shows; a wallets-only form needs nothing more.
278
+
279
+ ## Which Stripe elements work
280
+
281
+ `superwall/checkout/stripe` re-exports Stripe's components unchanged, with
282
+ every option Stripe documents (`PaymentElement`'s `layout: "tabs"` or
283
+ `"accordion"`, `fields`, `wallets`, `terms`, `defaultValues`…). Two are
284
+ wrapped because superwall needs their events; their props are Stripe's,
285
+ minus the handlers superwall owns.
286
+
287
+ | Element | Supported | Notes |
288
+ | ------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------- |
289
+ | `PaymentElement` | Yes | Cards and Link |
290
+ | `ExpressCheckoutElement` | Wrapped | Apple Pay, Google Pay, Link. superwall owns `onClick`, `onConfirm` and `onCancel`; `onReady` and the rest are yours |
291
+ | `LinkAuthenticationElement` | Wrapped | Hands the email to the purchase; pre-filled from the user's `email` attribute |
292
+ | `AddressElement` | Yes | `mode: "billing"`: the address goes onto the payment method |
293
+ | `CardElement`, `CardNumberElement`, `CardExpiryElement`, `CardCvcElement` | Yes | The classic card fields; styled with `options.style`, not `appearance` |
294
+ | `useStripe()`, `useElements()` | Yes | For reading the form; never confirm with them, call `useCheckout().submit()` |
295
+ | `ShippingAddressElement`, `AddressElement` with `mode: "shipping"` | No | A subscription ships nothing, and the purchase has nowhere to send it |
296
+ | `TaxIdElement` | No | The purchase has nowhere to send a tax ID |
297
+ | `IbanElement`, SEPA, ACH, iDEAL, Klarna, Afterpay, Cash App Pay | No | They redirect or need a bank mandate: a return-and-resume flow superwall doesn't have |
298
+ | `PaymentMethodMessagingElement` | No | It advertises the buy-now-pay-later methods above |
299
+ | `EmbeddedCheckout`, `CheckoutProvider` | No | Stripe's own hosted checkout: use `checkout: "sheet"` instead |
300
+
301
+ Saved cards and a customer's earlier payment methods aren't offered: the
302
+ form pays as a new customer each time. A promotion code box is not a Stripe
303
+ element: it is a plain input on `useDiscount()`, superwall's own codes, and
304
+ a redeemed code re-prices the form and the charge.
305
+
306
+ ## Matching the paywall's design
307
+
308
+ Stripe draws its fields in its own frame, so they can't read the paywall's
309
+ CSS variables. The example's `components/appearance.ts` is the pattern:
310
+
311
+ - **Resolve the tokens to plain colours.** Read each CSS variable from the
312
+ surface's `theme.css` (`--surface`, `--fg`, `--fg-muted`, `--border`,
313
+ `--accent`…) through `getComputedStyle`, turn it into `rgb()`, and read
314
+ them again when the root's `light`/`dark` class changes.
315
+ - **`appearance.variables`**: `colorBackground` is the plan rows' surface,
316
+ not the page background; text, placeholder, accent, `colorDanger`, font,
317
+ `fontSizeBase: "16px"` and the corner radius come from the tokens.
318
+ - **`appearance.rules`**: a hairline border and `boxShadow: "none"` on
319
+ `.Input`, `.Tab`, `.AccordionItem` and `.Block` (Link's "save my
320
+ information" box), and the accent border on `.Input:focus` and
321
+ `.Tab--selected`, so every field matches the paywall's own inputs.
322
+ - **`fonts`**: the font file itself, `{ family, src: "url(…woff2)", weight }`,
323
+ never a `cssSrc` stylesheet. Stripe fetches `cssSrc` from the paywall's
324
+ page, where the hosted page's Content Security Policy blocks Google Fonts;
325
+ a font file loads inside Stripe's frame.
326
+ - **The classic card fields** take `options.style` (`base`, `invalid`,
327
+ `::placeholder`) instead of `appearance`; wrap each in the paywall's own
328
+ input class for the surface, border and focus edge.
329
+ - **Wallet buttons** take `buttonHeight` and `buttonType` in
330
+ `ExpressCheckoutElement`'s options; `buttonType: { applePay: "plain" }`
331
+ shows the bare Apple Pay logo, the same size as Link's button.
332
+ - **Memoize the result.** Return the options from `useMemo` keyed on the
333
+ palette; a new object on every render redraws every field.
334
+
335
+ ## Recipes
336
+
337
+ Elements are plain components: put them in any order, around any UI.
338
+
339
+ - **Apple Pay, Link and a card (recommended).** superwall's own Apple Pay
340
+ sheet on a button of the paywall's own, because it is the most fully
341
+ instrumented path; Link alone in the express row; the card form with its
342
+ wallets off so no wallet shows twice. In `elements` mode the paywall
343
+ prepares the Apple Pay sheet from the form's price, so the button opens it
344
+ at once:
345
+
346
+ ```tsx
347
+ const ApplePayButton = ({ product }: { product: "annual" }) => {
348
+ const { product: wallet } = useApplePay(product);
349
+ const { purchase } = usePurchase();
350
+ return wallet.status === "ready" ? (
351
+ <button className="apple-pay" onClick={() => void purchase(product, { checkout: "applePay" })} />
352
+ ) : null;
353
+ };
354
+
355
+ <StripeCheckout product="annual" options={options}>
356
+ <ApplePayButton product="annual" />
357
+ <ExpressCheckoutElement
358
+ options={{ paymentMethods: { applePay: "never", googlePay: "never", link: "auto" } }}
359
+ />
360
+ <LinkAuthenticationElement />
361
+ <PaymentElement options={{ layout: "tabs", wallets: { applePay: "never", googlePay: "never" } }} />
362
+ <PurchaseButton>Subscribe</PurchaseButton>
363
+ </StripeCheckout>
364
+ ```
365
+
366
+ Use the full `ExpressCheckoutElement` only when the paywall wants every
367
+ express method together in Stripe's row.
368
+ - **Only one wallet in the row.** `paymentMethods` turns the others off:
369
+ `{ applePay: "auto", googlePay: "never", link: "never" }`.
370
+ - **A divider beside the wallets.** The express row renders nothing on a
371
+ device with no wallet, so show "or pay with card" only after
372
+ `ExpressCheckoutElement`'s `onReady` reports one:
373
+ `onReady={({ availablePaymentMethods }) => setShown(Object.values(availablePaymentMethods ?? {}).some(Boolean))}`.
374
+ - **Wallets only.** Just `ExpressCheckoutElement`, no CTA: the wallet pays
375
+ and asks for the email itself.
376
+ - **Split card fields.** `CardNumberElement`, `CardExpiryElement`,
377
+ `CardCvcElement` (or the one-line `CardElement`), the paywall's own email
378
+ `<input>` passed as `email`, and its own button on `submit()` that shows
379
+ an `incomplete` message.
380
+ - **Billing address.** `AddressElement` with `mode: "billing"`; put the
381
+ paywall's own tags on the subscription with `stripeMetadata`.
382
+ - **Promotion code.** A plain input calling `useDiscount().redeem(code)`; the
383
+ form re-prices and `amounts.discount` is set.
384
+
385
+ ## Events
386
+
387
+ `usePurchase` callbacks hear every purchase on the paywall, superwall's
388
+ Apple Pay sheet included; `<StripeCheckout>`'s hear only that form's. The
389
+ native SDK gets the matching `stripe_checkout_*` messages, so a
390
+ `transaction_abandon` reaches its analytics.
391
+
392
+ | What the shopper does | Callbacks, in order |
393
+ | ------------------------------------------ | ------------------------------------------- |
394
+ | Pays with a card | `onStart`, `onSubmit`, `onComplete` |
395
+ | Pays with an incomplete form or no email | nothing: `submit()` returns `incomplete` |
396
+ | Card declined | `onStart`, `onSubmit`, `onFailure` (reason) |
397
+ | Pays again after a decline | a new `onStart`, then as above |
398
+ | Fails 3D Secure | `onStart`, `onSubmit`, `onFailure` |
399
+ | Opens Link or a wallet in the express row | `onStart` |
400
+ | … and pays | `onSubmit`, `onComplete` |
401
+ | … and closes it | `onAbandon` |
402
+ | Taps superwall's Apple Pay button and pays | `onStart`, `onSubmit`, `onComplete` |
403
+ | … and closes the sheet | `onAbandon` (from `usePurchase` only) |
404
+
405
+ A card form never fires `onAbandon`. The callbacks don't say which method
406
+ paid; a paywall that needs it knows which of its buttons the shopper used.
407
+
408
+ ## Migrating an existing Stripe checkout
409
+
410
+ A custom Stripe checkout usually has an `<Elements>` provider with a client
411
+ secret, a server endpoint that creates the PaymentIntent or subscription, a
412
+ `stripe.confirmPayment()` call on submit and a webhook that grants access.
413
+
414
+ 1. **Set the mode.** `checkout: { mode: "elements" }` in `config.ts`, and
415
+ the Stripe products in `products`.
416
+ 2. **Swap the provider.** Replace `<Elements stripe={…} options={{ clientSecret }}>`
417
+ with `<StripeCheckout product="annual">`. Move `appearance`, `fonts`,
418
+ `locale` and `paymentMethodTypes` into its `options`; drop
419
+ `clientSecret`, `mode`, `amount` and `currency`, which come from the
420
+ product.
421
+ 3. **Keep the elements.** Same props, imported from
422
+ `superwall/checkout/stripe` instead of `@stripe/react-stripe-js`; remove
423
+ the `@stripe/*` dependencies.
424
+ 4. **Swap the submit.** Where you called `elements.submit()` and
425
+ `stripe.confirmPayment()`, call `useCheckout().submit()`, or render
426
+ `<PurchaseButton>`. 3D Secure, trials and failures are handled.
427
+ 5. **Collect the email.** Keep `LinkAuthenticationElement`, or pass your own
428
+ field's value as `email`.
429
+ 6. **Move the metadata.** What you put on the subscription goes in
430
+ `stripeMetadata`.
431
+ 7. **Delete the backend.** The PaymentIntent endpoint and the
432
+ access-granting webhook go: superwall creates the subscription, grants
433
+ the entitlement and redeems it in the app.
434
+ 8. **Move the reactions.** Success and error handling moves to
435
+ `onComplete`, `onFailure` and `onAbandon` on `<StripeCheckout>`, or to
436
+ `usePurchase()`'s callbacks.
437
+
438
+ Any element from the unsupported list has no place in the port; drop it
439
+ or keep that product on the hosted checkout.
440
+
441
+ ## Limits
442
+
443
+ - **Only card and Link.** `paymentMethodTypes` beyond `card` and `link` are
444
+ dropped with a console warning. A payment method of any other type, say
445
+ from an `IbanElement` imported straight from Stripe's package, fails with
446
+ `card_not_supported` (code `payment_method_unsupported`) before anything
447
+ is charged. Redirect and bank-debit methods need a return-and-resume flow
448
+ that doesn't exist yet.
449
+ - **Not inside the iOS app.** There `status` is `unavailable`
450
+ (`unsupported_host`) and a purchase opens hosted checkout in the browser.
451
+ Studio and SDKs below 4.10.8 report the same; a teleport page and a web
452
+ paywall take payment.
453
+ - **Studio never pays.** The preview shows the form's `unavailable` state;
454
+ try a real payment on a published web paywall with Stripe test cards:
455
+ `4242 4242 4242 4242` pays, `4000 0000 0000 0002` is declined,
456
+ `4000 0025 0000 3155` asks for 3D Secure.
457
+ - **Subscriptions only.** A one-time price reports `session_unsupported`.
@@ -56,6 +56,7 @@ number.
56
56
  | Example | The one idea |
57
57
  | --- | --- |
58
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
+ | `elements-checkout` | A checkout form of the paywall's own in `checkout: "elements"` mode: `<StripeCheckout>` around Stripe's elements, the CTA on `useCheckout()` and `<PurchaseButton>`, an email always collected, fields styled from the design tokens (`components/appearance.ts`), ten layouts on chips (superwall's Apple Pay + Link + card is the default) and an event log showing which callbacks fire for each path ([elements-checkout.md](elements-checkout.md)) |
59
60
  | `trial-eligibility` | Two paywalls in one, chosen by the store — every string forks and both states read as intentional |
60
61
  | `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
62
  | `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 |
@@ -228,6 +228,16 @@ It applies once the page takes over: the pre-rendered first paint has no
228
228
  Safari), so a page with a bottom `env()` can still move by that much. An
229
229
  edge `insets` sets in `config.ts` is written inline and wins over this rule.
230
230
 
231
+ **In the studio, a teleport shows the browser page.** Walk to the
232
+ teleported route in `superwall dev` (tap the button that runs
233
+ `router.push(route, { teleport: true })`) and the preview becomes the page
234
+ the shopper lands on: `data-sw-platform="web"`, no idiom or cutout, no
235
+ in-app floors, and on a portrait iPhone a viewport that ends above Safari's
236
+ toolbar. Check the `:root[data-sw-platform="web"]` rules, sticky footers
237
+ and safe-area padding there; the toolbar is browser chrome, never padding
238
+ the page adds. A landscape iPhone keeps the app's insets with the bar
239
+ drawn over the page, and going back to the app restores the in-app frame.
240
+
231
241
  `push` and `noAnimation` are fullscreen. The attributes come from the
232
242
  device the host reports and are absent, never guessed, until the host's
233
243
  first message; the studio sets them per preset, so switching devices
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: teleport
3
- description: Set up an app-to-web flow or experiment with the superwall framework's teleport — the shopper starts on a paywall or onboarding in the iOS app and finishes on the web, paying with Apple Pay through Stripe, and the app is credited on its own. Covers the recommended setup (`teleport.route` in config.ts, the Apple Pay gate with `useApplePay().available` and `router.push(route, { teleport: false })`, `teleport.fallbacks`, blocking prepaid cards), what buying a Stripe product inside the app does, direct Apple Pay checkout (not with Stripe Managed Payments), A/B testing teleport by paywall in a campaign, and a catalogue of setups and experiments (web pricing, discounts, failure rescue, abandonment offers, custom teleport screens, trial eligibility, `completion`, attribution). Use when the user asks to "set up app to web", "app-to-web experiment", "teleport", "send users to web checkout from the app", "sell on the web from iOS", "Stripe / Apple Pay from the app", or to test web checkout against the App Store. Needs the superwall-framework skill for everything else about the paywall.
3
+ description: Set up an app-to-web flow or experiment with the superwall framework's teleport — the shopper starts on a paywall or onboarding in the iOS app and finishes on the web, paying with Apple Pay through Stripe, and the app is credited on its own. Covers the recommended setup (`teleport.route` in config.ts, the Apple Pay gate with `useApplePay().available` and `router.push(route, { teleport:false })`, `teleport.fallbacks`, blocking prepaid cards), what buying a Stripe product inside the app does, direct Apple Pay checkout (not with Stripe Managed Payments), A/B testing teleport by paywall in a campaign, and a catalogue of setups and experiments (web pricing, discounts, failure rescue, abandonment offers, custom teleport screens, trial eligibility, `completion`, attribution). Use when the user asks to "set up app to web", "app-to-web experiment", "teleport", "send users to web checkout from the app", "sell on the web from iOS", "Stripe / Apple Pay from the app", or to test web checkout against the App Store. Needs the superwall-framework skill for everything else about the paywall.
4
4
  user-invocable: true
5
5
  ---
6
6
 
@@ -1,8 +1,8 @@
1
- import { T as isNonInteractive, c as CHANNELS, s as CHANNEL, v as TELEMETRY_HOST, x as VERSION, y as TELEMETRY_KEY } from "./environment-Dn7irhZr.js";
2
- import { _ as writeTelemetryNoticeShown, c as readSkillsSync, g as writeSkillsSync, t as readAnonymousId, u as telemetryNoticeShown } from "./config-DCqRQTJ4.js";
3
- import { n as ui } from "./ui-hFgji1e8.js";
4
- import { n as withSpinner } from "./spinner-Dcr-Dqdi.js";
5
- import { i as packagedDir, t as AGENT_SKILLS_DIR } from "./paths-Cb1RfjaX.js";
1
+ import { T as isNonInteractive, c as CHANNELS, s as CHANNEL, v as TELEMETRY_HOST, x as VERSION, y as TELEMETRY_KEY } from "./environment-BQiaGqjB.js";
2
+ import { _ as writeTelemetryNoticeShown, c as readSkillsSync, g as writeSkillsSync, t as readAnonymousId, u as telemetryNoticeShown } from "./config-CJRNScT0.js";
3
+ import { n as ui } from "./ui-Dye-QvEj.js";
4
+ import { n as withSpinner } from "./spinner-hTCJZAoJ.js";
5
+ import { i as packagedDir, t as AGENT_SKILLS_DIR } from "./paths-B4FNcaHO.js";
6
6
  import { execFile, spawn } from "node:child_process";
7
7
  import { appendFileSync, existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
8
8
  import { tmpdir } from "node:os";