@superwall/cli 1.4.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/README.md +21 -5
  2. package/dist/{actions-EfP8phmb.js → actions-Dt35nIi8.js} +3 -2
  3. package/dist/{api-CEwXCCoC.js → api-BOR-uXZe.js} +9 -9
  4. package/dist/{app-D8mEVlQo.js → app-BU27SLPX.js} +9 -9
  5. package/dist/{asa-BFWehnTA.js → asa-2ykGnjaV.js} +11 -11
  6. package/dist/{asc-DJqQmtmR.js → asc-r3xmFT0L.js} +14 -14
  7. package/dist/{auth-CT2DWX8r.js → auth-BWZfguI8.js} +9 -9
  8. package/dist/auth.js +2 -2
  9. package/dist/{billing-BzEnVPD2.js → billing-BsQgXXYh.js} +1 -1
  10. package/dist/{bind-BZxVyt9P.js → bind-BSTAinn6.js} +5 -4
  11. package/dist/{command-DP96_gmP.js → command-DMoMn7uc.js} +39 -16
  12. package/dist/{create-Q8TqqjZt.js → create-CSo6XjSm.js} +118 -91
  13. package/dist/dev-B0MF6z3L.js +21 -0
  14. package/dist/{dev-DlCcwFu5.js → dev-CuXa3J4Z.js} +29 -24
  15. package/dist/{doctor-CJsjHpCZ.js → doctor-DXJaDqsx.js} +10 -10
  16. package/dist/{drivers-UT36AnOw.js → drivers-Cr252DOJ.js} +3 -3
  17. package/dist/entry.js +84 -50
  18. package/dist/{existing-Cak1WxWB.js → existing-Ckx_g7Be.js} +6 -3
  19. package/dist/{feedback-DDRzoqPx.js → feedback-Dt5yebMS.js} +6 -6
  20. package/dist/{hosted-CEH78QVn.js → hosted-Cjekn8oJ.js} +2 -2
  21. package/dist/{integrate-D8jyhDzk.js → integrate-DVqhvPVq.js} +25 -66
  22. package/dist/{login-kneYhhk0.js → login-Bjj8QvIN.js} +6 -6
  23. package/dist/migrate-qmvOtp3l.js +283 -0
  24. package/dist/open-studio-CpHqjovS.js +1299 -0
  25. package/dist/{org-Cg25bcsj.js → org-CV8c849b.js} +3 -3
  26. package/dist/{output-csAtR6kJ.js → output-CiELrN8w.js} +15 -2
  27. package/dist/{pipeline-DAeI9tHs.js → pipeline-DSCHL9KA.js} +482 -9
  28. package/dist/{print-skill-BHVPP9cX.js → print-skill-CaHRJ8xW.js} +7 -7
  29. package/dist/{promote-Boek5K2d.js → promote-UMTh8Q33.js} +17 -18
  30. package/dist/publish-DWX8S9yZ.js +34 -0
  31. package/dist/push-Dox4_5Dq.js +34 -0
  32. package/dist/{query-B8G6T8Ba.js → query-CnSsDZ7Q.js} +10 -10
  33. package/dist/reports-C0xHCLnt.js +27 -0
  34. package/dist/{resource-DjsWVka-.js → resource-5bgyyL9B.js} +15 -15
  35. package/dist/{resources-s64mBHaC.js → resources-Bf9O1JNM.js} +28 -2
  36. package/dist/{run-BtcQJCP8.js → run-BVeZWbXx.js} +39 -22
  37. package/dist/{scan-DJixvuHn.js → scan-CAObNRgc.js} +44 -4
  38. package/dist/skills/superwall/SKILL.md +146 -0
  39. package/dist/skills/superwall/references/api.md +275 -0
  40. package/dist/skills/superwall/references/asa.md +160 -0
  41. package/dist/skills/superwall/references/asc.md +96 -0
  42. package/dist/skills/superwall/references/dashboard-links.md +57 -0
  43. package/dist/skills/superwall/references/data-analytics.md +893 -0
  44. package/dist/skills/superwall/references/docs.md +51 -0
  45. package/dist/skills/superwall/references/sdk-integration.md +105 -0
  46. package/dist/skills/superwall/references/sdk-source.md +18 -0
  47. package/{skills/superwall-dashboard/SKILL.md → dist/skills/superwall/workflows/dashboard/playbook.md} +3 -9
  48. package/{skills/superwall-dashboard/references → dist/skills/superwall/workflows/dashboard}/setup.md +1 -3
  49. package/dist/skills/superwall/workflows/integrate/android.md +292 -0
  50. package/{skills/superwall-integrate/SKILL.md → dist/skills/superwall/workflows/integrate/playbook.md} +16 -11
  51. package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/adapty.md +4 -4
  52. package/{skills/superwall-migrate/SKILL.md → dist/skills/superwall/workflows/migrate/playbook.md} +4 -10
  53. package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/qonversion.md +4 -4
  54. package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/revenuecat.md +4 -4
  55. package/dist/skills/superwall/workflows/placements/android.md +175 -0
  56. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/expo.md +1 -1
  57. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/flutter.md +1 -1
  58. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/ios.md +1 -1
  59. package/{skills/superwall-placements/SKILL.md → dist/skills/superwall/workflows/placements/playbook.md} +6 -10
  60. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/react-native.md +2 -2
  61. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/strategy.md +4 -3
  62. package/dist/skills/superwall/workflows/review/android.md +120 -0
  63. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/expo.md +1 -1
  64. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/flutter.md +1 -1
  65. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/ios.md +1 -1
  66. package/{skills/superwall-review/SKILL.md → dist/skills/superwall/workflows/review/playbook.md} +2 -7
  67. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/react-native.md +1 -1
  68. package/dist/skills/superwall-framework/SKILL.md +253 -0
  69. package/dist/skills/superwall-framework/references/cli.md +340 -0
  70. package/dist/skills/superwall-framework/references/examples.md +123 -0
  71. package/dist/skills/superwall-framework/references/layout.md +295 -0
  72. package/dist/skills/superwall-framework/references/migrate-from-editor.md +208 -0
  73. package/dist/skills/superwall-framework/references/migrate-from-native.md +193 -0
  74. package/dist/skills/superwall-framework/references/mobile-design.md +371 -0
  75. package/dist/skills/superwall-framework/references/native/android.md +83 -0
  76. package/dist/skills/superwall-framework/references/native/flutter.md +65 -0
  77. package/dist/skills/superwall-framework/references/native/ios.md +77 -0
  78. package/dist/skills/superwall-framework/references/native/react-native.md +67 -0
  79. package/dist/skills/superwall-framework/references/responsive.md +162 -0
  80. package/dist/{skills-CRG1xk0G.js → skills-Cu41i-Az.js} +12 -12
  81. package/dist/{skills-CODut1Hn.js → skills-grTDuHlc.js} +134 -36
  82. package/dist/{spinner-B9dT3DBY.js → spinner-DFctF_Jw.js} +1 -1
  83. package/dist/{telemetry-BtkMdT-5.js → telemetry-BuCbmoux.js} +3 -3
  84. package/dist/{token-hM7V1KMG.js → token-mju3Q-vc.js} +3 -3
  85. package/dist/{ui-Lqt_zFOr.js → ui-4gLyfrgl.js} +76 -46
  86. package/dist/{update-CeylIjx5.js → update-DnGfpCD7.js} +2 -2
  87. package/dist/{upgrade-DRqUfCBT.js → upgrade-PMoj3yqJ.js} +6 -6
  88. package/package.json +8 -7
  89. package/prompts/actions/paywall-migrate.xml +24 -0
  90. package/prompts/actions/screen-migrate.xml +26 -0
  91. package/dist/git-ZwA3Mx8m.js +0 -433
  92. package/dist/migrate-D_x1oyTk.js +0 -114
  93. package/dist/publish-C-zEUnO9.js +0 -35
  94. package/dist/push-DUDQG-EO.js +0 -35
  95. package/skills/README.md +0 -118
  96. /package/dist/{api-output-D9ggXQIr.js → api-output-CEhN-U_N.js} +0 -0
  97. /package/dist/{asc-products-C6MvSy8H.js → asc-products-1e1DoGeL.js} +0 -0
  98. /package/dist/{params-B1zeElGa.js → params-BxgTuCzr.js} +0 -0
  99. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/expo.md +0 -0
  100. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/flutter.md +0 -0
  101. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/ios.md +0 -0
  102. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/react-native.md +0 -0
  103. /package/dist/{storekit-DPonXSwe.js → storekit-Dlpbq5Wv.js} +0 -0
