@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.
Files changed (39) hide show
  1. package/README.md +212 -19
  2. package/dist/{actions-MB-eBY64.js → actions-DYQTxMXS.js} +2 -2
  3. package/dist/{api-BF7-toqM.js → api-B2Zsf08U.js} +3 -3
  4. package/dist/{app-K6j9Es7h.js → app-rYAP19Jo.js} +6 -6
  5. package/dist/asa-DlM6dlPD.js +1194 -0
  6. package/dist/{asc-CArSwo5D.js → asc-D6qBCfuj.js} +4 -4
  7. package/dist/{auth-CY2cO_NF.js → auth-BEnVvJlK.js} +6 -6
  8. package/dist/{billing-DWyfEQ6l.js → billing-DO-gNWvW.js} +1 -1
  9. package/dist/{bind-hslFhcTR.js → bind-KZhPLTdC.js} +1 -1
  10. package/dist/{command-Kwx4ekbo.js → command-B12qooZb.js} +17 -13
  11. package/dist/{create-Bbi8BOO1.js → create-BTEvRC1X.js} +12 -12
  12. package/dist/{dev-D0lQDCQI.js → dev-CwfCGm36.js} +12 -12
  13. package/dist/{doctor-ByeRdMcl.js → doctor-DIxs8i8A.js} +7 -7
  14. package/dist/{drivers-DVAZgone.js → drivers-D6Ka26e2.js} +2 -2
  15. package/dist/entry.js +221 -25
  16. package/dist/{existing-CcJrIIAU.js → existing-CECenoHS.js} +2 -2
  17. package/dist/{feedback-Z0Wk7VC5.js → feedback-CV2coV73.js} +3 -3
  18. package/dist/{git-3OX9u3xE.js → git-CCJwXufi.js} +3 -3
  19. package/dist/{hosted-CHwaUqLd.js → hosted-BCwzTTEw.js} +1 -1
  20. package/dist/{integrate-DqOAqK7J.js → integrate-Bhq0wkU0.js} +16 -16
  21. package/dist/{login-Dr8UN_Gx.js → login-D5TjqsXJ.js} +1 -1
  22. package/dist/{migrate-D92bJTg6.js → migrate-Cz7VqQNj.js} +14 -14
  23. package/dist/{pipeline-CHHIg6BU.js → pipeline-ChRDxU9b.js} +4 -78
  24. package/dist/{print-skill-BnZAk7dV.js → print-skill-BPePCjy4.js} +5 -5
  25. package/dist/{promote-CRe9170G.js → promote-C54bfsg3.js} +12 -12
  26. package/dist/{publish-DsODvrOD.js → publish-NUNSIKri.js} +12 -12
  27. package/dist/{push-BDkZUC0v.js → push-BjEpY9-h.js} +12 -12
  28. package/dist/{query-DIllrSnk.js → query-CXjrBFow.js} +3 -3
  29. package/dist/{resource-CdP1MDla.js → resource-CM2bIB5v.js} +7 -7
  30. package/dist/{run-cGGBUMs5.js → run-CAIDPbwe.js} +2 -2
  31. package/dist/{scan-BQexuUPO.js → scan-BrikLKx5.js} +1 -1
  32. package/dist/{skills-xrfXt9u0.js → skills-BwXcAVIf.js} +1 -1
  33. package/dist/{skills-DhuUs28u.js → skills-_TULXe09.js} +4 -4
  34. package/dist/{telemetry-CcfrtXdf.js → telemetry-CpIXSAbQ.js} +1 -1
  35. package/dist/{update-BiVeR024.js → update-BdcpwRu_.js} +1 -1
  36. package/dist/{upgrade-DYWspApv.js → upgrade-BNPbzr5V.js} +3 -3
  37. package/package.json +2 -1
  38. /package/dist/{asc-products-YQ6Oc6YO.js → asc-products-C6MvSy8H.js} +0 -0
  39. /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">Superwall CLI</h1>
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
- Or run it without installing: `npx superwall`. The CLI ships inside the
23
- `superwall` package (the framework), which installs both the `superwall` and
24
- the short `sw` command. Upgrade any time with
25
- `superwall upgrade` - the CLI also tells you when a new version is out.
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. `push -m "why"` records a note in the source commit,
64
- and `promote --version <n>` points production at any pushed version, so a
65
- rollback is one command. A project can push to several platforms: each
66
- paywall's `config.ts` lists them (`platforms: ["ios", "android"]`; the lock
67
- binds one app per platform), and `--platform <p>` narrows `push`, `promote`,
68
- and `publish` to one of them. It asks for a starting point (`--example with-rive` to
69
- begin from any example in the public repo), then looks at the app around it:
70
- if the Superwall SDK is already configured, it finds your app by its API key
71
- and binds pushes to it; otherwise it can log you in, pick an app, or create
72
- one on the spot. `--yes` accepts the defaults; `--no-install` and
73
- `--no-connect` skip those steps.
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
- **Read [AGENTS.md](AGENTS.md) first** - command naming, UI rules, skill
189
- authoring, and the sync checklist are decided conventions, not suggestions.
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-CcfrtXdf.js";
2
- import { i as loadBundledSkill } from "./skills-xrfXt9u0.js";
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-CcfrtXdf.js";
1
+ import "./telemetry-CpIXSAbQ.js";
2
2
  import "./json-C3hPIMkI.js";
3
- import "./update-BiVeR024.js";
3
+ import "./update-BdcpwRu_.js";
4
4
  import "./token-DHRH8cxi.js";
5
- import { t as defineCommand } from "./command-Kwx4ekbo.js";
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-Kwx4ekbo.js";
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-Dr8UN_Gx.js";
5
- import { i as SUPPORTED_LABEL, t as scanProject } from "./scan-BQexuUPO.js";
6
- import { r as getHostedStatus } from "./hosted-CHwaUqLd.js";
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-hslFhcTR.js";
9
- import { t as ACTIONS } from "./actions-MB-eBY64.js";
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) {