@superwall/cli 2.1.1 → 2.2.1

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 (107) hide show
  1. package/README.md +12 -1
  2. package/dist/{apple-BHbX0jbn.js → apple-DaqaI4vD.js} +13 -13
  3. package/dist/auth.d.ts +1 -1
  4. package/dist/auth.js +3 -3
  5. package/dist/{billing-4zhIBFRQ.js → billing-DyKr2kmd.js} +3 -3
  6. package/dist/{bind-CHLHmxgA.js → bind-BpxebZf4.js} +4 -4
  7. package/dist/{build-5PQeSnNN.js → build-DzbdRThf.js} +6 -6
  8. package/dist/{client-BIvOmWPC.js → client-BF9rCULI.js} +3 -3
  9. package/dist/{create-VK-pNfN7.js → create-B55V99TD.js} +22 -22
  10. package/dist/create-BYAPuhhf.js +19 -0
  11. package/dist/{create-BSNIFsnN.js → create-D7AZHYGH.js} +6 -6
  12. package/dist/{doctor-9JS96QkX.js → doctor-B2mPKiaJ.js} +6 -6
  13. package/dist/{drivers-BamBJ10Y.js → drivers-DOMky8Ug.js} +3 -3
  14. package/dist/entry.js +19 -19
  15. package/dist/{environment-eV7LEnSN.js → environment-DBwo79dy.js} +1 -1
  16. package/dist/{existing-C8dSYHGk.js → existing-B4VK4BCL.js} +2 -2
  17. package/dist/held-C9FqvNbn.js +16 -0
  18. package/dist/{held-BMisHn8F.js → held-DjcZPCwn.js} +6 -6
  19. package/dist/{integrate-VWtTNPCr.js → integrate-B8oHbvwz.js} +21 -21
  20. package/dist/{login-BmwG14LC.js → login-B8hgMLhS.js} +1 -1
  21. package/dist/login-D-a7oS_8.js +16 -0
  22. package/dist/{login-BimbukE5.js → login-DfhqWY9C.js} +256 -33
  23. package/dist/{lookup-k9EeOiZr.js → lookup-r8p6H2ZC.js} +2 -2
  24. package/dist/{migrate-C86h6jeF.js → migrate-DQf2Fosc.js} +21 -21
  25. package/dist/{notification-url-BVaTgWZ5.js → notification-url-BxPTEmkv.js} +2 -2
  26. package/dist/{open-0tDCQOXC.js → open-CrEnSL4v.js} +21 -17
  27. package/dist/{org-DUwdrKPV.js → org-Cc2WGvl1.js} +2 -2
  28. package/dist/{paths-BCbjCLP5.js → paths-BcNbJfpw.js} +1 -1
  29. package/dist/{playbook-oov9yV0q.js → playbook-D9J8frkE.js} +10 -10
  30. package/dist/{promote-DPGPamkE.js → promote-C8T7DCFF.js} +16 -16
  31. package/dist/{push-Cz4lJ8Qd.js → push-Bzs1l_5C.js} +4 -4
  32. package/dist/push-snV3SrnH.js +22 -0
  33. package/dist/{registry-CTczUigi.js → registry-CpxZbmxp.js} +83 -63
  34. package/dist/{resources-B1qKDVXd.js → resources-Bo6i7wBi.js} +1 -1
  35. package/dist/{run-DTPsVmFw.js → run-BUp4r8Kk.js} +2 -2
  36. package/dist/{scan-Bb48xZqB.js → scan-8cxu2fx0.js} +1 -1
  37. package/dist/scan-nUeXs9a1.js +4 -0
  38. package/dist/{scope-B6UYGuwn.js → scope-CPG_wWXL.js} +4 -4
  39. package/dist/{selection-BbNk9r1q.js → selection-CMA4aG4V.js} +3 -3
  40. package/dist/server-Boqa8jh_.js +22 -0
  41. package/dist/{server-EYBMKAG1.js → server-Xb3wp-mx.js} +66 -16
  42. package/dist/{session-xG9E8J2N.js → session-DOZV1TP6.js} +1 -1
  43. package/dist/session-DtBpdlF-.js +6 -0
  44. package/dist/{session-Crg9X-FI.js → session-eZeXR9xU.js} +9 -8
  45. package/dist/skills/animate-onboarding/SKILL.md +1 -1
  46. package/dist/skills/index.json +18 -18
  47. package/dist/skills/mobile-design/SKILL.md +1 -1
  48. package/dist/skills/onboarding-questions/SKILL.md +1 -1
  49. package/dist/skills/superwall/SKILL.md +102 -17
  50. package/dist/skills/superwall/references/api.md +13 -2
  51. package/dist/skills/superwall/references/data-analytics.md +7 -8
  52. package/dist/skills/superwall/workflows/dashboard/playbook.md +2 -1
  53. package/dist/skills/superwall/workflows/dashboard/setup.md +3 -1
  54. package/dist/skills/superwall/workflows/integrate/playbook.md +4 -2
  55. package/dist/skills/superwall/workflows/migrate/adapty.md +3 -3
  56. package/dist/skills/superwall/workflows/migrate/playbook.md +2 -1
  57. package/dist/skills/superwall/workflows/migrate/qonversion.md +3 -3
  58. package/dist/skills/superwall/workflows/migrate/revenuecat.md +4 -4
  59. package/dist/skills/superwall-editor/SKILL.md +53 -1
  60. package/dist/skills/superwall-framework/SKILL.md +10 -5
  61. package/dist/skills/superwall-framework/references/migrate-from-editor.md +3 -2
  62. package/dist/skills/superwall-framework/references/mobile-design.md +1 -1
  63. package/dist/{skills-Dg3k6TRC.js → skills-BI19OGlS.js} +8 -8
  64. package/dist/{skills-BdMKE2uO.js → skills-DDf10ufO.js} +4 -4
  65. package/dist/{spinner-Ba3XhlMb.js → spinner-BClMQGGN.js} +3 -3
  66. package/dist/{storage-CerJ5KLP.d.ts → storage-BbJF7z3l.d.ts} +1 -0
  67. package/dist/{storage-DIkYajce.js → storage-Po9E-CHL.js} +12 -2
  68. package/dist/storekit-BU6Eq_UO.js +16 -0
  69. package/dist/{storekit-C2UzIIMs.js → storekit-Cbn9DBLA.js} +3 -3
  70. package/dist/{telemetry-CVP8O6Y3.js → telemetry-s6dag6tb.js} +1 -1
  71. package/dist/{token-IWv2httm.js → token-CPplNMVa.js} +1 -1
  72. package/dist/tools-skills/animate-onboarding/SKILL.md +1 -1
  73. package/dist/tools-skills/mobile-design/SKILL.md +1 -1
  74. package/dist/tools-skills/onboarding-questions/SKILL.md +1 -1
  75. package/dist/tools-skills/superwall/SKILL.md +80 -8
  76. package/dist/tools-skills/superwall/references/api.md +116 -24
  77. package/dist/tools-skills/superwall/references/apple-setup.md +316 -0
  78. package/dist/tools-skills/superwall/references/asc.md +74 -38
  79. package/dist/tools-skills/superwall/references/data-analytics.md +62 -29
  80. package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +3 -3
  81. package/dist/tools-skills/superwall/workflows/dashboard/setup.md +8 -8
  82. package/dist/tools-skills/superwall/workflows/migrate/adapty.md +6 -6
  83. package/dist/tools-skills/superwall/workflows/migrate/playbook.md +4 -4
  84. package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +5 -5
  85. package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +6 -6
  86. package/dist/tools-skills/superwall/workflows/placements/android.md +2 -2
  87. package/dist/tools-skills/superwall/workflows/placements/expo.md +2 -2
  88. package/dist/tools-skills/superwall/workflows/placements/flutter.md +2 -2
  89. package/dist/tools-skills/superwall/workflows/placements/ios.md +2 -2
  90. package/dist/tools-skills/superwall/workflows/placements/playbook.md +2 -2
  91. package/dist/tools-skills/superwall/workflows/placements/react-native.md +2 -2
  92. package/dist/tools-skills/superwall/workflows/placements/strategy.md +2 -2
  93. package/dist/tools-skills/superwall/workflows/review/playbook.md +1 -1
  94. package/dist/tools-skills/superwall-editor/SKILL.md +2 -2
  95. package/dist/tools.d.ts +8 -8
  96. package/dist/tools.js +21 -24
  97. package/dist/{upgrade-DLf0LJDh.js → upgrade-1OYm5NQU.js} +2 -2
  98. package/dist/{upgrade-1t3aQUxh.js → upgrade-ahapZeex.js} +1 -1
  99. package/package.json +2 -2
  100. package/dist/create-oj3zXvHZ.js +0 -19
  101. package/dist/held-DeJW2gUk.js +0 -16
  102. package/dist/login-2JHCG6c1.js +0 -16
  103. package/dist/push-Chp21y3a.js +0 -22
  104. package/dist/scan-B1SkkUi7.js +0 -4
  105. package/dist/server-CwrZ-I1r.js +0 -22
  106. package/dist/session-DItGa4z0.js +0 -6
  107. package/dist/storekit-DHNxDDpA.js +0 -16
