@superwall/cli 2.6.0 → 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 (142) hide show
  1. package/dist/{apple-D-rfsuDA.js → apple-DfYTDEJy.js} +16 -16
  2. package/dist/{approve-aPc5RoXB.js → approve-CoQJhii4.js} +7 -7
  3. package/dist/{assets-PyuXe45Y.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-CAU0hWoI.js → base-DAnzMjI8.js} +2 -2
  7. package/dist/{billing-Dt6L_l9R.js → billing-CFGrG-WZ.js} +3 -3
  8. package/dist/{build-CY5FnMNY.js → build-CTBvzIG8.js} +10 -10
  9. package/dist/{config-DOp5oChe.js → config-CJRNScT0.js} +4 -4
  10. package/dist/{create-BZL5VH4L.js → create-BLs-0ETi.js} +29 -29
  11. package/dist/create-C_kjQp0N.js +18 -0
  12. package/dist/{create-D6w3UL0m.js → create-aWzdpjJU.js} +8 -8
  13. package/dist/{doctor-C9FR0qw3.js → doctor-ChI2Kfru.js} +21 -21
  14. package/dist/entry.js +28 -29
  15. package/dist/{environment-sE2wZYdg.js → environment-BQiaGqjB.js} +1 -1
  16. package/dist/{existing--peXpOZj.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-CUBCOCGP.js → held-CmvNRCRD.js} +327 -22
  20. package/dist/{scope-BLLUxbrA.js → input-ApyzIzVy.js} +48 -7
  21. package/dist/{install-C5d82gZF.js → install-DM0JBdpE.js} +12 -12
  22. package/dist/{integrate-D8J_X1bj.js → integrate-ZQUaScQ0.js} +21 -22
  23. package/dist/login-Cnt3UZKV.js +13 -0
  24. package/dist/{login-DXhm9L0F.js → login-CvzBt9eM.js} +2 -2
  25. package/dist/{login-C6X7JrhM.js → login-Oo2NWLlX.js} +7 -7
  26. package/dist/{lookup-DqmIbUkv.js → lookup-CHLrO7v7.js} +3 -3
  27. package/dist/{migrate-BYF6hKZ2.js → migrate-mFKBset8.js} +30 -30
  28. package/dist/{notification-url-Bo54nkXv.js → notification-url-Dpx0pbYs.js} +3 -3
  29. package/dist/{open-xdgXUzaF.js → open-CxgE8kLT.js} +2 -2
  30. package/dist/{org-BD8U3D1_.js → org-0KDPRSlc.js} +4 -4
  31. package/dist/{organization-D-ZlB3qU.js → organization-Cg--QQtz.js} +4 -4
  32. package/dist/{orgs-DQQJ3sw_.js → orgs-Df8DzIav.js} +1 -1
  33. package/dist/{paths-CIlyzF2I.js → paths-B4FNcaHO.js} +1 -1
  34. package/dist/{playbook-ecggWGFi.js → playbook-pFhIg_0e.js} +10 -10
  35. package/dist/{promote-QVMLGYlU.js → promote-Crwz1xI0.js} +23 -23
  36. package/dist/{pull-CCXhb2a7.js → pull-BixwETu1.js} +10 -10
  37. package/dist/pull-C0gY7HGj.js +30 -0
  38. package/dist/{pull-CrdsfsAl.js → pull-D8GfsKha.js} +30 -30
  39. package/dist/{push-DJMGG7zW.js → push-BKoav_FU.js} +10 -10
  40. package/dist/{push-DiMDwGfe.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-BSnQXft4.js → registry-BPqRG08G.js} +270 -435
  44. package/dist/registry-DGHTk7l-.js +21 -0
  45. package/dist/{resolve-DO7bPota.js → resolve-CarLrF4b.js} +3 -3
  46. package/dist/{resources-XwvXA20E.js → resources-BeXleviK.js} +15 -34
  47. package/dist/{run-B-YvxfRc.js → run-naBCXCfn.js} +14 -14
  48. package/dist/{scan-ViBhmrB7.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-C07e_GGY.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-CBtHzl9y.js → server-Dp5Imq3v.js} +11 -11
  55. package/dist/{session-BfVx50iA.js → session-6HA1OwHe.js} +6 -6
  56. package/dist/session-BatiAUPQ.js +5 -0
  57. package/dist/{session-BlrwAdGN.js → session-BpLOLurZ.js} +1 -1
  58. package/dist/{setup-a4B72xJ8.js → setup-RL-5c6SV.js} +10 -10
  59. package/dist/skills/index.json +5 -0
  60. package/dist/skills/superwall/SKILL.md +8 -1
  61. package/dist/skills/superwall/references/api.md +34 -3
  62. package/dist/skills/superwall/references/asc.md +5 -1
  63. package/dist/skills/superwall/workflows/dashboard/playbook.md +1 -1
  64. package/dist/skills/superwall/workflows/dashboard/setup.md +6 -2
  65. package/dist/skills/superwall/workflows/migrate/adapty.md +1 -1
  66. package/dist/skills/superwall/workflows/migrate/playbook.md +6 -1
  67. package/dist/skills/superwall/workflows/migrate/qonversion.md +1 -1
  68. package/dist/skills/superwall/workflows/migrate/revenuecat.md +1 -1
  69. package/dist/skills/superwall/workflows/placements/android.md +4 -1
  70. package/dist/skills/superwall/workflows/placements/expo.md +4 -1
  71. package/dist/skills/superwall/workflows/placements/flutter.md +4 -1
  72. package/dist/skills/superwall/workflows/placements/ios.md +4 -1
  73. package/dist/skills/superwall/workflows/placements/playbook.md +6 -1
  74. package/dist/skills/superwall/workflows/placements/react-native.md +4 -1
  75. package/dist/skills/superwall/workflows/placements/strategy.md +4 -1
  76. package/dist/skills/superwall-framework/SKILL.md +105 -26
  77. package/dist/skills/superwall-framework/references/cli.md +6 -0
  78. package/dist/skills/superwall-framework/references/elements-checkout.md +457 -0
  79. package/dist/skills/superwall-framework/references/examples.md +1 -0
  80. package/dist/skills/superwall-framework/references/layout.md +40 -2
  81. package/dist/skills/teleport/SKILL.md +154 -0
  82. package/dist/skills/teleport/references/experiments.md +328 -0
  83. package/dist/skills/teleport/references/setup.md +157 -0
  84. package/dist/{skills-BB1uIt8t.js → skills-C1ku2pgy.js} +5 -5
  85. package/dist/{skills-SnxFa2in.js → skills-CkAWJveA.js} +8 -8
  86. package/dist/{source-push-w7miTr6m.js → source-push-D59hV02W.js} +6 -6
  87. package/dist/{spinner-BQp7fQvK.js → spinner-hTCJZAoJ.js} +42 -7
  88. package/dist/{starter-BlJ_InZJ.js → starter-jYb2nmlb.js} +3 -3
  89. package/dist/{status-DxsIw9zq.js → status-DrD9CHtK.js} +7 -7
  90. package/dist/{storage-BR6imSqm.js → storage-D0Q4xBi-.js} +1 -1
  91. package/dist/storekit-CAOpa6_f.js +14 -0
  92. package/dist/{storekit-BqyujKQ_.js → storekit-TLBxGIrN.js} +5 -5
  93. package/dist/{theme-Ed0gz6hr.js → theme-Bvv0yrk_.js} +5 -5
  94. package/dist/{token-CWQ6tdva.js → token-SEWilQo9.js} +1 -1
  95. package/dist/tools-skills/superwall/SKILL.md +8 -1
  96. package/dist/tools-skills/superwall/references/api.md +34 -3
  97. package/dist/tools-skills/superwall/references/asc.md +5 -1
  98. package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +1 -1
  99. package/dist/tools-skills/superwall/workflows/dashboard/setup.md +6 -2
  100. package/dist/tools-skills/superwall/workflows/migrate/adapty.md +1 -1
  101. package/dist/tools-skills/superwall/workflows/migrate/playbook.md +6 -1
  102. package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +1 -1
  103. package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +1 -1
  104. package/dist/tools-skills/superwall/workflows/placements/android.md +4 -1
  105. package/dist/tools-skills/superwall/workflows/placements/expo.md +4 -1
  106. package/dist/tools-skills/superwall/workflows/placements/flutter.md +4 -1
  107. package/dist/tools-skills/superwall/workflows/placements/ios.md +4 -1
  108. package/dist/tools-skills/superwall/workflows/placements/playbook.md +6 -1
  109. package/dist/tools-skills/superwall/workflows/placements/react-native.md +4 -1
  110. package/dist/tools-skills/superwall/workflows/placements/strategy.md +4 -1
  111. package/dist/tools-skills/teleport/SKILL.md +154 -0
  112. package/dist/tools-skills/teleport/references/experiments.md +328 -0
  113. package/dist/tools-skills/teleport/references/setup.md +157 -0
  114. package/dist/tools.d.ts +4 -2
  115. package/dist/tools.js +1357 -1191
  116. package/dist/{try-C3HW3hPZ.js → try-BpMpLGCs.js} +15 -15
  117. package/dist/{ui-hFgji1e8.js → ui-Dye-QvEj.js} +26 -1
  118. package/dist/{upgrade-Cw9jVt-r.js → upgrade-BLFWdbGR.js} +7 -7
  119. package/dist/upgrade-BzN7PjKg.js +27 -0
  120. package/package.json +2 -2
  121. package/dist/create-DM5Y1Pyk.js +0 -18
  122. package/dist/held-DVxvPMSG.js +0 -15
  123. package/dist/input-DOT_2Zvb.js +0 -42
  124. package/dist/login-et319ESO.js +0 -13
  125. package/dist/pull-h71pL3r_.js +0 -30
  126. package/dist/push-BIq6R8Ro.js +0 -29
  127. package/dist/push-D6pJM_vv.js +0 -21
  128. package/dist/registry-YwzTfCNc.js +0 -22
  129. package/dist/scan-B36wkZmI.js +0 -4
  130. package/dist/server-CZwSfzKe.js +0 -33
  131. package/dist/session-Cip4j99n.js +0 -5
  132. package/dist/storekit-ELVCMF0X.js +0 -15
  133. package/dist/upgrade-DVsonzDF.js +0 -27
  134. /package/dist/{design-lint-mgO-2SGS.js → design-lint-CeG3_ZWN.js} +0 -0
  135. /package/dist/{devtools-B6Vp6HMy.js → devtools-B3tCQFD-.js} +0 -0
  136. /package/dist/{download-DhGd4hOB.js → download-DVFHIwia.js} +0 -0
  137. /package/dist/{project-BomArwSj.js → project-Dml4t7jO.js} +0 -0
  138. /package/dist/{reports-hbxsd3Zo.js → reports-CJQ-8sj4.js} +0 -0
  139. /package/dist/{screenshot-file-Dix2Qynm.js → screenshot-file-CcqMLpL5.js} +0 -0
  140. /package/dist/{source-DQs6iLtC.js → source-Ct9kOCAb.js} +0 -0
  141. /package/dist/{storage-Bh3wT1Rn.d.ts → storage-BaK-MUM8.d.ts} +0 -0
  142. /package/dist/{timing-BKEEIBij.js → timing-m0ZUzYiP.js} +0 -0
