@superwall/cli 1.1.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 (85) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +201 -0
  3. package/dist/actions-MB-eBY64.js +140 -0
  4. package/dist/api-BF7-toqM.js +151 -0
  5. package/dist/api-output-B5hh0q4V.js +20 -0
  6. package/dist/app-K6j9Es7h.js +189 -0
  7. package/dist/asc-CArSwo5D.js +539 -0
  8. package/dist/asc-products-YQ6Oc6YO.js +93 -0
  9. package/dist/auth-CY2cO_NF.js +139 -0
  10. package/dist/auth.d.ts +30 -0
  11. package/dist/auth.js +4 -0
  12. package/dist/billing-DWyfEQ6l.js +80 -0
  13. package/dist/bind-hslFhcTR.js +213 -0
  14. package/dist/chunk-DQxbwPpZ.js +30 -0
  15. package/dist/command-Kwx4ekbo.js +283 -0
  16. package/dist/create-Bbi8BOO1.js +410 -0
  17. package/dist/dev-D0lQDCQI.js +397 -0
  18. package/dist/devtools-8EgLo86w.js +3638 -0
  19. package/dist/doctor-ByeRdMcl.js +88 -0
  20. package/dist/drivers-DVAZgone.js +413 -0
  21. package/dist/entry.d.ts +9 -0
  22. package/dist/entry.js +495 -0
  23. package/dist/existing-CcJrIIAU.js +88 -0
  24. package/dist/feedback-Z0Wk7VC5.js +73 -0
  25. package/dist/git-3OX9u3xE.js +433 -0
  26. package/dist/hosted-CHwaUqLd.js +32 -0
  27. package/dist/integrate-DqOAqK7J.js +863 -0
  28. package/dist/json-C3hPIMkI.js +7 -0
  29. package/dist/login-Dr8UN_Gx.js +290 -0
  30. package/dist/migrate-D92bJTg6.js +114 -0
  31. package/dist/org-B2gy9Pmu.js +40 -0
  32. package/dist/params-Bvq0iqQK.js +52 -0
  33. package/dist/pipeline-CHHIg6BU.js +1056 -0
  34. package/dist/print-skill-BnZAk7dV.js +74 -0
  35. package/dist/promote-CRe9170G.js +88 -0
  36. package/dist/publish-DsODvrOD.js +35 -0
  37. package/dist/push-BDkZUC0v.js +35 -0
  38. package/dist/query-DIllrSnk.js +53 -0
  39. package/dist/resource-CdP1MDla.js +483 -0
  40. package/dist/resources-CVrWwA1K.js +233 -0
  41. package/dist/run-cGGBUMs5.js +89 -0
  42. package/dist/scan-BQexuUPO.js +236 -0
  43. package/dist/skills-DhuUs28u.js +64 -0
  44. package/dist/skills-xrfXt9u0.js +205 -0
  45. package/dist/spawn-DSoTXy_j.js +69 -0
  46. package/dist/spinner-gOxIMz-V.js +18 -0
  47. package/dist/storekit-Ddvs4Ynw.js +29 -0
  48. package/dist/telemetry-CcfrtXdf.js +204 -0
  49. package/dist/token-DHRH8cxi.js +102 -0
  50. package/dist/ui-C4ncRJqd.js +27703 -0
  51. package/dist/update-BiVeR024.js +137 -0
  52. package/dist/upgrade-DYWspApv.js +72 -0
  53. package/package.json +87 -0
  54. package/prompts/actions/dashboard-setup.xml +10 -0
  55. package/prompts/actions/integrate.xml +5 -0
  56. package/prompts/actions/migrate.xml +11 -0
  57. package/prompts/actions/placements-implement.xml +20 -0
  58. package/prompts/actions/placements-review.xml +18 -0
  59. package/prompts/actions/review-fix.xml +18 -0
  60. package/prompts/actions/review.xml +18 -0
  61. package/prompts/commandments.xml +17 -0
  62. package/prompts/context.xml +9 -0
  63. package/skills/README.md +118 -0
  64. package/skills/superwall-dashboard/SKILL.md +81 -0
  65. package/skills/superwall-dashboard/references/setup.md +101 -0
  66. package/skills/superwall-integrate/SKILL.md +76 -0
  67. package/skills/superwall-integrate/references/expo.md +269 -0
  68. package/skills/superwall-integrate/references/flutter.md +285 -0
  69. package/skills/superwall-integrate/references/ios.md +314 -0
  70. package/skills/superwall-integrate/references/react-native.md +245 -0
  71. package/skills/superwall-migrate/SKILL.md +83 -0
  72. package/skills/superwall-migrate/references/adapty.md +229 -0
  73. package/skills/superwall-migrate/references/qonversion.md +227 -0
  74. package/skills/superwall-migrate/references/revenuecat.md +414 -0
  75. package/skills/superwall-placements/SKILL.md +73 -0
  76. package/skills/superwall-placements/references/expo.md +161 -0
  77. package/skills/superwall-placements/references/flutter.md +139 -0
  78. package/skills/superwall-placements/references/ios.md +165 -0
  79. package/skills/superwall-placements/references/react-native.md +145 -0
  80. package/skills/superwall-placements/references/strategy.md +221 -0
  81. package/skills/superwall-review/SKILL.md +75 -0
  82. package/skills/superwall-review/references/expo.md +100 -0
  83. package/skills/superwall-review/references/flutter.md +99 -0
  84. package/skills/superwall-review/references/ios.md +108 -0
  85. package/skills/superwall-review/references/react-native.md +100 -0