@@ -0,0 +1,316 @@
1
+ # Apple setup — bundle ID, keys, server notifications, revenue provider
2
+
3
+ You are connecting an iOS app to Superwall from the CLI: its bundle ID, its two
4
+ Apple keys, where Apple sends its purchase events, and which revenue source the
5
+ dashboard counts. Each is one command that does one thing. This file is the order to run
6
+ them in and what to do with each answer.
7
+
8
+ - [ ] Confirm the app (`superwall apps list --json`) and use `--app <id>` on every command
9
+ - [ ] Make sure it has the right bundle ID (step 6), found in the project, before anything else
10
+ - [ ] Look at what is saved before changing anything
11
+ - [ ] Import a key the organization already has before creating one
12
+ - [ ] Create only the key that is still missing, and never a second one
13
+ - [ ] Read both notification URLs before setting anything
14
+ - [ ] Treat the revenue provider as its own decision, made by a person
15
+
16
+ Every command prints what it changes, what it never does, and its exit codes:
17
+
18
+ ```bash
19
+ superwall asc --help
20
+ superwall apps update --help
21
+ ```
22
+
23
+ ## The three things, and why they are separate
24
+
25
+ | Thing | What it does | Command group |
26
+ | --- | --- | --- |
27
+ | `api_key` (App Store Connect API key) | Lets Superwall read the app's products and set its server notification URL | `superwall asc keys` |
28
+ | `purchase_key` (In-App Purchase key) | Lets Superwall read transactions for one bundle ID | `superwall asc keys` |
29
+ | Server notification URL | Where Apple sends the app's purchase events, one URL per environment | `superwall asc notification-url` |
30
+ | Revenue provider | Which source every revenue figure in the dashboard counts | `superwall apps update --revenue-provider` |
31
+
32
+ An app can receive Apple's notifications in Superwall and still count its
33
+ revenue from RevenueCat. Setting the URL never chooses the provider, and
34
+ choosing the provider never touches the URL.
35
+
36
+ ## 1. Look at what is saved
37
+
38
+ ```bash
39
+ superwall apps get <id> --json
40
+ # integrations.app_store_connect_configuration, integrations.in_app_purchase_configuration,
41
+ # server_notifications, notification_url, app.bundle_id, sdk.candidates, integrations.revenue_provider
42
+ ```
43
+
44
+ `superwall asc keys list --app <id> --json` shows just the two keys. A kind
45
+ that is not `null` is done. Leave it alone: a second key is clutter at
46
+ Apple, and Apple caps active keys per team.
47
+
48
+ ## 2. Import before you create
49
+
50
+ ```bash
51
+ superwall asc keys import --app <id> --json # both kinds
52
+ superwall asc keys import purchase_key --app <id> --json
53
+ ```
54
+
55
+ It tries the keys the organization already has and saves the first one Apple
56
+ confirms for this app's bundle ID. Per kind, `status` is:
57
+
58
+ - `imported` — saved. Done for that kind.
59
+ - `already_saved` — the app had one. Done for that kind.
60
+ - `not_found` — nothing was saved. `tried: 0` means the organization has no
61
+ such key; `timed_out: true` means run it again. Otherwise go to step 3.
62
+
63
+ Exit code 0 means every kind asked for is now saved.
64
+
65
+ To copy one specific key, list the candidates and name the source app:
66
+
67
+ ```bash
68
+ superwall asc keys sources --app <id> --json
69
+ superwall asc keys import api_key --app <id> --from <other app id> --json
70
+ ```
71
+
72
+ `import --from` can answer `unconfirmed`: the key works, but Apple shows no app with
73
+ this bundle ID on its team. Nothing is saved. Show the user that message and
74
+ ask whether it is the right team's key. Only after they say yes, run it again
75
+ with `--allow-unconfirmed`. Never add that flag on your own. A `purchase_key`
76
+ Apple won't accept for the bundle ID is never saved, flag or not.
77
+
78
+ ## 3. Create only what is still missing
79
+
80
+ Creating a key means signing in to Apple. The person does that, not you:
81
+
82
+ > Ask the user to run this in their own terminal, then tell you when it is done.
83
+
84
+ ```bash
85
+ superwall asc keys create api_key --app <id>
86
+ superwall asc keys create purchase_key --app <id>
87
+ ```
88
+
89
+ It asks for their Apple Account email, password (masked) and the verification
90
+ code Apple sends, creates one key named "Superwall", and saves it on the app.
91
+ The password goes from their computer to Apple; Superwall never receives it.
92
+ When the app already has that kind of key the command creates nothing and says
93
+ so. Do not pass `--replace` unless the user asked to replace a key that has
94
+ stopped working.
95
+
96
+ Both keys are missing and the URL too? One sign-in covers all of it:
97
+
98
+ ```bash
99
+ superwall setup apple --app <id> # creates only the keys the app lacks, then sets the URL
100
+ ```
101
+
102
+ Afterwards, confirm with `superwall apps get <id> --json`.
103
+
104
+ ### If the user asks you to run the sign-in yourself
105
+
106
+ Only when they say so. Then:
107
+
108
+ 1. **Never ask for the Apple password in conversation, and never print, echo
109
+ or log it.** The user puts it where your shell can read it, as
110
+ `SUPERWALL_APPLE_PASSWORD` (and `SUPERWALL_APPLE_ID`). If it is not set, the command prints how to
111
+ collect it through a private file without it passing through the chat.
112
+ Follow that.
113
+ 2. Run `superwall asc keys create <kind> --app <id> --no-interactive --json`.
114
+ It exits 1 with `"status": "verification_required"`: Apple has sent a code
115
+ to the user's devices.
116
+ 3. Tell the user a code was sent and that they can either run the `next`
117
+ command from the output themselves, or give you the code. This six-digit
118
+ code is the only one-time code you may accept in conversation, and only for
119
+ a sign-in the user asked you to run. Use it once, within 10 minutes, with
120
+ the same flags plus `--code <code>`. Do not store or repeat it.
121
+ 4. Add `--sms` to have Apple text the code instead.
122
+
123
+ ## 4. Apple's notifications
124
+
125
+ Read both sides first. Neither command changes anything.
126
+
127
+ ```bash
128
+ superwall apps get <id> --json # notification_url: this app's Superwall URL
129
+ superwall asc notification-url check --app <id> --json # what Apple has, and whose it is
130
+ ```
131
+
132
+ `check` asks Apple with the app's saved `api_key`, and Superwall says whose
133
+ each environment's URL is in `apple.production.owner` and
134
+ `apple.sandbox.owner`. Do not compare the URLs yourself: Superwall has issued
135
+ this app's URL in more than one form, and all of them count as the app's own.
136
+
137
+ | `owner` | Meaning |
138
+ | --- | --- |
139
+ | `this_app` | This app's Superwall URL. Nothing to do for that environment. |
140
+ | `none` | Apple has no URL there. |
141
+ | `superwall_app` | Another Superwall app's. `application` names it when the user can read that app; otherwise `url` has its token replaced by `REDACTED` and `application` is null. |
142
+ | `other` | Someone else's: RevenueCat, the user's own server, anything that isn't Superwall. `url` says which. |
143
+
144
+ | `apple.status` | Meaning | What to do |
145
+ | --- | --- | --- |
146
+ | `set` | `set` only: Superwall just wrote this app's URL where Apple had none | Nothing. It is done. |
147
+ | `already_set` | Both environments are this app's | Nothing. It is done. |
148
+ | `not_set` | Production, sandbox or both are empty, and no other server holds either | `superwall asc notification-url set --app <id>` |
149
+ | `conflict` | Another server or another Superwall app holds one or both | Do not replace it. See "Another server holds the URL". |
150
+ | `skipped` | The app has no `api_key`, or no bundle ID, saved | Go back to steps 1–3, or set the bundle ID (step 6). |
151
+ | `failed` | Apple couldn't be asked. `message` says which of three causes it is | A key saved in the last few minutes isn't active yet: wait a minute and run it again. Apple refused the saved key (it may have been revoked): save a new `api_key` (steps 1–3). The key can't see an app with this bundle ID: check the bundle ID (step 6), then use an `api_key` from the Apple team that owns the app. |
152
+
153
+ `check` and `set` work with a `superwall login` session or an API key with
154
+ `applications:write`.
155
+
156
+ `set` writes the URL into whichever environment is empty, never replaces
157
+ another server's URL, and leaves the revenue provider alone. Pass
158
+ `--set-revenue-provider` only when the user has also decided to count revenue
159
+ from the store (step 5).
160
+
161
+ ### Another server holds the URL
162
+
163
+ Apple allows one URL per environment, and the CLI will not take it from
164
+ whoever has it. Look at the `owner` and `url` of each environment in the
165
+ `conflict` and pick the matching route. None of them needs App Store Connect
166
+ to be the revenue provider.
167
+
168
+ **RevenueCat holds it** (the URL is on `api.revenuecat.com`). Keep it there and
169
+ have RevenueCat forward Apple's notifications:
170
+
171
+ 1. Get this app's URL: `notification_url` in `superwall apps get <id> --json`.
172
+ 2. The user opens RevenueCat, the iOS app's settings, **Apple Server to Server
173
+ notification settings**, and pastes it into **Apple Server Notification
174
+ Forwarding URL**.
175
+
176
+ This is a different thing from RevenueCat's "Superwall" integration, which
177
+ sends RevenueCat's own events. The field holds one URL. If it already forwards
178
+ to the user's server, forward from that server instead.
179
+
180
+ **The user's own server holds it.** Add a forward in the handler that receives
181
+ Apple's notifications, before any other logic:
182
+
183
+ - An HTTP POST to this app's Superwall URL with `Content-Type: application/json`.
184
+ - The body is the request as received: JSON with one `signedPayload` string.
185
+ Pass it through; never decode, re-encode or edit that string.
186
+ - Forward every notification, production and sandbox, whatever its type.
187
+ - Use a timeout of about 5 seconds and catch every error, so a failed forward
188
+ never changes what the server answers Apple.
189
+ - The URL carries the app's token. Read it from configuration or the
190
+ environment, keep it out of source control and logs.
191
+
192
+ **Another Superwall app holds it** (`owner` is `superwall_app`). The Apple app
193
+ is connected to a different Superwall app: `application.name` says which when
194
+ the user can read it. Stop and ask the user which Superwall app should own it.
195
+ Do not work around it, and never try to recover a token shown as `REDACTED`.
196
+
197
+ **The user wants Superwall to replace it.** That is theirs to do: clear the URL
198
+ in App Store Connect → App Information → App Store Server Notifications, or
199
+ replace it from the dashboard, which asks them to confirm. Then run `set`.
200
+
201
+ Verify any route after the next purchase, renewal or cancellation: an Apple
202
+ event appears under Recent events on the dashboard's Revenue tracking page.
203
+
204
+ ## 5. The revenue provider is its own decision
205
+
206
+ ```bash
207
+ superwall apps get <id> --json
208
+ # integrations.revenue_provider: "revenue_cat"
209
+ # integrations.revenue_provider_events: { "window_days": 30, "open_revenue": {…}, "revenue_cat": {…} }
210
+ ```
211
+
212
+ - `open_revenue` — the store's own events (App Store Connect or Google Play), sent straight to Superwall
213
+ - `revenue_cat` — RevenueCat's events
214
+ - `null` — none chosen; events from every source are counted
215
+
216
+ Both sources keep arriving and being stored whichever is chosen. The provider
217
+ only decides which one every revenue figure in the dashboard counts, so a
218
+ change moves the user's numbers. Never change it as a side effect of anything
219
+ else, and never on your own:
220
+
221
+ 1. Show the user the current value and what each source sent.
222
+ 2. Say what would change: only the chosen source is counted from then on.
223
+ 3. After they agree, run `superwall apps update <id> --revenue-provider <value> --yes --json`.
224
+
225
+ Without `--yes` outside a terminal the command changes nothing and exits 1.
226
+ That is the confirmation, not an error to work around.
227
+
228
+ Revenue queries depend on it too: `superwall query --app <id>` passes the
229
+ provider's integrations to SQL, see the analytics reference.
230
+
231
+ ## 6. The bundle ID
232
+
233
+ The bundle ID (package name on Android) decides which builds the SDK treats
234
+ as this app. A build whose ID is neither the saved one nor starts with it
235
+ followed by a dot runs in test mode, so a wrong one quietly puts real users in
236
+ test mode. Finding the App Store Connect app, the In-App Purchase key and the
237
+ notification URL all need it too.
238
+
239
+ 1. **Look in the project first.** It is the source of truth for what ships:
240
+ - Xcode: `PRODUCT_BUNDLE_IDENTIFIER` of the app target, for the Release
241
+ configuration, in `project.pbxproj` or an `.xcconfig` it uses, with any
242
+ variables resolved.
243
+ - `Info.plist`: `CFBundleIdentifier`, when it is a literal rather than
244
+ `$(PRODUCT_BUNDLE_IDENTIFIER)`.
245
+ - Expo: `ios.bundleIdentifier` (and `android.package`) in `app.json`,
246
+ `app.config.js` or `app.config.ts`, per build profile if set there.
247
+ - React Native and Flutter: the app target in `ios/<Project>.xcodeproj` or
248
+ `ios/Runner.xcodeproj`, read as above.
249
+ - Android: `applicationId` in the app module's `build.gradle(.kts)`
250
+ `defaultConfig`, with the release build type's `applicationIdSuffix` and
251
+ the shipping flavor applied; the manifest's `package` only when Gradle
252
+ sets none.
253
+ Ignore test targets, extensions, widgets, watch apps and debug or staging
254
+ variants.
255
+ 2. **Compare with what the SDK reported:**
256
+
257
+ ```bash
258
+ superwall apps get <id> --json
259
+ # "app": { "bundle_id": null, ... }, "sdk": { "available": true, "candidates": [
260
+ # { "bundle_id": "com.acme.app", "production_devices": 9630, "sandbox_devices": 12, ... } ] }
261
+ ```
262
+
263
+ The candidate with the production devices should match what you found. If
264
+ they disagree, or several IDs have production devices, tell the user what
265
+ you found and what the SDK reported, and let them choose.
266
+ 3. **State the test-mode impact before saving.** Production devices on IDs
267
+ that neither equal the new one nor start with it followed by a dot would
268
+ run in test mode. The command counts them and asks first; outside a
269
+ terminal it changes nothing without `--yes`. Show the user the count and
270
+ pass `--yes` only after they agree.
271
+
272
+ ```bash
273
+ superwall apps update <id> --bundle-id com.acme.app --json
274
+ ```
275
+
276
+ 4. **Never replace one that is saved on your own.** When the app already has
277
+ a different ID, ask the user, with what each ID is and what the SDK
278
+ reported for it, before running `apps update --bundle-id` (and `--yes`).
279
+
280
+ `setup apple` and `asc keys create purchase_key` (with or without `--key-file`)
281
+ also set the app's bundle ID when it has none: the App Store Connect app's, or
282
+ the one `--bundle-id` names, saved with the In-App Purchase key, both or
283
+ neither. They say so, and how many reported builds would run in test mode.
284
+ When the app already has a different one they stop before anything is created
285
+ and point at `superwall apps update <id> --bundle-id <id>`, which is still the
286
+ user's decision.
287
+
288
+ ## When Apple refuses
289
+
290
+ | What you see | Cause | What to tell the user |
291
+ | --- | --- | --- |
292
+ | "Only an Admin or the Account Holder can create team keys" | The Apple Account's role is too low | Sign in with an Admin or the Account Holder, or ask one of them to run the command |
293
+ | "…or the team has an agreement waiting to be signed" | Apple gives the same refusal for a pending agreement | Only the Account Holder can accept it, at https://appstoreconnect.apple.com/agreements |
294
+ | "This team is at Apple's limit of active keys" | Too many active keys | Revoke one they don't use in App Store Connect → Users and Access → Integrations |
295
+ | "No App Store Connect app with bundle ID … on the Apple team …" | The signed-in team does not own the bundle ID. Nothing was created | Sign in to the right team (`--team <id or name>`), or fix the bundle ID |
296
+ | `unconfirmed` from `asc keys import --from` | The key's team shows no app with this bundle ID | Ask whether it is the right team's key before `--allow-unconfirmed` |
297
+ | "…was saved to ./AuthKey_<KEY_ID>.p8" | Apple created the key, Superwall couldn't save it | Save it with `superwall asc keys create <kind> --app <id> --key-id … --issuer … --key-file …`, then delete the file |
298
+ | "can't … yet" naming the API host | That Superwall API doesn't offer the step yet. Nothing changed | Do that step in the dashboard |
299
+
300
+ ## What to ask the person for, and what never to ask for
301
+
302
+ Ask for:
303
+ - which Superwall app (`--app`), and which Apple team if their account has several
304
+ - approval before a key's `--replace`, changing a saved bundle ID, `--allow-unconfirmed`, `asc keys delete`, any revenue provider change, and a bundle ID that would put production devices in test mode
305
+ - to run the Apple sign-in themselves
306
+
307
+ Never ask for, print, echo or log the Apple Account password. Loading it from
308
+ the user's private file into `SUPERWALL_APPLE_PASSWORD`, as the CLI describes,
309
+ is the only way you handle it.
310
+
311
+ Never ask for, read, print or move:
312
+ - a `.p8` private key or its contents
313
+ - a Superwall API key or session file
314
+
315
+ A person who already holds a `.p8` file saves it themselves with
316
+ `superwall asc keys create <kind> --app <id> --key-id <id> --issuer <id> --key-file <path>`.
@@ -24,7 +24,7 @@ and correct the payload.
24
24
 
