@superwall/cli 2.6.0-beta.1 → 2.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +47 -16
- package/dist/{apple-Bmt_iywx.js → apple-D-rfsuDA.js} +17 -19
- package/dist/{approve-D2UgqaRx.js → approve-aPc5RoXB.js} +14 -13
- package/dist/{assets-B_quADds.js → assets-PyuXe45Y.js} +3 -3
- package/dist/auth.d.ts +11 -4
- package/dist/auth.js +4 -5
- package/dist/base-CAU0hWoI.js +82 -0
- package/dist/{billing-ZIETn0j4.js → billing-Dt6L_l9R.js} +3 -3
- package/dist/{build-BWjXurjs.js → build-CY5FnMNY.js} +35 -16
- package/dist/config-DOp5oChe.js +377 -0
- package/dist/{create-C3uklw-U.js → create-BZL5VH4L.js} +41 -41
- package/dist/{create-BCIgjRHn.js → create-D6w3UL0m.js} +9 -9
- package/dist/create-DM5Y1Pyk.js +18 -0
- package/dist/{doctor-D2Q1EZe8.js → doctor-C9FR0qw3.js} +50 -10
- package/dist/entry.js +45 -40
- package/dist/{environment-BocmdvZ-.js → environment-sE2wZYdg.js} +1 -1
- package/dist/{drivers-BQkO5tHs.js → existing--peXpOZj.js} +305 -8
- package/dist/framework-DW5fqjh4.js +65 -0
- package/dist/{source-BccdO4aL.js → git-Hf9Wc7Hp.js} +34 -92
- package/dist/{held-Bykbwy-m.js → held-CUBCOCGP.js} +8 -8
- package/dist/held-DVxvPMSG.js +15 -0
- package/dist/{install-dXZZ79Oe.js → install-C5d82gZF.js} +15 -17
- package/dist/{integrate-DiSjlOjC.js → integrate-D8J_X1bj.js} +33 -38
- package/dist/{login-5sWIKDI2.js → login-C6X7JrhM.js} +8 -9
- package/dist/{login-Jp6E6d2e.js → login-DXhm9L0F.js} +3 -3
- package/dist/login-et319ESO.js +13 -0
- package/dist/{lookup-CWzVfPpq.js → lookup-DqmIbUkv.js} +28 -4
- package/dist/{migrate-BKiOUsMY.js → migrate-BYF6hKZ2.js} +66 -45
- package/dist/{notification-url-BDBxbwZq.js → notification-url-Bo54nkXv.js} +4 -4
- package/dist/{open-DNd49kT-.js → open-xdgXUzaF.js} +2 -2
- package/dist/{org-Dud1rF9f.js → org-BD8U3D1_.js} +4 -4
- package/dist/{organization-7vJA3uy1.js → organization-D-ZlB3qU.js} +4 -4
- package/dist/{orgs-Z0H9WOs1.js → orgs-DQQJ3sw_.js} +1 -2
- package/dist/{paths-CzTJVpfi.js → paths-CIlyzF2I.js} +1 -1
- package/dist/{playbook-DJ__edOW.js → playbook-ecggWGFi.js} +10 -14
- package/dist/{products-Cqq59DBQ.js → products-CJq_iXv5.js} +1 -1
- package/dist/{promote-DLtPSvmL.js → promote-QVMLGYlU.js} +27 -28
- package/dist/{pull-AoUmaiMK.js → pull-CCXhb2a7.js} +72 -26
- package/dist/{pull-D-YuT3e0.js → pull-CrdsfsAl.js} +33 -39
- package/dist/pull-h71pL3r_.js +30 -0
- package/dist/push-BIq6R8Ro.js +29 -0
- package/dist/push-D6pJM_vv.js +21 -0
- package/dist/{push-BMblzg_6.js → push-DJMGG7zW.js} +23 -12
- package/dist/{push-BrzMFd4Z.js → push-DiMDwGfe.js} +15 -8
- package/dist/{registry-DDU10_Ix.js → registry-BSnQXft4.js} +1288 -901
- package/dist/registry-YwzTfCNc.js +22 -0
- package/dist/{resolve-DpOSDDdr.js → resolve-DO7bPota.js} +52 -6
- package/dist/{resources-CptT7HD6.js → resources-XwvXA20E.js} +15 -2
- package/dist/{run-r3foWfhV.js → run-B-YvxfRc.js} +15 -17
- package/dist/scan-B36wkZmI.js +4 -0
- package/dist/{scan-nVQO7JLx.js → scan-ViBhmrB7.js} +1 -1
- package/dist/{scope-l1qGLsgz.js → scope-BLLUxbrA.js} +24 -18
- package/dist/{scope-ehZ7L1nj.js → scope-Cg1AdAfO.js} +33 -3
- package/dist/screenshot-file-Dix2Qynm.js +127 -0
- package/dist/{sdk-DEfQttek.js → sdk-BFunw4Hc.js} +1 -1
- package/dist/{framework-CLmf4swr.js → selection-C07e_GGY.js} +4 -54
- package/dist/{series-D2ZpZ8cx.js → series-B8NJK4yS.js} +1 -1
- package/dist/{server-DLARhh1k.js → server-CBtHzl9y.js} +40 -18
- package/dist/server-CZwSfzKe.js +33 -0
- package/dist/{base-ChTi42M0.js → session-BfVx50iA.js} +8 -83
- package/dist/{session-Z0BeaJPf.js → session-BlrwAdGN.js} +1 -1
- package/dist/session-Cip4j99n.js +5 -0
- package/dist/{migration-Z69tLeHC.js → setup-a4B72xJ8.js} +290 -28
- package/dist/skills/superwall/SKILL.md +37 -10
- package/dist/skills/superwall/references/api.md +66 -21
- package/dist/skills/superwall/references/asa.md +109 -64
- package/dist/skills/superwall/references/dashboard-links.md +65 -28
- package/dist/skills/superwall/references/data-analytics.md +1 -1
- package/dist/skills/superwall/workflows/dashboard/setup.md +15 -5
- package/dist/skills/superwall/workflows/integrate/flutter.md +9 -7
- package/dist/skills/superwall-artifacts/SKILL.md +7 -2
- package/dist/skills/superwall-artifacts/references/cli.md +4 -1
- package/dist/skills/superwall-framework/SKILL.md +197 -14
- package/dist/skills/superwall-framework/references/cli.md +98 -7
- package/dist/skills/superwall-framework/references/examples.md +2 -2
- package/dist/skills/superwall-framework/references/migrate-from-editor.md +5 -0
- package/dist/skills/superwall-framework/references/migrate-from-native.md +5 -0
- package/dist/{skills-421SFEyF.js → skills-BB1uIt8t.js} +139 -9
- package/dist/{skills-CdKwaTRS.js → skills-SnxFa2in.js} +8 -12
- package/dist/source-DQs6iLtC.js +82 -0
- package/dist/{source-push-B4s6r9bB.js → source-push-w7miTr6m.js} +38 -14
- package/dist/{spinner-DPdBlZe2.js → spinner-BQp7fQvK.js} +7 -5
- package/dist/{starter-0OdVPH4l.js → starter-BlJ_InZJ.js} +16 -6
- package/dist/{status-Dsc7d3z2.js → status-DxsIw9zq.js} +9 -11
- package/dist/{output-Ggzq5_-t.js → storage-BR6imSqm.js} +40 -1
- package/dist/storekit-BqyujKQ_.js +203 -0
- package/dist/storekit-ELVCMF0X.js +15 -0
- package/dist/{bind-ClFjTt0U.js → theme-Ed0gz6hr.js} +29 -6
- package/dist/token-CWQ6tdva.js +100 -0
- package/dist/tools-skills/animate-onboarding/SKILL.md +1 -1
- package/dist/tools-skills/mobile-design/SKILL.md +1 -1
- package/dist/tools-skills/onboarding-questions/SKILL.md +1 -1
- package/dist/tools-skills/superwall/SKILL.md +43 -17
- package/dist/tools-skills/superwall/references/api.md +74 -24
- package/dist/tools-skills/superwall/references/asa.md +109 -64
- package/dist/tools-skills/superwall/references/dashboard-links.md +65 -28
- package/dist/tools-skills/superwall/references/data-analytics.md +1 -1
- package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +4 -3
- package/dist/tools-skills/superwall/workflows/dashboard/setup.md +21 -8
- package/dist/tools-skills/superwall/workflows/integrate/flutter.md +9 -7
- package/dist/tools-skills/superwall/workflows/migrate/adapty.md +4 -3
- package/dist/tools-skills/superwall/workflows/migrate/playbook.md +2 -2
- package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +4 -3
- package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +4 -3
- package/dist/tools-skills/superwall-editor/SKILL.md +2 -3
- package/dist/tools.d.ts +6 -1
- package/dist/tools.js +1290 -747
- package/dist/{try-B8FYkTvQ.js → try-C3HW3hPZ.js} +20 -22
- package/dist/{lock-DgSx-p8Y.js → types-Dc9U_4kp.js} +86 -80
- package/dist/upgrade-Cw9jVt-r.js +348 -0
- package/dist/upgrade-DVsonzDF.js +27 -0
- package/package.json +11 -3
- package/dist/client-CyrYJzBF.js +0 -180
- package/dist/config-CGcG7GOt.js +0 -113
- package/dist/create-7HDW3DCl.js +0 -20
- package/dist/existing-Cl5x6_5u.js +0 -97
- package/dist/held-Chw3BtBV.js +0 -17
- package/dist/log-C0MDCfA2.js +0 -62
- package/dist/login-DZ8Pipf6.js +0 -17
- package/dist/pull-C1xm2zqG.js +0 -36
- package/dist/push-B42D8fKf.js +0 -22
- package/dist/push-Co5jk6Kr.js +0 -30
- package/dist/run-c1O2_8pp.js +0 -100
- package/dist/scan-D86kLtM7.js +0 -4
- package/dist/screenshot-file-XAS0Xy0e.js +0 -16
- package/dist/server-BEcsQaPu.js +0 -29
- package/dist/session-Csuaw6RU.js +0 -6
- package/dist/setup-C6NFy14d.js +0 -217
- package/dist/spawn-DmmmHIP-.js +0 -71
- package/dist/storage-DT_wxwJ8.js +0 -41
- package/dist/storekit-B9M2raxe.js +0 -47
- package/dist/storekit-BWZf-fNE.js +0 -17
- package/dist/telemetry-ovPiseFm.js +0 -56
- package/dist/theme-DUsCh-Vd.js +0 -25
- package/dist/token-Bu3FaRkv.js +0 -70
- package/dist/upgrade-B7TmvEPP.js +0 -206
- package/dist/upgrade-CAHyrWUL.js +0 -7
- /package/dist/{browser-Bp3yRKlU.js → browser-BVjaf98V.js} +0 -0
- /package/dist/{client-BJQXl62Q.js → client-BwYhzITp.js} +0 -0
- /package/dist/{design-lint-CiFc78aM.js → design-lint-mgO-2SGS.js} +0 -0
- /package/dist/{devtools-ByZ6XYnn.js → devtools-B6Vp6HMy.js} +0 -0
- /package/dist/{input-MDd67UIp.js → input-DOT_2Zvb.js} +0 -0
- /package/dist/{project-NoMtbMyl.js → project-BomArwSj.js} +0 -0
- /package/dist/{reports-HYVp169R.js → reports-hbxsd3Zo.js} +0 -0
- /package/dist/{storage-Bdz5AmqS.d.ts → storage-Bh3wT1Rn.d.ts} +0 -0
- /package/dist/{timing-Ca0TXY-A.js → timing-BKEEIBij.js} +0 -0
- /package/dist/{ui-D_qf3Gvw.js → ui-hFgji1e8.js} +0 -0
|
@@ -22,6 +22,8 @@ superwall artifacts dev --app <app> # http://localhost:8790, real data, re
|
|
|
22
22
|
superwall artifacts try transactions --app <app> # a metric on the real runtime
|
|
23
23
|
superwall artifacts try home --org <org> # a page in the dashboard
|
|
24
24
|
superwall artifacts push --org <org> # build it; only you see it until an admin approves it
|
|
25
|
+
superwall artifacts approve # an admin approves it; every slot but org.page then needs install
|
|
26
|
+
superwall artifacts install transactions --app <app> # a metric shows in Charts only once installed
|
|
25
27
|
```
|
|
26
28
|
|
|
27
29
|
1. **`dev`** bundles it the way the builder does and runs it in workerd. A local page plays the
|
|
@@ -36,7 +38,10 @@ superwall artifacts push --org <org> # build it; only you see it until an
|
|
|
36
38
|
4. **Only the author can see a pushed version until an admin approves it.** Say so. A staff account gets no copy, so
|
|
37
39
|
nobody can see what it pushes until then, and `push` and `share` say which. After approval, the author keeps a
|
|
38
40
|
copy marked "Not installed" until an entrypoint has an install. `share` asks for review,
|
|
39
|
-
an admin runs `approve`, and `install` chooses where it shows. `org.page@1` needs no install
|
|
41
|
+
an admin runs `approve`, and `install` chooses where it shows. `org.page@1` needs no install; every other
|
|
42
|
+
entrypoint does, a `chart.source@1` metric included: it isn't in Charts until
|
|
43
|
+
`superwall artifacts install <entrypoint> --app <app>` has run. `push` and `approve` print that command for
|
|
44
|
+
each entrypoint that has no install yet (`not_installed` in `--json`), so run it or tell the person to.
|
|
40
45
|
5. **A pusher's own copy can include teammates' merged code, and it runs with the pusher's reads.** `push` lists
|
|
41
46
|
those commits and asks first. Without a terminal it stops unless `--accept-merged-commits` is passed. That flag
|
|
42
47
|
is for a person who has read them, so don't add it to get past the refusal.
|
|
@@ -52,7 +57,7 @@ scope it knows is missing; a draft holds only the manifest's read scopes ∩ you
|
|
|
52
57
|
| `src/worker.ts` | The code. One default export and no other exports. |
|
|
53
58
|
| `wrangler.jsonc` | `name`, `main` and `compatibility_date`. No bindings of any kind. |
|
|
54
59
|
| `package-lock.json` | Required, from npm. The builder installs exactly this. |
|
|
55
|
-
| `superwall.artifact.json` | Written by the first push: which artifact this is. Commit it, so teammates push to the same one. |
|
|
60
|
+
| `superwall.artifact.json` | Written by the first push: `artifact_id`, `organization_id` and `slug`, so commands know which artifact this is, plus `synced_commit` (where this copy last matched the artifact's source) and `reviewed_commit` (the newest teammates' commit `push` already asked you about), which stay out of the artifact's own source. Commit it, so teammates push to the same one. Never edit it. |
|
|
56
61
|
| `vendor/artifact-sdk` | Generated, never edited. `superwall artifacts update` refreshes it. There is no npm package. |
|
|
57
62
|
|
|
58
63
|
## A metric
|
|
@@ -134,7 +134,10 @@ and `diff`, and exits 1, so run that first and show the person the result.
|
|
|
134
134
|
With no entrypoint, lists what's installed. Otherwise installs it from the live version for the whole organization,
|
|
135
135
|
or one app with `--app`. `--disable` turns it off and keeps its row, `--remove` deletes the row and ends open
|
|
136
136
|
sessions (`--yes` without a terminal), and `--position` orders entrypoints in a slot. Every slot but `org.page@1`
|
|
137
|
-
shows only where it's installed and enabled.
|
|
137
|
+
shows only where it's installed and enabled, so a metric isn't in Charts until it's installed for that app.
|
|
138
|
+
`push` and `approve` print one line per entrypoint with no install yet, for example
|
|
139
|
+
`Charts won't show "Transactions" until you install it: superwall artifacts install transactions --app 42`
|
|
140
|
+
(`--app <app-id>` when the organization has more than one app), and list them as `not_installed` in `--json`.
|
|
138
141
|
|
|
139
142
|
## What errors mean
|
|
140
143
|
|
|
@@ -44,9 +44,32 @@ Entry points: `superwall` (SuperwallProvider — mounted for you),
|
|
|
44
44
|
`superwall/assets`.
|
|
45
45
|
|
|
46
46
|
The framework is in public beta. The CLI has `create`/`dev`/`push`/`promote`/`publish`
|
|
47
|
-
and the rebuild forms of `migrate` by default. `Unknown command
|
|
48
|
-
|
|
49
|
-
`superwall
|
|
47
|
+
and the rebuild forms of `migrate` by default. An `Unknown command` (such as
|
|
48
|
+
`Unknown command: create`, or `Unknown command: pull` before 2.3.0) means the
|
|
49
|
+
CLI that ran is older than that command; `superwall --version` shows which one
|
|
50
|
+
ran. Inside a project, the project's own `superwall` dependency is the CLI that
|
|
51
|
+
runs, whichever copy was started, and a newer CLI prints the command that
|
|
52
|
+
updates it on stderr, e.g. `cd superwall && npm i superwall@latest`. A missing
|
|
53
|
+
`pull` is never a reason to use `--overwrite-source`.
|
|
54
|
+
|
|
55
|
+
When a newer release is out, every command (`dev` at start, the rest at the
|
|
56
|
+
end) also prints an upgrade prompt on stderr, even under `--json`:
|
|
57
|
+
|
|
58
|
+
- `Update available 2.5.2 → 2.6.0 · run cd superwall && pnpm add superwall@latest`
|
|
59
|
+
is a patch or minor: tell the user in one line, run that command, then
|
|
60
|
+
carry on (or retry the command that failed).
|
|
61
|
+
- `Major update available 2.5.2 → 3.0.0`, followed by a release-notes link and
|
|
62
|
+
`Update: <command>`, is a major: tell the user, link the notes and ask
|
|
63
|
+
before running it, since a major can break paywalls. If they decline, keep
|
|
64
|
+
working on the pinned version.
|
|
65
|
+
|
|
66
|
+
Run the command exactly as printed: the project bump when the project pins
|
|
67
|
+
`superwall`, `superwall upgrade` when it doesn't. A beta pin follows npm's
|
|
68
|
+
`next` tag, so its command says `superwall@next`; never change it to
|
|
69
|
+
`@latest`. The older-pin notice above follows the same rule: run it when
|
|
70
|
+
only the minor or patch differs, ask first when the major does. The dev
|
|
71
|
+
studio shows the same update as a banner whose Copy prompt hands you these
|
|
72
|
+
steps.
|
|
50
73
|
|
|
51
74
|
## Local references — the agent playbooks
|
|
52
75
|
|
|
@@ -89,8 +112,8 @@ curl -sL https://superwall.com/docs/framework/{page}.md # one page
|
|
|
89
112
|
| `purchase()` outcomes, restore, the two channels | `purchases` |
|
|
90
113
|
| Introductory-offer eligibility forking (`useIntroductoryOffer`), reminder notifications | `trials` |
|
|
91
114
|
| Selling on the web — modes, prefetch, the Stripe sheet, hosted checkout, promotion codes (`useDiscount`), the shopper's email, after the purchase (`postPurchase`, `useCheckoutRedemption`), `stripeMetadata`, managed payments, blocking prepaid cards (`prepaidCards`), direct Apple Pay availability (`useApplePay`, `examples/apple-pay`); a Stripe product inside an iOS app (app to web: always hosted checkout, priced from the dashboard at push) | `web-checkout`, `products` |
|
|
92
|
-
| Custom store products (external purchase controller, custom-store Stripe products) — declared by identifier, pushed with the dashboard's store | `products` |
|
|
93
|
-
| Continuing a flow on the web (teleport: `teleport: true` or `{ route, fallbacks, completion, … }`, `router.push(route, { teleport: true })`, prefetch, the teleport screen, `useTeleport`'s typed status, returning to the app) | `teleport` |
|
|
115
|
+
| Custom store products (external purchase controller, custom-store Stripe products) — declared by identifier, pushed with the dashboard's store; on a hosted web paywall `purchase()` opens the store's checkout itself | `products`, `web-checkout` |
|
|
116
|
+
| Continuing a flow on the web (teleport: `teleport: true` or `{ route, fallbacks, completion, … }`, `router.push(route, { teleport: true })`, prefetch, the teleport screen, `useTeleport`'s typed status, returning to the app with `returnToApp({ data })` and its `"opened" \| "cancelled" \| "no_app"` result, the page's `failure` and `data` back in the app, `onReturnData`) | `teleport` |
|
|
94
117
|
| Web funnels — answers in the URL (`useQueryState`), resume after a browser hand-off, `shift` | `web-funnels` |
|
|
95
118
|
| Multi-page flows, router, cross-page state, shared chrome | `navigation` |
|
|
96
119
|
| Built-in + custom transitions, bottom sheets | `transitions` |
|
|
@@ -121,11 +144,23 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
121
144
|
2. **`purchase()` never throws for flow outcomes** — it resolves
|
|
122
145
|
`completed | abandoned | failed`. React to the awaited result; treat
|
|
123
146
|
abandoned as an outcome. Never put the buy button in a loading state.
|
|
124
|
-
|
|
125
|
-
|
|
147
|
+
A store purchase through the SDK resolves `failed` with
|
|
148
|
+
`reason: "unknown"` (or `"superseded"` when a newer purchase replaced it)
|
|
149
|
+
on iOS only: Android reports no purchase failures, so there a failed purchase stays pending until the user
|
|
126
150
|
abandons or completes. The paywall runs no timer of its own; design the
|
|
127
151
|
pending state to be survivable and never gate irreversible UI on
|
|
128
|
-
`failed` on Android.
|
|
152
|
+
`failed` on Android. On a hosted web paywall (`*.superwall.app`),
|
|
153
|
+
`purchase()` of a custom store product (`custom|…`) opens the store's
|
|
154
|
+
checkout itself in the same tab; never POST
|
|
155
|
+
`/v1/checkout/custom-store/session` yourself. It resolves `abandoned`
|
|
156
|
+
once the tab navigates (a second tap while the first is in flight also
|
|
157
|
+
resolves `abandoned` and opens nothing), and `failed` only when the
|
|
158
|
+
backend refuses the buyer's id (a placeholder such as `null`), no web
|
|
159
|
+
checkout is configured, or the network fails. A buyer without
|
|
160
|
+
`app_user_id` still gets the checkout as an anonymous buyer and a
|
|
161
|
+
redemption code after paying. Under the Web SDK custom store products
|
|
162
|
+
resolve `failed` as unsupported; inside an app they go to the SDK's
|
|
163
|
+
purchase. What happens *after* a completed purchase is
|
|
129
164
|
`postPurchase` in config (or per call): `"dismiss"` (default), `"stay"`
|
|
130
165
|
to keep the paywall up, and on the web `"redeem"` / `{ redirect }`;
|
|
131
166
|
`"stay"` on the web is finished with `useCheckoutRedemption()`. Pass
|
|
@@ -146,6 +181,64 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
146
181
|
// abandoned: the user closed the store sheet — nothing changes, nothing is said
|
|
147
182
|
```
|
|
148
183
|
|
|
184
|
+
**Why a payment failed.** A failed Stripe purchase resolves
|
|
185
|
+
`{ status: "failed", product, failure }`, and `usePurchase().failure`
|
|
186
|
+
holds the last failed purchase until the next one starts. `failure` is a
|
|
187
|
+
`CheckoutFailure`: `reason` in superwall's own words, `store: "stripe"`,
|
|
188
|
+
and Stripe's raw `code`, `declineCode` and `message` when Stripe gave
|
|
189
|
+
them. Branch on `reason`, never on Stripe's codes: the reasons stay the
|
|
190
|
+
same whichever store or payment method took the payment. `reason`
|
|
191
|
+
(`CheckoutFailureReason`) is one of:
|
|
192
|
+
|
|
193
|
+
| `reason` | Meaning |
|
|
194
|
+
| --- | --- |
|
|
195
|
+
| `card_declined` | the issuer declined and gave no more specific reason |
|
|
196
|
+
| `insufficient_funds` | not enough money or credit on the card |
|
|
197
|
+
| `expired_card` | the card has expired |
|
|
198
|
+
| `incorrect_card_details` | a wrong number, CVC, expiry, postal code or PIN |
|
|
199
|
+
| `authentication_failed` | 3D Secure or another bank check failed or was cancelled |
|
|
200
|
+
| `card_not_supported` | the card can't pay for this kind of purchase or in this currency |
|
|
201
|
+
| `limit_exceeded` | a spending, frequency or PIN-attempt limit was hit |
|
|
202
|
+
| `fraud_suspected` | the issuer or Stripe flagged it, or the card is lost or stolen |
|
|
203
|
+
| `processing_error` | the issuer or the network failed; trying again may work |
|
|
204
|
+
| `unknown` | nobody reported why, or the reason is one superwall doesn't know |
|
|
205
|
+
|
|
206
|
+
`unknown` means "no reason known": the purchase still failed, so never
|
|
207
|
+
read it as success and never guess a reason behind it. Give it the
|
|
208
|
+
generic copy. What each purchase path reports:
|
|
209
|
+
|
|
210
|
+
| Purchase | `failure.reason` |
|
|
211
|
+
| --- | --- |
|
|
212
|
+
| Stripe, direct Apple Pay on the web | the exact reason |
|
|
213
|
+
| Stripe, embedded sheet (`checkout: "sheet"`) | `unknown` until the subscriptions backend reports it; subscriptions may stay `unknown` |
|
|
214
|
+
| Stripe, hosted (redirect) checkout, every Stripe purchase in an iOS app | `unknown`; reasons aren't supported there |
|
|
215
|
+
| Stripe, teleport seen from the app | the page's exact reason when the page returned it, else as for its checkout |
|
|
216
|
+
| App Store or Play Store through the SDK | `reason: "unknown"` or `"superseded"` on the failure itself, no `failure` object; iOS only |
|
|
217
|
+
| Custom store (`custom|…`) | no reason, and no callbacks |
|
|
218
|
+
|
|
219
|
+
**Purchase callbacks.** Use superwall's callbacks, never Stripe's own
|
|
220
|
+
events: `usePurchase({ onStart, onSubmit, onComplete, onAbandon,
|
|
221
|
+
onFailure })` fires for every purchase on the paywall, whichever
|
|
222
|
+
component started it; `purchase(product, { onFailure, … })` takes the
|
|
223
|
+
same callbacks for that call only, beside the hook's. They fire on every
|
|
224
|
+
platform (native store purchases, the sheet, Apple Pay, hosted checkout,
|
|
225
|
+
teleport) except for custom store products. `onSubmit` is web checkout
|
|
226
|
+
only: the shopper submitted the sheet or authorized Apple Pay. The others
|
|
227
|
+
receive the product; `onFailure` receives the failed purchase, with
|
|
228
|
+
`reason` on it (and `store`, `code`, `declineCode`, `message` for a web
|
|
229
|
+
failure). In the embedded sheet `onFailure` fires on each decline while
|
|
230
|
+
the sheet stays open for another card, and `purchase()` resolves only
|
|
231
|
+
when the sheet is paid or closed:
|
|
232
|
+
|
|
233
|
+
```tsx
|
|
234
|
+
const { purchase, failure } = usePurchase({
|
|
235
|
+
onFailure: (failed) => track("payment_failed", { reason: failed.reason }),
|
|
236
|
+
});
|
|
237
|
+
const result = await purchase("annual");
|
|
238
|
+
if (result.status === "failed" && "failure" in result && result.failure)
|
|
239
|
+
setNotice(t(`failure.${result.failure.reason}`)); // one string per reason, unknown included
|
|
240
|
+
```
|
|
241
|
+
|
|
149
242
|
The embedded Stripe sheet waits 10 s after a tap for Stripe's checkout
|
|
150
243
|
to be ready. The wait only hides the spinner and resolves `failed`: Stripe
|
|
151
244
|
keeps loading, the buyer stays on the paywall, and the next tap opens the
|
|
@@ -328,7 +421,11 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
328
421
|
merchant's site vs Superwall's hosted web paywall page, the teleport
|
|
329
422
|
page, the studio) branches on `useDevice().host` — `"ios-sdk" |
|
|
330
423
|
"android-sdk" | "web-sdk" | "web-paywall" | "web-teleport" | "studio" |
|
|
331
|
-
"browser"`, never `undefined` — never on the URL or `window`.
|
|
424
|
+
"browser"`, never `undefined` — never on the URL or `window`. It is
|
|
425
|
+
reliable on web pages that carry a WebKit message handler: a hosted web
|
|
426
|
+
paywall reads `"web-paywall"` and the Web SDK `"web-sdk"`; only a real
|
|
427
|
+
iOS app reads `"ios-sdk"`. Never detect a hosted page yourself through
|
|
428
|
+
`window.webPaywallCtrl`, `client_surface` or `window.webkit`. UI that
|
|
332
429
|
depends on which browser shows the page (an "open in Safari" hint for a
|
|
333
430
|
funnel opened from an Instagram ad) branches on `useDevice().browser` —
|
|
334
431
|
`SuperwallBrowser | undefined`, known from the first render — never on
|
|
@@ -358,14 +455,83 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
358
455
|
`useTeleport().prefetch(route)` for a route only the router teleports).
|
|
359
456
|
The route opens on the web with every `useQueryState` value carried
|
|
360
457
|
along, and the app is credited when the shopper pays. Keep answers the
|
|
361
|
-
web half needs in `useQueryState`, not component state.
|
|
362
|
-
|
|
363
|
-
|
|
458
|
+
web half needs in `useQueryState`, not component state. The
|
|
459
|
+
`teleport.route` page is pre-rendered at `superwall push` per locale,
|
|
460
|
+
Stripe product (plus none) and trial, and the browser paints it before
|
|
461
|
+
any JS runs, so its first render draws only from the locale, the
|
|
462
|
+
products and prices, the trial and `useTeleport().productReference`.
|
|
463
|
+
Read `window`, dates, random values, dark mode and `useQueryState`
|
|
464
|
+
answers in an effect or below the first frame, never in that first
|
|
465
|
+
render, or the page redraws when it takes over. A pre-render warning in
|
|
466
|
+
`push` output means those pages render in the browser instead; fix what
|
|
467
|
+
it names. A custom teleport screen renders while
|
|
468
|
+
`useTeleport().status === "waiting"` and not `returned`, reopens with
|
|
469
|
+
`open()`, and buys the fallback with plain
|
|
364
470
|
`purchase()`; count cancels and returns with `useTeleport({ onCancel,
|
|
365
471
|
onReturn })`, never with your own timers (`onCancel` is the Cancel
|
|
366
472
|
button only; an unpaid return shows as `purchase()` resolving
|
|
367
|
-
`abandoned`).
|
|
368
|
-
`
|
|
473
|
+
`abandoned`). On the web half, go back to the app only with
|
|
474
|
+
`useTeleport().returnToApp()` (or `close()` / `router.back()` on the
|
|
475
|
+
first web route) — never `openDeepLink`, `openUrl` or a hand-built scheme
|
|
476
|
+
or universal link. The framework picks the link: the universal link
|
|
477
|
+
first, the URL scheme when iOS won't follow it, which is every return
|
|
478
|
+
nobody tapped, such as one after Apple Pay is closed. While iOS asks
|
|
479
|
+
"Open in…?" it dims the page and points at Open itself; draw nothing for
|
|
480
|
+
it. `returnToApp()` resolves `"opened" | "cancelled" | "no_app"`
|
|
481
|
+
(`"cancelled"`: the shopper tapped Cancel; `"no_app"`: nothing could open
|
|
482
|
+
the app), and `useTeleport().returning` is true meanwhile. On anything
|
|
483
|
+
but `"opened"` the shopper is still on the page: leave it as it is, ready
|
|
484
|
+
to buy again.
|
|
485
|
+
|
|
486
|
+
```tsx
|
|
487
|
+
const { returnToApp } = useTeleport();
|
|
488
|
+
const result = await purchase("web");
|
|
489
|
+
if (result.status === "completed") haptics.success();
|
|
490
|
+
else if (result.status === "failed") setNotice(t("purchase.failed")); // say so, keep the button
|
|
491
|
+
else {
|
|
492
|
+
// abandoned: the shopper closed the sheet without paying
|
|
493
|
+
const back = await returnToApp(); // "opened" | "cancelled" | "no_app"
|
|
494
|
+
if (back === "opened") return;
|
|
495
|
+
// "cancelled" or "no_app": still on this page — change nothing, the buy button stays
|
|
496
|
+
}
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
**Sending a failed payment back to the app.** After a decline on the
|
|
500
|
+
teleport page, `returnToApp()` leaves the app the page's `failure`
|
|
501
|
+
without being asked (its return link carries `reason=failed`), and
|
|
502
|
+
`returnToApp({ data })` adds your own plain JSON, at most 16 KB: over
|
|
503
|
+
that the page logs a warning and leaves only the failure. Put new
|
|
504
|
+
fields inside `data`; never encode them in the link. In the app,
|
|
505
|
+
`useTeleport()` shows them as `failure` and `data` while `status ===
|
|
506
|
+
"waiting"`, `onFailure` fires and `usePurchase().failure` is set;
|
|
507
|
+
`useTeleport({ onReturnData })` fires once the data is read. You never
|
|
508
|
+
pass the reason yourself. Nothing is left after a paid purchase (the
|
|
509
|
+
teleport is closed), and no SDK change is needed: the app reads them
|
|
510
|
+
from the teleport's session. Until the backend reports the sheet's
|
|
511
|
+
reason, a sheet decline reaches the app as `unknown`; Apple Pay's is
|
|
512
|
+
exact. Branch on `failure.reason` in the app as anywhere else:
|
|
513
|
+
|
|
514
|
+
```tsx
|
|
515
|
+
// teleport page: send a shopper short on funds back to the App Store plan
|
|
516
|
+
const teleport = useTeleport();
|
|
517
|
+
const { purchase } = usePurchase({
|
|
518
|
+
onFailure: (failure) => {
|
|
519
|
+
if (teleport.status !== "arrived") return;
|
|
520
|
+
const offer = failure.reason === "insufficient_funds" ? "app_store" : "retry";
|
|
521
|
+
void teleport.returnToApp({ data: { offer } });
|
|
522
|
+
},
|
|
523
|
+
});
|
|
524
|
+
|
|
525
|
+
// app route: offer another way to pay
|
|
526
|
+
const back = useTeleport({ onReturnData: (data) => console.info("back from the page", data) });
|
|
527
|
+
const failure = back.status === "waiting" ? back.failure : undefined;
|
|
528
|
+
if (failure?.reason === "insufficient_funds" || failure?.reason === "card_declined") {
|
|
529
|
+
// show a store product (purchase("annual")) or Apple Pay; `unknown` says only that it failed
|
|
530
|
+
}
|
|
531
|
+
```
|
|
532
|
+
|
|
533
|
+
Fetch `teleport`; the `teleport` example is the complete flow to start
|
|
534
|
+
from.
|
|
369
535
|
13. **Shipping includes the dashboard.** A push that fails on missing
|
|
370
536
|
products is not a blocker to report — create them with
|
|
371
537
|
`superwall products create` ([references/cli.md](references/cli.md)).
|
|
@@ -447,6 +613,13 @@ superwall push # sealed version, production untouched; diagnostics har
|
|
|
447
613
|
superwall promote # ship (or: superwall publish -m "why")
|
|
448
614
|
```
|
|
449
615
|
|
|
616
|
+
After a push, promote or publish, give the user the paywall's studio link:
|
|
617
|
+
`https://app.superwall.com/{orgId}/{applicationId}/paywalls/{paywallId}/studio`.
|
|
618
|
+
The app and paywall ids are in `superwall.lock`; `orgId` is
|
|
619
|
+
`organization_id` in `GET /v2/projects`. Never link a code-first paywall to
|
|
620
|
+
the legacy `superwall.com/editor` — it cannot open one. Every other
|
|
621
|
+
dashboard page is in the `superwall` skill's `references/dashboard-links.md`.
|
|
622
|
+
|
|
450
623
|
Before calling a paywall done, run the audit at the end of the
|
|
451
624
|
`mobile-design` skill (and the framework items in
|
|
452
625
|
[references/mobile-design.md](references/mobile-design.md)) and the matrix
|
|
@@ -465,6 +638,16 @@ it, so pass it only when the user says to. In an empty folder,
|
|
|
465
638
|
`superwall pull --app <id>` gets every paywall of an app without GitHub
|
|
466
639
|
([references/cli.md](references/cli.md)).
|
|
467
640
|
|
|
641
|
+
In a pnpm monorepo whose `pnpm-workspace.yaml` does not list `superwall`,
|
|
642
|
+
a bare `pnpm install` in `superwall/` installs the parent workspace, exits
|
|
643
|
+
0 and leaves `superwall/` empty; `superwall dev` then fails with
|
|
644
|
+
`No superwall framework found`. Install and re-install there with
|
|
645
|
+
`pnpm install --ignore-workspace` and commit `superwall/pnpm-lock.yaml`, or
|
|
646
|
+
add `superwall` to the workspace patterns to share the root lockfile.
|
|
647
|
+
Never take a clean `pnpm install` exit as proof: check that
|
|
648
|
+
`superwall/node_modules/superwall` exists. bun and npm are not affected
|
|
649
|
+
([references/cli.md](references/cli.md#installing-in-a-pnpm-monorepo)).
|
|
650
|
+
|
|
468
651
|
## Report what's broken
|
|
469
652
|
|
|
470
653
|
When you confirm the framework, the CLI or these docs don't behave as they
|
|
@@ -20,6 +20,15 @@ The scaffolded package scripts mirror these (`dev`, `push`, `promote`,
|
|
|
20
20
|
`SUPERWALL_API_KEY`, which is only ever the organization's secret key
|
|
21
21
|
(`sk_…`), never an app's public `pk_…` key. `dev` needs no login.
|
|
22
22
|
|
|
23
|
+
When a newer release is out, every command prints an upgrade prompt on
|
|
24
|
+
stderr, even under `--json`: at the end, or right after the intro for `dev`,
|
|
25
|
+
which never ends. A patch or minor reads `Update available 2.5.2 → 2.6.0 ·
|
|
26
|
+
run cd superwall && pnpm add superwall@latest`; a major is a
|
|
27
|
+
`Major update available 2.5.2 → 3.0.0` block with a release-notes link.
|
|
28
|
+
Run the printed command for a patch or minor; for a major, tell the user,
|
|
29
|
+
link the release notes and ask first. A beta project's command says
|
|
30
|
+
`superwall@next`; keep it. The full rule is near the top of SKILL.md.
|
|
31
|
+
|
|
23
32
|
## `superwall create`
|
|
24
33
|
|
|
25
34
|
Inside an app that already has a `superwall/` project (or inside the
|
|
@@ -33,7 +42,10 @@ Superwall app instead of detecting one from the SDK key or asking — the
|
|
|
33
42
|
dashboard's **Copy Prompt** button hands you this form, so use the id it
|
|
34
43
|
gives rather than picking; it fails if the id isn't in the account, and it
|
|
35
44
|
cannot be combined with `--no-connect`. `--yes` accepts the defaults,
|
|
36
|
-
`--no-install` skips dependencies
|
|
45
|
+
`--no-install` skips dependencies, and `--no-git` skips the git step:
|
|
46
|
+
outside a git repository `create` otherwise runs `git init` and commits
|
|
47
|
+
the scaffold along with everything else in the folder. Pass `--no-git`
|
|
48
|
+
whenever the user or the repository's rules forbid committing on your own.
|
|
37
49
|
|
|
38
50
|
`--from <paywall-id>` rebuilds a dashboard (visual editor) paywall as
|
|
39
51
|
code: it scaffolds `paywalls/<slug>/config.ts` from the paywall's
|
|
@@ -47,10 +59,49 @@ The rebuild itself is
|
|
|
47
59
|
[migrate-from-editor.md](migrate-from-editor.md). After the scaffold the
|
|
48
60
|
CLI asks whether to run the rebuild headless with the user's agent, copy
|
|
49
61
|
the prompt, or stop; `superwall migrate <paywall-id>` asks the same later
|
|
50
|
-
(and scaffolds first if needed), `--skill` prints the prompt.
|
|
62
|
+
(and scaffolds first if needed), `--skill` prints the prompt.
|
|
63
|
+
`superwall migrate <paywall-id> --dry-run` reads the paywall and its
|
|
64
|
+
served document, runs the same refusals, prints the `paywalls/<slug>` it
|
|
65
|
+
would create and the paywall and app ids it would save in `superwall.lock`,
|
|
66
|
+
and ends with "Dry run - no changes made." It writes no files and skips
|
|
67
|
+
the agent / copy / stop choice and the studio; it still needs a login, and
|
|
68
|
+
fails like the real run when the paywall has no served document. When *you*
|
|
51
69
|
are the agent driving it, read the playbook and do the inventory step with
|
|
52
70
|
the user rather than running the headless path.
|
|
53
71
|
|
|
72
|
+
### Installing in a pnpm monorepo
|
|
73
|
+
|
|
74
|
+
`superwall/` owns its own `package.json`, lockfile and `node_modules`. In a
|
|
75
|
+
pnpm monorepo whose `pnpm-workspace.yaml` patterns don't list `superwall`
|
|
76
|
+
(say `apps/*` and `packages/*`), a bare `pnpm install` inside `superwall/`
|
|
77
|
+
installs the parent workspace instead, exits 0, and leaves `superwall/`
|
|
78
|
+
without `node_modules`; `superwall dev` then fails with `No superwall
|
|
79
|
+
framework found`. bun and npm are not affected.
|
|
80
|
+
|
|
81
|
+
`create` checks that `superwall` resolves from `superwall/` after the
|
|
82
|
+
install instead of trusting the exit code. For pnpm it retries once with
|
|
83
|
+
`pnpm install --ignore-workspace` and says so:
|
|
84
|
+
``Dependencies installed with `pnpm install --ignore-workspace` — superwall/ is outside the pnpm workspace``.
|
|
85
|
+
If the framework still doesn't resolve, with any manager, it says
|
|
86
|
+
``` `<command>` finished, but superwall is still not installed for superwall/ — install it there before `superwall dev` ```
|
|
87
|
+
and keeps that command in the next steps. With `--no-install` under a
|
|
88
|
+
pnpm workspace, the next steps add
|
|
89
|
+
``Not listed in the pnpm workspace? Use `pnpm install --ignore-workspace` instead``.
|
|
90
|
+
|
|
91
|
+
Pick one setup and keep to it:
|
|
92
|
+
|
|
93
|
+
- **Standalone (what the CLI does):** install and re-install with
|
|
94
|
+
`pnpm install --ignore-workspace` inside `superwall/`, every time: a
|
|
95
|
+
later bare `pnpm install` there is again a silent no-op. It writes
|
|
96
|
+
`superwall/pnpm-lock.yaml`; commit it.
|
|
97
|
+
- **Workspace member:** add `superwall` to the patterns in
|
|
98
|
+
`pnpm-workspace.yaml`. A bare `pnpm install` then works and the project
|
|
99
|
+
shares the root lockfile. Don't run `--ignore-workspace` there: it
|
|
100
|
+
would give a member its own lockfile.
|
|
101
|
+
|
|
102
|
+
Never treat a clean `pnpm install` exit as proof: check that
|
|
103
|
+
`superwall/node_modules/superwall` exists before running `superwall dev`.
|
|
104
|
+
|
|
54
105
|
## `superwall migrate --screen <path>`
|
|
55
106
|
|
|
56
107
|
Rebuilds a native screen — SwiftUI or UIKit (`.swift`), Jetpack Compose or
|
|
@@ -61,7 +112,12 @@ hooks, the placement to register) and an `origins` entry in
|
|
|
61
112
|
`superwall.lock`, then offers the same agent / copy / stop choice. No
|
|
62
113
|
path: it lists likely screens in the app and asks. `--screenshot <file>`
|
|
63
114
|
saves the original for **Compare › Original**; with a booted iOS simulator
|
|
64
|
-
it offers to capture one. `--skill` prints the prompt.
|
|
115
|
+
it offers to capture one. `--skill` prints the prompt. `--dry-run` reads
|
|
116
|
+
the screen, runs the same refusals, prints the `paywalls/<slug>` it would
|
|
117
|
+
create and ends with "Dry run - no changes made." It writes no files and
|
|
118
|
+
skips the screenshot prompt, the agent / copy / stop choice and the
|
|
119
|
+
studio. When the screen is already scaffolded, either dry run says so and
|
|
120
|
+
stops. The rebuild and the
|
|
65
121
|
wiring are [migrate-from-native.md](migrate-from-native.md).
|
|
66
122
|
|
|
67
123
|
## `superwall dev`
|
|
@@ -90,7 +146,8 @@ Three consequences for you, not the user:
|
|
|
90
146
|
1290 x 2796 render, the App Store size Apple takes for a product page and
|
|
91
147
|
for subscription review attachments, so it uploads without resizing.
|
|
92
148
|
- **It previews; only chat edits.** The dashboard hosts the same studio for a
|
|
93
|
-
code-first paywall (its live snapshot plus every pushed version)
|
|
149
|
+
code-first paywall (its live snapshot plus every pushed version), at
|
|
150
|
+
`https://app.superwall.com/{orgId}/{applicationId}/paywalls/{paywallId}/studio`. Nothing
|
|
94
151
|
there is point-and-click editable, so never tell the user to drag a headless
|
|
95
152
|
paywall into shape — changes ship through `push`/`promote`/`publish`. Its
|
|
96
153
|
**Chat** panel is the one exception: it edits the source in a sandbox and
|
|
@@ -100,7 +157,9 @@ Three consequences for you, not the user:
|
|
|
100
157
|
preview is a `superwall build` snapshot taken when a turn ends, not a live
|
|
101
158
|
server. So edits may have arrived that a local checkout has never seen —
|
|
102
159
|
`main` carries the source commit of the last published version; run
|
|
103
|
-
`superwall pull` to bring them into the local project.
|
|
160
|
+
`superwall pull` to bring them into the local project. A chat's edits that
|
|
161
|
+
were never published stay on `studio/<paywallId>`, and `pull` doesn't bring
|
|
162
|
+
them in.
|
|
104
163
|
|
|
105
164
|
The mechanism behind both (the envelope, the `ping` reply, hosting a paywall
|
|
106
165
|
yourself) is `curl -sL superwall.com/docs/framework/host-protocol.md`.
|
|
@@ -394,6 +453,23 @@ Promote never rebuilds — it only moves the live pointer.
|
|
|
394
453
|
Push + promote in one step. Also warns about other paywalls that are
|
|
395
454
|
pushed-but-not-live, so nothing ships half-forgotten.
|
|
396
455
|
|
|
456
|
+
## The studio link after shipping
|
|
457
|
+
|
|
458
|
+
None of `push`, `promote` or `publish` prints a dashboard link, so end each
|
|
459
|
+
with the paywall's studio link yourself:
|
|
460
|
+
|
|
461
|
+
```
|
|
462
|
+
https://app.superwall.com/{orgId}/{applicationId}/paywalls/{paywallId}/studio
|
|
463
|
+
```
|
|
464
|
+
|
|
465
|
+
`applicationId` and `paywallId` are in `superwall.lock`
|
|
466
|
+
(`apps.<platform>`, `paywalls.<name>.<platform>.paywallId`); `orgId` is
|
|
467
|
+
`organization_id` of the project holding the app in `GET /v2/projects`.
|
|
468
|
+
On several platforms, give one link per platform. A paywall never pushed
|
|
469
|
+
has no studio page yet; the builder for a new one is
|
|
470
|
+
`…/paywalls/new/studio`. Never give a code-first paywall the legacy
|
|
471
|
+
`superwall.com/editor/#/…` link.
|
|
472
|
+
|
|
397
473
|
## `superwall pull`
|
|
398
474
|
|
|
399
475
|
Merges the app's source repo into this project: teammates' paywalls and
|
|
@@ -401,6 +477,16 @@ shared files, their `superwall.lock` bindings, and the sync point the next
|
|
|
401
477
|
push merges from. Run it inside a project; it pulls the repo of every app
|
|
402
478
|
`superwall.lock` binds (`--platform <p>` limits it to those platforms).
|
|
403
479
|
|
|
480
|
+
`pull` needs superwall 2.3.0 or later. Inside a project, the project's own
|
|
481
|
+
`superwall` dependency is the CLI that runs, whichever copy was started
|
|
482
|
+
(global, `npx superwall@…`), and `superwall --version` prints its version.
|
|
483
|
+
When that copy is older than the one started, the CLI says so on stderr
|
|
484
|
+
(`Running superwall 2.0.0 pinned by superwall/package.json, not 2.6.0.
|
|
485
|
+
Update it: cd superwall && npm i superwall@latest`). So `Unknown command:
|
|
486
|
+
pull` means the project pins a version older than 2.3.0: run the update
|
|
487
|
+
command it printed, then pull again. Never fall back to `--overwrite-source`
|
|
488
|
+
because `pull` is missing.
|
|
489
|
+
|
|
404
490
|
- **Local edits stay.** Uncommitted changes in the project are merged with
|
|
405
491
|
the repo's, and only the files that changed are written.
|
|
406
492
|
- **A conflict changes nothing.** If both sides changed a file (with no
|
|
@@ -423,7 +509,10 @@ clones the app's source into an empty `<dir>/superwall/` (default: the
|
|
|
423
509
|
current directory), with its `superwall.lock` bindings, `superwall.d.ts`
|
|
424
510
|
and sync point — the way to work on an app's paywalls without its codebase
|
|
425
511
|
or GitHub. It installs nothing; it prints the next step, `cd superwall &&
|
|
426
|
-
<manager> install && <dev
|
|
512
|
+
<manager> install && <dev>`; under a pnpm workspace it adds the
|
|
513
|
+
`Not listed in the pnpm workspace?` line, and when the workspace doesn't
|
|
514
|
+
list `superwall` that install must be `pnpm install --ignore-workspace`
|
|
515
|
+
([above](#installing-in-a-pnpm-monorepo)). It refuses a directory that is already a
|
|
427
516
|
superwall project (run `superwall pull` there instead) or one that already
|
|
428
517
|
has files, and an app with no code paywall or an empty source repo (start
|
|
429
518
|
one with `superwall create --app <id>`).
|
|
@@ -460,7 +549,8 @@ than listing none.
|
|
|
460
549
|
| --- | --- |
|
|
461
550
|
| `Not a superwall project` | Run inside the app (or `superwall/`); the project's `package.json` must depend on `superwall` |
|
|
462
551
|
| `…package.json is named "superwall"` | Rename the package — that name shadows the framework |
|
|
463
|
-
| `No superwall framework found` | `bun add superwall` (or npm) inside the project |
|
|
552
|
+
| `No superwall framework found` | `bun add superwall` (or npm) inside the project. In a pnpm monorepo the message adds `A pnpm workspace above … skips a project it does not list`: run `pnpm install --ignore-workspace` in `superwall/`, or add `superwall` to `pnpm-workspace.yaml` ([above](#installing-in-a-pnpm-monorepo)) |
|
|
553
|
+
| ``… finished, but superwall is still not installed for superwall/`` | The install exited 0 without installing the framework. Run the named command in `superwall/` and check `superwall/node_modules/superwall` exists ([above](#installing-in-a-pnpm-monorepo)) |
|
|
464
554
|
| `These N products do not exist on Superwall` | Create them with `superwall products create` (above) — don't just report it — or fix the identifiers in `config.ts` |
|
|
465
555
|
| `Superwall for Agents is in private beta and isn't enabled for this app yet` | Enabled per app on Superwall's side; contact support@superwall.com. Nothing in the CLI can set it |
|
|
466
556
|
| `You can open N projects - pass --app <id\|dashboard link> or --project <id>` | Add `--app <id\|dashboard link>` to the resource command |
|
|
@@ -473,6 +563,7 @@ than listing none.
|
|
|
473
563
|
| `paywall x has never been pushed` (promote) | Push first |
|
|
474
564
|
| `superwall publish requires git` | Install git — the source snapshot is part of every publish |
|
|
475
565
|
| `… version N has no source yet` (promote) | Run `superwall push` to finish that version's source, then promote |
|
|
566
|
+
| `Unknown command: pull` | The project's own `superwall` is older than 2.3.0 and is the CLI that runs (`superwall --version`). Run the update command it prints on stderr, e.g. `cd superwall && npm i superwall@latest`, then pull again ([above](#superwall-pull)) |
|
|
476
567
|
| `Someone else published changes to …` | Run `superwall pull`, then publish again; `--overwrite-source` (this paywall only) only on the user's say-so |
|
|
477
568
|
| `The source repo differs from this project in …` | Run `superwall pull`, then publish again; `--overwrite-source` (this paywall only) only on the user's say-so |
|
|
478
569
|
| `Your project and the source repo both changed …, so nothing was pulled` | Ask the user which copy wins; to take the repo's, copy their edits aside if wanted, then `superwall pull --theirs` |
|
|
@@ -55,12 +55,12 @@ number.
|
|
|
55
55
|
|
|
56
56
|
| Example | The one idea |
|
|
57
57
|
| --- | --- |
|
|
58
|
-
| `purchase-states` | The two channels: what your `purchase()` call resolves vs what the SDK reports on its own (restore arrives as `transaction_complete` with no purchase in sight) |
|
|
58
|
+
| `purchase-states` | The two channels: what your `purchase()` call resolves vs what the SDK reports on its own (restore arrives as `transaction_complete` with no purchase in sight); a failed purchase shows one string per `result.failure.reason` and `usePurchase({ onFailure })` logs each failure. Its `annual` is a store product, so in the studio it shows the generic notice; `apple-pay` sells Stripe test prices and logs `onFailure`, `onComplete` and `usePurchase().failure` for a real reason |
|
|
59
59
|
| `trial-eligibility` | Two paywalls in one, chosen by the store — every string forks and both states read as intentional |
|
|
60
60
|
| `abandonment-offer` | `purchase()` resolving `abandoned` is a signal only this paywall can act on — push a last-chance offer (a second product, not a second design) with a custom `sheet` transition |
|
|
61
61
|
| `trial-reminders` | A local notification declared in config, scheduled by the SDK when the trial starts — the paywall needn't be open when it fires |
|
|
62
62
|
| `web-funnel` | Selling on the web: steps as routes on `shift`, the answer kept in the URL with `useQueryState` (the rule for every web-funnel answer), then `checkout: "sheet"` — `purchase()` unchanged; `prefetch(reference)` on selection so the sheet opens instantly |
|
|
63
|
-
| `teleport` | Finishing an app flow on the web: `teleport: { route: "plan" }` makes `router.push("plan")` open the plan in the browser with the app's `useQueryState` answer carried along; `fallbacks: { monthly: "annual" }` offers the App Store plan on the teleport screen; the plan page reads `useTeleport().status === "arrived"` |
|
|
63
|
+
| `teleport` | Finishing an app flow on the web: `teleport: { route: "plan" }` makes `router.push("plan")` open the plan in the browser with the app's `useQueryState` answer carried along; `fallbacks: { monthly: "annual" }` offers the App Store plan on the teleport screen; the plan page reads `useTeleport().status === "arrived"`; its `onFailure` calls `returnToApp({ data: { offer, plan } })`, and back in the app the goal route reads `useTeleport().failure` and `.data` (with `onReturnData`) to offer the App Store plan to a shopper short on funds |
|
|
64
64
|
|
|
65
65
|
`purchase-states` is the only example showing the full haptic vocabulary
|
|
66
66
|
(`success()` / `error()` keyed to outcomes). `abandonment-offer` contains
|
|
@@ -19,6 +19,11 @@ screenshot, product table and an inventory, records the source in
|
|
|
19
19
|
`superwall.lock` under `origins`, and connects the project to the same
|
|
20
20
|
app. Read the brief first; every step below refers to it.
|
|
21
21
|
|
|
22
|
+
To preview first, run `superwall migrate <paywall-id> --dry-run`: it
|
|
23
|
+
needs a login, reads the paywall and its served document, prints the
|
|
24
|
+
`paywalls/<slug>` and `superwall.lock` entries it would write, and ends
|
|
25
|
+
with "Dry run - no changes made." without writing a file.
|
|
26
|
+
|
|
22
27
|
## What you are migrating from
|
|
23
28
|
|
|
24
29
|
The served document (the brief's "Served document" URL) is a rendered
|
|
@@ -13,6 +13,11 @@ superwall migrate --screen App/UpdateRequiredView.swift # in the app's root
|
|
|
13
13
|
superwall migrate --screen # scan for likely screens and pick
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
+
Add `--dry-run` to preview first: it reads the screen, prints the
|
|
17
|
+
`paywalls/<slug>` it would create and ends with "Dry run - no changes
|
|
18
|
+
made." without writing a file, prompting for a screenshot or starting the
|
|
19
|
+
agent or the studio.
|
|
20
|
+
|
|
16
21
|
The scan reads that one file — SwiftUI or UIKit (`.swift`), Jetpack Compose or
|
|
17
22
|
Android Views (`.kt`), React Native (`.tsx`), Flutter (`.dart`) — and writes into the project it finds (or a
|
|
18
23
|
new `superwall/`):
|