@superwall/cli 1.7.0 → 2.0.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 (165) hide show
  1. package/README.md +192 -52
  2. package/dist/{setup-Bxj22rYi.js → apple-CkKlHBZ9.js} +82 -76
  3. package/dist/auth.d.ts +4 -19
  4. package/dist/auth.js +4 -2
  5. package/dist/{actions-B7ym3oVS.js → billing-XCZU_T46.js} +98 -28
  6. package/dist/{bind-YrJvuRF9.js → bind-drne__Ys.js} +38 -33
  7. package/dist/{build-DLoCW5Ri.js → build-Gpdq5QXP.js} +20 -26
  8. package/dist/{asc-Bf7zBbyS.js → client-BZ1UbpXz.js} +16 -15
  9. package/dist/client-DP6Rc0t_.js +176 -0
  10. package/dist/config-BO1Y87kV.js +105 -0
  11. package/dist/{notification-url-DuKF2659.js → create-BBrtgUgS.js} +235 -539
  12. package/dist/{create-pkANt1Gs.js → create-Cwc3SRWJ.js} +194 -168
  13. package/dist/create-Yvf2gStM.js +19 -0
  14. package/dist/doctor-C9ldpPFC.js +83 -0
  15. package/dist/{drivers-Qx9LxmRN.js → drivers-DNrx4LWA.js} +185 -172
  16. package/dist/entry.d.ts +0 -5
  17. package/dist/entry.js +28073 -1134
  18. package/dist/environment-DF1qKlny.js +58 -0
  19. package/dist/{existing-AVEfZu2A.js → existing-78LWSsqS.js} +12 -6
  20. package/dist/held-Cy8Wl4D1.js +1112 -0
  21. package/dist/held-Ddw1XSsr.js +16 -0
  22. package/dist/input-vi0bou04.js +42 -0
  23. package/dist/{integrate-brmhPG-S.js → integrate-DcJhpXy8.js} +277 -254
  24. package/dist/kinds-GFXB3sYu.js +11 -0
  25. package/dist/log-NVhVe_oe.js +62 -0
  26. package/dist/login-B2TsCE2H.js +53 -0
  27. package/dist/login-BoBe8Psl.js +16 -0
  28. package/dist/{login-Do4wFuLv.js → login-D0lh3_JI.js} +118 -55
  29. package/dist/lookup-D-nmmAbw.js +71 -0
  30. package/dist/migrate-Cfec564E.js +274 -0
  31. package/dist/notification-url-YDbq6FMA.js +100 -0
  32. package/dist/{open-studio-DOw-6ydc.js → open-Ba2vBl1_.js} +34 -43
  33. package/dist/org-D0g_q3mv.js +35 -0
  34. package/dist/output-Ggzq5_-t.js +122 -0
  35. package/dist/paths-DxSLdpOI.js +29 -0
  36. package/dist/playbook-DIeb7hne.js +53 -0
  37. package/dist/{asc-products-9JXtDxI4.js → products-DH_fK9tY.js} +6 -6
  38. package/dist/promote-COD4fYdz.js +91 -0
  39. package/dist/push-CncywhkQ.js +482 -0
  40. package/dist/push-CtD4FZQV.js +22 -0
  41. package/dist/registry-DSrosOYs.js +10228 -0
  42. package/dist/{reports-CfJqoava.js → reports-DdPq4blM.js} +7 -6
  43. package/dist/{resources-Bf9O1JNM.js → resources-Dqr01Dep.js} +150 -55
  44. package/dist/{run-DsVZ5snL.js → run-C9qg_QlC.js} +16 -22
  45. package/dist/scan-Cv5uOwVY.js +4 -0
  46. package/dist/{scan-zKsddO72.js → scan-DLrsrFS9.js} +48 -37
  47. package/dist/scope-V336uz8j.js +198 -0
  48. package/dist/screenshot-file-0UETadF8.js +16 -0
  49. package/dist/{selection-CxZoX4NT.js → selection-Rdw-ZUoG.js} +94 -51
  50. package/dist/send-BxD9yf6F.js +150 -0
  51. package/dist/{dev-DmB3XqaJ.js → server-D0tGG8C4.js} +82 -92
  52. package/dist/server-z1LH94R_.js +22 -0
  53. package/dist/session-1AV_Bs_d.js +6 -0
  54. package/dist/session-CFAmMhem.js +40 -0
  55. package/dist/session-D_nEWKXT.js +768 -0
  56. package/dist/skills/animate-onboarding/SKILL.md +467 -0
  57. package/dist/skills/animate-onboarding/references/engine.md +494 -0
  58. package/dist/skills/animate-onboarding/references/framework/Question.tsx +71 -0
  59. package/dist/skills/animate-onboarding/references/framework/README.md +40 -0
  60. package/dist/skills/animate-onboarding/references/framework/answers.ts +19 -0
  61. package/dist/skills/animate-onboarding/references/framework/flow.ts +80 -0
  62. package/dist/skills/animate-onboarding/references/framework/handoffs.ts +869 -0
  63. package/dist/skills/animate-onboarding/references/framework/layout.tsx +113 -0
  64. package/dist/skills/animate-onboarding/references/framework/motion.css +559 -0
  65. package/dist/skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
  66. package/dist/skills/animate-onboarding/references/handoffs.md +375 -0
  67. package/dist/skills/animate-onboarding/references/imageReady.ts +92 -0
  68. package/dist/skills/animate-onboarding/references/morphFrame.ts +356 -0
  69. package/dist/skills/animate-onboarding/references/performance.md +41 -0
  70. package/dist/skills/animate-onboarding/references/web-runtime/README.md +17 -0
  71. package/dist/skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
  72. package/dist/skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
  73. package/dist/skills/index.json +37 -0
  74. package/dist/skills/mobile-design/SKILL.md +447 -0
  75. package/dist/skills/mobile-design/references/responsive.md +162 -0
  76. package/dist/skills/onboarding-questions/SKILL.md +231 -0
  77. package/dist/skills/onboarding-questions/references/arpu-questions.md +139 -0
  78. package/dist/skills/onboarding-questions/references/craft.md +142 -0
  79. package/dist/skills/onboarding-questions/references/example-reflective.md +117 -0
  80. package/dist/skills/superwall/SKILL.md +82 -9
  81. package/dist/skills/superwall/references/api.md +153 -37
  82. package/dist/skills/superwall/references/apple-setup.md +316 -0
  83. package/dist/skills/superwall/references/asc.md +74 -38
  84. package/dist/skills/superwall/references/data-analytics.md +55 -21
  85. package/dist/skills/superwall/workflows/dashboard/playbook.md +3 -3
  86. package/dist/skills/superwall/workflows/dashboard/setup.md +8 -8
  87. package/dist/skills/superwall/workflows/migrate/adapty.md +6 -6
  88. package/dist/skills/superwall/workflows/migrate/playbook.md +4 -4
  89. package/dist/skills/superwall/workflows/migrate/qonversion.md +5 -5
  90. package/dist/skills/superwall/workflows/migrate/revenuecat.md +6 -6
  91. package/dist/skills/superwall/workflows/placements/android.md +2 -2
  92. package/dist/skills/superwall/workflows/placements/expo.md +2 -2
  93. package/dist/skills/superwall/workflows/placements/flutter.md +2 -2
  94. package/dist/skills/superwall/workflows/placements/ios.md +2 -2
  95. package/dist/skills/superwall/workflows/placements/playbook.md +2 -2
  96. package/dist/skills/superwall/workflows/placements/react-native.md +2 -2
  97. package/dist/skills/superwall/workflows/placements/strategy.md +2 -2
  98. package/dist/skills/superwall/workflows/review/playbook.md +1 -1
  99. package/dist/skills/superwall-editor/SKILL.md +61 -0
  100. package/dist/skills/superwall-editor/references/cli.md +135 -0
  101. package/dist/skills/superwall-editor/references/design.md +51 -0
  102. package/dist/skills/superwall-editor/references/native-elements.md +171 -0
  103. package/dist/skills/superwall-editor/references/workflow.md +65 -0
  104. package/dist/skills/superwall-editor/scripts/sw-editor.sh +662 -0
  105. package/dist/skills/superwall-framework/SKILL.md +78 -28
  106. package/dist/skills/superwall-framework/references/cli.md +58 -28
  107. package/dist/skills/superwall-framework/references/examples.md +4 -3
  108. package/dist/skills/superwall-framework/references/layout.md +30 -8
  109. package/dist/skills/superwall-framework/references/migrate-from-editor.md +1 -1
  110. package/dist/skills/superwall-framework/references/onboarding-state.md +245 -0
  111. package/dist/skills/wwdc/SKILL.md +22 -0
  112. package/dist/skills/wwdc/references/docs.md +52 -0
  113. package/dist/skills/wwdc/scripts/wwdc.sh +266 -0
  114. package/dist/{skills-DPzlnfCK.js → skills-BvFOa4y6.js} +99 -122
  115. package/dist/skills-DMG4bpKk.js +14 -0
  116. package/dist/{spawn-DSoTXy_j.js → spawn-DmmmHIP-.js} +14 -12
  117. package/dist/spinner-CneRK5rk.js +294 -0
  118. package/dist/storage-DYvmIOHa.d.ts +16 -0
  119. package/dist/storage-s2Dnz-yl.js +31 -0
  120. package/dist/storekit-DafAnGkM.js +16 -0
  121. package/dist/storekit-yY_kS2iR.js +47 -0
  122. package/dist/telemetry-DtG92m5O.js +56 -0
  123. package/dist/theme-DUsCh-Vd.js +25 -0
  124. package/dist/timing-BVxPrYq3.js +5 -0
  125. package/dist/{token-C0it-Xh7.js → token-DzRh7dI1.js} +6 -38
  126. package/dist/tools.d.ts +96 -0
  127. package/dist/tools.js +11178 -0
  128. package/dist/ui-D_qf3Gvw.js +53 -0
  129. package/dist/upgrade-Bt4Ouw1y.js +117 -0
  130. package/dist/upgrade-Cqy5orjb.js +7 -0
  131. package/package.json +10 -5
  132. package/dist/api-CZzirVMj.js +0 -151
  133. package/dist/api-output-aJNw7Syy.js +0 -20
  134. package/dist/app-DH6U8yuI.js +0 -190
  135. package/dist/asa-C-sQzPPn.js +0 -1194
  136. package/dist/asc-1ZBJ6DwS.js +0 -778
  137. package/dist/auth-YRhlV3DE.js +0 -140
  138. package/dist/billing-CCYHdApx.js +0 -80
  139. package/dist/bundle-id-CKxl_026.js +0 -121
  140. package/dist/command-CMIz81Da.js +0 -301
  141. package/dist/dev-DZy6pOnB.js +0 -22
  142. package/dist/doctor-H-hf-Yww.js +0 -88
  143. package/dist/feedback-CKf-rpBW.js +0 -152
  144. package/dist/hosted-CXe9TrWx.js +0 -32
  145. package/dist/migrate-C9ERDR6y.js +0 -284
  146. package/dist/org-sj7uyvp-.js +0 -40
  147. package/dist/output-C4o2gJ1K.js +0 -146
  148. package/dist/params-l3CrvRtR.js +0 -51
  149. package/dist/pipeline-BqzqZhX1.js +0 -977
  150. package/dist/print-skill-ZojRSybs.js +0 -74
  151. package/dist/promote-BG8X4Nv_.js +0 -88
  152. package/dist/publish-sxLh-G4G.js +0 -35
  153. package/dist/push-bQ6Vxtg8.js +0 -35
  154. package/dist/query-_FbybaH-.js +0 -53
  155. package/dist/resource-CGIwSd29.js +0 -323
  156. package/dist/revenue-provider-ebsRINY8.js +0 -100
  157. package/dist/scope-BvzD-kO4.js +0 -223
  158. package/dist/skills-D_R-lEsK.js +0 -64
  159. package/dist/spinner-TWa0hia6.js +0 -18
  160. package/dist/storekit-Cj9Cpjcz.js +0 -29
  161. package/dist/telemetry-DeA1mvnT.js +0 -169
  162. package/dist/ui-Dy0b-9L8.js +0 -27738
  163. package/dist/update-B2fWIc4q.js +0 -59
  164. package/dist/upgrade-BmzkTKrh.js +0 -72
  165. /package/dist/{devtools-8EgLo86w.js → devtools-ByZ6XYnn.js} +0 -0