25
25
  The schema is fetched from Apple on first use (a one-time few-second load),
26
26
  cached under `~/.superwall`, and refreshed automatically in the background when
27
- stale. Force an update with `superwall asc docs refresh`.
27
+ stale. Force an update with `superwall asc docs --refresh`.
28
28
 
29
29
  ## Flat params, not hand-written JSON:API
30
30
 
@@ -40,56 +40,92 @@ superwall asc post /v1/subscriptions \
40
40
 
41
41
  An already-enveloped body (`-d data[type]=…`) is passed through untouched.
42
42
 
43
- ## Recipe: create a subscription end to end
43
+ ## Recipe: a subscription ready for review
44
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.
45
+ Apple needs a group, the subscription, its localization, where it is sold, a
46
+ price in every territory, and a review screenshot. The resource commands do
47
+ each in one step on Apple's current endpoints and end by reporting what is
48
+ still `missing`:
47
49
 
48
50
  ```bash
49
- # 1. Subscription group (one per app)
50
- superwall asc post /v1/subscriptionGroups \
51
- -d referenceName="Premium" -d app=<ascAppId> --json
51
+ # 1. A group (one per app is typical), with its en-US name
52
+ superwall asc subscription-groups create --asc-app <bundle-id> --reference-name Pro --display-name Pro --json
52
53
 
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
54
+ # 2. The subscription: localization, availability, the price equalized to every territory, a free trial
55
+ superwall asc subscriptions create --group <group-id> --asc-app <bundle-id> \
56
+ --product-id pro_monthly --name "Pro Monthly" --subscription-period ONE_MONTH \
57
+ --price 9.99 --display-name "Pro" --description "Everything unlocked" --trial ONE_WEEK --json
57
58
 
58
- # 3. Discover a price point (Apple's fixed tiers, per territory)
59
- superwall asc /v1/subscriptions/<subId>/pricePoints --json
59
+ # 3. The App Review screenshot, then submit (an app's first products go with a version: asc release submit)
60
+ superwall asc screenshots upload --subscription <id> review.png
61
+ superwall asc submit --asc-app <bundle-id> --group <group-id> --subscription <id>
62
+ ```
60
63
 