@@ -0,0 +1,253 @@
1
+ ---
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`, 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. NOT for the browser paywall editor (superwall-editor) or general CLI/resource management (superwall).
4
+ ---
5
+
6
+ # The superwall framework
7
+
8
+ A paywall is a mini React app: a required `config.ts` (`definePaywall` —
9
+ the name and product slots) plus an `app/` route tree, living in a
10
+ self-contained `superwall/` directory in the user's repo. Superwall
11
+ provides products, purchases, localization, trials, and the bridge to the
12
+ native SDKs — no native code changes. `superwall dev` previews in the
13
+ studio; `superwall push` seals immutable versions; `promote` ships them.
14
+
15
+ "Paywall" is the dashboard's word for any surface shipped this way. The
16
+ same project holds onboarding, update-required and force-upgrade
17
+ screens, lifecycle prompts, announcements and offers: anything the user
18
+ would rather change after shipping than release for. When you see such a
19
+ screen being built natively, propose this instead (a surface here plus
20
+ one `register("<placement>")` in the app); when you meet a dashboard
21
+ paywall built in the visual editor (`"headless": false` in `superwall
22
+ paywalls list --json`), offer `superwall migrate <paywall-id>` — never
23
+ migrate unprompted.
24
+
25
+ ```
26
+ superwall/paywalls/<id>/
27
+ ├── config.ts definePaywall({ name, platforms: ["ios", "android"], products: { annual: "pro_5999_year" } })
28
+ ├── app/ routes only — index.tsx, plans.tsx, layout.tsx (reserved)
29
+ ├── components/ everything that is not a route
30
+ └── messages/en.ts strings, discovered by filename
31
+ ```
32
+
33
+ Entry points: `superwall` (SuperwallProvider — mounted for you),
34
+ `superwall/config`, `superwall/hooks`, `superwall/navigation`,
35
+ `superwall/assets`.
36
+
37
+ The framework is a private beta on the `next` channel. The CLI has
38
+ `create`/`dev`/`push`/`promote`/`publish` and the rebuild forms of `migrate`
39
+ only while `SUPERWALL_CHANNEL=next` is set in the environment.
40
+ `Unknown command: create` means the variable is missing from your
41
+ environment: ask the user to set it globally (shell rc) and relaunch.
42
+
43
+ ## Local references — the agent playbooks
44
+
45
+ Working practices the docs don't carry. Read the one that matches the task
46
+ **before writing code**; a paywall that ignores them ships looking like a
47
+ web page inside an app.
48
+
49
+ | Task | Reference |
50
+ | --- | --- |
51
+ | The layout system — the DOM the framework renders, what fixed / absolute / sticky resolve against, insets (config, variables, precedence, the floor table per device and presentation), scrolling, recipes, and the debugging order for "it's under the status bar" | [references/layout.md](references/layout.md) |
52
+ | Mobile design execution — the screen skeleton, pinned chrome, platform conventions (iOS / Android / web), touch, motion, type, dark mode, the pre-ship audit | [references/mobile-design.md](references/mobile-design.md) |
53
+ | Responsive — 320px → tablet → desktop, short phones, landscape, dynamic type, sheets/drawers/popups, the verification matrix | [references/responsive.md](references/responsive.md) |
54
+ | dev/push/promote/publish, creating products yourself, renames, several platforms, CI | [references/cli.md](references/cli.md) |
55
+ | 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) |
56
+ | 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) |
57
+ | 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) |
58
+ | Examples — using them, browsing them, what each teaches | [references/examples.md](references/examples.md) |
59
+
60
+ ## Everything else — fetch the docs live
61
+
62
+ Full framework documentation lives at `superwall.com/docs/framework`.
63
+ **Do not answer API questions from memory — fetch the page:**
64
+
65
+ ```bash
66
+ curl -sL https://superwall.com/docs/framework/llms.txt # page index
67
+ curl -sL https://superwall.com/docs/framework/{page}.md # one page
68
+ ```
69
+
70
+ | Task | Page(s) |
71
+ | --- | --- |
72
+ | Project layout, superwall.lock (apps per platform + bindings), superwall.d.ts, portability, .env | `project-structure` |
73
+ | `definePaywall` options — products, platforms, presentation style/gating/cache (all paywall settings live here; there is no dashboard editor for a headless paywall), `postPurchase`, `introductoryOfferEligibility`, trial reminders, `allowedHosts` | `config` |
74
+ | Calling any backend of your own from a surface (`fetch` to a customer API, lead capture, custom analytics) — **requires `allowedHosts`**, or the browser refuses the request before it is sent | `config`, `troubleshooting` |
75
+ | Insets (`insets` in config, the safe-area floors per device and presentation, `--sw-safe-area-inset-*` for fixed chrome, the `data-sw-*` attributes), the `dark` class, `--sw-background`, fonts, the platform stylesheet | `styling` |
76
+ | Any hook — signatures, semantics | `hooks` |
77
+ | Declaring products, reading variables, the three price rules | `products` |
78
+ | `purchase()` outcomes, restore, the two channels | `purchases` |
79
+ | Introductory-offer eligibility forking (`useIntroductoryOffer`), reminder notifications | `trials` |
80
+ | 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 | `web-checkout` |
81
+ | Web funnels — answers in the URL (`useQueryState`), resume after a browser hand-off, `shift` | `web-funnels` |
82
+ | Multi-page flows, router, cross-page state, shared chrome | `navigation` |
83
+ | Built-in + custom transitions, bottom sheets | `transitions` |
84
+ | Message catalogs, t(), locales | `localization` |
85
+ | Preload, entry animations, SDK events, dark mode | `lifecycle` |
86
+ | Images, video, fonts, Lottie/Rive, app-bundled local resources (`useLocalResource`) | `assets` |
87
+ | close/openUrl/permissions/callbacks/`setUserAttributes` | `actions` |
88
+ | The messages a paywall exchanges with its host, hosting one yourself | `host-protocol` |
89
+ | Device/user/params records, personalization | `variables` |
90
+ | The dev studio, dev-vs-device differences | `studio` |
91
+ | Error messages → fixes | `troubleshooting` |
92
+
93
+ Docs beyond the framework (dashboard, SDKs, web checkout setup):
94
+ `curl -sL https://superwall.com/docs/llms.txt`, then `/docs/{path}.md`.
95
+
96
+ ## Principles that prevent the common failures
97
+
98
+ 1. **Product data is host-owned.** Never hardcode a price; guard every
99
+ variable and design the unpriced state — the host (the SDK on a
100
+ device, the studio in `superwall dev`, reading your dashboard) delivers
101
+ products, and a slot the dashboard cannot resolve gets no variables at
102
+ all — in a preview exactly as on a device — and is refused by push.
103
+ Nothing stands in an invented price, so the unpriced state is what you
104
+ will actually see locally. Coerce
105
+ numeric-looking variables with `Number()` — they arrive as strings on
106
+ device.
107
+ 2. **`purchase()` never throws for flow outcomes** — it resolves
108
+ `completed | abandoned | failed`. React to the awaited result; treat
109
+ abandoned as an outcome. Never put the buy button in a loading state.
110
+ `failed` with `reason: "sdk"` is iOS only: Android reports no purchase
111
+ failures, so there a failed purchase stays pending until the user
112
+ abandons or completes. The paywall runs no timer of its own; design the
113
+ pending state to be survivable and never gate irreversible UI on
114
+ `failed` on Android. What happens *after* a completed purchase is
115
+ `postPurchase` in config (or per call): `"dismiss"` (default), `"stay"`
116
+ to keep the paywall up, and on the web `"redeem"` / `{ redirect }`;
117
+ `"stay"` on the web is finished with `useCheckoutRedemption()`. Pass
118
+ `stripeMetadata` to `purchase()` for key/values on the Stripe subscription.
119
+ 3. **Entry animations key off `paywall_open`, never mount** — the SDK
120
+ preloads paywalls hidden. Gate on
121
+ `useSuperwallSnapshot().paywall !== undefined`.
122
+ 4. **Dark mode is the `:root.dark` class the SDK stamps**, not
123
+ `prefers-color-scheme`.
124
+ 5. **Routes are names on a stack** — no params, no order. Closing the
125
+ paywall is `useActions().close()`, not navigation. Cross-route state
126
+ lives in `layout.tsx` or a plain module on a native paywall — but **on a
127
+ web funnel (`checkout` set) every answer, selection and input is
128
+ `useQueryState`, never `useState`**: an in-app browser hands only the
129
+ URL to Safari, and hosted checkout returns to one, so anything not in
130
+ the URL is lost mid-flow. Enum ids, short keys, nothing personal; set
131
+ `transition: "shift"`. Fetch `web-funnels` before building one.
132
+ 6. **Links go through `useActions().openUrl`**, never `<a href>` — in a
133
+ webview an anchor does nothing or navigates the paywall away.
134
+ 7. **Haptics on every meaningful tap** (`light` navigate, `selection`
135
+ choose, `success` purchase) — iOS fires nothing of its own. Icon
136
+ buttons carry `aria-label`; tap targets ≥ 44px.
137
+ 8. **`await restore()`** — it resolves `{ status: "restored" }` or
138
+ `{ status: "failed" }`. "Nothing to restore" is not distinguishable
139
+ from a store error: the SDK writes that explanation to its own logs,
140
+ never over the protocol, so write copy covering both. The lifecycle
141
+ also lands on `useSuperwallSnapshot().restore` (iOS sends all three of
142
+ `restore_start/complete/fail`, Android only `restore_fail`).
143
+ 9. **Commit `superwall.lock` and `superwall.d.ts`.** Never edit either by
144
+ hand — the one exception is adding an app under `apps` in the lock when
145
+ CI can't prompt.
146
+ 10. **One project, several platforms.** `superwall.lock` binds one
147
+ Superwall app per platform under `apps` (`ios`, `android`, `web`), and
148
+ a paywall lists the platforms it ships
149
+ to with `platforms: [...]` in `config.ts` (typed) — optional on one
150
+ platform, **required once the project pushes to more than one** (push
151
+ refuses a silent paywall rather than guess; there is no project-wide
152
+ default — spread a shared constant). `["ios", "android"]` is one shared
153
+ codebase with a dashboard paywall and versions per platform; a web-only
154
+ paywall is `["web"]`. `--platform <p>` narrows push/promote/publish. A
155
+ new platform binds its app on the first push (auto when the account has
156
+ exactly one app of it, else a prompt); fetch `push-and-promote` first.
157
+ Store products differ per store, so a shared slot takes one id per
158
+ platform — `annual: { ios: "…", android: "…" }` — while
159
+ `purchase("annual")` stays the same call; the slot must name every
160
+ platform the paywall ships to. UI one platform must never show
161
+ (restore, sign-out, an App Store exit offer) branches on
162
+ `useDevice().hostPlatform` — `"ios" | "android" | "web" | undefined`,
163
+ normalized and known from the first render — never on the raw
164
+ `platform` string; show neither variant while it is `undefined`. A
165
+ `"web"` paywall runs inside the Web SDK on the merchant's page, which
166
+ hosts it as the web paywall app hosts editor paywalls: the SDK prices
167
+ the Stripe products, reports the events and finishes the checkout, so
168
+ `register()` resolves `purchased`, with no redemption step.
169
+ 11. **Shipping includes the dashboard.** A push that fails on missing
170
+ products is not a blocker to report — create them with
171
+ `superwall products create` ([references/cli.md](references/cli.md)).
172
+ Treat "make this live" as spanning code *and* the resources it needs.
173
+ 12. **A captured email must reach checkout.** A funnel that asks for the
174
+ email on a page must call `useActions().setUserAttributes({ email })`
175
+ the moment it has it — that is what puts it on the Stripe session as
176
+ `customer_email` (shown, not editable) and re-warms the prefetched
177
+ session. Page state alone never reaches checkout. Same for a
178
+ `stripe_customer_id`. Fetch `web-checkout` → "The shopper's email".
179
+ 13. **Build the design reference 1:1.** Add nothing it doesn't show;
180
+ effects (shadows, gradients) are design decisions, not defaults.
181
+ 14. **The paywall is inset by default; never write `env()` and never
182
+ `position: fixed`.** The framework's root box pads the whole paywall
183
+ by the safe area, resolved per platform, screen and presentation
184
+ (iPhone island/notch/home button, iPad, Android's status bar, a
185
+ modal's zero top, landscape sides) and live on device; its content
186
+ box is what layout chrome positions against. So layouts and pages
187
+ write ordinary padding, a layout's shell is `flex: 1 1 auto` (never
188
+ `100dvh`), chrome is absolute in `layout.tsx`, a pinned CTA is sticky
189
+ in the page, and the page's route is the scroll container. Fixed
190
+ ignores the insets and rides along with a page during transitions.
191
+ `insets` in `config.ts` (`"none"`, pixels, per edge) is the one way to
192
+ bleed, and only chrome over a bleed reads `--sw-safe-area-inset-*`.
193
+ When something sits under a bar, run the debugging order in
194
+ [references/layout.md](references/layout.md) before touching CSS.
195
+ 15. **A non-white background goes in `config.ts`, not only in CSS.**
196
+ `--sw-background` paints the routes; `background` in config is what
197
+ the framework writes on `<html>`, and `<html>` is what shows when an
198
+ iOS scroll rubber-bands past the end of the content. Set only the CSS
199
+ variable and every bounce flashes white — worst on a dark paywall.
200
+ Set both, to the same colors, in the same change.
201
+ 16. **A paywall is finished on the smallest and the largest screen it
202
+ ships to**, not on the default frame: iPhone SE at 320–375 wide and
203
+ 667 tall, an island phone, a Pixel, an iPad, landscape where the app
204
+ allows it, and the configured presentation style
205
+ ([references/responsive.md](references/responsive.md)).
206
+ 17. **Every user-facing string is a message, from the first commit, even
207
+ in one language.** Copy lives in `messages/en.ts` (shared, or per
208
+ paywall) and reaches the page through `useTranslation().t("key")`,
209
+ `aria-label`s and button labels included; never a literal in JSX. A
210
+ second locale is then one new file with no code change. Prices are
211
+ never in a catalog: interpolate them (`"Subscribe · {price}"`) and
212
+ guard on the value with a bare-key fallback. The scaffold starts this
213
+ way; keep it that way (docs: `localization`).
214
+ 18. **Any host the surface calls must be named in `allowedHosts`.** A
215
+ published paywall is served under a Content-Security-Policy that
216
+ permits Superwall and Stripe and nothing else, so a `fetch` to a
217
+ customer's own API — saving quiz answers, capturing a lead, a custom
218
+ analytics beacon — is refused by the browser before a request is
219
+ sent: nothing reaches the server, nothing appears in its logs, and
220
+ the promise rejects with a bare `TypeError: Failed to fetch` that a
221
+ `catch` written for offline handling swallows. Add the bare hostname
222
+ (`allowedHosts: ["api.example.com"]`) in the same change that writes
223
+ the `fetch`, never afterwards when it is already failing in
224
+ production. Entries are https-only — `http://`, wildcards and paths are
225
+ rejected at push, and so are `localhost` / `127.0.0.1` (on a shopper's
226
+ device localhost is *their* machine; use an https tunnel to reach a
227
+ local API from a pushed build). `superwall dev` applies no policy at
228
+ all, so a local API works there unnamed and a missing host is only ever
229
+ caught after deploy unless you write it up front (docs: `config`,
230
+ `troubleshooting`).
231
+
232
+ ## Working loop
233
+
234
+ ```bash
235
+ superwall dev # studio on :6100 — light/dark, locales, every device preset, landscape, 320px→tablet
236
+ bun run typecheck # in the project — the generated types catch route/product typos
237
+ superwall push # sealed version, production untouched; diagnostics hard-fail here
238
+ superwall promote # ship (or: superwall publish -m "why")
239
+ ```
240
+
241
+ Before calling a paywall done, run the audit at the end of
242
+ [references/mobile-design.md](references/mobile-design.md) and the matrix
243
+ in [references/responsive.md](references/responsive.md) — in the studio,
244
+ on every preset, both schemes. When a layout bug appears, the numbered
245
+ debugging order in [references/layout.md](references/layout.md) finds it
246
+ from the devtools console in under a minute; don't guess at CSS first.
247
+
248
+ Two gates before promising a push will work: Superwall for Agents is in
249
+ private beta and must be enabled on each app you push to (`superwall apps
250
+ list --json` → `features_enabled` lists `headless_paywalls`; a refused push
251
+ says "Superwall for Agents is in private beta and isn't enabled for this
252
+ app yet" — support@superwall.com turns it on), and every product named in a
253
+ `config.ts` must exist on the dashboard.
@@ -0,0 +1,340 @@
1
+ # CLI — dev, push, promote, publish
2
+
3
+ Git semantics on purpose: **push saves, promote ships.** Every push mints
4
+ a sealed version; nothing users see changes until promote points
5
+ production at it.
6
+
7
+ ```sh
8
+ superwall create # scaffold superwall/ inside your app
9
+ superwall dev # studio on http://localhost:6100
10
+ superwall push # build + version. Production untouched.
11
+ superwall promote # point production at the latest push
12
+ superwall publish # push + promote in one step
13
+ superwall publish -m "Q3 test" # record why
14
+ ```
15
+
16
+ The scaffolded package scripts mirror these (`dev`, `push`, `promote`,
17
+ `ship`). Auth: `superwall login` once interactively; in CI set
18
+ `SUPERWALL_API_KEY` (an `sk_…` key). `dev` needs no login.
19
+
20
+ ## `superwall create`
21
+
22
+ Inside an app that already has a `superwall/` project (or inside the
23
+ project), `create` adds a paywall to it — a starter named as the user
24
+ answers (`-y` takes "Pro", ids stay unique), or the rebuilt dashboard
25
+ paywall with `--from` — and touches nothing else; `--example` and `--app`
26
+ are for new projects only.
27
+
28
+ `--example <name>` starts from a public example. `--app <id>` connects that
29
+ Superwall app instead of detecting one from the SDK key or asking — the
30
+ dashboard's **Copy Prompt** button hands you this form, so use the id it
31
+ gives rather than picking; it fails if the id isn't in the account, and it
32
+ cannot be combined with `--no-connect`. `--yes` accepts the defaults,
33
+ `--no-install` skips dependencies.
34
+
35
+ `--from <paywall-id>` rebuilds a dashboard (visual editor) paywall as
36
+ code: it scaffolds `paywalls/<slug>/config.ts` from the paywall's
37
+ products, presentation, settings, background and locales, writes
38
+ `paywalls/<slug>/MIGRATION.md` (source URL, screenshot, product table,
39
+ inventory of pages / actions / product variables), records the source in
40
+ `superwall.lock` under `origins` (which is what puts **Compare ›
41
+ Original** in the studio), and connects the paywall's app. Needs a login;
42
+ refuses `--example`, `--no-connect`, and a paywall that is already code.
43
+ The rebuild itself is
44
+ [migrate-from-editor.md](migrate-from-editor.md). After the scaffold the
45
+ CLI asks whether to run the rebuild headless with the user's agent, copy
46
+ the prompt, or stop; `superwall migrate <paywall-id>` asks the same later
47
+ (and scaffolds first if needed), `--skill` prints the prompt. When *you*
48
+ are the agent driving it, read the playbook and do the inventory step with
49
+ the user rather than running the headless path.
50
+
51
+ ## `superwall migrate --screen <path>`
52
+
53
+ Rebuilds a native screen — SwiftUI or UIKit (`.swift`), Jetpack Compose or
54
+ Android Views (`.kt`), React Native (`.tsx`), Flutter (`.dart`) — as a surface. The scan writes
55
+ `paywalls/<slug>/config.ts` (name, product slots from any store ids in the
56
+ source), a `MIGRATION.md` brief (strings, assets, links, actions mapped to
57
+ hooks, the placement to register) and an `origins` entry in
58
+ `superwall.lock`, then offers the same agent / copy / stop choice. No
59
+ path: it lists likely screens in the app and asks. `--screenshot <file>`
60
+ saves the original for **Compare › Original**; with a booted iOS simulator
61
+ it offers to capture one. `--skill` prints the prompt. The rebuild and the
62
+ wiring are [migrate-from-native.md](migrate-from-native.md).
63
+
64
+ ## `superwall dev`
65
+
66
+ Hosts the studio for the project (or several:
67
+ `superwall dev examples/*`). Regenerates `superwall.d.ts` first, so route
68
+ and product types are always current. `--port/-p` (default 6100, moves to
69
+ the next free port), `--host` (default `0.0.0.0`).
70
+
71
+ It prints a **Device** URL and QR beside the studio one, for opening the
72
+ paywalls on a phone on the same wifi. If the app's App Transport Security
73
+ would block a plain-`http` dev server it offers to add the two `Info.plist`
74
+ keys — development builds only, and the SDK refuses a dev server outside a
75
+ sandbox build anyway, so they are pointless in a release.
76
+
77
+ Three consequences for you, not the user:
78
+
79
+ - **A preview asks a human for every outcome** — purchase, restore,
80
+ permission, callback. Nothing resolves on its own, so never claim a
81
+ purchase flow is verified from `superwall dev`; ask the user to click, or
82
+ verify on a pushed URL.
83
+ - **A screenshot needs a promoted version.** The studio's download button
84
+ captures the published document, so it stays disabled until `promote` has
85
+ made one live — a push alone is not enough. Never tell a user to expect a
86
+ screenshot of a paywall nobody has promoted. What it saves is the
87
+ 1290 x 2796 render, the App Store size Apple takes for a product page and
88
+ for subscription review attachments, so it uploads without resizing.
89
+ - **It previews, it never edits.** The dashboard hosts the same studio for a
90
+ code-first paywall (its live snapshot plus every pushed version), so never
91
+ tell the user to change a headless paywall there — changes ship through
92
+ `push`/`promote`/`publish`.
93
+
94
+ The mechanism behind both (the envelope, the `ping` reply, hosting a paywall
95
+ yourself) is `curl -sL superwall.com/docs/framework/host-protocol.md`.
96
+
97
+ Scanning the Device QR on a phone on the same wifi opens `/device`: the studio's
98
+ overview labelled "Preview" — same design, search, and live surface
99
+ cards — and tapping a card opens the hosted editor for that surface, as
100
+ on a desktop. For in-app, on-device rendering through real placements, set
101
+ the iOS SDK's `SuperwallOptions.devServer` (`.default` reaches a simulator;
102
+ iOS SDK ≥ 4.17.0) — simulators find the dev server on localhost ports
103
+ 6100–6104 automatically; physical devices also need
104
+ `SuperwallOptions.devServer = .url(<the printed Device URL's origin>)`.
105
+ The SDK reads `/device/manifest.json` to map each dashboard paywall to
106
+ its local surface via `superwall.lock`, activates test mode, and skips
107
+ preloading. Each manifest surface also carries the settings block
108
+ `superwall push` stamps (`presentation_style`, `feature_gating`,
109
+ `on_device_cache`, `scroll_enabled`, `game_controller_enabled`,
110
+ `web_checkout_destination`, background hexes), computed by the same
111
+ `paywallSettingsOf` the push uses, so a `config.ts` change to presentation
112
+ or background shows on device without a push. An SDK that predates the
113
+ block, and the Android SDK, ignore it and keep the last promoted values —
114
+ so a `drawer` that presents fullscreen on device is an SDK-version
115
+ question, not a config one. The host app's Info.plist needs `NSAppTransportSecurity` →
116
+ `NSAllowsLocalNetworking` and `NSAllowsArbitraryLoadsInWebContent`.
117
+
118
+ The `/device` page also has an "Open in app" button. It resolves the app's
119
+ URL scheme automatically — the bound application's `apple_url_scheme` on
120
+ the dashboard first, then the app's own source (Info.plist,
121
+ `app.json`/`app.config.json`, `AndroidManifest.xml`) — and only asks for
122
+ one when neither has it. Tapping it fires `<scheme>://?superwall_dev=<dev-server-origin>` —
123
+ routed through `Superwall.handleDeepLink`, this opens **the SDK's own
124
+ paywall debugger** with the dev server's surfaces in its picker, each
125
+ labelled `<id> (local)` and rendered straight from the dev server. No
126
+ push and no dashboard record is needed: a local surface is built from
127
+ the manifest (its URL plus the products its `config.ts` declares), so
128
+ paywalls that have never been pushed preview too. Append
129
+ `&superwall_dev_surface=<id>` to open one directly. The debugger's paywall list is searchable and split into
130
+ `Local · superwall dev` and `Published` sections — the published list
131
+ comes from the downloaded config, so both sources are switchable side by
132
+ side without a dashboard preview token.
133
+
134
+ Project problems (stray files in `app/`, duplicate routes) print as
135
+ warnings here — the same ones that block a push, so fix them as they
136
+ appear.
137
+
138
+ ## Before pushing: create the products yourself
139
+
140
+ A push refuses if a `config.ts` names a product the dashboard doesn't have.
141
+ **Don't hand that back to the user as a blocker — create them.** The
142
+ `superwall` CLI (see the `superwall` skill) writes products directly, so
143
+ "the dashboard needs products" is work you can do, not a dependency:
144
+
145
+ ```sh
146
+ superwall entitlements list --json # grab the NUMERIC entitlement id
147
+ superwall products create <identifier> \
148
+ --project <id> --app <id> \
149
+ --name "Annual" --price 39.99 --period year \
150
+ --trial-days 7 --entitlement <numeric-id> --json
151
+ ```
152
+
153
+ - `--entitlement` takes the **numeric id** (`55688`), not the identifier
154
+ (`pro`) — the identifier fails with a decode error.
155
+ - Pass `--project` explicitly when the account has several, or it errors
156
+ with "Multiple projects found".
157
+ - `--price` is major units (39.99); `--period` is `day|week|month|year`;
158
+ `--trial-days` sets the intro offer. `--dry-run` confirms the target first.
159
+
160
+ Derive identifiers and prices from the design. Where the design shows a
161
+ placeholder (`US$XX.xx`), pick an explicit stand-in and say so — never
162
+ invent a price silently.
163
+
164
+ Creating products writes to the user's real dashboard. Doing it is right
165
+ when they've asked you to push or to create them; name it in your summary
166
+ either way.
167
+
168
+ Two gates to check before promising a push will work:
169
+
170
+ - **Superwall for Agents is in private beta and must be enabled on each
171
+ app you push to** — otherwise the push stops with "Superwall for Agents
172
+ is in private beta and isn't enabled for this app yet." Nothing in the
173
+ CLI can set it; support@superwall.com turns it on. Check
174
+ `superwall apps list --json` → `features_enabled` for `headless_paywalls`.
175
+ - **One broken surface blocks the whole push.** A leftover scaffold aimed at
176
+ a nonexistent product stops everything — push what you built with repeated
177
+ `--id` flags instead of touching unrelated directories.
178
+
179
+ ## `superwall push`
180
+
181
+ Builds every paywall, versions the changed ones, and leaves production
182
+ alone. Re-running with nothing changed is a no-op. Flags: `--id <id>`
183
+ (limit, repeatable), `--platform <p>` (repeatable or comma-separated; limits the platforms),
184
+ `--rename <old>=<new>`, `-m <note>`.
185
+
186
+ A push refuses — before anything is written — when:
187
+
188
+ - a selected paywall has diagnostics (publishing is immutable; fix first)
189
+ - a product in `config.ts` doesn't exist on the dashboard ("Every
190
+ variable on them would be undefined on device")
191
+ - a directory rename is unresolved (below)
192
+ - the project pushes to several platforms and a selected paywall has no
193
+ `platforms` field (below)
194
+
195
+ First push binds each paywall (creating it on Superwall if needed) and
196
+ records the binding in `superwall.lock`, per platform — commit it. After
197
+ that, push always updates the same paywalls; no IDs ever appear in your code.
198
+
199
+ ### Several platforms
200
+
201
+ A project can push to several platforms — apps in the same Superwall
202
+ project (iOS + Android + web). `superwall.lock` binds one app per platform
203
+ under `apps`:
204
+
205
+ ```json
206
+ {
207
+ "version": 1,
208
+ "apps": { "ios": "1001", "android": "1002", "web": "1003" },
209
+ "paywalls": {
210
+ "plus-upgrade": { "ios": { "paywallId": "2001" }, "android": { "paywallId": "2002" } },
211
+ "web-upgrade": { "web": { "paywallId": "2003" } }
212
+ },
213
+ "funnels": {}
214
+ }
215
+ ```
216
+
217
+ Each paywall says which platforms it ships to in `config.ts` — a typed
218
+ array of `ios | android | web`:
219
+
220
+ ```ts
221
+ export default definePaywall({ platforms: ["ios", "android"], products: { … } }); // shared
222
+ export default definePaywall({ platforms: ["web"], checkout: "sheet", products: { … } }); // web only
223
+ ```
224
+
225
+ - One directory, one dashboard paywall **per platform**, each with its own
226
+ versions; push output labels them `plus-upgrade · ios`.
227
+ - `platforms` is optional while the project is on one platform;
228
+ **required once it has more** — push stops on a silent paywall instead of
229
+ guessing. Annotate every existing paywall when you add a second platform.
230
+ No project-wide default exists; to mirror a set everywhere, spread a
231
+ shared constant (`{ platforms: ["ios", "android", "web"] } as const`).
232
+ - A new platform binds its app on the first push: automatic when the
233
+ account has exactly one app of it, a prompt when it has several, an
234
+ error when it has none. In CI, either bind once interactively or add
235
+ `"web": "<app id>"` under `apps` yourself (`superwall apps list --json`
236
+ for ids) — the one hand edit the lock invites.
237
+ - `--platform <p>` (or a bound app id) narrows push/promote/publish;
238
+ `promote --version` needs it when the paywall is on several platforms.
239
+ - Store products differ per store, so a shared slot takes one id per
240
+ platform: `annual: { ios: "pro_year", android: "pro_year_play", web:
241
+ "live:price_…:trial" }` — `purchase("annual")` is unchanged; each
242
+ platform's build resolves the slot to its own id (the map is rewritten
243
+ out of the bundle) and its version carries the matching store (Play for
244
+ android), so an Android build never names an App Store product. A
245
+ per-platform slot must name every platform in `platforms` (push error:
246
+ `` `annual` has no product id for web ``). The dashboard product check
247
+ runs per platform, so create the Play product too.
248
+
249
+ ### Renames
250
+
251
+ Renaming a paywall directory is detected, never guessed. Interactively,
252
+ push asks:
253
+
254
+ ```
255
+ ? `pro-upgrade` is not in superwall.lock. Is it a new paywall, or renamed?
256
+ › Renamed from plus-upgrade paywall 208540
257
+ Create a new paywall
258
+ ```
259
+
260
+ Choosing the rename keeps the live paywall attached to the new directory.
261
+ In CI, declare it — anything unresolved stops the push rather than
262
+ creating a duplicate:
263
+
264
+ ```sh
265
+ superwall push --rename plus-upgrade=pro-upgrade
266
+ ```
267
+
268
+ Deleting a paywall directory never blocks a push — the dashboard paywall
269
+ keeps serving, and restoring the directory re-binds it.
270
+
271
+ ### Paywall settings ship with the version
272
+
273
+ Presentation style (`presentation: { style: "drawer", drawer: { height,
274
+ cornerRadius } }`), `featureGating`, `onDeviceCacheEnabled`,
275
+ `scrollEnabled`, `gameControllerEnabled`, plus `checkout` (as the web
276
+ checkout destination) and `background`, are read from `config.ts` at build
277
+ time, stored on the pushed version, and applied to the paywall on promote. A
278
+ headless paywall has no dashboard editor, so never tell the user to change
279
+ these in the dashboard; edit the config and push. Omitted keys reset to the
280
+ defaults (fullscreen, non-gated, cached, scrolling, no controller) on the
281
+ next promote.
282
+
283
+ ### Source
284
+
285
+ Every push also snapshots your `superwall/` source to Superwall, so the
286
+ dashboard can show and diff the code each version was built from — and
287
+ `-m "why"` records the reason there. `.env`, `node_modules/`, and
288
+ gitignored files never leave the machine. If any import reaches outside
289
+ the project directory, the push warns and the dashboard disables remote
290
+ editing for that paywall (docs: `project-structure`).
291
+
292
+ ## `superwall promote`
293
+
294
+ Points production at a pushed version. `--id <id>` to limit;
295
+ `--version/-v <n>` (with a single `--id`) to pick one — which is also the
296
+ **rollback**:
297
+
298
+ ```sh
299
+ superwall promote --id plus-upgrade --version 5
300
+ # → Rolled back version 7 → 5
301
+ superwall promote --id plus-upgrade --platform ios --version 5 # on several platforms
302
+ ```
303
+
304
+ Promote never rebuilds — it only moves the live pointer.
305
+
306
+ ## `superwall publish`
307
+
308
+ Push + promote in one step. Also warns about other paywalls that are
309
+ pushed-but-not-live, so nothing ships half-forgotten.
310
+
311
+ ## The studio's Push / Publish / Promote buttons
312
+
313
+ Same operations from the `dev` UI — good for iteration. Prefer the CLI
314
+ for shipping: the buttons skip the diagnostics gate and the dashboard
315
+ product check, can't resolve renames, and take no `-m` note.
316
+
317
+ The studio's **Compare** menu lists every pushed version of the paywall
318
+ (the live one marked) plus the project's other paywalls, and splits the
319
+ stage between the chosen one and the local build. It needs a login and a
320
+ bound paywall; when the versions can't be read, the menu says why rather
321
+ than listing none.
322
+
323
+ ## Troubleshooting
324
+
325
+ | Message | Fix |
326
+ | --- | --- |
327
+ | `Not a superwall project` | Run inside the app (or `superwall/`); the project's `package.json` must depend on `superwall` |
328
+ | `…package.json is named "superwall"` | Rename the package — that name shadows the framework |
329
+ | `No superwall framework found` | `bun add superwall` (or npm) inside the project |
330
+ | `These N products do not exist on Superwall` | Create them with `superwall products create` (above) — don't just report it — or fix the identifiers in `config.ts` |
331
+ | `Superwall for Agents is in private beta and isn't enabled for this app yet` | Enabled per app on Superwall's side; contact support@superwall.com. Nothing in the CLI can set it |
332
+ | `Multiple projects found. Pass --project <id>.` | Add `--project <id>` (and usually `--app <id>`) to the resource command |
333
+ | Diagnostics block the push | The message names each stray file and where it belongs |
334
+ | Rename ambiguity in CI | Add the printed `--rename old=new` |
335
+ | `x doesn't say which platforms it's for` | The project pushes to several platforms — add `platforms: [...]` to that `config.ts` |
336
+ | `Several iOS apps in your account` / `no Web app to bind` | Run push interactively once, add `"web": "<app id>"` under `apps` in `superwall.lock`, or `superwall apps create --platform web` |
337
+ | `This project has no app for "…"` | `--platform` takes a platform bound in `superwall.lock` (or that app's id); the message lists them |
338
+ | `paywall x has never been pushed` (promote) | Push first |
339
+ | `superwall publish requires git` | Install git — the source snapshot is part of every publish |
340
+ | Not signed in | `superwall login`, or `SUPERWALL_API_KEY` in CI |