@superwall/cli 1.1.0 → 1.2.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 +212 -19
- package/dist/{actions-MB-eBY64.js → actions-DYQTxMXS.js} +2 -2
- package/dist/{api-BF7-toqM.js → api-B2Zsf08U.js} +3 -3
- package/dist/{app-K6j9Es7h.js → app-rYAP19Jo.js} +6 -6
- package/dist/asa-DlM6dlPD.js +1194 -0
- package/dist/{asc-CArSwo5D.js → asc-D6qBCfuj.js} +4 -4
- package/dist/{auth-CY2cO_NF.js → auth-BEnVvJlK.js} +6 -6
- package/dist/{billing-DWyfEQ6l.js → billing-DO-gNWvW.js} +1 -1
- package/dist/{bind-hslFhcTR.js → bind-KZhPLTdC.js} +1 -1
- package/dist/{command-Kwx4ekbo.js → command-B12qooZb.js} +17 -13
- package/dist/{create-Bbi8BOO1.js → create-BTEvRC1X.js} +12 -12
- package/dist/{dev-D0lQDCQI.js → dev-CwfCGm36.js} +12 -12
- package/dist/{doctor-ByeRdMcl.js → doctor-DIxs8i8A.js} +7 -7
- package/dist/{drivers-DVAZgone.js → drivers-D6Ka26e2.js} +2 -2
- package/dist/entry.js +221 -25
- package/dist/{existing-CcJrIIAU.js → existing-CECenoHS.js} +2 -2
- package/dist/{feedback-Z0Wk7VC5.js → feedback-CV2coV73.js} +3 -3
- package/dist/{git-3OX9u3xE.js → git-CCJwXufi.js} +3 -3
- package/dist/{hosted-CHwaUqLd.js → hosted-BCwzTTEw.js} +1 -1
- package/dist/{integrate-DqOAqK7J.js → integrate-Bhq0wkU0.js} +16 -16
- package/dist/{login-Dr8UN_Gx.js → login-D5TjqsXJ.js} +1 -1
- package/dist/{migrate-D92bJTg6.js → migrate-Cz7VqQNj.js} +14 -14
- package/dist/{pipeline-CHHIg6BU.js → pipeline-ChRDxU9b.js} +4 -78
- package/dist/{print-skill-BnZAk7dV.js → print-skill-BPePCjy4.js} +5 -5
- package/dist/{promote-CRe9170G.js → promote-C54bfsg3.js} +12 -12
- package/dist/{publish-DsODvrOD.js → publish-NUNSIKri.js} +12 -12
- package/dist/{push-BDkZUC0v.js → push-BjEpY9-h.js} +12 -12
- package/dist/{query-DIllrSnk.js → query-CXjrBFow.js} +3 -3
- package/dist/{resource-CdP1MDla.js → resource-CM2bIB5v.js} +7 -7
- package/dist/{run-cGGBUMs5.js → run-CAIDPbwe.js} +2 -2
- package/dist/{scan-BQexuUPO.js → scan-BrikLKx5.js} +1 -1
- package/dist/{skills-xrfXt9u0.js → skills-BwXcAVIf.js} +1 -1
- package/dist/{skills-DhuUs28u.js → skills-_TULXe09.js} +4 -4
- package/dist/{telemetry-CcfrtXdf.js → telemetry-CpIXSAbQ.js} +1 -1
- package/dist/{update-BiVeR024.js → update-BdcpwRu_.js} +1 -1
- package/dist/{upgrade-DYWspApv.js → upgrade-BNPbzr5V.js} +3 -3
- package/package.json +2 -1
- /package/dist/{asc-products-YQ6Oc6YO.js → asc-products-C6MvSy8H.js} +0 -0
- /package/dist/{storekit-Ddvs4Ynw.js → storekit-DPonXSwe.js} +0 -0
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
</a>
|
|
5
5
|
</p>
|
|
6
6
|
|
|
7
|
-
<h1 align="center"
|
|
7
|
+
<h1 align="center">@superwall/cli</h1>
|
|
8
8
|
|
|
9
9
|
<p align="center">
|
|
10
10
|
Build paywalls and funnels as code, set up the SDK, manage products and
|
|
@@ -19,15 +19,18 @@ npm install --global superwall
|
|
|
19
19
|
superwall login
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
`superwall
|
|
22
|
+
This package is the engine behind the `superwall` command — every command
|
|
23
|
+
lives here — and the [`superwall`](https://www.npmjs.com/package/superwall)
|
|
24
|
+
package installs it for you, along with the framework and both the
|
|
25
|
+
`superwall` and the short `sw` binaries. Install `superwall`, not this
|
|
26
|
+
package; everything below is what you get.
|
|
26
27
|
|
|
27
28
|
`superwall login` opens your browser once and every command shares that
|
|
28
29
|
session. In CI, log in without a browser: `superwall login --api-key <key>`.
|
|
29
30
|
If your account belongs to more than one organization, pick one with
|
|
30
31
|
`superwall orgs use` (you'll otherwise be asked the first time it matters).
|
|
32
|
+
Upgrade any time with `superwall upgrade` - the CLI also tells you when a new
|
|
33
|
+
version is out.
|
|
31
34
|
|
|
32
35
|
## Set up your app
|
|
33
36
|
|
|
@@ -59,18 +62,141 @@ superwall promote # point production at a pushed version
|
|
|
59
62
|
superwall publish # push and promote in one step
|
|
60
63
|
```
|
|
61
64
|
|
|
65
|
+
Every paywall and web funnel is a mini React app: file-based routes, your
|
|
66
|
+
components, your design system, plain React state. The `superwall` package is
|
|
67
|
+
the framework too — `definePaywall`, the hooks, the typed router, web
|
|
68
|
+
checkout — and Superwall takes it from there: products and purchases,
|
|
69
|
+
localization, trials, experimentation, and delivery through the native SDKs
|
|
70
|
+
(iOS, Android, Flutter, React Native) and the web.
|
|
71
|
+
|
|
62
72
|
`create` sets up a `superwall/` directory in your app — always that name,
|
|
63
|
-
always self-contained.
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
73
|
+
always self-contained. It asks for a starting point (`--example with-rive`
|
|
74
|
+
to begin from any example in the
|
|
75
|
+
[public repo](https://github.com/superwall/superwall/tree/main/examples)),
|
|
76
|
+
then looks at the app around it: if the Superwall SDK is already configured,
|
|
77
|
+
it finds your app by its API key and binds pushes to it; otherwise it can log
|
|
78
|
+
you in, pick an app, or create one on the spot. `--yes` accepts the defaults;
|
|
79
|
+
`--no-install` and `--no-connect` skip those steps.
|
|
80
|
+
|
|
81
|
+
### A project is a directory
|
|
82
|
+
|
|
83
|
+
```
|
|
84
|
+
superwall/
|
|
85
|
+
├── package.json the project's own deps, and the project marker
|
|
86
|
+
├── superwall.lock app + paywall bindings, per platform (commit it)
|
|
87
|
+
├── components/ shared design system
|
|
88
|
+
├── messages/en.ts shared strings, inherited by every surface
|
|
89
|
+
├── assets/ shared images, video, and fonts
|
|
90
|
+
├── paywalls/
|
|
91
|
+
│ └── plus-upgrade/ each paywall is a mini React app
|
|
92
|
+
│ ├── config.ts required — name, products, platforms, settings
|
|
93
|
+
│ ├── app/ routes only — every .tsx here is a route
|
|
94
|
+
│ │ ├── layout.tsx optional — wraps every route
|
|
95
|
+
│ │ ├── index.tsx where the flow starts
|
|
96
|
+
│ │ ├── plans.tsx one file per route
|
|
97
|
+
│ │ └── goals/ directories prefix route names
|
|
98
|
+
│ │ └── setup.tsx "goals/setup"
|
|
99
|
+
│ ├── components/
|
|
100
|
+
│ └── messages/en.ts
|
|
101
|
+
└── funnels/
|
|
102
|
+
└── onboarding/ same shape — onboarding, web2app, win-back
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Identity is the path: `paywalls/plus-upgrade` **is** the paywall's ID. No name
|
|
106
|
+
fields, no registration, no build config — the tooling owns bundling.
|
|
107
|
+
`components/`, `messages/`, and `assets/` work at both levels: shared at the
|
|
108
|
+
`superwall/` root (`@/…` aliases it), local inside a surface.
|
|
109
|
+
|
|
110
|
+
### `config.ts`
|
|
111
|
+
|
|
112
|
+
```ts
|
|
113
|
+
import { definePaywall } from "superwall/config";
|
|
114
|
+
|
|
115
|
+
export default definePaywall({
|
|
116
|
+
name: "Plus — Annual, 3-day trial",
|
|
117
|
+
platforms: ["ios", "android"],
|
|
118
|
+
products: {
|
|
119
|
+
monthly: "pro_999_month",
|
|
120
|
+
annual: { ios: "pro_5999_year", android: "pro_5999_year_play" },
|
|
121
|
+
},
|
|
122
|
+
presentation: { style: "drawer", height: 70 },
|
|
123
|
+
featureGating: "gated",
|
|
124
|
+
});
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
`config.ts` is the whole truth for its paywall — there are no project-wide
|
|
128
|
+
defaults. `platforms` is a typed array of `ios | android | web`; the project
|
|
129
|
+
binds one Superwall app per platform, and a project on several platforms
|
|
130
|
+
never guesses which one a paywall means. `products` are slots by reference:
|
|
131
|
+
one store identifier, or one per platform when the store product differs —
|
|
132
|
+
`purchase("annual")` stays one call, and each platform's build carries only
|
|
133
|
+
its own ids. Product data (price, period, trial…) arrives from the SDK at
|
|
134
|
+
runtime and is never invented locally. Presentation style, feature gating,
|
|
135
|
+
caching, scrolling, game controller, introductory-offer eligibility,
|
|
136
|
+
background, and web checkout are all settings here too: pushed with the
|
|
137
|
+
version, stamped on promote, and an omitted key resets to its default. Share
|
|
138
|
+
settings by exporting a plain object and spreading it.
|
|
139
|
+
|
|
140
|
+
### Hooks
|
|
141
|
+
|
|
142
|
+
```tsx
|
|
143
|
+
import { useProducts, usePurchase, useTranslation } from "superwall/hooks";
|
|
144
|
+
|
|
145
|
+
export default function PlusUpgrade() {
|
|
146
|
+
const { getProduct } = useProducts();
|
|
147
|
+
const { purchase, isPurchasing } = usePurchase();
|
|
148
|
+
const { t } = useTranslation();
|
|
149
|
+
// your components, your design system — superwall is headless
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
One concern each: `useProducts`, `usePurchase` (resolves `completed |
|
|
154
|
+
abandoned | failed`, never throws for flow outcomes), `useActions`,
|
|
155
|
+
`useHaptics`, `useColorScheme`, `useTranslation`, `useTrialEligibility`,
|
|
156
|
+
`useDevice` / `useUser` / `useVariables`, `useLocalResource`,
|
|
157
|
+
`useSuperwallEvent`, `useGameController`.
|
|
158
|
+
|
|
159
|
+
### Navigation
|
|
160
|
+
|
|
161
|
+
```tsx
|
|
162
|
+
import { useRouter } from "superwall/navigation";
|
|
163
|
+
|
|
164
|
+
const router = useRouter();
|
|
165
|
+
router.push("goals/setup");
|
|
166
|
+
router.push("plans", { transition: "fade" });
|
|
167
|
+
router.back();
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
expo-router's API, method for method. Route names are generated into
|
|
171
|
+
`superwall.d.ts` on every `dev` and `push`, so a typo is a compile error.
|
|
172
|
+
Routes are names, not paths — the whole flow ships as one HTML file — and
|
|
173
|
+
`useQueryState` (nuqs's API) keeps web funnel state in the URL so hosted
|
|
174
|
+
checkout and in-app browsers hand a flow back where it left off.
|
|
175
|
+
|
|
176
|
+
### Dev — the studio
|
|
177
|
+
|
|
178
|
+
`superwall dev` discovers every surface and opens the studio: every paywall
|
|
179
|
+
and funnel as a live card, and an editor with a device-frame preview (nine
|
|
180
|
+
devices, iPhone SE to Desktop), light/dark, locale switching, and live
|
|
181
|
+
controls for the user, device, params, and product variables the SDK
|
|
182
|
+
reports. Previews run against a stand-in SDK host — purchases resolve, trials
|
|
183
|
+
start — while product data is read from Superwall, never invented. The same
|
|
184
|
+
build runs unchanged inside a real SDK webview.
|
|
185
|
+
|
|
186
|
+
### Push, promote, publish
|
|
187
|
+
|
|
188
|
+
Git semantics on purpose: **push saves, promote ships.** Every push builds
|
|
189
|
+
each paywall once per platform, uploads assets by content hash, and mints an
|
|
190
|
+
immutable version; nothing users see changes until `promote` repoints
|
|
191
|
+
production. `promote --version <n>` makes a rollback one command, `-m "why"`
|
|
192
|
+
records a note in the source commit that rides along with every version, and
|
|
193
|
+
`--platform <p>` narrows `push`, `promote`, and `publish` to one platform.
|
|
194
|
+
Renames are resolved, never guessed — interactively, or with
|
|
195
|
+
`push --rename old=new` in CI.
|
|
196
|
+
|
|
197
|
+
The full reference — assets, localization, trials, transitions, web
|
|
198
|
+
checkout, troubleshooting — lives at
|
|
199
|
+
[superwall.com/docs/framework](https://superwall.com/docs/framework).
|
|
74
200
|
|
|
75
201
|
## Manage your account
|
|
76
202
|
|
|
@@ -166,6 +292,37 @@ and the validation, an agent can build and manage your whole ASC catalog —
|
|
|
166
292
|
groups, subscriptions, prices, introductory offers — without ever memorizing the
|
|
167
293
|
API or eating a silent rejection.
|
|
168
294
|
|
|
295
|
+
## Apple Search Ads
|
|
296
|
+
|
|
297
|
+
The **entire** Apple Ads Campaign Management API (v5), proxied by Superwall —
|
|
298
|
+
no client secret, OAuth token, or org id to manage locally. It uses the
|
|
299
|
+
credentials you connect in the dashboard (app → Integrations → Apple Search
|
|
300
|
+
Ads → Advanced); the CLI finds the connected app on its own, or takes
|
|
301
|
+
`--app <id>`.
|
|
302
|
+
|
|
303
|
+
```bash
|
|
304
|
+
superwall asa campaigns list
|
|
305
|
+
superwall asa campaigns find --field status --op EQUALS --values ENABLED --all
|
|
306
|
+
superwall asa keywords create --campaign 123 --adgroup 456 \
|
|
307
|
+
--text "grammar checker" --match-type EXACT --bid 1.25
|
|
308
|
+
superwall asa reports campaigns --start 2025-01-01 --end 2025-01-31 --group-by countryOrRegion
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
Every resource follows the same shape — `asa <resource> <action> [id]`, scoped
|
|
312
|
+
with `--campaign` / `--adgroup` / `--adam-id` — and the catalog is the
|
|
313
|
+
documentation:
|
|
314
|
+
|
|
315
|
+
```bash
|
|
316
|
+
superwall asa docs # every endpoint, grouped
|
|
317
|
+
superwall asa docs keywords # one resource: usage, flags, Apple links
|
|
318
|
+
superwall asa docs campaigns create # Apple's own page: fields, enums, examples
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
Writes take typed flags (money flags pick up the account's currency),
|
|
322
|
+
`-d key=value` for any other field, or `--body` for the whole payload. Anything
|
|
323
|
+
not covered is `asa get|post|put|delete /path`, sent straight to Apple with
|
|
324
|
+
your access token and org context attached.
|
|
325
|
+
|
|
169
326
|
## For agents and scripts
|
|
170
327
|
|
|
171
328
|
Pass `--json` to any command: stable output shape, structured errors, never
|
|
@@ -175,7 +332,9 @@ prompts.
|
|
|
175
332
|
Logging in also installs the [Superwall agent skills](https://github.com/superwall/skills)
|
|
176
333
|
into your coding agent and keeps them updated. `superwall skills` reinstalls
|
|
177
334
|
them (or a subset) manually; `superwall skills -y` installs everything without
|
|
178
|
-
asking.
|
|
335
|
+
asking. The framework itself is built to be written by agents: a plain npm
|
|
336
|
+
project, file-based routes, ordinary React state — conventions an agent
|
|
337
|
+
already knows, so it gets a paywall right on the first try.
|
|
179
338
|
|
|
180
339
|
## Telemetry
|
|
181
340
|
|
|
@@ -183,10 +342,37 @@ The CLI sends fully anonymous usage events (which workflow ran and whether it
|
|
|
183
342
|
succeeded — never emails, IDs, file paths, SQL, prompts, or error messages).
|
|
184
343
|
Opt out with `SUPERWALL_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1`.
|
|
185
344
|
|
|
345
|
+
## Package layout
|
|
346
|
+
|
|
347
|
+
```
|
|
348
|
+
packages/cli/
|
|
349
|
+
├── bin.ts the entry the `superwall` launcher runs
|
|
350
|
+
├── src/
|
|
351
|
+
│ ├── cli.ts every command, flag, and help line (yargs)
|
|
352
|
+
│ ├── commands/
|
|
353
|
+
│ │ ├── account/ login, whoami, orgs, doctor, feedback, skills, upgrade
|
|
354
|
+
│ │ ├── resource/ apps, products, entitlements, campaigns, paywalls, bootstrap
|
|
355
|
+
│ │ ├── workflow/ integrate, migrate, review
|
|
356
|
+
│ │ ├── platform/ get/post/patch/delete, query, asc, asc keys
|
|
357
|
+
│ │ └── paywalls/ create, dev, push, promote, publish
|
|
358
|
+
│ ├── core/ api client, auth, project detection, paywall
|
|
359
|
+
│ │ binding + lock, agent runners, telemetry, skills sync
|
|
360
|
+
│ └── ui/ the renderer: human output, --json envelopes, prompts
|
|
361
|
+
├── skills/ the bundled playbooks integrate/migrate/review run
|
|
362
|
+
└── tests/ mirrors src/
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
The paywall commands load the framework's tooling contract
|
|
366
|
+
(`superwall/build`, `superwall/preview`, `superwall/discover`) dynamically
|
|
367
|
+
from the project's own install, so they always run against the framework
|
|
368
|
+
version in the project's lockfile.
|
|
369
|
+
|
|
186
370
|
## Develop
|
|
187
371
|
|
|
188
|
-
|
|
189
|
-
|
|
372
|
+
This package lives in the [`superwall/superwall`](https://github.com/superwall/superwall)
|
|
373
|
+
monorepo. **Read [AGENTS.md](https://github.com/superwall/superwall/blob/main/AGENTS.md)
|
|
374
|
+
first** - command naming, UI rules, skill authoring, and the sync checklist
|
|
375
|
+
are decided conventions, not suggestions.
|
|
190
376
|
|
|
191
377
|
```bash
|
|
192
378
|
bun install
|
|
@@ -199,3 +385,10 @@ bun run test
|
|
|
199
385
|
The global `superwall`/`sw` binaries are declared by the framework package:
|
|
200
386
|
`cd ../superwall && bun link` links them. They run this package's built
|
|
201
387
|
`dist/`, so rebuild after every change.
|
|
388
|
+
|
|
389
|
+
## License
|
|
390
|
+
|
|
391
|
+
[MIT](https://github.com/superwall/superwall/blob/main/packages/cli/LICENSE).
|
|
392
|
+
The framework it launches is licensed under the
|
|
393
|
+
[Functional Source License](https://github.com/superwall/superwall/blob/main/packages/superwall/LICENSE)
|
|
394
|
+
(FSL-1.1-ALv2).
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { T as Integration } from "./telemetry-
|
|
2
|
-
import { i as loadBundledSkill } from "./skills-
|
|
1
|
+
import { T as Integration } from "./telemetry-CpIXSAbQ.js";
|
|
2
|
+
import { i as loadBundledSkill } from "./skills-BwXcAVIf.js";
|
|
3
3
|
|
|
4
4
|
//#region src/core/agent/actions.ts
|
|
5
5
|
/** Skill reference file per framework, so an agent only sees its own platform's docs. */
|
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
import "./telemetry-
|
|
1
|
+
import "./telemetry-CpIXSAbQ.js";
|
|
2
2
|
import "./json-C3hPIMkI.js";
|
|
3
|
-
import "./update-
|
|
3
|
+
import "./update-BdcpwRu_.js";
|
|
4
4
|
import "./token-DHRH8cxi.js";
|
|
5
|
-
import { t as defineCommand } from "./command-
|
|
5
|
+
import { t as defineCommand } from "./command-B12qooZb.js";
|
|
6
6
|
import "./ui-C4ncRJqd.js";
|
|
7
7
|
import { C as rowName, h as listResource, m as listProjects, p as listOrganizations, w as titleCase, y as platformLabel } from "./resources-CVrWwA1K.js";
|
|
8
8
|
import { t as parseParams } from "./params-Bvq0iqQK.js";
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
import { i as loadSession, r as clearSession } from "./token-DHRH8cxi.js";
|
|
2
|
-
import { r as SuperwallApi } from "./command-
|
|
2
|
+
import { r as SuperwallApi } from "./command-B12qooZb.js";
|
|
3
3
|
import { n as ui } from "./ui-C4ncRJqd.js";
|
|
4
|
-
import { n as performLogin, r as onboardingHooks } from "./login-
|
|
5
|
-
import { i as SUPPORTED_LABEL, t as scanProject } from "./scan-
|
|
6
|
-
import { r as getHostedStatus } from "./hosted-
|
|
4
|
+
import { n as performLogin, r as onboardingHooks } from "./login-D5TjqsXJ.js";
|
|
5
|
+
import { i as SUPPORTED_LABEL, t as scanProject } from "./scan-BrikLKx5.js";
|
|
6
|
+
import { r as getHostedStatus } from "./hosted-BCwzTTEw.js";
|
|
7
7
|
import { t as withSpinner } from "./spinner-gOxIMz-V.js";
|
|
8
|
-
import { n as resolveAppBinding, r as resolveScopeFromKey, t as platformForIntegration } from "./bind-
|
|
9
|
-
import { t as ACTIONS } from "./actions-
|
|
8
|
+
import { n as resolveAppBinding, r as resolveScopeFromKey, t as platformForIntegration } from "./bind-KZhPLTdC.js";
|
|
9
|
+
import { t as ACTIONS } from "./actions-DYQTxMXS.js";
|
|
10
10
|
|
|
11
11
|
//#region src/commands/workflow/integrate/app.ts
|
|
12
12
|
async function performLoginWithUi(app, onProvisioned) {
|