@@ -10,8 +10,17 @@ Use the CLI for every query. It resolves the current organization and authentica
10
10
  superwall query "SHOW TABLES FROM sw" --json
11
11
  superwall query "SELECT applicationId, name FROM sw.applications_rep FINAL LIMIT 20" --json
12
12
  superwall query --file report.sql --json
13
+ superwall query --file revenue.sql --app <id> --json
13
14
  ```
14
15
 
16
+ Queries about one app take `--app <id>`: it fills `{app:UInt64}` (used in every
17
+ example below), `{revenue_provider:String}` and
18
+ `{revenue_integrations:Array(String)}` as ClickHouse parameters, so the SQL
19
+ needs no hand-edited ids. Other values go in with `--param`, e.g.
20
+ `--param user_id=abc` for `{user_id:String}`. **Every revenue query filters by
21
+ the app's revenue provider** (see "Revenue provider" below), or it double-counts
22
+ apps that send revenue from both the store and RevenueCat.
23
+
15
24
  Agents should reach for `superwall query` proactively for revenue questions,
16
25
  subscription health, conversion analysis, user behavior, ad hoc investigation,
17
26
  custom dashboards, and reusable reports. Create recurring schedules or send notifications only
@@ -214,7 +223,7 @@ These are system events emitted by the SDK:
214
223
  -- Check SDK configuration (purchase controller, StoreKit version)
215
224
  SELECT props
216
225
  FROM sw.events_rep
217
- WHERE applicationId = {app_id}
226
+ WHERE applicationId = {app:UInt64}
218
227
  AND name = 'config_attributes'
219
228
  AND ts > toStartOfHour(now() - INTERVAL 1 HOUR) AND ts < now()
220
229
  LIMIT 1
@@ -232,7 +241,7 @@ LIMIT 1
232
241
  -- Recent event volume by name for an app
233
242
  SELECT name, count() as cnt
234
243
  FROM sw.events_rep
235
- WHERE applicationId = {app_id} AND isSandbox = 0
244
+ WHERE applicationId = {app:UInt64} AND isSandbox = 0
236
245
  AND ts > toStartOfHour(now() - INTERVAL 7 DAY) AND ts < now()
237
246
  GROUP BY name ORDER BY cnt DESC LIMIT 30
238
247
  ```