61
- # 4. Set the price
62
- superwall asc post /v1/subscriptionPrices \
63
- -d subscription=<subId> -d subscriptionPricePoint=<pricePointId> \
64
- -d territory=USA --json
64
+ Add `--dry-run` to any write to see every request first. Reach for raw
65
+ requests (`asc get|post|patch|delete`) only for what these don't cover.
65
66
 
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
- ```
67
+ ## Products: the asc resource commands
71
68
 
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.
69
+ Selling something on the App Store takes many Apple calls (product, version,
70
+ localization, availability, a price in every territory, a review screenshot).
71
+ The resource commands do each job in one step, on Apple's current endpoints.
72
+ Reach for them before raw requests:
74
73
 
75
- ## Convenience shortcuts (formatted reads)
74
+ ```bash
75
+ superwall asc apps --json # ASC apps for the team
76
+ superwall asc products <bundle-id | asc-app-id> --json # everything one app sells
77
+ superwall asc subscription-groups list <bundle-id> --json
78
+ superwall asc subscriptions list <bundle-id> --json
79
+ superwall asc iaps list <bundle-id> --json
80
+
81
+ # A subscription ready for review: localization, availability, price equalized everywhere
82
+ superwall asc subscriptions create --group <id|name> --asc-app <bundle-id> \
83
+ --product-id pro_monthly --name "Pro Monthly" --subscription-period ONE_MONTH \
84
+ --price 9.99 --display-name "Pro" --description "Everything unlocked" --trial ONE_WEEK
85
+
86
+ superwall asc iaps create --asc-app <bundle-id> --product-id coins_100 --name "100 coins" \
87
+ --in-app-purchase-type CONSUMABLE --price 0.99 --display-name "100 coins"
88
+
89
+ superwall asc prices points --subscription <id> --territory USA --price 9.99 # Apple's price tier
90
+ superwall asc prices set --subscription <id> --price 12.99 --preserve-current-price
91
+ superwall asc offers create --subscription <id> --offer-mode FREE_TRIAL --duration ONE_WEEK # every territory
92
+ superwall asc offers list --subscription <id>
93
+ superwall asc availability set --iap <id> --available-territories USA,CAN
94
+ superwall asc localizations add --subscription <id> --locale de-DE --name "Pro" --description "…"
95
+ superwall asc screenshots upload --subscription <id> review.png # needed before review
96
+ superwall asc submit --asc-app <bundle-id> --group <id> --subscription <id>
97
+ ```
76
98
 
77
- For the common reads there are hand-built shortcuts (not raw endpoints):
99
+ Releases have their own commands:
78
100
 
79
101
  ```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
