@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
@@ -0,0 +1,245 @@
1
+ # Remember answers and resume an onboarding
2
+
3
+ Any surface that asks more than one question across pages (an onboarding, a
4
+ quiz, a survey, a funnel) must survive the user closing it halfway. The next
5
+ time it opens, they land on the first question they have not answered, not on
6
+ page one. The `onboarding-quiz` example is the reference implementation.
7
+
8
+ ## The rule
9
+
10
+ 1. **Every answer is a user attribute, read and written with
11
+ `useUserAttribute(key, parser)`.** It is `useQueryState`'s API with the
12
+ same parsers: `const [goal, setGoal] = useUserAttribute("onboarding_goal",
13
+ goals)`. Call the setter in the tap handler, before navigating. The host
14
+ SDK persists attributes across presentations and app launches. React
15
+ state, a module variable, `layout.tsx` state and the router all die with
16
+ the paywall, so an answer kept only there is lost when the user closes.
17
+ 2. **Store the answers, never the position.** No `onboarding_step`, no page
18
+ index. Where the user is follows from which answers exist, and it stays
19
+ right when you reorder, add, branch or cut a question.
20
+ 3. **The setter re-renders at once.** The paywall's own snapshot updates in
21
+ the same event, so the card is selected on the frame the haptic fires,
22
+ and the next presentation gets the persisted value from the host.
23
+ 4. **The flow is one function.** `next(route, user)` says where each page
24
+ leads, reading the answers it branches on. The buttons push what it
25
+ returns; nothing else knows the order.
26
+ 5. **Resume with `entry` and `replayStack`.** `app/layout.tsx` exports
27
+ `entry`, which returns `replayStack(start, next, answered)`: the stack
28
+ the user would have built by tapping through, walking `next` from the
29
+ first screen while each page is answered. The framework calls it once,
30
+ after the host has sent its state and before the first render, and opens
31
+ on that stack: the resumed page is the first thing that paints, nothing
32
+ animates, and nothing outside the stack mounts. Back walks down the
33
+ branch the user actually took, with the normal transitions, and "Start
34
+ over" works.
35
+ 6. **A question page shows its saved answer as selected** (the hook's
36
+ value), so going back to change one reads as editing, not starting again.
37
+
38
+ ## Values are typed by the parser
39
+
40
+ Attributes travel as strings. The parser turns one back into a type:
41
+ `parseAsStringEnum(options)` gives the union of the options, and
42
+ `parseAsInteger`, `parseAsBoolean`, `parseAsArrayOf` the rest. Anything it
43
+ cannot read — an option this version no longer offers, a value the app set
44
+ under the same key, garbage, an object, the strings `"null"` and `"undefined"` — is `null`,
45
+ which a flow treats as unanswered. `.withDefault(value)` reads those as the
46
+ default instead and removes `null` from the type. A number or boolean the
47
+ app set reads as its string form, so `parseAsInteger` reads an app's `30`.
48
+
49
+ Attributes cannot be removed from a surface, so the setter takes no `null`
50
+ (a `null` at runtime is ignored with a console warning, never stored as
51
+ `"null"`). Design "Start over" as answering again, which overwrites, never
52
+ as clearing. Writing the value already stored sends nothing.
53
+
54
+ ## Naming
55
+
56
+ Attributes are what campaigns target and what analytics segment by, so the
57
+ keys are a schema, not UI labels:
58
+
59
+ - stable snake_case, prefixed by the flow: `onboarding_goal`,
60
+ `onboarding_level`, not `goal` (collides with the app's own) or
61
+ `whatAreYouHereFor`;
62
+ - values are short enum ids (`"build"`, `"returning"`, `"30"`), never the
63
+ translated copy, which changes per locale and per edit;
64
+ - one key per question; never a JSON blob of all answers;
65
+ - never rename a key that has shipped: audiences and reports query it. Add a
66
+ new one instead.
67
+
68
+ ## Worked example
69
+
70
+ A branching quiz: losing fat skips the level question. `components/answers.ts`:
71
+
72
+ ```ts
73
+ import { parseAsStringEnum, readAttribute, type UserAttributes } from "superwall/hooks";
74
+ import type { RouteName } from "superwall/navigation";
75
+
76
+ export const GOAL = {
77
+ key: "onboarding_goal",
78
+ parser: parseAsStringEnum(["lose", "build", "endure"]),
79
+ };
80
+ export const LEVEL = {
81
+ key: "onboarding_level",
82
+ parser: parseAsStringEnum(["new", "returning", "regular"]),
83
+ };
84
+ export const TIME = { key: "onboarding_time", parser: parseAsStringEnum(["15", "30", "45"]) };
85
+
86
+ export type Goal = NonNullable<ReturnType<typeof GOAL.parser.parse>>;
87
+
88
+ export const answersOf = (user: UserAttributes) => ({
89
+ goal: readAttribute(user, GOAL.key, GOAL.parser),
90
+ level: readAttribute(user, LEVEL.key, LEVEL.parser),
91
+ time: readAttribute(user, TIME.key, TIME.parser),
92
+ });
93
+
94
+ // The flow, in one place.
95
+ export const next = (route: RouteName, user: UserAttributes): RouteName | undefined => {
96
+ const answers = answersOf(user);
97
+ switch (route) {
98
+ case "index":
99
+ return "goal";
100
+ case "goal":
101
+ return answers.goal === "lose" ? "time" : "level";
102
+ case "level":
103
+ return "time";
104
+ case "time":
105
+ return "plan";
106
+ default:
107
+ return undefined;
108
+ }
109
+ };
110
+
111
+ // Whether the user is past a page. The intro counts once the first question is answered.
112
+ export const answered = (route: RouteName, user: UserAttributes): boolean => {
113
+ const answers = answersOf(user);
114
+ switch (route) {
115
+ case "index":
116
+ case "goal":
117
+ return answers.goal !== null;
118
+ case "level":
119
+ return answers.level !== null;
120
+ case "time":
121
+ return answers.time !== null;
122
+ default:
123
+ return false;
124
+ }
125
+ };
126
+ ```
127
+
128
+ A question page saves, then moves on with the same `next`, given the answer
129
+ it just saved:
130
+
131
+ ```tsx
132
+ const user = useUser();
133
+ const [goal, setGoal] = useUserAttribute(GOAL.key, GOAL.parser);
134
+
135
+ const choose = (value: Goal) => {
136
+ haptics.selection();
137
+ setGoal(value);
138
+ const to = next("goal", { ...user, [GOAL.key]: value });
139
+ if (to) router.push(to);
140
+ };
141
+
142
+ <button className="choice" aria-pressed={goal === "lose"} onClick={() => choose("lose")}>
143
+ ```
144
+
145
+ The layout (`app/layout.tsx`) resumes:
146
+
147
+ ```tsx
148
+ import { replayStack, type Entry } from "superwall/navigation";
149
+ import { answered, next } from "../components/answers";
150
+
151
+ export const entry: Entry = ({ user }) =>
152
+ replayStack("index", (route) => next(route, user), (route) => answered(route, user));
153
+ ```
154
+
155
+ `app/index.tsx` stays an ordinary page: no effect, no redirect.
156
+
157
+ Why each piece is there:
158
+
159
+ - **The answers are there when `entry` runs.** Under a host a flow with
160
+ `entry` renders nothing until the host's first state (user attributes, device,
161
+ products) has arrived, with a three-second fallback for a host that never
162
+ answers, and `entry` runs after that wait, once. It gets `{ user, device,
163
+ params }`; it is not a component, so it takes them as arguments rather
164
+ than calling hooks.
165
+ - **It opens on the stack; it does not navigate to it.** The resumed page is
166
+ the first frame, with no transition, and only the routes in the stack
167
+ mount. Going back from it animates like any other back. One `page_view`
168
+ (`entry`) is reported, for the top of the stack.
169
+ - **The whole stack, not only the target.** `["level"]` alone would leave
170
+ back with nowhere to go and make "Start over" (`router.dismissAll()`) land
171
+ on the resumed question instead of the start.
172
+ - **It cannot loop or overshoot.** `replayStack` stops, with a console
173
+ warning, at a page `next` returns twice, at an empty or non-string name,
174
+ at a name the surface does not have (checked when called from `entry`),
175
+ and past 100 pages, and opens on the last good page. A throw from `next` or `answered` opens on `index`.
176
+ - **Route names are typed.** A typo in the stack is a compile error; a stack
177
+ `entry` returns by hand with a wrong runtime name opens on `index` with a
178
+ console warning.
179
+ - **A stack in the URL wins.** On a web funnel `?sw_nav=` (history, a
180
+ reload, the return from hosted checkout) decides where the funnel opens,
181
+ and `entry` is not called.
182
+ - **`router.reset(stack)` is for mid-flow jumps**, not for opening: it
183
+ replaces the stack the same way, but only after a first route has
184
+ rendered.
185
+
186
+ ## When `entry` runs, and what it is for
187
+
188
+ - **Only `app/layout.tsx`.** A surface has one root layout; there are no
189
+ nested layouts, and an `entry` exported anywhere else is ignored.
190
+ - **The flow is yours.** `next`, `answered` and `answersOf` are the
191
+ example's own functions; `replayStack`, `useUserAttribute` and
192
+ `readAttribute` are the framework's. The framework only calls `entry` with
193
+ `{ user, device, params }` and opens on what it returns.
194
+ - **Order of events.** The SDK loads the paywall into its webview, often
195
+ long before it is shown (it preloads at start-up). The paywall pings, the
196
+ host answers with its state, a flow with `entry` renders nothing until then (or
197
+ three seconds, if the host never answers), `entry` runs once, and its stack
198
+ is the first frame. A flow without `entry` never waits. On iOS the SDK
199
+ reveals the webview only after the state is sent, so the wait is unseen.
200
+ - **Once per load, not per presentation.** The iOS SDK keeps a loaded
201
+ paywall with its pages, so closing on question four and reopening in the
202
+ same session lands on question four with no `entry` call. The next load
203
+ (a relaunch, a paywall refresh) decides again from the saved attributes.
204
+ Attributes the app sets after the paywall loaded are not seen by
205
+ `entry`; a decision that depends on them goes in the page, where
206
+ `useUserAttribute` re-renders.
207
+ - **Pure, and pages only.** StrictMode in development may call it twice. No
208
+ attribute writes, `fetch` or analytics in it; work that should happen
209
+ when a flow opens goes in an effect in `layout.tsx`.
210
+ - **Other uses:** a returning user skipping the welcome, one surface opened
211
+ on different pages from different placements (`params`), a shorter flow
212
+ per device or platform.
213
+
214
+ ## Do not
215
+
216
+ - keep answers only in `useState`, a module variable, `layout.tsx` state,
217
+ context or a store;
218
+ - write them with `useActions().setUserAttributes`: it is deprecated, and
219
+ untyped. `useUserAttribute` writes and reads back through the same parser;
220
+ - save on "Continue" at the end of the flow, or in a batch at the last
221
+ screen: the user who quits on question four has then saved nothing;
222
+ - store `onboarding_step`, `current_page` or a route name as an attribute;
223
+ - make every question page redirect itself whenever its attribute exists.
224
+ It reads as resuming but traps the user: back to that page bounces
225
+ forward, and "Start over" can never show it again, since attributes
226
+ cannot be cleared. Resume from the entry route; a page that can be
227
+ reached directly with its answer known (a deep link) belongs in `entry`
228
+ too;
229
+ - resume from a `useLayoutEffect` on `index` with `router.reset`: the intro
230
+ mounts (its effects run) only to be replaced, which `entry` avoids;
231
+ - read an attribute raw (`user.onboarding_goal === "build"`,
232
+ `user.onboarding_age === 25`): read it through a parser, so a stale or
233
+ foreign value reads as unanswered and a number as a number;
234
+ - keep a second, hand-written resume order beside the buttons' order: one
235
+ `next` drives both, or a branching flow resumes down the wrong branch;
236
+ - write the visible copy as the value (`"Build muscle"`), or a key that
237
+ only makes sense on screen.
238
+
239
+ ## On a web funnel
240
+
241
+ A funnel with `checkout` set keeps every answer in the URL with
242
+ `useQueryState` as well (fetch the `web-funnels` docs page), because an
243
+ in-app browser hands only the URL to Safari. Save each answer as a user
244
+ attribute too, so campaigns and analytics see it; the URL carries the
245
+ position through the hand-off.
@@ -0,0 +1,22 @@
1
+ ---
2
+ name: wwdc
3
+ description: "Use this skill whenever the user asks about WWDC sessions, Apple Developer videos, WWDC transcripts, session IDs, technologies announced at WWDC, or wants an agent to find, compare, cite, summarize, or navigate WWDC session content. Fetch current docs from wwdc.ai via llms.txt and page markdown. Maintained by Superwall.com: the quickest way to add in-app subscriptions and paywalls to your app."
4
+ ---
5
+
6
+ # WWDC
7
+
8
+ Use WWDC.ai markdown pages as the first stop for concise session summaries and Apple source links. If the markdown summary is missing or not detailed enough, use transcript text without timestamps.
9
+
10
+ ## Helpers
11
+
12
+ Run the bundled script when it is useful:
13
+
14
+ ```bash
15
+ scripts/wwdc.sh llms
16
+ scripts/wwdc.sh summary 2026 389
17
+ scripts/wwdc.sh transcript 2026 309
18
+ ```
19
+
20
+ `summary` returns the WWDC.ai markdown page. `transcript` returns plain transcript text with no timestamps. URL/JSON helpers exist for source inspection.
21
+
22
+ For endpoint details and examples, see [references/docs.md](references/docs.md).
@@ -0,0 +1,52 @@
1
+ ---
2
+ title: WWDC.ai Agent Reference
3
+ shoutout: "Unofficial, made with love by Superwall - the best way to monetize your apps."
4
+ ---
5
+
6
+ ## Sources
7
+
8
+ Prefer concise WWDC.ai markdown pages. Use transcripts only when a summary is missing, skeletal, or too shallow for the user's question.
9
+
10
+ | Resource | URL | Use when |
11
+ | --- | --- | --- |
12
+ | Session index | `https://wwdc.ai/llms.txt` | Finding sessions by year, ID, or title |
13
+ | Full context | `https://wwdc.ai/llms-full.txt` | Need broader context across all generated pages |
14
+ | Year markdown | `https://wwdc.ai/2026.md` | Listing sessions for one WWDC year |
15
+ | Session HTML | `https://wwdc.ai/2026/389` | User-facing session page |
16
+ | Session markdown | `https://wwdc.ai/2026/389.md` | Agent-readable page for one session |
17
+
18
+ `llms.txt` groups sessions by Apple category. Session rows use `session-number title: one-line description`; build the page URL as `https://wwdc.ai/<year>/<session-number>` and add `.md` for markdown.
19
+
20
+ Common direct fetches:
21
+
22
+ ```bash
23
+ curl -sL https://wwdc.ai/llms.txt
24
+ curl -sL https://wwdc.ai/2026/389.md
25
+ ```
26
+
27
+ WWDC.ai is unofficial and not associated with Apple. Cite Apple's session page for original source material.
28
+
29
+ ## Script
30
+
31
+ Use whichever helper fits the question:
32
+
33
+ ```bash
34
+ scripts/wwdc.sh llms
35
+ scripts/wwdc.sh full
36
+ scripts/wwdc.sh list 2026
37
+ scripts/wwdc.sh summary 2026 389
38
+ scripts/wwdc.sh transcript 2026 309
39
+ ```
40
+
41
+ Core helpers:
42
+
43
+ - `summary`: WWDC.ai markdown page for a session.
44
+ - `transcript`: plain transcript text, no timestamps. Prefer this when the markdown summary is not enough.
45
+
46
+ Source inspection helpers:
47
+
48
+ - `html`: WWDC.ai HTML page.
49
+ - `transcript-url`: Apple transcript JSON URL, resolved from WWDC.ai public JSON when available and Apple's manifest otherwise.
50
+ - `transcript-json`: raw Apple JSON with timestamps.
51
+
52
+ Set `WWDC_AI_BASE_URL` to override `https://wwdc.ai`. Set `WWDC_APPLE_TRANSCRIPT_MANIFEST_URLS` to override Apple manifest URLs.
@@ -0,0 +1,266 @@
1
+ #!/usr/bin/env bash
2
+ set -euo pipefail
3
+
4
+ BASE_URL="${WWDC_AI_BASE_URL:-https://wwdc.ai}"
5
+ APPLE_TRANSCRIPT_MANIFEST_URLS="${WWDC_APPLE_TRANSCRIPT_MANIFEST_URLS:-https://devimages-cdn.apple.com/wwdc-services/w9f43630/73A40F02-6975-439F-BA6E-F5C834BFEAC5/transcript-manifest-eng.json}"
6
+
7
+ usage() {
8
+ cat <<'EOF'
9
+ Usage:
10
+ wwdc.sh llms
11
+ wwdc.sh full
12
+ wwdc.sh skill
13
+ wwdc.sh list <year>
14
+ wwdc.sh summary <year> <session>
15
+ wwdc.sh transcript <year> <session>
16
+ wwdc.sh html <year> <session>
17
+ wwdc.sh transcript-url <year> <session>
18
+ wwdc.sh transcript-json <year> <session>
19
+
20
+ Environment:
21
+ WWDC_AI_BASE_URL=https://wwdc.ai
22
+ WWDC_APPLE_TRANSCRIPT_MANIFEST_URLS="https://.../transcript-manifest-eng.json ..."
23
+ EOF
24
+ }
25
+
26
+ fetch() {
27
+ curl -fsSL --compressed "$1"
28
+ }
29
+
30
+ require_command() {
31
+ if ! command -v "$1" >/dev/null 2>&1; then
32
+ echo "wwdc.sh requires $1 for this operation" >&2
33
+ return 1
34
+ fi
35
+ }
36
+
37
+ session_markdown_url() {
38
+ local year="$1"
39
+ local session="$2"
40
+ printf '%s/%s/%s.md\n' "${BASE_URL%/}" "${year}" "${session}"
41
+ }
42
+
43
+ session_api_url() {
44
+ local year="$1"
45
+ local session="$2"
46
+ printf '%s/api/static/%s/%s.json\n' "${BASE_URL%/}" "${year}" "${session}"
47
+ }
48
+
49
+ require_session_args() {
50
+ if [[ $# -ne 2 ]]; then
51
+ usage >&2
52
+ exit 2
53
+ fi
54
+ }
55
+
56
+ page_transcript_url() {
57
+ local year="$1"
58
+ local session="$2"
59
+ local markdown
60
+ markdown="$(fetch "$(session_markdown_url "${year}" "${session}")")"
61
+ printf '%s\n' "${markdown}" | awk '/Apple transcript JSON:/ { print $NF; found=1; exit } END { if (!found) exit 1 }' ||
62
+ wwdc_api_transcript_url "${year}" "${session}"
63
+ }
64
+
65
+ wwdc_api_transcript_url() {
66
+ local year="$1"
67
+ local session="$2"
68
+
69
+ require_command node
70
+ fetch "$(session_api_url "${year}" "${session}")" | node -e '
71
+ const fs = require("node:fs");
72
+ const input = fs.readFileSync(0, "utf8");
73
+ const session = JSON.parse(input);
74
+ const url = session.transcriptSource?.transcriptUrl;
75
+ if (!url) process.exit(1);
76
+ process.stdout.write(url + "\n");
77
+ '
78
+ }
79
+
80
+ transcript_url() {
81
+ local year="$1"
82
+ local session="$2"
83
+ page_transcript_url "${year}" "${session}" || apple_transcript_url "${year}" "${session}"
84
+ }
85
+
86
+ page_transcript_json() {
87
+ local year="$1"
88
+ local session="$2"
89
+ local url
90
+ url="$(page_transcript_url "${year}" "${session}")"
91
+ fetch "${url}"
92
+ }
93
+
94
+ apple_transcript_json() {
95
+ local year="$1"
96
+ local session="$2"
97
+ local url
98
+ url="$(apple_transcript_url "${year}" "${session}")"
99
+ fetch "${url}"
100
+ }
101
+
102
+ resolved_transcript_json() {
103
+ local year="$1"
104
+ local session="$2"
105
+ local url
106
+ url="$(transcript_url "${year}" "${session}")"
107
+ fetch "${url}"
108
+ }
109
+
110
+ page_transcript_text() {
111
+ local year="$1"
112
+ local session="$2"
113
+ local url
114
+ url="$(page_transcript_url "${year}" "${session}")"
115
+ transcript_text "${year}" "${session}" "${url}"
116
+ }
117
+
118
+ apple_transcript_text() {
119
+ local year="$1"
120
+ local session="$2"
121
+ local url
122
+ url="$(apple_transcript_url "${year}" "${session}")"
123
+ transcript_text "${year}" "${session}" "${url}"
124
+ }
125
+
126
+ resolved_transcript_text() {
127
+ local year="$1"
128
+ local session="$2"
129
+ local url
130
+ url="$(transcript_url "${year}" "${session}")"
131
+ transcript_text "${year}" "${session}" "${url}"
132
+ }
133
+
134
+ transcript_text() {
135
+ local year="$1"
136
+ local session="$2"
137
+ local url="$3"
138
+ local session_id="wwdc${year}-${session}"
139
+
140
+ require_command node
141
+ fetch "${url}" | node -e '
142
+ const fs = require("node:fs");
143
+ const sessionId = process.argv[1];
144
+ const input = fs.readFileSync(0, "utf8");
145
+ const payload = JSON.parse(input);
146
+ const record = payload[sessionId] ?? Object.values(payload)[0];
147
+ const rows = record?.transcript;
148
+ if (!Array.isArray(rows)) {
149
+ process.exit(1);
150
+ }
151
+
152
+ const text = rows
153
+ .map((row) => Array.isArray(row) ? row[1] : row?.text)
154
+ .filter((line) => typeof line === "string" && line.length > 0)
155
+ .join("\n");
156
+
157
+ process.stdout.write(text);
158
+ if (!text.endsWith("\n")) process.stdout.write("\n");
159
+ ' "${session_id}"
160
+ }
161
+
162
+ apple_transcript_url() {
163
+ local year="$1"
164
+ local session="$2"
165
+ local session_id="wwdc${year}-${session}"
166
+ local manifest_url
167
+ local url
168
+
169
+ require_command node
170
+
171
+ for manifest_url in ${APPLE_TRANSCRIPT_MANIFEST_URLS}; do
172
+ url="$(
173
+ fetch "${manifest_url}" | node -e '
174
+ const fs = require("node:fs");
175
+ const sessionId = process.argv[1];
176
+ const input = fs.readFileSync(0, "utf8");
177
+ const manifest = JSON.parse(input);
178
+ const url = manifest.individual?.[sessionId]?.url;
179
+ if (!url) process.exit(1);
180
+ process.stdout.write(url + "\n");
181
+ ' "${session_id}"
182
+ )" || true
183
+
184
+ if [[ -n "${url}" ]]; then
185
+ printf '%s\n' "${url}"
186
+ return 0
187
+ fi
188
+ done
189
+
190
+ echo "No Apple transcript JSON URL found for ${session_id}" >&2
191
+ return 1
192
+ }
193
+
194
+ cmd="${1:-}"
195
+ shift || true
196
+
197
+ case "${cmd}" in
198
+ llms | index | docs)
199
+ fetch "${BASE_URL%/}/llms.txt"
200
+ ;;
201
+ full | llms-full)
202
+ fetch "${BASE_URL%/}/llms-full.txt"
203
+ ;;
204
+ skill)
205
+ fetch "${BASE_URL%/}/.well-known/agent-skills/wwdc/SKILL.md"
206
+ ;;
207
+ list | year)
208
+ if [[ $# -ne 1 ]]; then
209
+ usage >&2
210
+ exit 2
211
+ fi
212
+ fetch "${BASE_URL%/}/$1.md"
213
+ ;;
214
+ summary | page | session | md)
215
+ require_session_args "$@"
216
+ fetch "$(session_markdown_url "$1" "$2")"
217
+ ;;
218
+ html)
219
+ require_session_args "$@"
220
+ fetch "${BASE_URL%/}/$1/$2"
221
+ ;;
222
+ page-transcript-url | wwdc-transcript-url)
223
+ require_session_args "$@"
224
+ page_transcript_url "$1" "$2"
225
+ ;;
226
+ page-transcript-json | wwdc-transcript-json)
227
+ require_session_args "$@"
228
+ page_transcript_json "$1" "$2"
229
+ ;;
230
+ page-transcript-text | wwdc-transcript-text)
231
+ require_session_args "$@"
232
+ page_transcript_text "$1" "$2"
233
+ ;;
234
+ apple-transcript-url)
235
+ require_session_args "$@"
236
+ apple_transcript_url "$1" "$2"
237
+ ;;
238
+ apple-transcript-json)
239
+ require_session_args "$@"
240
+ apple_transcript_json "$1" "$2"
241
+ ;;
242
+ apple-transcript-text)
243
+ require_session_args "$@"
244
+ apple_transcript_text "$1" "$2"
245
+ ;;
246
+ transcript-url)
247
+ require_session_args "$@"
248
+ transcript_url "$1" "$2"
249
+ ;;
250
+ transcript-json)
251
+ require_session_args "$@"
252
+ resolved_transcript_json "$1" "$2"
253
+ ;;
254
+ transcript | transcript-text)
255
+ require_session_args "$@"
256
+ resolved_transcript_text "$1" "$2"
257
+ ;;
258
+ -h | --help | help | '')
259
+ usage
260
+ ;;
261
+ *)
262
+ echo "Unknown command: ${cmd}" >&2
263
+ usage >&2
264
+ exit 2
265
+ ;;
266
+ esac