@@ -299,7 +308,7 @@ SETTINGS index_granularity = 8192
299
308
  -- Demand score distribution for an app
300
309
  SELECT demandScore, count() as cnt
301
310
  FROM sw.demand_score_events_rep
302
- WHERE applicationId = {app_id} AND isSandbox = 0
311
+ WHERE applicationId = {app:UInt64} AND isSandbox = 0
303
312
  AND ts >= now() - INTERVAL 30 DAY AND demandScore >= 0
304
313
  GROUP BY demandScore ORDER BY demandScore
305
314
  ```
@@ -311,7 +320,7 @@ SELECT name,
311
320
  quantile(0.5)(demandScore) as p50,
312
321
  quantile(0.95)(demandScore) as p95
313
322
  FROM sw.demand_score_events_rep
314
- WHERE applicationId = {app_id} AND isSandbox = 0
323
+ WHERE applicationId = {app:UInt64} AND isSandbox = 0
315
324
  AND ts >= now() - INTERVAL 7 DAY AND demandScore >= 0
316
325
  GROUP BY name
317
326
  ```
@@ -363,7 +372,7 @@ SELECT name, sum(hourly_uniques) as total
363
372
  FROM (
364
373
  SELECT name, ts, uniqMerge(count) as hourly_uniques
365
374
  FROM sw.events_hr_agg
366
- WHERE applicationId = {app_id} AND isSandbox = 0
375
+ WHERE applicationId = {app:UInt64} AND isSandbox = 0
367
376
  AND ts >= now() - INTERVAL 7 DAY AND ts < now()
368
377
  GROUP BY name, ts
369
378
  ) GROUP BY name ORDER BY total DESC