@@ -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 |
@@ -171,7 +171,7 @@ the attributes the framework stamps on `<html>`:
171
171
  | android · fullscreen | 24 (drawn under the status bar) | 0 (the SDK margins the webview above the nav bar) | 0 |
172
172
  | android · modal or drawer | 0 (sheet starts below the bar) | 0 (SDK pads it) | 0 |
173
173
  | any · popup | 0 | 0 | 0 (the SDK insets it) |
174
- | web | 0 | 0 | 0 (the browser owns its chrome) |
174
+ | web, including a page an app teleported to (`host` `"web-teleport"`) | 0 | 0 | 0 (the browser owns its chrome) |
175
175
 
176
176
  A **simulator** reports its host architecture (`arm64`) as `deviceModel`,
177
177
  not an `iPhone17,1`. SDKs that know it also report the simulated phone as
@@ -198,7 +198,45 @@ the insets can't make.
198
198
  `device.safeAreaInsets` (`{ top, right, bottom, left }`); the framework
199
199
  writes those as the `--sw-safe-area-floor-*`, so they stand in where
200
200
  `env()` reads 0. The studio's iPhone Duo (Closed) and (Open) presets do
201
- this with the insets measured in Apple's Duo simulator.
201
+ this with the insets measured in Apple's Duo simulator. Not on a page an
202
+ app teleported to: it runs in the shopper's browser, below the browser's
203
+ own bar, so the framework describes the browser there rather than the
204
+ app's phone. `<html>` gets `data-sw-platform="web"`, no `data-sw-idiom` or
205
+ `data-sw-cutout`, and `device.safeAreaInsets` is not written as floors, so
206
+ only the browser's `env()` applies, as on the pre-rendered first paint.
207
+
208
+ **Branch logic on `useDevice()`, not on `data-sw-platform`.** On a
209
+ teleported page `useDevice().hostPlatform` still reports the app's platform
210
+ (`"ios"`) and `useDevice().host` is `"web-teleport"`; only the attributes the
211
+ CSS reads say `web`. Key styles on `data-sw-platform`; key behaviour (copy,
212
+ which store, whether to show a step) on `hostPlatform` and `host`.
213
+
214
+ **No padding in the browser at all.** Zero the insets for every web host,
215
+ a teleported page included, and leave the in-app safe area as it is:
216
+
217
+ ```css
218
+ :root[data-sw-platform="web"] {
219
+ --sw-inset-top: 0px;
220
+ --sw-inset-right: 0px;
221
+ --sw-inset-bottom: 0px;
222
+ --sw-inset-left: 0px;
223
+ }
224
+ ```
225
+
226
+ It applies once the page takes over: the pre-rendered first paint has no
227
+ `data-sw-platform` yet and keeps the browser's own `env()` (0 at the top in
228
+ Safari), so a page with a bottom `env()` can still move by that much. An
229
+ edge `insets` sets in `config.ts` is written inline and wins over this rule.
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.
202
240
 
203
241
  `push` and `noAnimation` are fullscreen. The attributes come from the
204
242
  device the host reports and are absent, never guessed, until the host's