@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
@@ -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,9 +112,10 @@ 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`), direct Apple Pay availability (`useApplePay`, `examples/apple-pay`); a Stripe product inside an iOS app (app to web: always hosted checkout, priced from the dashboard at push) | `web-checkout`, `products` |
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
- | Continuing a flow on the web (teleport: `teleport: true` or `{ route, fallbacks, completion, … }`, `router.push(route, { teleport: true })`, prefetch, the teleport screen, `useTeleport`'s typed status, returning to the app with `returnToApp({ data })` and its `"opened" \| "cancelled" \| "no_app"` result, the page's `failure` and `data` back in the app, `onReturnData`) | `teleport` |
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` |
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` |
117
119
  | Web funnels — answers in the URL (`useQueryState`), resume after a browser hand-off, `shift` | `web-funnels` |
118
120
  | Multi-page flows, router, cross-page state, shared chrome | `navigation` |
119
121
  | Built-in + custom transitions, bottom sheets | `transitions` |
@@ -144,6 +146,10 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
144
146
  2. **`purchase()` never throws for flow outcomes** — it resolves
145
147
  `completed | abandoned | failed`. React to the awaited result; treat
146
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"`).
147
153
  A store purchase through the SDK resolves `failed` with
148
154
  `reason: "unknown"` (or `"superseded"` when a newer purchase replaced it)
149
155
  on iOS only: Android reports no purchase failures, so there a failed purchase stays pending until the user
@@ -251,40 +257,60 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
251
257
  on `stripe_error`; read them in Safari Web Inspector or Chrome DevTools to
252
258
  debug a slow checkout before changing the paywall.
253
259
 