@@ -375,7 +384,7 @@ FROM (
375
384
  -- Hourly unique event count for an app (recent)
376
385
  SELECT ts, name, source, uniqMerge(count) as unique_events
377
386
  FROM sw.events_hr_agg
378
- WHERE applicationId = {app_id} AND isSandbox = 0
387
+ WHERE applicationId = {app:UInt64} AND isSandbox = 0
379
388
  AND ts >= now() - INTERVAL 2 DAY AND ts < now()
380
389
  GROUP BY ts, name, source
381
390
  ORDER BY ts DESC LIMIT 20
@@ -385,7 +394,7 @@ ORDER BY ts DESC LIMIT 20
385
394
  -- Check if an app is sending events (last 5 minutes proxy: check last hour)
386
395
  SELECT name, uniqMerge(count) as cnt
387
396
  FROM sw.events_hr_agg
388
- WHERE applicationId = {app_id} AND isSandbox = 0
397
+ WHERE applicationId = {app:UInt64} AND isSandbox = 0
389
398
  AND ts >= now() - INTERVAL 1 HOUR AND ts < now()
390
399
  GROUP BY name ORDER BY cnt DESC
391
400
  ```
@@ -438,7 +447,7 @@ SELECT
438
447
  JSONExtractString(props, '$subscription_status') as status,
439
448
  count() as cnt
440
449
  FROM sw.subscription_status_rep FINAL
441
- WHERE applicationId = {app_id} AND isSandbox = 0 AND isDeleted = 0
450
+ WHERE applicationId = {app:UInt64} AND isSandbox = 0 AND isDeleted = 0
442
451
  GROUP BY status ORDER BY cnt DESC
443
452
  ```
444
453
 
@@ -448,14 +457,14 @@ SELECT appUserId,
448
457
  JSONExtractString(props, '$subscription_status') as status,
449
458
  ts
450
459
  FROM sw.subscription_status_rep FINAL
451
- WHERE applicationId = {app_id} AND appUserId = '{user_id}' AND isSandbox = 0
460
+ WHERE applicationId = {app:UInt64} AND appUserId = {user_id:String} AND isSandbox = 0
452
461
  ```
453
462
 
454
463
  ```sql
455
464
  -- Count active subscribers
456
465
  SELECT count() as active_subscribers
457
466
  FROM sw.subscription_status_rep FINAL
458
- WHERE applicationId = {app_id} AND isSandbox = 0 AND isDeleted = 0
467
+ WHERE applicationId = {app:UInt64} AND isSandbox = 0 AND isDeleted = 0
459
468
  AND JSONExtractString(props, '$subscription_status') = 'ACTIVE'
460
469
  ```
461
470
 
@@ -515,8 +524,8 @@ App-specific: `first_name`, `created_at`, `subscription_canceled`, `apns_token`,
515
524
  -- Get all attributes for a specific user
516
525
  SELECT key, type, value, ts
517
526
  FROM sw.user_attributes_rep FINAL
518
- WHERE applicationId = {app_id} AND isSandbox = 0
519
- AND appUserId = '{user_id}' AND isDeleted = 0
527
+ WHERE applicationId = {app:UInt64} AND isSandbox = 0
528
+ AND appUserId = {user_id:String} AND isDeleted = 0
520
529
  ORDER BY key
521
530
  ```
522
531
 
@@ -524,7 +533,7 @@ ORDER BY key
524
533
  -- List available attribute keys for an app
525
534
  SELECT key, count() as user_count, any(type) as sample_type
526
535
  FROM sw.user_attributes_rep FINAL
527
- WHERE applicationId = {app_id} AND isSandbox = 0 AND isDeleted = 0
536
+ WHERE applicationId = {app:UInt64} AND isSandbox = 0 AND isDeleted = 0
528
537
  GROUP BY key ORDER BY user_count DESC LIMIT 30
529
538
  ```
530
539
 
@@ -532,7 +541,7 @@ GROUP BY key ORDER BY user_count DESC LIMIT 30
532
541
  -- Segment users by an attribute value
533
542
  SELECT value as subscription_status, uniq(appUserId) as users
534
543
  FROM sw.user_attributes_rep FINAL
535
- WHERE applicationId = {app_id} AND isSandbox = 0 AND isDeleted = 0
544
+ WHERE applicationId = {app:UInt64} AND isSandbox = 0 AND isDeleted = 0
536
545
  AND key = 'paying_user'
537
546
  GROUP BY value ORDER BY users DESC
538
547
  ```
@@ -643,9 +652,32 @@ SETTINGS index_granularity = 8192
643
652
  ##### Source and Integration
644
653
 
645
654
  - **source**: `sdk` (from Superwall SDK `transaction_complete`) or `integration` (from RevenueCat, App Store Connect, etc.)
646
- - **integration values**: `revenue_cat`, `app_store_connect`
655
+ - **integration values**: `app_store_connect`, `google_play`, `stripe`, `revenue_cat`
647
656
  - `transaction_complete` events always have source=`sdk`; all other event names come from integrations
648
657
 
658
+ ##### Revenue provider — filter every revenue query by it
659
+
660
+ An app that receives revenue from its store *and* RevenueCat gets the same
661
+ purchase from both. Its **revenue provider** decides which one the dashboard
662
+ counts, and a query must count the same rows to match it:
663
+
664
+ | Provider (`apps get`) | `integration` rows counted |
665
+ | --- | --- |
666
+ | `open_revenue` | `app_store_connect`, `google_play`, `stripe` |
667
+ | `revenue_cat` | `revenue_cat`, `stripe` |
668
+ | none chosen | every integration |
669
+
670
+ Rows with `source = 'sdk'` always count, and RevenueCat's copies of Stripe
671
+ purchases never do. `superwall query --app <id>` passes the app's list as
672
+ `{revenue_integrations:Array(String)}` (and the id as `{app:UInt64}`), so write
673
+ the filter once and let the CLI fill it:
674
+
675
+ ```sql
676
+ WHERE applicationId = {app:UInt64}
677
+ AND (integration IN {revenue_integrations:Array(String)} OR source = 'sdk')
678
+ AND NOT (coalesce(integration, '') = 'revenue_cat' AND store = 'STRIPE')
679
+ ```
680
+
649
681
  ##### Attribution
650
682
 
651
683
  - **attributionEventId**: Non-empty when the revenue event is attributed to a Superwall paywall presentation
@@ -687,7 +719,7 @@ name = 'billing_issue' AND lower(periodType) = 'trial' -- Trial billing iss
687
719
 
688
720
  #### Dedup Pattern for Revenue
689
721
 
690
- Events can arrive from multiple sources (SDK + RevenueCat + App Store Connect). Dedup by `(applicationId, name, originalTransactionId, transactionId, attributed)`:
722
+ Events can arrive from multiple sources (SDK + RevenueCat + App Store Connect). Filter by the app's revenue provider (above), then dedup by `(applicationId, name, originalTransactionId, transactionId, attributed)`:
691
723
 
692
724
  ```sql
693
725
  SELECT applicationId, attributed,
@@ -701,7 +733,9 @@ FROM (
701
733
  attributionEventId != '' as attributed,
702
734
  argMax(price, ts) AS price
703
735
  FROM open_revenue.attributed_events_by_ts_rep FINAL
704
- WHERE isSandbox = 0 AND applicationId = {app_id}
736
+ WHERE isSandbox = 0 AND applicationId = {app:UInt64}
737
+ AND (integration IN {revenue_integrations:Array(String)} OR source = 'sdk')
738
+ AND NOT (coalesce(integration, '') = 'revenue_cat' AND store = 'STRIPE')
705
739
  AND ts >= now() - INTERVAL 90 DAY AND ts < now()
706
740
  AND isFamilyShare = 0
707
741
  GROUP BY applicationId, name, originalTransactionId, transactionId, attributed
@@ -724,7 +758,7 @@ WITH opens AS (
724
758
  CASE WHEN breakdown['paywallId'] IN ('id1','id2') THEN 'a' ELSE 'b' END as seg,
725
759
  uniqIfMerge(vendorIds) as open_users
726
760
  FROM open_revenue.sdk_events_agg
727
- WHERE applicationId = {app_id} AND isSandbox = 0
761
+ WHERE applicationId = {app:UInt64} AND isSandbox = 0
728
762
  AND name = 'paywall_open' AND tsType = 'event_time'
729
763
  AND ts >= now() - INTERVAL 45 DAY AND ts < now()
730
764
  GROUP BY day, seg
@@ -792,7 +826,7 @@ SELECT paywallId, placement, experimentId, variantId,
792
826
  uniqMerge(users_state) as unique_users,
793
827
  uniqMerge(views_state) as total_views
794
828
  FROM open_revenue.paywall_open_events_agg
795
- WHERE applicationId = {app_id} AND environment = 'PRODUCTION'
829
+ WHERE applicationId = {app:UInt64} AND environment = 'PRODUCTION'
796
830
  GROUP BY paywallId, placement, experimentId, variantId
797
831
  ORDER BY unique_users DESC LIMIT 20
798
832
  ```
@@ -803,7 +837,7 @@ SELECT variantId,
803
837
  uniqMerge(users_state) as unique_users,
804
838
  uniqMerge(views_state) as total_views
805
839
  FROM open_revenue.paywall_open_events_agg
806
- WHERE applicationId = {app_id} AND environment = 'PRODUCTION'
840
+ WHERE applicationId = {app:UInt64} AND environment = 'PRODUCTION'
807
841
  AND experimentId = {exp_id}
808
842
  GROUP BY variantId ORDER BY variantId
809
843
  ```
@@ -838,7 +872,7 @@ Pre-aggregated SDK events. Much faster than raw tables for counts/uniques.
838
872
  -- Weekly installs
839
873
  SELECT toStartOfWeek(ts, 1) as week, uniqIfMerge(vendorIds) as installs
840
874
  FROM open_revenue.sdk_events_agg
841
- WHERE applicationId = {app_id} AND isSandbox = 0
875
+ WHERE applicationId = {app:UInt64} AND isSandbox = 0
842
876
  AND name = 'first_seen' AND tsType = 'install_time'
843
877
  AND ts >= now() - INTERVAL 90 DAY AND ts < now()
844
878
  GROUP BY week ORDER BY week
@@ -33,14 +33,14 @@ placement (in code) → campaign (routes it) → audience (who) → paywal
33
33
  2. **Find registered placements.** Grep the app for `register(`, `registerPlacement(`,
34
34
  `usePlacement(`, `Superwall.shared.register` - collect the exact event-name strings.
35
35
  3. **Ensure an entitlement.** `superwall entitlements list --project <id> --json`; reuse an existing one, else
36
- `superwall entitlements create pro --project <id> --json`. Default to a single `pro` entitlement unless the
36
+ `superwall entitlements create --identifier pro --project <id> --json`. Default to a single `pro` entitlement unless the
37
37
  app clearly has tiers.
38
38
  4. **Ensure products.** `superwall products list --project <id> --json` first. If none:
39
39
  - App Store Connect connected (`superwall asc keys list --json`) → import (see `setup.md` beside this file).
40
40
  - Otherwise create with real pricing:
41
- `superwall products create pro_yearly --price 39.99 --period year --trial-days 7 --entitlement pro --project <id> --json`
41
+ `superwall products create --identifier pro_yearly --price 39.99 --period year --trial-days 7 --entitlement pro --project <id> --json`
42
42
  5. **Carry each placement.** `superwall campaigns list --project <id> --app <id> --json`. For each placement not already on
43
- a campaign: `superwall campaigns create "<description>" <placement> --project <id> --app <id> --json` (campaigns require an initial placement; it seeds a 100% holdout audience), or add more with `superwall campaigns placement <campaignId> <placement> --project <id> --app <id> --json`.
43
+ a campaign: `superwall campaigns create --description "<description>" --placement <placement> --project <id> --app <id> --json` (campaigns require an initial placement; it seeds a 100% holdout audience), or add more with `superwall campaigns placements create <campaignId> --event-name <placement> --project <id> --app <id> --json`.
44
44
 
45
45
  ## Guardrails
46
46
 
@@ -18,7 +18,7 @@ single app the CLI auto-scopes; agents always pass the flags explicitly.
18
18
  ### Create by hand (real pricing)
19
19
 
20
20
  ```bash
21
- superwall products create <identifier> \
21
+ superwall products create --identifier <identifier> \
22
22
  --price 39.99 \ # major units; converted to cents for you
23
23
  --currency USD \ # default USD
24
24
  --period year \ # day | week | month | year
@@ -39,7 +39,7 @@ There is **no** `products import` subcommand. `superwall integrate --skill`
39
39
  prints the full setup instructions without spawning another agent. To import
40
40
  products yourself, use credentials the user has already connected privately,
41
41
  enumerate via the signed ASC proxy, then create products in the approved scope.
42
- If credentials are missing, have the user consult `superwall asc keys set --help`
42
+ If credentials are missing, have the user consult `superwall asc keys create --help`
43
43
  at their own terminal and complete setup themselves. Do not request, inspect,
44
44
  or upload their private key.
45
45
 
@@ -47,13 +47,13 @@ or upload their private key.
47
47
  superwall asc keys list --json # confirm connected; note the team id
48
48
 
49
49
  # enumerate real products for the app (by bundle id or ASC app id)
50
- superwall asc subscriptions com.app.bundle --json # renewing subs
51
- superwall asc iaps com.app.bundle --json # one-time / non-renewing
50
+ superwall asc subscriptions list com.app.bundle --json # renewing subs
51
+ superwall asc iaps list com.app.bundle --json # one-time / non-renewing
52
52
  superwall asc products com.app.bundle --json # everything
53
53
  superwall asc apps --json # list ASC apps if unsure of the id
54
54
 
55
55
  # create each returned productId, granting your entitlement
56
- superwall products create com.app.pro.yearly --entitlement pro --project <id> --json
56
+ superwall products create --identifier com.app.pro.yearly --entitlement pro --project <id> --json
57
57
  ```
58
58
 
59
59
  Products imported this way carry only the identifier (and reference name); Xcode/StoreKit and
@@ -71,7 +71,7 @@ Seeds product identifiers into a StoreKit configuration file; Xcode refines pric
71
71
 
72
72
  ```bash
73
73
  superwall entitlements list --project <id> --json
74
- superwall entitlements create pro --project <id> --json
74
+ superwall entitlements create --identifier pro --project <id> --json
75
75
  ```
76
76
 
77
77
  Default to a single coarse `pro` entitlement. Add more only for genuine tiers (e.g. `pro`,
@@ -81,8 +81,8 @@ Default to a single coarse `pro` entitlement. Add more only for genuine tiers (e
81
81
 
82
82
  ```bash
83
83
  superwall campaigns list --project <id> --app <id> --json
84
- superwall campaigns create "Onboarding" onboarding_complete --project <id> --app <id> --json
85
- superwall campaigns placement <campaignId> another_placement --project <id> --app <id> --json
84
+ superwall campaigns create --description "Onboarding" --placement onboarding_complete --project <id> --app <id> --json
85
+ superwall campaigns placements create <campaignId> --event-name another_placement --project <id> --app <id> --json
86
86
  ```
87
87
 
88
88
  - `create` takes a **description**, not an identifier - name it for the surface.
@@ -119,14 +119,14 @@ Produce: product ids, access-level ids (→ entitlements), and one row per `getP
119
119
  ## 4. Dashboard-side re-creation (CLI)
120
120
 
121
121
  ```bash
122
- superwall entitlements create premium --project <projectId> --json
123
- superwall products create com.app.premium_monthly --name "Premium Monthly" --project <projectId> --json
124
- superwall products create com.app.premium_yearly --name "Premium Yearly" --project <projectId> --json
125
- superwall campaigns create "Main paywall" main --project <projectId> --app <appId> --json
126
- superwall campaigns placement <campaignId> onboarding --project <projectId> --app <appId> --json
122
+ superwall entitlements create --identifier premium --project <projectId> --json
123
+ superwall products create --identifier com.app.premium_monthly --name "Premium Monthly" --project <projectId> --json
124
+ superwall products create --identifier com.app.premium_yearly --name "Premium Yearly" --project <projectId> --json
125
+ superwall campaigns create --description "Main paywall" --placement main --project <projectId> --app <appId> --json
126
+ superwall campaigns placements create <campaignId> --event-name onboarding --project <projectId> --app <appId> --json
127
127
  ```
128
128
 
129
- Product ids MUST equal existing App Store / Play SKUs (import from ASC via `superwall asc keys set --help`).
129
+ Product ids MUST equal existing App Store / Play SKUs (import from ASC via `superwall asc keys create --help`).
130
130
  Verify with the same explicit ids: `superwall entitlements list --project <projectId> --json`,
131
131
  `superwall products list --project <projectId> --json`, and `superwall campaigns list --project <projectId> --app <appId> --json`.
132
132
 
@@ -68,10 +68,10 @@ Agents always use `--json` and explicit scope:
68
68
  superwall whoami --json
69
69
  superwall apps list --json
70
70
  superwall entitlements list --project <projectId> --json
71
- superwall entitlements create <id> --project <projectId> --json
71
+ superwall entitlements create --identifier <id> --project <projectId> --json
72
72
  superwall products list --project <projectId> --json
73
- superwall products create <storeId> --project <projectId> --json
73
+ superwall products create --identifier <storeId> --project <projectId> --json
74
74
  superwall campaigns list --project <projectId> --app <appId> --json
75
- superwall campaigns create "<description>" <placement> --project <projectId> --app <appId> --json
76
- superwall campaigns placement <campaignId> <placement> --project <projectId> --app <appId> --json
75
+ superwall campaigns create --description "<description>" --placement <placement> --project <projectId> --app <appId> --json
76
+ superwall campaigns placements create <campaignId> --event-name <placement> --project <projectId> --app <appId> --json
77
77
  ```
@@ -116,13 +116,13 @@ Produce: product ids, entitlement/permission ids (→ entitlements), and one row
116
116
  ## 4. Dashboard-side re-creation (CLI)
117
117
 
118
118
  ```bash
119
- superwall entitlements create premium --project <projectId> --json
120
- superwall products create com.app.premium_monthly --name "Premium Monthly" --project <projectId> --json
121
- superwall products create com.app.premium_yearly --name "Premium Yearly" --project <projectId> --json
122
- superwall campaigns create "Main paywall" paywall_main --project <projectId> --app <appId> --json
119
+ superwall entitlements create --identifier premium --project <projectId> --json
120
+ superwall products create --identifier com.app.premium_monthly --name "Premium Monthly" --project <projectId> --json
121
+ superwall products create --identifier com.app.premium_yearly --name "Premium Yearly" --project <projectId> --json
122
+ superwall campaigns create --description "Main paywall" --placement paywall_main --project <projectId> --app <appId> --json
123
123
  ```
124
124
 
125
- Product ids MUST equal existing App Store / Play SKUs (import from ASC via `superwall asc keys set --help`).
125
+ Product ids MUST equal existing App Store / Play SKUs (import from ASC via `superwall asc keys create --help`).
126
126
  Verify with the same explicit ids: `superwall entitlements list --project <projectId> --json`,
127
127
  `superwall products list --project <projectId> --json`, and `superwall campaigns list --project <projectId> --app <appId> --json`.
128
128
 
@@ -203,18 +203,18 @@ call the migration complete with dashboard work silently skipped.
203
203
  For each entitlement and product found, use the project/app ids from the account gate:
204
204
 
205
205
  ```bash
206
- superwall entitlements create pro --project <projectId> --json
207
- superwall products create com.app.pro_monthly --name "Pro Monthly" --project <projectId> --json
208
- superwall products create com.app.pro_yearly --name "Pro Yearly" --project <projectId> --json
206
+ superwall entitlements create --identifier pro --project <projectId> --json
207
+ superwall products create --identifier com.app.pro_monthly --name "Pro Monthly" --project <projectId> --json
208
+ superwall products create --identifier com.app.pro_yearly --name "Pro Yearly" --project <projectId> --json
209
209
  ```
210
210
 
211
211
  Product ids MUST equal the existing App Store / Play SKUs (import via ASC connection instead of
212
- manual create when possible - `superwall asc keys set --help`). Then one campaign with
212
+ manual create when possible - `superwall asc keys create --help`). Then one campaign with
213
213
  a placement per call site:
214
214
 
215
215
  ```bash
216
- superwall campaigns create "Main paywall" start_workout --project <projectId> --app <appId> --json
217
- superwall campaigns placement <campaignId> unlock_export --project <projectId> --app <appId> --json
216
+ superwall campaigns create --description "Main paywall" --placement start_workout --project <projectId> --app <appId> --json
217
+ superwall campaigns placements create <campaignId> --event-name unlock_export --project <projectId> --app <appId> --json
218
218
  ```
219
219
 
220
220
  Verify with the same explicit ids: `superwall entitlements list --project <projectId> --json`,
@@ -147,8 +147,8 @@ A placement is inert without a campaign:
147
147
 
148
148
  ```bash
149
149
  superwall campaigns list --project <id> --app <id> --json
150
- superwall campaigns create "Editor upgrade paywall" unlock_export --project <id> --app <id> --json
151
- superwall campaigns placement <campaignId> another_placement --project <id> --app <id> --json
150
+ superwall campaigns create --description "Editor upgrade paywall" --placement unlock_export --project <id> --app <id> --json
151
+ superwall campaigns placements create <campaignId> --event-name another_placement --project <id> --app <id> --json
152
152
  ```
153
153
 
154
154
  ## Pitfalls
@@ -131,8 +131,8 @@ function AddProjectButton({ count, freeLimit }: { count: number; freeLimit: numb
131
131
 
132
132
  ```bash
133
133
  superwall campaigns list --project <id> --app <id> --json
134
- superwall campaigns create "Editor upgrade paywall" unlock_export --project <id> --app <id> --json
135
- superwall campaigns placement <campaignId> another_placement --project <id> --app <id> --json
134
+ superwall campaigns create --description "Editor upgrade paywall" --placement unlock_export --project <id> --app <id> --json
135
+ superwall campaigns placements create <campaignId> --event-name another_placement --project <id> --app <id> --json
136
136
  ```
137
137
 
138
138
  ## Pitfalls
@@ -113,8 +113,8 @@ ElevatedButton(
113
113
 
114
114
  ```bash
115
115
  superwall campaigns list --project <id> --app <id> --json
116
- superwall campaigns create "Editor upgrade paywall" unlock_export --project <id> --app <id> --json
117
- superwall campaigns placement <campaignId> another_placement --project <id> --app <id> --json
116
+ superwall campaigns create --description "Editor upgrade paywall" --placement unlock_export --project <id> --app <id> --json
117
+ superwall campaigns placements create <campaignId> --event-name another_placement --project <id> --app <id> --json
118
118
  ```
119
119
 
120
120
  ## Pitfalls
@@ -140,8 +140,8 @@ A placement is inert without a campaign:
140
140
 
141
141
  ```bash
142
142
  superwall campaigns list --project <id> --app <id> --json
143
- superwall campaigns create "Editor upgrade paywall" unlock_export --project <id> --app <id> --json
144
- superwall campaigns placement <campaignId> another_placement --project <id> --app <id> --json
143
+ superwall campaigns create --description "Editor upgrade paywall" --placement unlock_export --project <id> --app <id> --json
144
+ superwall campaigns placements create <campaignId> --event-name another_placement --project <id> --app <id> --json
145
145
  ```
146
146
 
147
147
  ## Pitfalls
@@ -46,8 +46,8 @@ Exact API, gating semantics, placement examples, audit checklist, and pitfalls:
46
46
  A placement cannot present a paywall until a campaign routes it in the dashboard:
47
47
 
48
48
  - `superwall campaigns list --project <id> --app <id> --json` - existing campaigns and placements.
49
- - `superwall campaigns create "<description>" <placement_name> --project <id> --app <id> --json` - create one with its required first placement.
50
- - `superwall campaigns placement <campaignId> <placement_name> --project <id> --app <id> --json` - route another placement.
49
+ - `superwall campaigns create --description "<description>" --placement <placement_name> --project <id> --app <id> --json` - create one with its required first placement.
50
+ - `superwall campaigns placements create <campaignId> --event-name <placement_name> --project <id> --app <id> --json` - route another placement.
51
51
 
52
52
  Analytics-only, future, and paused placements may intentionally remain unrouted.
53
53
  For placements expected to present now, use one campaign per distinct paywall
@@ -116,8 +116,8 @@ function AddProjectButton({ count, freeLimit }: { count: number; freeLimit: numb
116
116
 
117
117
  ```bash
118
118
  superwall campaigns list --project <id> --app <id> --json
119
- superwall campaigns create "Editor upgrade paywall" unlock_export --project <id> --app <id> --json
120
- superwall campaigns placement <campaignId> another_placement --project <id> --app <id> --json
119
+ superwall campaigns create --description "Editor upgrade paywall" --placement unlock_export --project <id> --app <id> --json
120
+ superwall campaigns placements create <campaignId> --event-name another_placement --project <id> --app <id> --json
121
121
  ```
122
122
 
123
123
  ## Pitfalls
@@ -213,8 +213,8 @@ user sees. Analytics-only or future placements can remain unrouted intentionally
213
213
 
214
214
  ```bash
215
215
  superwall campaigns list --project <id> --app <id> --json
216
- superwall campaigns create "Editor upgrade paywall" unlock_export --project <id> --app <id> --json
217
- superwall campaigns placement <campaignId> another_placement --project <id> --app <id> --json
216
+ superwall campaigns create --description "Editor upgrade paywall" --placement unlock_export --project <id> --app <id> --json
217
+ superwall campaigns placements create <campaignId> --event-name another_placement --project <id> --app <id> --json
218
218
  ```
219
219
 
220
220
  Rule of thumb: one campaign per distinct paywall surface/decision (onboarding,
@@ -50,7 +50,7 @@ project/app ids and pass them to `superwall products list --project <id> --json`
50
50
  `superwall entitlements list --project <id> --json`, `superwall campaigns list
51
51
  --project <id> --app <id> --json`, and `superwall paywalls list --project <id>
52
52
  --app <id> --json`. When App Store Connect is linked,
53
- use `superwall asc subscriptions <bundle-id> --json` to compare store identifiers.
53
+ use `superwall asc subscriptions list <bundle-id> --json` to compare store identifiers.
54
54
 
55
55
  ## Framework reference
56
56
 
@@ -0,0 +1,61 @@
1
+ ---
2
+ name: superwall-editor
3
+ description: Build, edit, or review Superwall paywall, onboarding, and web2app flows from a local coding agent with terminal access. Launch a browser editor session through the local CLI or attach to one with a pairing code, then discover its current tools. Covers native sw-* elements, design standards, and the attach/call/release lifecycle.
4
+ ---
5
+
6
+ # Superwall Paywall Editor
7
+
8
+ Paywalls are built in a browser editor that exposes its tools over an authenticated relay. This skill drives the same surface used by the MCP gateway, so every tool runs inside the live browser session the user has open.
9
+
10
+ ## When to use
11
+
12
+ - The user wants to build, edit, or review a Superwall paywall, onboarding, or web2app flow.
13
+ - The user pastes a pairing code and asks you to take over editing.
14
+ - The user asks "what tools can you run right now?" Discover them via the browser, not from memory.
15
+
16
+ ## Start here: attach, then discover
17
+
18
+ Never assume a tool name or signature from memory. The browser is the source of truth and its tool set changes across releases.
19
+
20
+ For `--agent-name`, use your agent's recognized slug, such as `codex`, `claude`,
21
+ or `cursor`. Use `other` for Grok Build, Muse Code, or any agent not listed in
22
+ the [CLI reference](references/cli.md#agent-identity).
23
+
24
+ Preferred API launch flow:
25
+
26
+ 1. Create an auto-expose URL: `scripts/sw-editor.sh expose --application-id <id> --paywall-id <id> --agent-name <agent> --open --wait`
27
+ 2. Ask the user to complete browser authorization if prompted. The editor auto-exposes; do not ask them to click the expose button.
28
+ 3. Discover what is available right now: `scripts/sw-editor.sh tools`
29
+ 4. Invoke tools: `scripts/sw-editor.sh call <tool-name> --args '<json>'`
30
+
31
+ Fallback manual flow:
32
+
33
+ 1. Ask the user for the **pairing code** shown in the editor UI.
34
+ 2. Attach: `scripts/sw-editor.sh attach <pairing-code> --agent-name <agent>`
35
+ 3. Continue with `tools` and `call`.
36
+
37
+ Full CLI reference: [references/cli.md](references/cli.md).
38
+
39
+ ## How to build and edit
40
+
41
+ - Workflow, build order, and when to use which tool: [references/workflow.md](references/workflow.md)
42
+ - Native `sw-*` elements (multiple-choice, indicator, drawer, picker, lottie, navigation): [references/native-elements.md](references/native-elements.md)
43
+ - Design standards, review checkpoints, typography, and conversion principles: [references/design.md](references/design.md)
44
+
45
+ ## Orchestration rules
46
+
47
+ - Always establish an attachment before editing. Use `expose --open --wait` when possible, otherwise use `attach <pairing-code> --agent-name <agent>`. `tools`, `call`, `status`, `release` all require an attached session.
48
+ - Prefer `expose --open --wait` when you have `SUPERWALL_API_KEY`, an application id, and a paywall id. It uses the same relay as manual pairing but removes the human pairing-code step.
49
+ - Before calling a tool you have not used this session, run `tools` to confirm it exists and to read the current parameter schema. Tools are defined in the browser bundle, so an updated editor can ship new or renamed tools without changing this skill.
50
+ - Use `get_screenshot` (if present in the tool list) every two or three modifications to verify. Don't fly blind.
51
+ - Prefer semantic tools (`update_styles`, `set_text_content`, `set_dynamic_value`, `move_nodes`) over re-running `write_html` on existing structure. See `references/workflow.md`.
52
+ - Prefer native `sw-*` elements over hand-rolled `<div>` recreations whenever the UI represents a semantic control. See `references/native-elements.md`.
53
+ - When parsing CLI output, use `jq`, not Python. Example: `sw-editor.sh call get_subtree --args '...' | jq -r '.content[0].text'`
54
+ - Release when the user is done: `scripts/sw-editor.sh release`.
55
+
56
+ ## When things go wrong
57
+
58
+ - `session_not_ready`: the browser disconnected or reloaded. Ask the user to bring the editor tab back, then re-attach. The pairing code rotates, so they must provide the new one.
59
+ - `session_locked`: another client is already attached. The user either attached from another MCP client, or a previous CLI attachment wasn't released. They can detach from the editor UI and you can retry.
60
+ - `unauthorized`: the controller token is stale. Re-attach with a fresh pairing code.
61
+ - `attach_failed: provide a valid current pairingCode`: pairing codes expire after ~10 minutes and rotate on detach. Ask the user to show you the current one.