@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,275 @@
1
+ # CLI Reference
2
+
3
+ Everything is available through the `superwall` CLI. Install it globally, then
4
+ use `superwall login` once for device-flow OAuth. The saved session lives in
5
+ `~/.superwall`.
6
+
7
+ ```bash
8
+ npm install --global superwall
9
+ superwall login # device-flow OAuth (opens browser); acts as you
10
+ superwall login --api-key <key> # headless, for CI - a dashboard org key, à la STRIPE_API_KEY
11
+ superwall whoami --json # show the logged-in account / org
12
+ superwall logout --json
13
+ ```
14
+
15
+ Add `--help` / `-h` to any command for its flags.
16
+
17
+ ## Data hierarchy
18
+
19
+ Organization → Projects → Applications. Each application has a `platform` (ios,
20
+ android, flutter, react_native, web), a `bundle_id`, and a `public_api_key`
21
+ (the `pk_…` key used for SDK initialization - distinct from the OAuth session
22
+ used for CLI/REST calls). Projects own products + entitlements; applications own
23
+ campaigns + paywalls.
24
+
25
+ ## Scoping
26
+
27
+ Commands auto-scope only when exactly one project/app exists. With several, rich
28
+ interactive mode prompts; JSON and noninteractive modes require explicit scope:
29
+
30
+ - `--project <id>` - scope to a project.
31
+ - `--app <id|name>` - scope to an application. `superwall apps use <id|name>` sets
32
+ the rich UI's default, but automation still passes scope explicitly.
33
+
34
+ **Everything is org-scoped.** The session pins one active organization, and every
35
+ command runs against it: resource listings and creates, `query` (that org's
36
+ ClickHouse data), the `asc` proxy (that org's App Store Connect key vault), and
37
+ the `asa` proxy (that org's apps' Apple Search Ads credentials).
38
+ Single-org accounts resolve it automatically and never think about it. Multi-org
39
+ accounts are prompted once in rich mode; automation runs
40
+ `superwall orgs use <id|name>` once to persist the choice. The switch is global
41
+ and sticky (stored in the session) - to work in another org, switch, run the
42
+ commands, and switch back. `superwall whoami --json` shows the active org.
43
+
44
+ **Agent contract:** always pass `--json` to resource, ASC, ASA, raw API, query,
45
+ `bootstrap`, `whoami`, and `doctor` commands. JSON is the stable machine contract,
46
+ uses two-space indentation, never prompts, and returns errors as `{ "error": {
47
+ "code", "message", "status"? } }`. `--dry-run` plans a create without writing.
48
+
49
+ ## Resources
50
+
51
+ ```bash
52
+ superwall orgs list --json
53
+ superwall orgs use <id|name> # persist the org for org-scoped commands (multi-org accounts)
54
+ superwall apps list --json
55
+ superwall products list --project <id> --json
56
+ superwall entitlements list --project <id> --json
57
+ superwall campaigns list --project <id> --app <id> --json
58
+ superwall paywalls list --project <id> --app <id> --json
59
+ ```
60
+
61
+ `apps list` nests apps under their projects - there is no separate projects
62
+ command; `--project <id>` is how you scope when it matters.
63
+
64
+ ### Create
65
+
66
+ ```bash
67
+ # Apps: an app is a platform of a project. Without --project a new project is spun
68
+ # up for it; each project allows one app per platform.
69
+ superwall apps create "My App" --platform ios [--bundle com.acme.app] [--project <projectId>] --json
70
+
71
+ # Entitlements
72
+ superwall entitlements create pro --project <id> --json
73
+
74
+ # Products (identifier is required; the rest is a full definition, mainly for agents)
75
+ superwall products create com.acme.pro.monthly \
76
+ --name "Pro Monthly" \
77
+ --price 9.99 --currency USD \
78
+ --period month --period-count 1 \
79
+ --trial-days 7 \
80
+ --entitlement pro \
81
+ --project <id> --json # repeatable: grant multiple entitlements
82
+
83
+ # Campaigns (the create arg is a description)
84
+ superwall campaigns create "Onboarding paywall" onboarding_complete --project <id> --app <id> --json
85
+
86
+ # Placements: attach a placement (event name) to a campaign
87
+ superwall campaigns placement <campaignId> onboarding_complete --project <id> --app <id> --json
88
+ ```
89
+
90
+ Projects aren't created directly - add the first platform with `apps create` and
91
+ a project is created for you.
92
+
93
+ ### StoreKit config
94
+
95
+ ```bash
96
+ superwall products storekit --project <id> [--out Superwall.storekit] --json
97
+ ```
98
+
99
+ ## App Store Connect
100
+
101
+ Superwall proxies the App Store Connect API with a signed request - no `.p8`
102
+ file or JWT to manage locally. First connect ASC credentials (uploaded to
103
+ Superwall's vault, nothing sensitive stored locally):
104
+
105
+ ```bash
106
+ superwall asc keys set --key-id <id> --issuer <id> --key-file ./AuthKey.p8 [--name "My Team"] --json
107
+ superwall asc keys list --json
108
+ superwall asc keys rm <team_id> --json
109
+ ```
110
+
111
+ Then call ASC through the proxy:
112
+
113
+ ```bash
114
+ # Shortcuts
115
+ superwall asc apps --json
116
+ superwall asc products <bundle-id | asc-app-id> --json
117
+ superwall asc subscriptions com.acme.app --json
118
+
119
+ # Raw API - a verb + path, or just a path (defaults to GET)
120
+ superwall asc get /v1/apps --json
121
+ superwall asc /v1/apps --json
122
+ superwall asc post /v1/... -d key=value -d count:=3 --json
123
+
124
+ # Multiple connected teams
125
+ superwall asc apps --team <teamId> --json
126
+ ```
127
+
128
+ ### Request schema & docs — do this before every write
129
+
130
+ The proxy is schema-aware, backed by Apple's own OpenAPI spec. **Before any
131
+ `post`/`patch`, look up the exact schema — never guess a body:**
132
+
133
+ ```bash
134
+ superwall asc docs # catalog: every resource root
135
+ superwall asc docs "introductory offer" # find endpoints by keyword
136
+ superwall asc docs /v1/subscriptions post # required fields, enums, relationships, example
137
+ ```
138
+
139
+ Pass flat `-d` params — the proxy builds the JSON:API envelope for you
140
+ (`data.type`, `attributes`, `relationships`) and casts values by declared type:
141
+
142
+ ```bash
143
+ superwall asc post /v1/subscriptions -d name=Pro -d productId=com.acme.pro -d group=<subscriptionGroups id> --json
144
+ ```
145
+
146
+ A malformed body is rejected locally with the exact fix (missing required field,
147
+ invalid enum value) before it ever reaches Apple's opaque errors. Pass `--force`
148
+ to skip validation and send as-is.
149
+
150
+ For end-to-end recipes (creating a subscription with prices and offers) and the
151
+ full workflow, see the [App Store Connect reference](asc.md).
152
+
153
+ ## Apple Search Ads
154
+
155
+ Superwall proxies the Apple Ads Campaign Management API v5 with the credentials
156
+ connected in the dashboard (app → Integrations → Apple Search Ads → Advanced).
157
+ Nothing is stored locally; the CLI picks the connected iOS app itself, or takes
158
+ `--app <id>`:
159
+
160
+ ```bash
161
+ superwall asa keys list --json # which apps are connected
162
+
163
+ # Resources: asa <resource> <action> [id], scoped with --campaign / --adgroup / --adam-id
164
+ superwall asa campaigns list --json
165
+ superwall asa campaigns get <id> --json
166
+ superwall asa campaigns find --field status --op EQUALS --values ENABLED --all --json
167
+ superwall asa adgroups list --campaign <id> --json
168
+ superwall asa keywords list --campaign <id> --adgroup <id> --all --json
169
+ superwall asa reports campaigns --start 2025-01-01 --end 2025-01-31 --json
170
+
171
+ # Raw API - a verb + path, or just a path (defaults to GET); /api/v5 is implied
172
+ superwall asa get /campaigns --json
173
+ superwall asa /campaigns --json
174
+ superwall asa post /campaigns/find --body '{"conditions":[]}' --json
175
+
176
+ # Several Apple Search Ads orgs behind one API user
177
+ superwall asa campaigns list --org-id <appleOrgId> --json
178
+ ```
179
+
180
+ ### Request schema & docs — do this before every write
181
+
182
+ ```bash
183
+ superwall asa docs # catalog: every endpoint, grouped
184
+ superwall asa docs keywords # one resource: usage, flags, Apple links
185
+ superwall asa docs campaigns create # Apple's own page: fields, enums, examples
186
+ ```
187
+
188
+ Writes take typed flags (money flags resolve the account's currency from
189
+ `/acls`, or pass `--currency`), `-d key=value` / `key:=json` for any other
190
+ field, or `--body <json|@file|@->` for the whole payload:
191
+
192
+ ```bash
193
+ superwall asa campaigns create --name "Launch" --adam-id <adamId> --countries US,CA \
194
+ --daily-budget 50 --supply-sources APPSTORE_SEARCH_RESULTS --ad-channel-type SEARCH --json
195
+ superwall asa keywords update <id> --campaign <id> --adgroup <id> --bid 2 --json
196
+ superwall asa keywords delete <id,id,id> --campaign <id> --adgroup <id> --json
197
+ ```
198
+
199
+ Apple's validation errors come back as `Apple Search Ads rejected …` with each
200
+ field and message code. For the full resource list and recipes, see the
201
+ [Apple Search Ads reference](asa.md).
202
+
203
+ ## Raw API access - any endpoint
204
+
205
+ `bootstrap` prints the account overview; the verb commands hit any V2 endpoint
206
+ with the CLI's session auth (like `stripe get /v1/...`):
207
+
208
+ ```bash
209
+ superwall bootstrap --json # complete account tree
210
+
211
+ superwall get /v2/products -d project_id=25607 --json
212
+ superwall get /v2/campaigns -d project_id=25607 -d limit=10 --json
213
+ superwall post /v2/entitlements -d project_id=25607 -d identifier=pro --json
214
+ superwall patch /v2/projects/25607 -d name=Renamed --json
215
+ superwall delete /v2/... --json # careful
216
+
217
+ # -d key=value sends a string; key:=value sends typed JSON; nesting via key[sub]
218
+ superwall post /v2/products -d 'price[amount]:=4999' -d 'price[currency]=USD' --json
219
+ ```
220
+
221
+ Raw paths need explicit scope params (`project_id`, ...) - the nicely-named
222
+ resource commands above resolve scope for you; the verbs do not.
223
+
224
+ ## Data query - ClickHouse SQL
225
+
226
+ `query` runs read-only SQL against the logged-in organization's ClickHouse
227
+ analytics data. Use it for analysis, custom dashboards, scheduled reports, and
228
+ agent workflows. Prefer `--json` when another tool or agent will consume the
229
+ result; it returns ClickHouse's native JSON envelope (`meta`, `data`, `rows`, and
230
+ statistics).
231
+
232
+ ```bash
233
+ superwall query "SELECT applicationId, name FROM sw.applications_rep FINAL LIMIT 20" --json
234
+ superwall query "SELECT count() AS active FROM sw.subscription_status_rep FINAL WHERE applicationId = 123 AND isSandbox = 0" --json
235
+ superwall query --file daily-report.sql --json
236
+ printf 'SHOW TABLES FROM sw' | superwall query --json
237
+ ```
238
+
239
+ Pass SQL in exactly one place: as a quoted argument, with `--file <query.sql>`,
240
+ or on stdin. With `--json`, omit the SQL `FORMAT` clause because the CLI requests
241
+ ClickHouse JSON. Without `--json`, any explicit ClickHouse `FORMAT` clause is
242
+ preserved.
243
+
244
+ The CLI supplies the current organization ID and authenticated session. The
245
+ credential must have `data:read` access. See `data-analytics.md` for exposed
246
+ tables, query patterns, and performance guardrails.
247
+
248
+ ## Utilities
249
+
250
+ ```bash
251
+ superwall doctor --json # health-check the integration
252
+ superwall skills # install the Superwall agent skills into your agent
253
+ superwall upgrade # update the CLI to the latest version
254
+ superwall feedback "..." # send feedback about the CLI to the Superwall team
255
+ ```
256
+
257
+ ## Agent workflows
258
+
259
+ ```bash
260
+ superwall integrate # first-time SDK + dashboard setup
261
+ superwall migrate # move from RevenueCat / Adapty / Qonversion
262
+ superwall review # audit an existing setup end to end
263
+ superwall review --fix # apply verified, safe findings from the review
264
+ superwall <workflow> --skill # print the project-specific playbook for an agent
265
+ ```
266
+
267
+ `review` covers SDK configuration, purchase/subscription ownership, identity,
268
+ deep links, conditional Web Checkout readiness, placements, products,
269
+ entitlements, campaigns, paywalls, and analytics. It is not a placement-only
270
+ inventory. Agents should use `--skill` and follow the playbook themselves rather
271
+ than spawning a nested agent.
272
+
273
+ Responses are cursor-paginated: pass `limit` (1-100), `starting_after`, or
274
+ `ending_before` as query params and follow `has_more`. Prefer a CLI command
275
+ whenever one exists - reach for curl only for genuinely uncovered routes.
@@ -0,0 +1,160 @@
1
+ # Apple Search Ads — the full Apple Ads API via Superwall's proxy
2
+
3
+ `superwall asa` proxies the **entire** Apple Ads Campaign Management API v5
4
+ (`api.searchads.apple.com/api/v5`). Superwall holds the credentials connected
5
+ in the dashboard, mints the client secret, exchanges it for an access token,
6
+ and adds the `X-AP-Context` org header — nothing to manage locally. This lets
7
+ an agent read and manage campaigns, ad groups, keywords, ads, creatives, and
8
+ reports directly.
9
+
10
+ ## Which app
11
+
12
+ Credentials are per Superwall app (iOS). The CLI picks the one connected app
13
+ itself; with several connected, pass `--app <id|name>`.
14
+
15
+ ```bash
16
+ superwall asa keys list --json # every iOS app + whether Apple Search Ads is connected
17
+ ```
18
+
19
+ Not connected → the dashboard does it: open the app → Integrations → Apple
20
+ Search Ads → Advanced, paste Superwall's public key into Apple's Account
21
+ Settings → API, then enter the Client ID, Team ID and Key ID. `asa keys set`
22
+ is deliberately not a CLI command (Superwall generates the key pair).
23
+
24
+ If the Apple API user can reach several Apple Search Ads orgs, pass
25
+ `--org-id <appleOrgId>` (`superwall asa acls --json` lists them); otherwise the
26
+ proxy uses the API user's parent org.
27
+
28
+ ## Docs access — do this before every write
29
+
30
+ Never guess a request body. `asa docs` is the catalog, and for a specific
31
+ command it fetches Apple's own page live (fields, required flags, enums,
32
+ examples):
33
+
34
+ ```bash
35
+ superwall asa docs # every endpoint, grouped by resource
36
+ superwall asa docs keywords # one resource: usage, flags → Apple field names, links
37
+ superwall asa docs campaigns create # Apple's page for that call, plus the body object's fields
38
+ superwall asa docs "impression" # search by keyword
39
+ ```
40
+
41
+ ## Command shape
42
+
43
+ ```
44
+ superwall asa <resource> <action> [id] [--campaign <id>] [--adgroup <id>] [--adam-id <id>] --json
45
+ ```
46
+
47
+ | Resource | Actions |
48
+ |---|---|
49
+ | `campaigns` | `list`, `get <id>`, `find`, `create`, `update <id>`, `delete <id>` |
50
+ | `adgroups` | same, scoped with `--campaign` (`find` without `--campaign` searches the whole org) |
51
+ | `keywords` | `list`, `get`, `find` (`--campaign`, optional `--adgroup`), `create`, `update [id]`, `delete <id[,id…]>` |
52
+ | `negative-keywords` | same; `--adgroup` switches from campaign-level to ad-group-level; `find --adgroup-level` |
53
+ | `ads` | `list`, `get`, `find`, `create`, `update`, `delete` (`--campaign --adgroup`; `find` scopes down to org level) |
54
+ | `creatives` | `list`, `get`, `find`, `create` |
55
+ | `product-pages` | `list --adam-id`, `get <id> --adam-id`, `locales <id> --adam-id`, `countries`, `device-sizes` |
56
+ | `ad-rejections` | `find`, `get <id>`, `assets --adam-id` |
57
+ | `reports` | `campaigns`, `adgroups`, `keywords`, `searchterms`, `ads` (`--start --end`, `--campaign`, optional `--adgroup`) |
58
+ | `impression-share` | `list`, `get <id>`, `create` |
59
+ | `apps` | `search <query>`, `eligibility <adam-id>`, `get <adam-id>`, `localized <adam-id>` |
60
+ | `geo` | `search <query>`, `get <id> --entity <Country\|AdminArea\|Locality>` |
61
+ | `budget-orders` | `list`, `get <id>`, `create --body`, `update <id> --body` |
62
+ | `acls`, `me` | the API user's orgs and identity |
63
+
64
+ Raw escape hatch for anything else: `superwall asa get|post|put|delete /path
65
+ [-d k=v] [--body json]`, or `superwall asa /path` (GET). `/api/v5` is implied.
66
+
67
+ ## Reading
68
+
69
+ ```bash
70
+ superwall asa campaigns list --limit 50 --json
71
+ superwall asa campaigns list --all --json # walks every page
72
+ superwall asa campaigns find --field status --op EQUALS --values ENABLED --json
73
+ superwall asa campaigns find --selector '{"conditions":[{"field":"name","operator":"STARTSWITH","values":["US"]}],"orderBy":[{"field":"name","sortOrder":"ASCENDING"}]}' --all --json
74
+ superwall asa campaigns get <id> --fields id,name,status --json
75
+ superwall asa keywords find --campaign <id> --field matchType --op EQUALS --values EXACT --all --json
76
+ ```
77
+
78
+ `find` takes Apple's selector: `--selector <json|@file|@->` for the whole
79
+ thing, or the one-condition shorthand `--field/--op/--values` plus
80
+ `--order-by field[:asc|desc]`, `--fields`, `--limit`, `--offset`. `--all` pages
81
+ until Apple's `totalResults` is reached; the output is `{ data: [...],
82
+ pagination }` like a single page.
83
+
84
+ ## Writing
85
+
86
+ Typed flags map to Apple's field names (`asa docs <resource>` shows the
87
+ mapping). Money flags (`--budget`, `--daily-budget`, `--bid`, `--default-bid`,
88
+ `--cpa-goal`) become `{ amount, currency }`; the currency comes from
89
+ `--currency` or the account's `/acls` entry. Anything else goes through
90
+ `-d key=value` (`key:=value` for numbers/booleans/JSON, `key[sub]` nesting) or
91
+ `--body`.
92
+
93
+ ```bash
94
+ # Campaign (Apple requires supplySources and adChannelType alongside the budget)
95
+ superwall asa campaigns create --name "Launch" --adam-id <adamId> --countries US,CA \
96
+ --daily-budget 50 --supply-sources APPSTORE_SEARCH_RESULTS --ad-channel-type SEARCH \
97
+ --billing-event TAPS --json
98
+
99
+ # Pause it
100
+ superwall asa campaigns update <id> --status PAUSED --json
101
+
102
+ # Ad group
103
+ superwall asa adgroups create --campaign <id> --name "Exact match" --default-bid 1.50 \
104
+ --start 2025-06-01T00:00:00.000 --search-match=false --json
105
+
106
+ # Keywords are bulk: one from flags, or many from --body
107
+ superwall asa keywords create --campaign <id> --adgroup <id> --text "grammar checker" --match-type EXACT --bid 1.25 --json
108
+ superwall asa keywords create --campaign <id> --adgroup <id> \
109
+ --body '[{"text":"grammar","matchType":"BROAD","bidAmount":{"amount":"1","currency":"USD"}},{"text":"spell check","matchType":"EXACT"}]' --json
110
+ superwall asa keywords update <id> --campaign <id> --adgroup <id> --bid 2 --json
111
+ superwall asa keywords delete <id> --campaign <id> --adgroup <id> --json # one → DELETE
112
+ superwall asa keywords delete <id,id,id> --campaign <id> --adgroup <id> --json # several → bulk
113
+
114
+ # Negative keywords: campaign level, or ad group level with --adgroup
115
+ superwall asa negative-keywords create --campaign <id> --text free --match-type BROAD --json
116
+ superwall asa negative-keywords create --campaign <id> --adgroup <id> --text free --json
117
+
118
+ # Creative + ad (custom product page)
119
+ superwall asa creatives create --adam-id <adamId> --type CUSTOM_PRODUCT_PAGE --product-page-id <ppId> --name "Holiday" --json
120
+ superwall asa ads create --campaign <id> --adgroup <id> --creative-id <creativeId> --name "Holiday ad" --json
121
+ ```
122
+
123
+ Apple's validation failures come back as
124
+ `Apple Search Ads rejected asa campaigns create (400): • field: message (CODE)`.
125
+ Read the field, fix the flag, retry.
126
+
127
+ ## Reports
128
+
129
+ ```bash
130
+ superwall asa reports campaigns --start 2025-01-01 --end 2025-01-31 --json
131
+ superwall asa reports campaigns --start 2025-01-01 --end 2025-01-31 --granularity WEEKLY --group-by countryOrRegion --json
132
+ superwall asa reports adgroups --campaign <id> --start 2025-01-01 --end 2025-01-31 --json
133
+ superwall asa reports keywords --campaign <id> [--adgroup <id>] --start 2025-01-01 --end 2025-01-31 --json
134
+ superwall asa reports searchterms --campaign <id> --start 2025-01-01 --end 2025-01-31 --json
135
+ superwall asa reports ads --campaign <id> --start 2025-01-01 --end 2025-01-31 --json
136
+ ```
137
+
138
+ Defaults: `DAILY` granularity (search terms: none, since Apple allows row
139
+ totals or granularity but not both), rows sorted by `localSpend` descending,
140
+ `timeZone` UTC. `--selector` replaces the sort/filter; `--time-zone ORTZ` uses
141
+ the org's time zone. Impression share is asynchronous:
142
+
143
+ ```bash
144
+ superwall asa impression-share create --name weekly --start 2025-01-01 --end 2025-01-07 \
145
+ --granularity DAILY --dimensions appName,countryOrRegion --metrics lowImpressionShare,highImpressionShare --json
146
+ superwall asa impression-share get <id> --json # downloadUri once state is COMPLETED
147
+ ```
148
+
149
+ ## Discovery
150
+
151
+ ```bash
152
+ superwall asa apps search "grammar checker" --owned --json # find adamIds
153
+ superwall asa apps eligibility <adamId> --json
154
+ superwall asa product-pages list --adam-id <adamId> --json
155
+ superwall asa geo search "New York" --entity Locality --json
156
+ superwall asa geo get "US|CA|Cupertino" --entity Locality --json
157
+ superwall asa product-pages countries --json
158
+ superwall asa acls --json
159
+ superwall asa me --json
160
+ ```
@@ -0,0 +1,96 @@
1
+ # App Store Connect — the full ASC API via the signed proxy
2
+
3
+ `superwall asc` proxies the **entire** App Store Connect API through Superwall's
4
+ signed request — no `.p8` file or JWT locally. It is schema-aware: it builds
5
+ JSON:API request bodies from flat params and validates them against Apple's own
6
+ OpenAPI spec before anything reaches App Store Connect. This lets an agent create
7
+ and manage subscriptions, IAPs, prices, and offers directly.
8
+
9
+ ## Docs access — do this before every write
10
+
11
+ Never guess a request body. Before any `asc post` / `asc patch`, look up the
12
+ exact schema:
13
+
14
+ ```bash
15
+ superwall asc docs # catalog: every resource root
16
+ superwall asc docs "introductory offer" # find endpoints by keyword
17
+ superwall asc docs /v1/subscriptions post # exact schema: required fields, enums, relationships, example
18
+ ```
19
+
20
+ If you send a malformed body, the proxy **blocks it locally** and returns the
21
+ precise fix — a missing required field, an invalid enum value — before it ever
22
+ hits Apple's opaque errors. Read the correction and retry. `--force` skips
23
+ validation and sends as-is.
24
+
25
+ The schema is fetched from Apple on first use (a one-time few-second load),
26
+ cached under `~/.superwall`, and refreshed automatically in the background when
27
+ stale. Force an update with `superwall asc docs refresh`.
28
+
29
+ ## Flat params, not hand-written JSON:API
30
+
31
+ Pass flat `-d key=value`; the proxy assembles the JSON:API envelope
32
+ (`data.type` / `attributes` / `relationships`), casts values by declared type,
33
+ and wraps each relationship id. A relationship value is just the target id.
34
+
35
+ ```bash
36
+ superwall asc post /v1/subscriptions \
37
+ -d name="Premium Monthly" -d productId=com.acme.pro.monthly \
38
+ -d subscriptionPeriod=ONE_MONTH -d group=<subscriptionGroups id> --json
39
+ ```
40
+
41
+ An already-enveloped body (`-d data[type]=…`) is passed through untouched.
42
+
43
+ ## Recipe: create a subscription end to end
44
+
45
+ App Store Connect requires these in order; each step's returned id feeds the
46
+ next. Run `asc docs <path> post` for the full schema of any step.
47
+
48
+ ```bash
49
+ # 1. Subscription group (one per app)
50
+ superwall asc post /v1/subscriptionGroups \
51
+ -d referenceName="Premium" -d app=<ascAppId> --json
52
+
53
+ # 2. Subscription, inside that group
54
+ superwall asc post /v1/subscriptions \
55
+ -d name="Premium Monthly" -d productId=com.acme.pro.monthly \
56
+ -d subscriptionPeriod=ONE_MONTH -d group=<groupId> --json
57
+
58
+ # 3. Discover a price point (Apple's fixed tiers, per territory)
59
+ superwall asc /v1/subscriptions/<subId>/pricePoints --json
60
+
61
+ # 4. Set the price
62
+ superwall asc post /v1/subscriptionPrices \
63
+ -d subscription=<subId> -d subscriptionPricePoint=<pricePointId> \
64
+ -d territory=USA --json
65
+
66
+ # 5. (Optional) Introductory offer — e.g. a one-week free trial
67
+ superwall asc post /v1/subscriptionIntroductoryOffers \
68
+ -d subscription=<subId> -d duration=ONE_WEEK -d offerMode=FREE_TRIAL \
69
+ -d numberOfPeriods=1 -d subscriptionPricePoint=<pricePointId> --json
70
+ ```
71
+
72
+ Territory ids are three-letter store regions (`USA`, `GBR`, …). Whether
73
+ `territory` is required on a given call is marked by `asc docs` — don't assume.
74
+
75
+ ## Convenience shortcuts (formatted reads)
76
+
77
+ For the common reads there are hand-built shortcuts (not raw endpoints):
78
+
79
+ ```bash
80
+ superwall asc apps --json # ASC apps for the team
81
+ superwall asc products <bundle-id | asc-app-id> --json
82
+ superwall asc subscriptions com.acme.app --json
83
+ superwall asc iaps com.acme.app --json
84
+ superwall asc apps --team <teamId> --json # if the org has multiple teams
85
+ ```
86
+
87
+ Everything else — every one of Apple's endpoints — goes through the raw proxy
88
+ (`asc get|post|patch|delete /v1/…`), which is where validation applies.
89
+
90
+ ## Connecting ASC credentials (one-time)
91
+
92
+ ```bash
93
+ superwall asc keys set --key-id <id> --issuer <id> --key-file ./AuthKey.p8 [--name "My Team"] --json
94
+ superwall asc keys list --json
95
+ superwall asc keys rm <team_id> --json
96
+ ```
@@ -0,0 +1,57 @@
1
+ # Dashboard Links
2
+
3
+ ## Without applicationId
4
+
5
+ When you don't know the applicationId, use the `select-application` redirect - the user picks their app, then lands on the target page:
6
+
7
+ ```
8
+ https://superwall.com/select-application?pathname=/applications/:app/{page}
9
+ ```
10
+
11
+ | Page | URL |
12
+ |------|-----|
13
+ | Settings | `https://superwall.com/select-application?pathname=/applications/:app/settings` |
14
+ | API Keys | `https://superwall.com/select-application?pathname=/applications/:app/settings/api-keys` |
15
+ | Integrations | `https://superwall.com/select-application?pathname=/applications/:app/integrations` |
16
+ | Users | `https://superwall.com/select-application?pathname=/applications/:app/users/v2` |
17
+ | Surveys | `https://superwall.com/select-application?pathname=/applications/:app/surveys` |
18
+ | Products | `https://superwall.com/select-application?pathname=/applications/:app/products/v2` |
19
+ | Demand Score | `https://superwall.com/select-application?pathname=/applications/:app/demand-score` |
20
+ | Charts | `https://superwall.com/select-application?pathname=/applications/:app/charts/v2` |
21
+ | Campaigns | `https://superwall.com/select-application?pathname=/applications/:app/rules` |
22
+ | Paywalls | `https://superwall.com/select-application?pathname=/applications/:app/paywalls` |
23
+ | Templates | `https://superwall.com/select-application?pathname=/applications/:app/templates` |
24
+
25
+ ## With applicationId
26
+
27
+ When you know the applicationId (from `GET /v2/projects`), link directly:
28
+
29
+ ```
30
+ https://superwall.com/applications/{applicationId}/{page}
31
+ ```
32
+
33
+ Same pages as above - swap `:app` for the actual ID (e.g. `https://superwall.com/applications/40581/settings`).
34
+
35
+ ## Deep-linking to a specific paywall
36
+
37
+ Use the editor route for paywall links:
38
+
39
+ ```
40
+ https://superwall.com/editor/#/applications/{applicationId}/paywalls/{paywallId}/latest
41
+ ```
42
+
43
+ Example:
44
+
45
+ ```
46
+ https://superwall.com/editor/#/applications/40690/paywalls/201147/latest
47
+ ```
48
+
49
+ Do not use `https://superwall.com/applications/{applicationId}/paywalls/{paywallId}`; that is a legacy route.
50
+
51
+ ## Deep-linking to a specific user
52
+
53
+ ```
54
+ https://superwall.com/applications/{applicationId}/users/v2/{userId}
55
+ ```
56
+
57
+ `{userId}` can be a Superwall alias (e.g. `$SuperwallAlias:31FC167B-55CF-4197-9DF2-E5200C6A2E67`) or any user identifier.