102
+ superwall asc versions create --asc-app <bundle-id> --version-string 1.4.0
103
+ superwall asc builds list <bundle-id> --version-string 1.4.0
104
+ superwall asc builds attach <build-id> 1.4.0 --asc-app <bundle-id>
105
+ superwall asc metadata update 1.4.0 --asc-app <bundle-id> --locale en-US --whats-new "…"
106
+ superwall asc release submit 1.4.0 --asc-app <bundle-id> [--subscription <id>] # first in-app products ship with a version
107
+ superwall asc release status 1.4.0 --asc-app <bundle-id>
108
+ superwall asc release phased start 1.4.0 --asc-app <bundle-id>
85
109
  ```
86
110
 
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.
111
+ Raw requests to an endpoint Apple has replaced print a warning naming the replacement.
112
+
113
+ Every write takes `--dry-run` (prints each request, sends nothing). `create`
114
+ ends by reporting the product's `state` and anything still `missing` before it
115
+ can be submitted. `superwall asc <resource> --help` lists each one's operations.
116
+
117
+ Everything else goes through the raw proxy (`asc get|post|patch|delete /v1/…`),
118
+ which is where validation applies.
119
+
120
+ ## Connecting ASC credentials
89
121
 
90
- ## Connecting ASC credentials (user-managed)
122
+ Connecting an app's Apple keys, pointing Apple's server notifications at
123
+ Superwall, and choosing the revenue provider are in the
124
+ [Apple setup reference](apple-setup.md). Read it before running any
125
+ `superwall asc keys`, `superwall asc notification-url`, `superwall setup apple`
126
+ or `superwall apps update --revenue-provider` command.
91
127
 
92
- Use the credentials the user has already connected privately. If unavailable,
93
- have the user consult `superwall asc keys set --help` at their own terminal and
94
- complete setup themselves. Do not ask for, inspect, or upload an Apple private
95
- key, JWT, or authentication secret. Resume account operations after setup.
128
+ The short version: look at what is saved (`superwall apps get <app>`), import a
129
+ key the organization already has (`superwall asc keys import --app <app>`), and
130
+ have the user create only what is still missing. Do not ask for, inspect, or
131
+ upload an Apple password, private key, JWT, or authentication secret.