@@ -0,0 +1,137 @@
1
+ import { k as VERSION, p as getUpdateCheck, v as setUpdateCheck } from "./telemetry-CcfrtXdf.js";
2
+ import { t as formatJson } from "./json-C3hPIMkI.js";
3
+ import pc from "picocolors";
4
+ import { stripVTControlCharacters } from "node:util";
5
+
6
+ //#region src/output.ts
7
+ const blocks = {
8
+ intro: (text) => ({
9
+ kind: "intro",
10
+ text
11
+ }),
12
+ step: (text) => ({
13
+ kind: "step",
14
+ text
15
+ }),
16
+ info: (text) => ({
17
+ kind: "info",
18
+ text
19
+ }),
20
+ success: (text) => ({
21
+ kind: "success",
22
+ text
23
+ }),
24
+ warning: (text) => ({
25
+ kind: "warning",
26
+ text
27
+ }),
28
+ report: (text) => ({
29
+ kind: "report",
30
+ text
31
+ }),
32
+ list: (value) => ({
33
+ kind: "list",
34
+ value
35
+ }),
36
+ nextSteps: (items) => ({
37
+ kind: "nextSteps",
38
+ items
39
+ }),
40
+ outro: (text) => ({
41
+ kind: "outro",
42
+ text
43
+ })
44
+ };
45
+ function writeJson(stream, value) {
46
+ stream.write(`${formatJson(value)}\n`);
47
+ }
48
+ function createCommandOutput(mode, renderer, streams = { stdout: process.stdout }) {
49
+ return {
50
+ mode,
51
+ data(value) {
52
+ if (mode === "json") writeJson(streams.stdout, value);
53
+ else renderer.report(formatJson(value));
54
+ },
55
+ text(value) {
56
+ if (mode === "json") throw new Error("This command must return structured JSON in --json mode.");
57
+ const text = value.replace(/\n$/, "");
58
+ renderer.report(mode === "text" ? stripVTControlCharacters(text) : text);
59
+ },
60
+ render(...blocks$1) {
61
+ if (mode === "json") return;
62
+ for (const block of blocks$1) renderBlock(renderer, block);
63
+ }
64
+ };
65
+ }
66
+ function renderBlock(renderer, block) {
67
+ switch (block.kind) {
68
+ case "intro": return renderer.intro(block.text);
69
+ case "step": return renderer.step(block.text);
70
+ case "info": return renderer.info(block.text);
71
+ case "success": return renderer.success(block.text);
72
+ case "warning": return renderer.warn(block.text);
73
+ case "report": return renderer.report(block.text);
74
+ case "list": return renderer.list(block.value);
75
+ case "nextSteps":
76
+ if (block.items.length) renderer.note(block.items.map((item, index) => `${index + 1}. ${item}`).join("\n"), "Next steps");
77
+ return;
78
+ case "outro": return renderer.outro(block.text);
79
+ }
80
+ }
81
+
82
+ //#endregion
83
+ //#region src/core/update.ts
84
+ const CHECK_INTERVAL_MS = 1440 * 60 * 1e3;
85
+ const REGISTRY_URL = "https://registry.npmjs.org/superwall/latest";
86
+ const pending = [];
87
+ function isNewerVersion(latest, current) {
88
+ const l = latest.split(".").map((n) => parseInt(n, 10));
89
+ const c = current.split(".").map((n) => parseInt(n, 10));
90
+ for (let i = 0; i < 3; i++) {
91
+ const a = l[i] ?? 0;
92
+ const b = c[i] ?? 0;
93
+ if (Number.isNaN(a) || Number.isNaN(b)) return false;
94
+ if (a !== b) return a > b;
95
+ }
96
+ return false;
97
+ }
98
+ async function fetchLatestVersion() {
99
+ try {
100
+ const res = await fetch(REGISTRY_URL, {
101
+ headers: { accept: "application/json" },
102
+ signal: AbortSignal.timeout(5e3)
103
+ });
104
+ if (!res.ok) return null;
105
+ const { version } = await res.json();
106
+ return version ?? null;
107
+ } catch {
108
+ return null;
109
+ }
110
+ }
111
+ function availableUpdate() {
112
+ const cached = getUpdateCheck();
113
+ return cached?.latest && isNewerVersion(cached.latest, VERSION) ? cached.latest : null;
114
+ }
115
+ function refreshUpdateCheck() {
116
+ if (process.env.NODE_TEST_CONTEXT) return;
117
+ const cached = getUpdateCheck();
118
+ if ((cached?.checkedAt ? Date.now() - Date.parse(cached.checkedAt) : Infinity) < CHECK_INTERVAL_MS) return;
119
+ pending.push(fetchLatestVersion().then((version) => {
120
+ if (version) setUpdateCheck({
121
+ latest: version,
122
+ checkedAt: (/* @__PURE__ */ new Date()).toISOString()
123
+ });
124
+ }));
125
+ }
126
+ async function flushUpdateCheck(capMs = 2e3) {
127
+ if (pending.length === 0) return;
128
+ await Promise.race([Promise.allSettled(pending), new Promise((done) => setTimeout(done, capMs).unref())]);
129
+ }
130
+ function maybeNotifyUpdate(stream) {
131
+ const latest = availableUpdate();
132
+ if (!latest) return;
133
+ stream.write(`${pc.dim(`Update available ${VERSION} → ${latest} · run \`superwall upgrade\``)}\n`);
134
+ }
135
+
136
+ //#endregion
137
+ export { refreshUpdateCheck as a, writeJson as c, maybeNotifyUpdate as i, flushUpdateCheck as n, blocks as o, isNewerVersion as r, createCommandOutput as s, fetchLatestVersion as t };
@@ -0,0 +1,72 @@
1
+ import { k as VERSION, v as setUpdateCheck } from "./telemetry-CcfrtXdf.js";
2
+ import "./json-C3hPIMkI.js";
3
+ import { r as isNewerVersion, t as fetchLatestVersion } from "./update-BiVeR024.js";
4
+ import "./token-DHRH8cxi.js";
5
+ import { t as defineCommand } from "./command-Kwx4ekbo.js";
6
+ import "./ui-C4ncRJqd.js";
7
+ import { r as spawnStream } from "./spawn-DSoTXy_j.js";
8
+
9
+ //#region src/commands/account/upgrade.ts
10
+ const runUpgrade = defineCommand({
11
+ name: "upgrade",
12
+ output: "both",
13
+ async run(ctx) {
14
+ const { ui } = ctx;
15
+ if (process.argv[1]?.includes("_npx")) {
16
+ if (ctx.json) return ctx.output.data({
17
+ upgraded: false,
18
+ via: "npx"
19
+ });
20
+ ui.info("You're running via npx, which always fetches the latest published version - nothing to upgrade.");
21
+ return;
22
+ }
23
+ ui.intro("Superwall upgrade");
24
+ const spin = ui.spinner();
25
+ spin.start("Checking the latest version");
26
+ const latest = await fetchLatestVersion();
27
+ if (!latest) {
28
+ spin.stop("Check failed");
29
+ throw new Error("Couldn't reach the npm registry - try again.");
30
+ }
31
+ if (!isNewerVersion(latest, VERSION)) {
32
+ spin.stop(`You're on the latest version (\`${VERSION}\`)`);
33
+ if (ctx.json) return ctx.output.data({
34
+ upgraded: false,
35
+ version: VERSION
36
+ });
37
+ return;
38
+ }
39
+ spin.message(`Upgrading \`${VERSION}\` → \`${latest}\``);
40
+ const errors = [];
41
+ const { code } = await spawnStream({
42
+ bin: "npm",
43
+ args: [
44
+ "install",
45
+ "--global",
46
+ `superwall@${latest}`
47
+ ],
48
+ cwd: process.cwd(),
49
+ onStdoutLine: () => {},
50
+ onStderrLine: (line) => errors.push(line)
51
+ });
52
+ if (code !== 0) {
53
+ spin.stop("Upgrade failed");
54
+ const detail = errors.slice(-3).join(" ").trim();
55
+ throw new Error(`npm couldn't upgrade the package${detail ? ` (${detail.slice(0, 200)})` : ""}. Try: npm install --global superwall@latest`);
56
+ }
57
+ setUpdateCheck({
58
+ latest,
59
+ checkedAt: (/* @__PURE__ */ new Date()).toISOString()
60
+ });
61
+ spin.stop(`Upgraded \`${VERSION}\` → \`${latest}\``);
62
+ if (ctx.json) return ctx.output.data({
63
+ upgraded: true,
64
+ from: VERSION,
65
+ to: latest
66
+ });
67
+ ui.outro("You're on the latest version.");
68
+ }
69
+ });
70
+
71
+ //#endregion
72
+ export { runUpgrade };
package/package.json ADDED
@@ -0,0 +1,87 @@
1
+ {
2
+ "name": "@superwall/cli",
3
+ "version": "1.1.0",
4
+ "description": "The official CLI for managing Superwall from your terminal or coding agent.",
5
+ "keywords": [
6
+ "agent",
7
+ "android",
8
+ "app-store-connect",
9
+ "cli",
10
+ "ios",
11
+ "paywall",
12
+ "subscriptions",
13
+ "superwall"
14
+ ],
15
+ "homepage": "https://github.com/superwall/superwall/tree/main/packages/cli#readme",
16
+ "bugs": {
17
+ "url": "https://github.com/superwall/superwall/issues"
18
+ },
19
+ "license": "MIT",
20
+ "author": "Superwall",
21
+ "repository": {
22
+ "type": "git",
23
+ "url": "git+https://github.com/superwall/superwall.git",
24
+ "directory": "packages/cli"
25
+ },
26
+ "files": [
27
+ "dist",
28
+ "LICENSE",
29
+ "package.json",
30
+ "prompts",
31
+ "README.md",
32
+ "skills"
33
+ ],
34
+ "type": "module",
35
+ "exports": {
36
+ ".": {
37
+ "types": "./dist/entry.d.ts",
38
+ "import": "./dist/entry.js"
39
+ },
40
+ "./auth": {
41
+ "types": "./dist/auth.d.ts",
42
+ "import": "./dist/auth.js"
43
+ }
44
+ },
45
+ "scripts": {
46
+ "build": "tsdown",
47
+ "watch": "tsdown --watch",
48
+ "regen:asc": "tsx scripts/regen-asc-index.ts",
49
+ "dev": "bun bin.ts",
50
+ "test": "tsx --test $(rg --files tests -g '*.test.ts')",
51
+ "link:global": "tsdown && bun link",
52
+ "typecheck": "tsc --noEmit",
53
+ "prepack": "bun run build",
54
+ "prepublishOnly": "bun run typecheck && bun run test",
55
+ "test:run": "tsx --test $(rg --files tests -g '*.test.ts')",
56
+ "test:coverage": "tsx --test --experimental-test-coverage --test-coverage-lines=70 --test-coverage-branches=82 --test-coverage-functions=68 $(rg --files tests -g '*.test.ts')",
57
+ "clean": "rm -rf dist"
58
+ },
59
+ "dependencies": {
60
+ "@anthropic-ai/claude-agent-sdk": "0.3.201",
61
+ "ansi-escapes": "^7.3.0",
62
+ "fast-glob": "^3.3.3",
63
+ "ink": "^5.2.1",
64
+ "ink-spinner": "^5.0.0",
65
+ "picocolors": "^1.1.1",
66
+ "react": "^18.3.1",
67
+ "uqr": "^0.1.3",
68
+ "wrap-ansi": "^9.0.2",
69
+ "yargs": "^17.7.2"
70
+ },
71
+ "devDependencies": {
72
+ "@types/node": "^22.10.0",
73
+ "@types/react": "^18.3.31",
74
+ "@types/yargs": "^17.0.33",
75
+ "ink-testing-library": "^4.0.0",
76
+ "tsdown": "^0.15.0",
77
+ "tsx": "^4.19.0",
78
+ "typescript": "^5.7.0"
79
+ },
80
+ "engines": {
81
+ "node": ">=20.0.0"
82
+ },
83
+ "packageManager": "bun@1.3.14",
84
+ "publishConfig": {
85
+ "access": "public"
86
+ }
87
+ }
@@ -0,0 +1,10 @@
1
+ <task>
2
+ {{skill}}
3
+
4
+ The target app's public API key is {{app_key}} (also in <context>).
5
+
6
+ <report>
7
+ Short-line markdown: what already existed, what you created (with campaign/placement/paywall ids),
8
+ and any manual step left for the user (design the paywall, attach products, etc.).
9
+ </report>
10
+ </task>
@@ -0,0 +1,5 @@
1
+ <task>
2
+ {{skill}}
3
+
4
+ Emit a [STATUS] before each step. Do not write a long summary. End with '[STATUS] Done'.
5
+ </task>
@@ -0,0 +1,11 @@
1
+ <task>
2
+ Migrate this app from {{provider}} to Superwall - {{goal}}.
3
+
4
+ {{skill}}
5
+
6
+ <report>
7
+ Short-line markdown: the mapping (provider→Superwall), what you created (ids), what code changed, and any manual steps left.
8
+ </report>
9
+
10
+ Emit a [STATUS] before each step.
11
+ </task>
@@ -0,0 +1,20 @@
1
+ <task>
2
+ {{#prior_report}}
3
+ <prior_review note="a placement review was already run for this app - act on its findings">
4
+ {{prior_report}}
5
+ </prior_review>
6
+
7
+ {{/prior_report}}
8
+ Implement Superwall placements at the right feature-gate points in this app, and make sure each is routed through a campaign.
9
+ {{#campaigns}}
10
+
11
+ <current_campaigns>
12
+ {{campaigns}}
13
+ </current_campaigns>
14
+ {{/campaigns}}
15
+
16
+ {{skill}}
17
+
18
+ Keep edits minimal and idiomatic - do not reformat or refactor unrelated code. If a build command exists, build to verify.
19
+ Emit a [STATUS] before each step. Do not write a long summary. End with '[STATUS] Done'.
20
+ </task>
@@ -0,0 +1,18 @@
1
+ <task>
2
+ Audit this app's Superwall placement usage as the placement phase of a new integration. DO NOT modify any files.
3
+ {{#campaigns}}
4
+
5
+ <current_campaigns>
6
+ {{campaigns}}
7
+ </current_campaigns>
8
+ {{/campaigns}}
9
+
10
+ {{skill}}
11
+
12
+ <report>
13
+ Produce a concise placement report. Include verified coverage gaps and useful
14
+ opportunities, but do not treat analytics-backed placements, fire-and-forget
15
+ registrations, or intentionally unrouted analytics placements as defects.
16
+ Keep every bullet on one source line. End with overall placement health.
17
+ </report>
18
+ </task>
@@ -0,0 +1,18 @@
1
+ <task>
2
+ {{#prior_report}}
3
+ <prior_review note="a setup review was already run for this app - fix its verified findings">
4
+ {{prior_report}}
5
+ </prior_review>
6
+
7
+ {{/prior_report}}
8
+ Fix verified, actionable problems in this app's existing Superwall setup. If no
9
+ prior review is present, audit first. Do not implement optional opportunities or
10
+ make product, pricing, purchase-provider, or placement-naming decisions for the
11
+ user.
12
+
13
+ {{skill}}
14
+
15
+ Keep edits minimal and idiomatic. Do not reformat or refactor unrelated code. If
16
+ a build command exists, build to verify. Emit a [STATUS] before each step. Do not
17
+ write a long summary. End with '[STATUS] Done'.
18
+ </task>
@@ -0,0 +1,18 @@
1
+ <task>
2
+ Review this app's existing Superwall setup end to end. DO NOT modify any files.
3
+
4
+ {{skill}}
5
+
6
+ <report>
7
+ Produce a concise markdown report with these sections:
8
+ - Setup health - one evidence-backed line for each review area.
9
+ - Findings - only verified problems, ordered by impact, each with one fix.
10
+ - Opportunities - optional improvements, clearly labeled optional.
11
+ - Not verified - checks blocked by auth, network, runtime, or missing context.
12
+ - Overall - healthy / improvements recommended / needs attention.
13
+
14
+ Do not emit an exhaustive placement inventory. Keep every bullet on one source
15
+ line and let the terminal wrap it. For code evidence, use
16
+ `[relative/path:line](/absolute/path:line)` so the terminal can link the file.
17
+ </report>
18
+ </task>
@@ -0,0 +1,17 @@
1
+ <rules>
2
+ <rule>You are integrating Superwall into the user's app. Make the smallest set of edits that achieves a working, verifiable integration. Do not refactor unrelated code or reformat files.</rule>
3
+
4
+ <rule>Never invent or guess a Superwall API key. Use the exact public key provided in the prompt. Never write any API key directly into source that would be committed as a secret - prefer an environment variable or the platform's standard config mechanism, except where the public Superwall key is conventionally inlined (e.g. iOS configure()).</rule>
5
+
6
+ <rule>Before editing any file, read it first. Match the file's existing style and conventions.</rule>
7
+
8
+ <rule>Detect the package manager from the project (lockfiles, config) rather than assuming npm/yarn/pnpm/pod/spm.</rule>
9
+
10
+ <rule>When using the superwall CLI, pass --json for every data or mutation command and pass explicit --project/--app scope after discovering ids with `superwall apps list --json`.</rule>
11
+
12
+ <rule>Emit a one-line progress update prefixed with '[STATUS] ' before EVERY step, including before running any shell command (e.g. '[STATUS] Installing the Superwall package', '[STATUS] Building to verify'). The user only sees these [STATUS] lines - they do NOT see your tool calls, bash commands, or other prose - so keep a fresh, human-readable [STATUS] flowing the whole way through. Never go more than one tool call without a [STATUS] update.</rule>
13
+
14
+ <rule>Follow the task's output instructions exactly: for an implementation task, do NOT write a long summary - end with '[STATUS] Done'; for a review/report task, end with the concise report it asks for.</rule>
15
+
16
+ <rule>If you cannot complete the integration safely (ambiguous project, missing entry point, would require destructive changes), stop and explain what you need instead of guessing.</rule>
17
+ </rules>
@@ -0,0 +1,9 @@
1
+ <context>
2
+ <platform>{{platform}}</platform>
3
+ <app_directory>{{app_dir}}</app_directory>
4
+ <public_api_key purpose="SDK init">{{api_key}}</public_api_key>
5
+ <sdk_installed>{{sdk_installed}}</sdk_installed>
6
+ <configure_present>{{configure_present}}</configure_present>
7
+ <docs>{{docs_url}}</docs>
8
+ <dashboard note="for the user, not you">{{dashboard_url}}</dashboard>
9
+ </context>
@@ -0,0 +1,118 @@
1
+ # Skills
2
+
3
+ The agent skills that ship inside `@superwall/cli`. Each is a self-contained
4
+ playbook — a lean `SKILL.md` router plus deep `references/` — that the CLI
5
+ composes for the user's platform and hands to their coding agent (Claude Code
6
+ or Codex). They follow the [agent skills](https://agentskills.io) format, so
7
+ they also install directly into any agent with `npx skills add`.
8
+
9
+ | Skill | What it does | References | Driven by |
10
+ | -------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------ |
11
+ | [`superwall-integrate`](superwall-integrate) | Install and configure the SDK in an app for the first time | `ios` `expo` `react-native` `flutter` | `superwall integrate` |
12
+ | [`superwall-placements`](superwall-placements) | Add or audit placements at feature gates and route them to campaigns | `strategy` + one framework | `superwall integrate` (phase 2) |
13
+ | [`superwall-dashboard`](superwall-dashboard) | Create the entitlements, products, and campaigns a placement needs to present | `setup` | `superwall integrate` (phase 3) |
14
+ | [`superwall-review`](superwall-review) | Audit an existing setup end to end; `--fix` repairs verified findings | `ios` `expo` `react-native` `flutter` | `superwall review [--fix]` |
15
+ | [`superwall-migrate`](superwall-migrate) | Move an app off RevenueCat, Adapty, or Qonversion | `revenuecat` `adapty` `qonversion` | `superwall migrate` |
16
+
17
+ The broad toolkit skills — `superwall` (resources, analytics SQL, docs, SDK
18
+ triage) and `superwall-editor` (build paywalls in the visual editor from the
19
+ CLI) — live in the public [superwall/skills](https://github.com/superwall/skills)
20
+ repo. `superwall login` installs them into your agent and `superwall skills`
21
+ keeps them updated. Building paywalls and funnels as code is the framework's
22
+ job: see the [root README](../../../README.md) and `superwall create`.
23
+
24
+ ## How a skill reaches the agent
25
+
26
+ - **Composed at run time.** `loadBundledSkill(id, reference)` in
27
+ `src/core/agent/skills.ts` joins `SKILL.md` with exactly the references the
28
+ detected app needs (`FRAMEWORK_REF` in `src/core/agent/actions.ts`;
29
+ placements always adds `strategy`). An Expo agent never sees Swift docs.
30
+ Frontmatter is stripped; a missing reference file is a hard error.
31
+ - **Wrapped by the harness.** `prompts/actions/<action>.xml` adds the task
32
+ framing and `[STATUS]` protocol; `prompts/commandments.xml` the guardrails.
33
+ Harness protocol lives there, never in a skill.
34
+ - **Or printed.** `superwall integrate|migrate|review --skill` writes the
35
+ composed playbook to stdout for an agent you drive yourself. `integrate
36
+ --skill` is all three phases (integrate → placements → dashboard) in order.
37
+ - **Or installed.** `superwall skills` delegates to the `skills` CLI
38
+ (`npx -y skills@latest add …`), which owns locations and agent detection.
39
+
40
+ ## Layout
41
+
42
+ ```
43
+ skills/superwall-<task>/
44
+ SKILL.md router, ≤ ~80 lines: when to use, principles, the
45
+ flow, a table routing to references, the CLI commands
46
+ the agent will need, a Docs access block
47
+ references/<x>.md the depth — one file per framework or provider
48
+ ```
49
+
50
+ - Reference file names are the contract: they match `Integration` values
51
+ (`ios` for swift, `expo`, `react-native`, `flutter`) or provider slugs.
52
+ - `SKILL.md` frontmatter is `name` (equal to the directory) and `description`
53
+ written as when-to-use: what the skill does, the situations that activate
54
+ it, and what it is **not** for (pointing at the sibling skill).
55
+
56
+ ### Reference file anatomy, in order
57
+
58
+ 1. One-line context ("You are integrating Superwall into a <X> app.")
59
+ 2. Lifecycle checklist (markdown checkboxes)
60
+ 3. Docs access block — always include:
61
+ ```bash
62
+ curl -sL https://superwall.com/docs/llms.txt # index — find the path
63
+ curl -sL https://superwall.com/docs/{path}.md # any page as markdown
64
+ ```
65
+ 4. The steps — verified instructions plus the inline `curl -sL` for each
66
+ step's doc page (baked = fast and offline; fetched = source of truth)
67
+ 5. Decision points as explicit branches
68
+ 6. Verify section — build commands, what success looks like
69
+ 7. Pitfalls — real ones with fixes
70
+ 8. Deeper docs — the exact URLs used
71
+
72
+ `> **Important:**` callouts for critical steps; `→ references/x.md` arrows for
73
+ routing.
74
+
75
+ ## Content rules
76
+
77
+ - **Verify every API against live docs before writing it.** Package ids,
78
+ version bounds, signatures, config keys — fetched, not remembered. If a doc
79
+ is ambiguous, write the step and add "confirm against <exact doc url>".
80
+ Never invent sample code for a path with no official doc.
81
+ - **Never exaggerate.** Migration skills carry a prominent "what does NOT
82
+ migrate" callout. Paywall designs are rebuilt — as code with the framework
83
+ or in the editor — and the skill says so. Craft guidance (where placements
84
+ go, how many, naming) is introduced as recommended practice, not passed off
85
+ as documentation.
86
+ - **Dashboard changes go through the CLI** (`superwall entitlements create …`,
87
+ `campaigns placement …`, `--json` everywhere) — never raw curl when a
88
+ command exists.
89
+ - **No harness protocol in skills.** `[STATUS]` lines and report formats come
90
+ from `prompts/`.
91
+ - **No customer specifics.** Placeholders are `pk_YOUR_PUBLIC_KEY`,
92
+ `AuthKey_<KEY_ID>.p8`, `<campaignId>`; pitfalls are written generically.
93
+
94
+ ## Keeping skills in sync
95
+
96
+ Skills quote CLI commands constantly, and the public `superwall` skill
97
+ documents this CLI's whole surface. On any command change, sweep:
98
+
99
+ ```bash
100
+ cd packages/cli && grep -rn "superwall <old>" skills prompts README.md
101
+ ```
102
+
103
+ then `src/core/agent/actions.ts` (action vars, references),
104
+ `prompts/actions/*.xml` (task wrappers), and the `superwall` skill in
105
+ [superwall/skills](https://github.com/superwall/skills). Smoke the
106
+ composition with `superwall <workflow> --skill` in a fixture project of each
107
+ affected framework: right reference, no cross-framework leakage, no unresolved
108
+ `{{vars}}`.
109
+
110
+ ## Before calling a skill done
111
+
112
+ - [ ] An agent with only `SKILL.md` + one reference in context could execute it
113
+ flawlessly — no missing steps, no assumed context.
114
+ - [ ] Zero unverified API names, or each flagged with its doc URL.
115
+ - [ ] Composition tested per framework; grep for leakage.
116
+ - [ ] Honesty pass: nothing promises more than the product does.
117
+ - [ ] `bun run test` — `tests/core/agent/skill-contracts.test.ts` checks the
118
+ files the loader expects exist.
@@ -0,0 +1,81 @@
1
+ ---
2
+ name: superwall-dashboard
3
+ description: Set up the Superwall dashboard state required for placements to present paywalls. Creates entitlements, products with real pricing, and campaigns that carry each placement. Use after the SDK is integrated and placements are registered, or when a placement has no presenting campaign.
4
+ ---
5
+
6
+ # Set up the Superwall dashboard
7
+
8
+ Turn an app whose code registers placements into a working dashboard: entitlement(s),
9
+ products, and campaigns that route each placement to a paywall. Use the globally
10
+ installed, already-authenticated `superwall` CLI for every change. Pass `--json` on
11
+ every command. Run `superwall whoami --json` first; if not logged in, tell the user to run
12
+ `superwall login`.
13
+
14
+ ## The model (teach this, then act)
15
+
16
+ ```
17
+ placement (in code) → campaign (routes it) → audience (who) → paywall (what shows)
18
+ ↑
19
+ products + entitlements (what's sold / unlocked)
20
+ ```
21
+
22
+ - A **placement** is a `register("event")` call in the app. It does **nothing** until a
23
+ campaign carries it.
24
+ - A **campaign** is the container that routes placements. It holds **audiences** (top-to-bottom
25
+ filter rules; first match wins, sticky assignment) and each audience runs an **experiment**
26
+ that splits traffic across **paywalls**.
27
+ - A **paywall** sells **products**; buying grants an **entitlement** (e.g. `pro`) which is the
28
+ boolean the app gates features on.
29
+ - So: register a placement in code → add it to a campaign → the campaign shows a paywall. Without
30
+ the campaign step, the placement fires and silently does nothing.
31
+
32
+ ## Do it in order
33
+
34
+ 1. **Find the app.** `superwall apps list --json`. Match the app by its `public_api_key`
35
+ (the `pk_…` in the app's `configure()` call). Note its `id` → pass `--app <id>` to
36
+ campaign/paywall commands, `--project <id>` to product/entitlement commands. Always pass
37
+ these ids; JSON mode never guesses when multiple scopes exist.
38
+ 2. **Find registered placements.** Grep the app for `register(`, `registerPlacement(`,
39
+ `usePlacement(`, `Superwall.shared.register` - collect the exact event-name strings.
40
+ 3. **Ensure an entitlement.** `superwall entitlements list --project <id> --json`; reuse an existing one, else
41
+ `superwall entitlements create pro --project <id> --json`. Default to a single `pro` entitlement unless the
42
+ app clearly has tiers.
43
+ 4. **Ensure products.** `superwall products list --project <id> --json` first. If none:
44
+ - App Store Connect connected (`superwall asc keys list --json`) → import (see references/setup.md).
45
+ - Otherwise create with real pricing:
46
+ `superwall products create pro_yearly --price 39.99 --period year --trial-days 7 --entitlement pro --project <id> --json`
47
+ 5. **Carry each placement.** `superwall campaigns list --project <id> --app <id> --json`. For each placement not already on
48
+ 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`.
49
+
50
+ ## Guardrails
51
+
52
+ - **List before you create.** Never create a duplicate entitlement/product/campaign.
53
+ - **Never delete or destructively modify** existing campaigns, paywalls, products, or audiences.
54
+ - Reuse existing entitlements and products; only add what's missing.
55
+ - Idempotent by design - re-running should be a no-op when everything already exists.
56
+
57
+ ## Best practices
58
+
59
+ - **One campaign per surface** (e.g. an "Onboarding" campaign carrying the onboarding placement,
60
+ a "Feature gates" campaign carrying in-app gate placements) reads better than one campaign per
61
+ placement - a campaign can carry several related placements. When unsure, one campaign per
62
+ distinct user context.
63
+ - Name campaigns for the surface/intent, not the placement string.
64
+ - Keep entitlements coarse (`pro`); don't mint one per product.
65
+
66
+ ## Report back (short-line markdown)
67
+
68
+ - What already existed (ids).
69
+ - What you created: entitlement, product ids, campaign ids, placements attached.
70
+ - **Left manual:** paywall design - as code with the superwall framework (`superwall create` →
71
+ `superwall publish`) or in the dashboard editor - attaching products to the paywall, and - if
72
+ products were created by hand - reconciling identifiers with App Store Connect / Google Play.
73
+
74
+ See `references/setup.md` for the App Store Connect import path, `.storekit` generation, and pricing-flag reference.
75
+
76
+ ## Docs access
77
+
78
+ Any Superwall doc page is fetchable as markdown: `curl -sL https://superwall.com/docs/llms.txt`
79
+ to find the path (dashboard concepts live under `/docs/dashboard/`), then
80
+ `curl -sL https://superwall.com/docs/{path}.md` for the page. Use this for campaign/audience
81
+ details beyond this skill.