254
- `useApplePay()` says whether direct Apple Pay (the wallet the browser
255
- opens itself) is available, from `ApplePaySession.canMakePayments()`,
256
- known on the first render. Web hosts only (Web SDK, hosted web paywall,
257
- teleport page, plain browser): `{ available: true }` or
258
- `{ available: false, reason, message, error? }`; `undefined` in the iOS
259
- and Android SDKs and Studio. `reason` (`ApplePayUnavailableReason`) is
260
- `unsupported_browser` (no Apple Pay JS, as in desktop Chrome — its card
261
- sheet may still offer Apple Pay by QR code, which is not direct Apple
262
- Pay), `insecure_context` (not HTTPS, `http://localhost` included),
263
- `device_unsupported`, `cross_origin_frame` or `check_failed`; `error` is
264
- `{ name, message }` when the check threw. Only Stripe sees the cards in
265
- Wallet and the domain's registration: `useApplePay(product)` adds
266
- `product: { status: "preparing" | "ready" | "unavailable", reason?,
267
- message?, error? }`. Its `reason` is the browser's when the browser can't
268
- pay, else an `ApplePayWalletReason`: `not_prepared` means nothing has
269
- prepared that product's wallet yet, not that the device can't pay;
270
- `stripe_declined` means no card in Wallet, an unregistered domain or
271
- Safari's Apple Pay check setting off; the rest (`stripe_check_failed`,
260
+ `useApplePay()` says whether Apple Pay is set up with a card on this
261
+ device, the same way on every host: the iOS SDK, the Web SDK, a hosted
262
+ web paywall, a teleport page and a plain browser. It is Apple's
263
+ `ApplePaySession.canMakePaymentsWithActiveCard` for the page's own Stripe
264
+ merchant; the answer follows the cards in Wallet, not the domain's Stripe
265
+ registration, and any usable card counts (Apple Cash with no balance
266
+ too), so it means Apple Pay is set up, not that a payment will succeed.
267
+ It is always defined: `{ available: true }` or
268
+ `{ available: false, reason, message, error? }`, never `undefined`, so
269
+ read `applePay.available` without `?.`. `reason`
270
+ (`ApplePayUnavailableReason`) is `checking` until Apple answers (usually
271
+ right after the first render, at most 1.5 s), `no_active_card`,
272
+ `unsupported_browser` (no Apple Pay JS: the Android SDK, desktop Chrome,
273
+ whose card sheet may still offer Apple Pay by QR code), `insecure_context`
274
+ (not HTTPS, `http://localhost` included), `cross_origin_frame`,
275
+ `check_failed` (with the browser's `error`) or `timed_out` after 1.5 s,
276
+ which Apple's late answer still replaces. `checking` is not available:
277
+ a decision made on the first render keeps the shopper in the app. Apple
278
+ is asked once per page and every `useApplePay()` shares the answer; a
279
+ check that threw or timed out is asked again, and a paywall with
280
+ `teleport` in its config asks as it opens. `checkApplePay()` from
281
+ `superwall/hooks` is the same answer as a promise for code outside
282
+ React, never `checking`. `useVariables().device.isApplePayAvailable` is
283
+ `@deprecated` (the native SDK always reports `true`); never read it.
284
+
285
+ With a product, `useApplePay(product)` adds `product: { status:
286
+ "preparing" | "ready" | "unavailable", reason?, message?, error? }`,
287
+ whether the wallet is ready to open for that product. Only Stripe's
288
+ check, made when it prepares the product, sees the domain's registration.
289
+ Its `reason` (`ApplePayProductReason`) is `unsupported_host` inside the
290
+ iOS and Android SDKs and Studio (a purchase never opens the wallet
291
+ there), the device's reason when Apple Pay is not available, else an
292
+ `ApplePayWalletReason`: `not_prepared` means nothing has prepared that
293
+ product's wallet yet, not that the device can't pay; `stripe_declined`
294
+ means no card in Wallet, an unregistered domain or Safari's Apple Pay
295
+ check setting off; the rest (`stripe_check_failed`,
272
296
  `stripe_load_failed`, `missing_public_api_key`, `session_failed`,
273
297
  `session_unsupported`, `show_failed`) name the step that failed. The
274
298
  wallet opens only for a product prepared before the tap: config
275
299
  `checkout: "applePay"` prepares it on its own, a `"sheet"` paywall calls
276
300
  `prefetch(ref, { checkout: "applePay" })`, and an unprepared tap opens
277
- the sheet. Any other config `checkout` sends a Stripe purchase to the
278
- 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`
279
305
  renders the hook.
280
306
 
281
307
  ```tsx
282
308
  const { purchase, prefetch } = usePurchase();
283
309
  const applePay = useApplePay(reference);
284
310
  useEffect(() => {
285
- if (applePay?.available) prefetch(reference, { checkout: "applePay" });
286
- }, [applePay?.available, prefetch, reference]);
287
- return applePay?.available && applePay.product.status === "ready" ? (
311
+ if (applePay.available) prefetch(reference, { checkout: "applePay" });
312
+ }, [applePay.available, prefetch, reference]);
313
+ return applePay.product.status === "ready" ? (
288
314
  <button onClick={() => purchase(reference, { checkout: "applePay" })}>Apple Pay</button>
289
315
  ) : (
290
316
  <button onClick={() => purchase(reference, { checkout: "sheet" })}>Pay with card</button>
@@ -453,6 +479,20 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
453
479
  true })`, or `teleport: { route }` so a push to it and a Stripe purchase
454
480
  teleport on their own and it is prepared when the paywall opens (call
455
481
  `useTeleport().prefetch(route)` for a route only the router teleports).
482
+ A Stripe `purchase()` in the app teleports to `teleport.route` with the
483
+ tapped product preselected there (`useTeleport().productReference`);
484
+ without `teleport.route` it teleports the route it was tapped on, cold.
485
+ Teleport pays off only when the shopper can pay with Apple Pay on the
486
+ web page, so check `useApplePay().available` first and keep them in the
487
+ app when it is `false`: `router.push(route, { teleport: false })`
488
+ pushes even `teleport.route` in the app, or sell the store product. A
489
+ paywall with `teleport` asks Apple as it opens, so the answer is
490
+ usually there before the first tap. To set up an app-to-web flow or
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).
456
496
  The route opens on the web with every `useQueryState` value carried
457
497
  along, and the app is credited when the shopper pays. Keep answers the
458
498
  web half needs in `useQueryState`, not component state. The
@@ -604,6 +644,45 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
604
644
  attribute (`useUserAttribute`), which the host persists. Use storage only for something optional, inside a
605
645
  `try`/`catch` that treats a failure as unset (docs: `troubleshooting`).
606
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
+
607
686
  ## Working loop
608
687
 
609
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