@superwall/cli 2.4.0 → 2.5.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.
- package/dist/{apple-Bx_fm5M-.js → apple-Dyr7OFBx.js} +16 -15
- package/dist/approve-Czs1-JO9.js +186 -0
- package/dist/{assets-W5yvyf0V.js → assets-BrB9jQPQ.js} +3 -3
- package/dist/auth.d.ts +1 -1
- package/dist/auth.js +3 -3
- package/dist/{billing-C4lXR0xG.js → billing-D5qqIlVb.js} +3 -3
- package/dist/{bind-82oTpHZ3.js → bind-B3eEcRyp.js} +4 -4
- package/dist/browser-Bp3yRKlU.js +36 -0
- package/dist/{build-7_8cBgBm.js → build-DD9pSwHX.js} +9 -7
- package/dist/{client-ltxxHuxn.js → client-AI9H4GGB.js} +3 -3
- package/dist/{create-Dk8U_B49.js → create-B4m-IKlr.js} +8 -8
- package/dist/create-CJljlkJK.js +20 -0
- package/dist/{create-DEyveHS6.js → create-ChfgWpiM.js} +39 -67
- package/dist/{doctor-Df2GwS4K.js → doctor-XtXW6tKE.js} +6 -6
- package/dist/download-2Zu2I_Og.js +58 -0
- package/dist/{drivers-CTyYdBL7.js → drivers-CMEL13gp.js} +3 -3
- package/dist/entry.js +25 -24
- package/dist/{environment-djS0ik60.js → environment-BWT2S4qC.js} +3 -2
- package/dist/{existing-Das3PHGG.js → existing-b0GxFcnc.js} +2 -2
- package/dist/{session-CV0P8BjK.js → git-D7AVdugb.js} +96 -334
- package/dist/held-CX7Zf8u-.js +17 -0
- package/dist/{held-B8EFWDEc.js → held-D3PUNky2.js} +7 -7
- package/dist/install-CVUXsx8c.js +103 -0
- package/dist/{integrate-Cz48dm_h.js → integrate-qvKd9pVW.js} +27 -25
- package/dist/{login-girc324T.js → login-COmGHrU5.js} +2 -1
- package/dist/login-ClnJi1Ea.js +17 -0
- package/dist/{login-CiK5T4w8.js → login-PMoXUGqq.js} +8 -41
- package/dist/{lookup-us5vu5od.js → lookup-gjcKIZvh.js} +3 -2
- package/dist/{migrate-DaVwhdov.js → migrate-SkkLLdmr.js} +30 -25
- package/dist/{migration-cS6UGeUj.js → migration-DS44-3Zr.js} +9 -9
- package/dist/{notification-url-Hg42tAbW.js → notification-url-BjQPLf4-.js} +4 -4
- package/dist/{open-BIuOZ9ka.js → open-DQpm2yVs.js} +2 -2
- package/dist/{org-BrR4HGvl.js → org-C04eAO-j.js} +3 -2
- package/dist/organization-BOECL3vZ.js +39 -0
- package/dist/orgs-D6Kk96mG.js +81 -0
- package/dist/{paths-CdwjySxK.js → paths-REb-GrbX.js} +1 -1
- package/dist/{playbook-BJ3opYIS.js → playbook-Du4Oydbf.js} +10 -10
- package/dist/{products-DH_fK9tY.js → products-Cqq59DBQ.js} +1 -1
- package/dist/project-CP6hiHra.js +47 -0
- package/dist/{promote-BQO-1ScY.js → promote-Dm2_b1WK.js} +23 -18
- package/dist/pull-DsdOoG-D.js +36 -0
- package/dist/{pull-BhRswq6x.js → pull-F6pvO4To.js} +9 -28
- package/dist/pull-zYAbqo9n.js +106 -0
- package/dist/{push-CR110qRh.js → push-BIFLhAiO.js} +8 -6
- package/dist/push-CJVfvFZq.js +29 -0
- package/dist/push-D_l9KJZN.js +290 -0
- package/dist/push-SVzv7fzE.js +22 -0
- package/dist/{registry-DZsWoWqH.js → registry-DIJB0mJa.js} +687 -64
- package/dist/resolve--GsHj0Q1.js +171 -0
- package/dist/{resources-BMspgZO1.js → resources-BaP3p_LY.js} +3 -80
- package/dist/{run-D4V6mq8_.js → run-C5OPwhvS.js} +2 -2
- package/dist/run-CgLmD2vR.js +1345 -0
- package/dist/{scan-CRexsHOE.js → scan-Bj5y0zTZ.js} +1 -1
- package/dist/scan-v_WTE722.js +4 -0
- package/dist/{scope-Ct0_HoNq.js → scope-Bp_zwJOo.js} +5 -4
- package/dist/scope-CCb_7UvN.js +89 -0
- package/dist/sdk-TvT0p_nO.js +71 -0
- package/dist/selection-BltBpyp5.js +179 -0
- package/dist/series-TAixFBWW.js +685 -0
- package/dist/{server-Dv1VwbNh.js → server-CdVIboQn.js} +10 -8
- package/dist/server-CvJVusw3.js +29 -0
- package/dist/session-B8JNXkwN.js +6 -0
- package/dist/session-D3fgXQBt.js +219 -0
- package/dist/{session-UiPlLFn6.js → session-Ywim-P8M.js} +1 -1
- package/dist/{setup-UWLhQG3M.js → setup-zzjtTy8k.js} +9 -8
- package/dist/skills/index.json +5 -0
- package/dist/skills/superwall/SKILL.md +48 -30
- package/dist/skills/superwall/references/api.md +3 -2
- package/dist/skills/superwall-editor/SKILL.md +7 -5
- package/dist/skills/superwall-framework/SKILL.md +7 -5
- package/dist/skills/superwall-workspaces/SKILL.md +313 -0
- package/dist/skills/superwall-workspaces/references/cli.md +174 -0
- package/dist/skills/superwall-workspaces/references/slots.md +103 -0
- package/dist/{skills-CiWxt6vS.js → skills-2qYaUXGE.js} +4 -4
- package/dist/{skills-DzOvse9L.js → skills-8um2fBPS.js} +8 -8
- package/dist/{source-push-CX_k_yZD.js → source-push-kAep4gPe.js} +6 -5
- package/dist/{spinner-1uuKKZMc.js → spinner-BANVLncC.js} +16 -4
- package/dist/starter-CiLrp1cN.js +190 -0
- package/dist/status-CoYMK7QL.js +139 -0
- package/dist/{storage-CrXGgIbS.js → storage-DzP22xKn.js} +1 -1
- package/dist/storekit-D5eopLM0.js +17 -0
- package/dist/{storekit-CptdG4RJ.js → storekit-n1x0bWkQ.js} +4 -4
- package/dist/{telemetry-BqaPbM0k.js → telemetry-CXN6f-ZX.js} +1 -1
- package/dist/{token-zjjlkNDF.js → token-FmeHywYt.js} +1 -1
- package/dist/tools-skills/superwall/SKILL.md +49 -31
- package/dist/tools-skills/superwall/references/api.md +3 -2
- package/dist/tools-skills/superwall-editor/SKILL.md +7 -5
- package/dist/tools.d.ts +1 -1
- package/dist/tools.js +452 -27
- package/dist/try-BWbzgelb.js +120 -0
- package/dist/{selection-CgZJJ3FD.js → types-JdxmnCko.js} +1 -178
- package/dist/{upgrade-BBnmcyY2.js → upgrade-Bk5boOgW.js} +2 -2
- package/dist/{upgrade-AdyF7wXk.js → upgrade-CoWCEnoi.js} +2 -2
- package/package.json +5 -3
- package/dist/create-CBCDWuyo.js +0 -19
- package/dist/held-BL4oizD6.js +0 -16
- package/dist/login-DdrOmi6m.js +0 -16
- package/dist/push-B3Onn_mL.js +0 -24
- package/dist/scan-DUQjxOZf.js +0 -4
- package/dist/server-Cv-Ug9JF.js +0 -24
- package/dist/session-BCQuMcQ0.js +0 -6
- package/dist/storekit-B675ZNiA.js +0 -16
- /package/dist/{client-BZ1UbpXz.js → client-BJQXl62Q.js} +0 -0
- /package/dist/{devtools-pBl_vt03.js → devtools-ByZ6XYnn.js} +0 -0
- /package/dist/{input-vi0bou04.js → input-MDd67UIp.js} +0 -0
- /package/dist/{reports-CwwKLUh0.js → reports-CuhB1_ub.js} +0 -0
- /package/dist/{screenshot-file-tVBfUEIi.js → screenshot-file-XAS0Xy0e.js} +0 -0
- /package/dist/{storage-gRyQetN9.d.ts → storage-BjQCiTuz.d.ts} +0 -0
- /package/dist/{timing-BVxPrYq3.js → timing-Ca0TXY-A.js} +0 -0
|
@@ -0,0 +1,313 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: superwall-workspaces
|
|
3
|
+
description: Build and ship a Superwall workspace, a small Cloudflare Worker that adds to the Superwall dashboard, from your own machine with the `superwall workspaces` commands (`create`, `dev`, `try`, `update`, `push`, `pull`, `status`, `logs`, `share`, `approve`, `install`, `list`, `open`). Covers `superwall.json`, slots and their context, `metric()` for a chart in Charts, `readout()` for a row in a campaign's results, `fetch` for pages, panels, tabs, widgets and actions, the host bridge, scopes, and what the builder refuses. Use when the user wants a custom dashboard page, a metric or chart one query can't express, an own statistic on a campaign's results, or a panel or action on a user's page. NOT for screens shown inside an app (paywalls, onboarding), which are `superwall-framework`. For a one-off answer or a single query, use `superwall query`.
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Superwall workspaces
|
|
8
|
+
|
|
9
|
+
A workspace is a small Cloudflare Worker that adds to the Superwall dashboard. It holds no credential:
|
|
10
|
+
it calls Superwall as whoever is viewing it. You can build a page, a panel, a tab, a card, an action, a
|
|
11
|
+
metric in Charts or a row in a campaign's results.
|
|
12
|
+
|
|
13
|
+
The commands need `SUPERWALL_CHANNEL=next`, and Node 20 or later. `dev` and `try` need a browser login
|
|
14
|
+
(`superwall login`): an API key can't run them.
|
|
15
|
+
|
|
16
|
+
## The loop
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
superwall workspaces create my-workspace # downloads the starter and installs
|
|
20
|
+
cd my-workspace
|
|
21
|
+
superwall workspaces dev --app <app> # http://localhost:8790, real data, read-only
|
|
22
|
+
superwall workspaces try transactions --app <app> # a metric on the real runtime
|
|
23
|
+
superwall workspaces try home --org <org> # a page in the dashboard
|
|
24
|
+
superwall workspaces push --org <org> # build it; only you see it until an admin approves it
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
1. **`dev`** bundles it the way the builder does and runs it in workerd. A local page plays the
|
|
28
|
+
dashboard: it mounts pages and widgets, sends them context and theme, and runs metrics and readouts.
|
|
29
|
+
Saving a file rebuilds it. Only run code you trust: it reads everything you can read in that organization.
|
|
30
|
+
Its token is limited to one organization, which goes for a staff account too. Without a browser, POST to the page's own API (see `references/cli.md`).
|
|
31
|
+
2. **`try`** uploads a draft and runs it on the real runtime, as you, read-only and with no outside hosts.
|
|
32
|
+
Only you can reach a draft, for a day. A metric prints its series. A page, panel, tab, card or action
|
|
33
|
+
opens in the dashboard. Readouts can't be tried yet, so `dev` is how you run those.
|
|
34
|
+
3. Nothing is saved by either. **`push`** is what saves it: it sends the source over git, and the builder
|
|
35
|
+
makes a version from the commit. `push` waits for the build and shows the builder's message if it fails.
|
|
36
|
+
4. **Only the author can see a pushed version until an admin approves it.** Say so. A staff account gets no copy, so
|
|
37
|
+
nobody can see what it pushes until then, and `push` and `share` say which. `share` asks for review,
|
|
38
|
+
an admin runs `approve`, and `install` chooses where it shows. `org.page@1` needs no install.
|
|
39
|
+
5. **A pusher's own copy can include teammates' merged code, and it runs with the pusher's reads.** `push` lists
|
|
40
|
+
those commits and asks first. Without a terminal it stops unless `--accept-merged-commits` is passed. That flag
|
|
41
|
+
is for a person who has read them, so don't add it to get past the refusal.
|
|
42
|
+
|
|
43
|
+
Run `try` before you believe a scope is enough. `dev` reads everything you can read in its organization and warns about a
|
|
44
|
+
scope it knows is missing; a draft holds only the manifest's read scopes ∩ yours, and answers 403 otherwise.
|
|
45
|
+
|
|
46
|
+
## Files
|
|
47
|
+
|
|
48
|
+
| File | What it is |
|
|
49
|
+
| --------------------- | ------------------------------------------------------------------------------------------- |
|
|
50
|
+
| `superwall.json` | The manifest: what it can do and where it shows. |
|
|
51
|
+
| `src/worker.ts` | The code. One default export and no other exports. |
|
|
52
|
+
| `wrangler.jsonc` | `name`, `main` and `compatibility_date`. No bindings of any kind. |
|
|
53
|
+
| `package-lock.json` | Required, from npm. The builder installs exactly this. |
|
|
54
|
+
| `superwall.workspace.json` | Written by the first push: which workspace this is. Commit it, so teammates push to the same one. |
|
|
55
|
+
| `vendor/workspace-sdk` | Generated, never edited. `superwall workspaces update` refreshes it. There is no npm package. |
|
|
56
|
+
|
|
57
|
+
## A metric
|
|
58
|
+
|
|
59
|
+
`superwall.json`:
|
|
60
|
+
|
|
61
|
+
```json
|
|
62
|
+
{
|
|
63
|
+
"name": "Subscription health",
|
|
64
|
+
"scopes": ["data:read"],
|
|
65
|
+
"entrypoints": [
|
|
66
|
+
{
|
|
67
|
+
"id": "transactions",
|
|
68
|
+
"slot": "chart.source@1",
|
|
69
|
+
"title": "Transactions",
|
|
70
|
+
"metric": {
|
|
71
|
+
"description": "Under 280 characters.",
|
|
72
|
+
"value_type": "number",
|
|
73
|
+
"breakdowns": [{ "key": "store", "name": "Store" }],
|
|
74
|
+
"filters": [
|
|
75
|
+
{
|
|
76
|
+
"key": "store",
|
|
77
|
+
"name": "Store",
|
|
78
|
+
"values": [
|
|
79
|
+
{ "value": "APP_STORE", "label": "App Store" },
|
|
80
|
+
{ "value": "PLAY_STORE", "label": "Google Play" }
|
|
81
|
+
]
|
|
82
|
+
}
|
|
83
|
+
]
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
]
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Ids and keys are lowercase letters, digits and dashes, starting with a letter. `value_type` is `number`,
|
|
91
|
+
`percentage` or `currency`. `breakdowns` and `filters` are optional, 10 of each at most. `total` is `sum`
|
|
92
|
+
(the default) or `last`, for a count at a moment, where adding the days up means nothing.
|
|
93
|
+
|
|
94
|
+
`src/worker.ts`:
|
|
95
|
+
|
|
96
|
+
```ts
|
|
97
|
+
import type { MetricRequest, MetricSeries } from "@superwall/workspace-sdk/metrics"
|
|
98
|
+
import { defineWorkspace, superwallFetch } from "@superwall/workspace-sdk/server"
|
|
99
|
+
|
|
100
|
+
const UNITS = { hour: "HOUR", day: "DAY", week: "WEEK", month: "MONTH" }
|
|
101
|
+
const dateTime = (iso: string) => iso.slice(0, 19).replace("T", " ")
|
|
102
|
+
|
|
103
|
+
const metric = async ({
|
|
104
|
+
context,
|
|
105
|
+
from,
|
|
106
|
+
to,
|
|
107
|
+
interval,
|
|
108
|
+
timezone,
|
|
109
|
+
breakdown,
|
|
110
|
+
filters,
|
|
111
|
+
}: MetricRequest): Promise<MetricSeries> => {
|
|
112
|
+
const search = new URLSearchParams({
|
|
113
|
+
default_format: "JSON",
|
|
114
|
+
param_app: String(context.applicationId),
|
|
115
|
+
param_from: dateTime(from),
|
|
116
|
+
param_to: dateTime(to),
|
|
117
|
+
param_tz: timezone,
|
|
118
|
+
})
|
|
119
|
+
let storeFilter = ""
|
|
120
|
+
if (filters.store) {
|
|
121
|
+
storeFilter = "AND store IN {stores:Array(String)}"
|
|
122
|
+
search.set("param_stores", `[${filters.store.map((store) => `'${store}'`).join(",")}]`)
|
|
123
|
+
}
|
|
124
|
+
const unit = UNITS[interval]
|
|
125
|
+
const bucketOf = (time: string) =>
|
|
126
|
+
`toDateTime(toStartOfInterval(${time}, INTERVAL 1 ${unit}, {tz:String}), {tz:String})`
|
|
127
|
+
const sql = `
|
|
128
|
+
SELECT toString(toTimeZone(bucket, 'UTC')) AS t, breakdown, value
|
|
129
|
+
FROM (
|
|
130
|
+
SELECT ${bucketOf("ts")} AS bucket,
|
|
131
|
+
${breakdown === "store" ? "store" : "NULL"} AS breakdown,
|
|
132
|
+
uniq(transactionId) AS value
|
|
133
|
+
FROM open_revenue.attributed_events_by_ts_rep
|
|
134
|
+
WHERE applicationId = {app:UInt64} AND ts >= {from:DateTime} AND ts < {to:DateTime} AND ts < now()
|
|
135
|
+
AND isSandbox = 0 ${storeFilter}
|
|
136
|
+
GROUP BY bucket, breakdown
|
|
137
|
+
ORDER BY breakdown, bucket WITH FILL
|
|
138
|
+
FROM ${bucketOf("toDateTime({from:DateTime}, 'UTC')")}
|
|
139
|
+
TO least(toDateTime({to:DateTime}, 'UTC'), now())
|
|
140
|
+
STEP INTERVAL 1 ${unit}
|
|
141
|
+
)
|
|
142
|
+
ORDER BY breakdown, t`
|
|
143
|
+
const response = await superwallFetch(`/v2/organizations/${context.organizationId}/query?${search}`, {
|
|
144
|
+
method: "POST",
|
|
145
|
+
headers: { "content-type": "text/plain" },
|
|
146
|
+
body: sql,
|
|
147
|
+
})
|
|
148
|
+
if (!response.ok) throw new Error((await response.text()).slice(0, 500))
|
|
149
|
+
const { data } = (await response.json()) as {
|
|
150
|
+
data: ReadonlyArray<{ t: string; value: string | number; breakdown: string | null }>
|
|
151
|
+
}
|
|
152
|
+
return {
|
|
153
|
+
points: data.map((row) => ({
|
|
154
|
+
t: `${row.t.replace(" ", "T")}Z`,
|
|
155
|
+
value: Number(row.value),
|
|
156
|
+
breakdown: row.breakdown,
|
|
157
|
+
})),
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
export default defineWorkspace({
|
|
162
|
+
fetch: () => new Response("Not found", { status: 404 }),
|
|
163
|
+
metric,
|
|
164
|
+
})
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
- `metric()` is called with `metric` (the entrypoint id), `context` `{ organizationId, applicationId }`,
|
|
168
|
+
`from` and `to` (ISO 8601 in UTC, ending in Z), `interval` (`hour`, `day`, `week` or `month`), `timezone`,
|
|
169
|
+
`breakdown` (a declared key or null) and `filters` (declared keys to the values chosen; a key is absent
|
|
170
|
+
when nothing is chosen). Bucket in `timezone`, as the example does, or days land on the wrong side of the
|
|
171
|
+
viewer's midnight.
|
|
172
|
+
- It returns `{ points: [{ t, value, breakdown? }] }`. `t` is the bucket's start as ISO 8601 with an offset.
|
|
173
|
+
A bucket with no point is a gap, so return 0 where zero is what you mean. The example's `WITH FILL` does that;
|
|
174
|
+
a window with no rows at all still returns no points.
|
|
175
|
+
- Always honor `interval`, `breakdown` and `filters`, as the example does. Only ever build SQL from values
|
|
176
|
+
you control, or from filter values the manifest declares, which are the only ones that reach you.
|
|
177
|
+
- Prefer aggregated tables, filter `applicationId` and `isSandbox = 0`, and keep `ts < now()`. A slow query
|
|
178
|
+
fails the metric, so test it over the widest window you expect. Test the SQL with `superwall query` first.
|
|
179
|
+
- Limits: 10 seconds, 5,000 points, 50 series, 256 KB returned, 1 MB bundled for a draft.
|
|
180
|
+
|
|
181
|
+
A readout is the same idea for a campaign's results; see `references/slots.md`.
|
|
182
|
+
|
|
183
|
+
## A page
|
|
184
|
+
|
|
185
|
+
Name the page's browser code in `superwall.json`, and `dev`, `try` and the builder bundle it the same way.
|
|
186
|
+
No build script of yours runs. The starter's page is the worked example.
|
|
187
|
+
|
|
188
|
+
```json
|
|
189
|
+
{ "client": { "entry": "src/client.tsx" } }
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
```ts
|
|
193
|
+
// src/worker.ts. Browser code holds no credential, so it asks this Worker, which calls Superwall as the viewer.
|
|
194
|
+
import client from "@superwall/workspace-sdk/client-bundle"
|
|
195
|
+
import { clientPage, defineWorkspace, superwallFetch, type WorkspaceRequest } from "@superwall/workspace-sdk/server"
|
|
196
|
+
import type { OrgPageContextV1 } from "@superwall/workspace-sdk/slots"
|
|
197
|
+
|
|
198
|
+
const serve = ({ request, context }: WorkspaceRequest) => {
|
|
199
|
+
const { pathname } = new URL(request.url)
|
|
200
|
+
if (pathname === "/") return clientPage(client, { title: "Projects" })
|
|
201
|
+
if (pathname === "/api/projects") {
|
|
202
|
+
const { organizationId } = context as OrgPageContextV1
|
|
203
|
+
return superwallFetch(`/v2/projects?organization_id=${organizationId}`)
|
|
204
|
+
}
|
|
205
|
+
return new Response("Not found", { status: 404 })
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
export default defineWorkspace({ client, fetch: serve })
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
```tsx
|
|
212
|
+
// src/client.tsx
|
|
213
|
+
import type { Theme } from "@superwall/workspace-sdk/bridge"
|
|
214
|
+
import { connect } from "@superwall/workspace-sdk/client"
|
|
215
|
+
import { useEffect, useState } from "react"
|
|
216
|
+
import { createRoot } from "react-dom/client"
|
|
217
|
+
import "./styles.css"
|
|
218
|
+
|
|
219
|
+
const applyTheme = ({ tokens }: Theme) => {
|
|
220
|
+
for (const [name, value] of Object.entries(tokens)) document.documentElement.style.setProperty(`--${name}`, value)
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
const Home = () => {
|
|
224
|
+
const [projects, setProjects] = useState<ReadonlyArray<{ name: string }>>([])
|
|
225
|
+
useEffect(() => {
|
|
226
|
+
void connect().then((bridge) => {
|
|
227
|
+
applyTheme(bridge.theme)
|
|
228
|
+
bridge.onTheme(applyTheme)
|
|
229
|
+
})
|
|
230
|
+
// On a refusal, show the API's message: the starter's src/client.tsx does.
|
|
231
|
+
void fetch("/api/projects")
|
|
232
|
+
.then((response) => response.json() as Promise<{ data: ReadonlyArray<{ name: string }> }>)
|
|
233
|
+
.then(({ data }) => setProjects(data))
|
|
234
|
+
}, [])
|
|
235
|
+
return <ul>{projects.map((project) => <li key={project.name}>{project.name}</li>)}</ul>
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
createRoot(document.getElementById("root")!).render(<Home />)
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
`defineWorkspace({ client })` serves the bundle at `/_client/<hash>.js` and `.css`, and `clientPage` writes the
|
|
242
|
+
document that loads them, with an empty `<div id="root">`. The Worker also needs the import: with no `client` in the
|
|
243
|
+
manifest, it doesn't bundle.
|
|
244
|
+
|
|
245
|
+
**What the build does.** React's automatic JSX, TypeScript, CSS imports, images and fonts as data URLs, one script
|
|
246
|
+
and at most one stylesheet, 8 MiB together. `dev` rebuilds on any change in the project.
|
|
247
|
+
|
|
248
|
+
**What it doesn't do yet, because no customer script runs:**
|
|
249
|
+
|
|
250
|
+
- PostCSS and Tailwind's build. Run them yourself and commit the CSS they make.
|
|
251
|
+
- `paths` from `tsconfig.json` in browser code, because the build doesn't read that file. Wrangler still honors them
|
|
252
|
+
in the Worker, so the two differ. Use relative imports in browser code.
|
|
253
|
+
- Web Workers from `new URL(...)`.
|
|
254
|
+
|
|
255
|
+
**A draft can be 1 MiB at most,** so a large page works in `dev` and `push` and is refused by `try`.
|
|
256
|
+
|
|
257
|
+
A page with no npm packages can skip all of this: answer HTML from `fetch` and load the bridge from
|
|
258
|
+
`@superwall/workspace-sdk/client-script` in a `<script>`.
|
|
259
|
+
|
|
260
|
+
```json
|
|
261
|
+
{ "id": "home", "slot": "org.page@1", "title": "Projects", "path": "/" }
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
With scopes `["projects:read"]`, and connect within 8 seconds or the dashboard shows the load error. The
|
|
265
|
+
context comes from the platform, already authorized for the viewer. Never trust a user's id from the URL
|
|
266
|
+
over it. If you write HTML yourself, escape everything that came from the API or an end user.
|
|
267
|
+
|
|
268
|
+
## What it can reach
|
|
269
|
+
|
|
270
|
+
`https://api.workspace.internal` is the Superwall API (`superwallFetch` is a `fetch` to it). The viewer's
|
|
271
|
+
own access still applies on every call, narrowed by the manifest's `scopes`.
|
|
272
|
+
|
|
273
|
+
**Declare a scope for every API you call.** A route whose scope isn't declared answers a bare 403 at run
|
|
274
|
+
time, and `data:read` covers only SQL:
|
|
275
|
+
|
|
276
|
+
| Route | Read scope |
|
|
277
|
+
| ------------------------------------------- | ------------------------- |
|
|
278
|
+
| `/v2/organizations/:id/query` (SQL) | `data:read` |
|
|
279
|
+
| `/v2/projects` | `projects:read` |
|
|
280
|
+
| `/v2/applications/…` | `applications:read` |
|
|
281
|
+
| `/v2/paywalls` | `paywalls:read` |
|
|
282
|
+
| `/v2/campaigns` | `campaigns:read` |
|
|
283
|
+
| `/v2/products` | `products:read` |
|
|
284
|
+
| `/v2/entitlements` | `entitlements:read` |
|
|
285
|
+
| `/v2/charts/…`, `/v2/demand-score/…` | `charts:read` |
|
|
286
|
+
| `/v2/users`, `/v3/users` | `users:read` |
|
|
287
|
+
| `/v2/onboarding` | `onboarding:read` |
|
|
288
|
+
| `/v2/surveys` | `surveys:read` |
|
|
289
|
+
| `/v2/assets` | `assets:read` |
|
|
290
|
+
| `/v2/retention-messages` and its family | `retention_messages:read` |
|
|
291
|
+
| `/v2/projects/:id/custom-stores` | `custom_stores:read` |
|
|
292
|
+
|
|
293
|
+
**SQL runs only in an `org.page@1` or a metric.** Every other frame (`app.page`,
|
|
294
|
+
`app.dashboard.widget`, `campaign.tab`, `user.panel`, `user.action`) is tied to one app and can't reach
|
|
295
|
+
`/v2/organizations/:id/query`. Before you write one, decide where its data comes from: an API in the table,
|
|
296
|
+
which reaches only that app, or an `org.page@1` or a metric instead of it. Don't write a widget that needs SQL.
|
|
297
|
+
|
|
298
|
+
Dev and drafts read only, with no outside hosts and no raw sockets, whatever the manifest asks for.
|
|
299
|
+
|
|
300
|
+
**Not available yet:** storage, cron, events, jobs and secrets. The manifest fields exist, but nothing runs
|
|
301
|
+
them, and an admin can't approve a version that declares secrets. If the user's idea needs them, build the read-only part and say the rest can't be tried here.
|
|
302
|
+
|
|
303
|
+
## What the builder refuses
|
|
304
|
+
|
|
305
|
+
- Any binding in `wrangler.jsonc`: KV, R2, D1, services, vars, AI, assets, Durable Objects, Workflows,
|
|
306
|
+
Containers, cron triggers. Everything goes through `fetch`.
|
|
307
|
+
- A custom `build.command`, `no_bundle` or `find_additional_modules`, and text, data or wasm modules. A
|
|
308
|
+
workspace is exactly one bundled ES module, at most 10 MiB, exporting only its default handlers.
|
|
309
|
+
- `@superwall/workspace-sdk` from anywhere but `file:vendor/workspace-sdk`.
|
|
310
|
+
- A lockfile with a package from outside `registry.npmjs.org`, or without an integrity hash.
|
|
311
|
+
|
|
312
|
+
`dev` applies the bundle rules as it builds. `references/cli.md` lists what `dev` doesn't copy from the
|
|
313
|
+
real runtime, and what its errors mean.
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
# The commands
|
|
2
|
+
|
|
3
|
+
## `superwall workspaces dev [dir]`
|
|
4
|
+
|
|
5
|
+
| Flag | What it fills in |
|
|
6
|
+
| ---------------------------- | ------------------------------------------------------------------ |
|
|
7
|
+
| `--port`, `-p` | The dev page's port, 8790 by default. The frame takes the next one. |
|
|
8
|
+
| `--org`, `--app` | The organization, which is all its token reaches, and the app. `--app` alone finds the organization. |
|
|
9
|
+
| `--campaign`, `--audience`, `--variant` | A campaign tab's or readout's context. `--variant` repeats. |
|
|
10
|
+
| `--user`, `--alias` | A user panel's or action's context. `--alias` repeats. |
|
|
11
|
+
| `--environment` | `PRODUCTION` or `SANDBOX`, in capitals. |
|
|
12
|
+
| `--from`, `--to` | A date range, ISO 8601. The last 30 days by default. |
|
|
13
|
+
| `--context` | The whole context as JSON, for a slot this CLI doesn't know. |
|
|
14
|
+
|
|
15
|
+
The page lets you change all of these but the organization. To use another one, restart `dev` with its `--org`.
|
|
16
|
+
Without a browser, use its own API on the dev page's origin. A POST needs
|
|
17
|
+
that origin in an `Origin` header. It answers JSON, with `error` on a 400:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
curl -X POST localhost:8790/__dev/metric -H 'origin: http://localhost:8790' -H 'content-type: application/json' -d '{
|
|
21
|
+
"entrypoint": "transactions",
|
|
22
|
+
"input": { "applicationId": "42" },
|
|
23
|
+
"from": "2026-10-01T00:00:00Z", "to": "2026-10-08T00:00:00Z",
|
|
24
|
+
"interval": "day", "breakdown": "store", "filters": { "store": ["APP_STORE"] }
|
|
25
|
+
}'
|
|
26
|
+
|
|
27
|
+
curl -X POST localhost:8790/__dev/readout -H 'origin: http://localhost:8790' -H 'content-type: application/json' -d '{
|
|
28
|
+
"entrypoint": "lift",
|
|
29
|
+
"input": { "applicationId": "42", "campaignId": "7", "audienceId": "8", "variantIds": ["9", "10"] }
|
|
30
|
+
}'
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
### How `dev` differs from the real runtime
|
|
34
|
+
|
|
35
|
+
The same: workerd, a worker loader with the platform's modules, the bundle's own compatibility date and flags, no bindings, the same
|
|
36
|
+
bundling step, handlers called over RPC, the same checks on what a handler returns and how long it takes, no
|
|
37
|
+
`caches`, no outside hosts, no raw sockets, the same response headers and content security policy, a frame on
|
|
38
|
+
its own origin that really goes through the bridge, and which routes a slot can reach.
|
|
39
|
+
|
|
40
|
+
Different, so run `try` before believing these:
|
|
41
|
+
|
|
42
|
+
- **Scopes.** `dev` uses a read-only token as you, limited to one organization, for an hour at a time. It makes a new
|
|
43
|
+
one when that runs out. A staff account gets the same limit, so it reaches only that organization, and `dev` no
|
|
44
|
+
longer reads across every organization. It warns when a known route's scope isn't declared, and still answers. A
|
|
45
|
+
draft holds only the manifest's read scopes, and answers 403. Against an API that hasn't deployed limited tokens,
|
|
46
|
+
`dev` warns that its token reaches everything you can read.
|
|
47
|
+
- **App narrowing.** `dev` refuses the same routes the runtime does, for the slot's narrowing, with the same 403:
|
|
48
|
+
"Workspaces may not call this endpoint." It doesn't narrow data: on a route the slot can reach, the real runtime
|
|
49
|
+
holds it to one app, and `dev` lets it read another app in the organization. So don't rely on `dev` to catch an id
|
|
50
|
+
from the wrong app.
|
|
51
|
+
- **Frames** have one session per dev server, so two tabs of it share the last one opened. The local dashboard is
|
|
52
|
+
a stand-in, and its theme tokens are close to the real ones, not the same.
|
|
53
|
+
- **Limits.** CPU and subrequest limits don't apply locally.
|
|
54
|
+
- **The bundle** uses your project's wrangler and the esbuild it brings, and the builder uses its own pinned ones.
|
|
55
|
+
`client.entry` needs that esbuild to be the builder's version, so keep wrangler where the starter pins it. Both
|
|
56
|
+
ignore `.env`, `.wrangler/deploy/config.json` and your shell's `CLOUDFLARE_ENV`, and both refuse the same things,
|
|
57
|
+
so a config or an import the builder would fail stops `dev` and `try` first. A bundle runs on the `compatibility_date`
|
|
58
|
+
and flags in its wrangler config, in `dev` as on the platform. The date must be from 2024-09-23 to today, and the
|
|
59
|
+
only flags allowed are `nodejs_compat`, `nodejs_compat_v2` and `nodejs_als`.
|
|
60
|
+
- **Storage, cron, events, jobs and secrets** aren't available anywhere yet. The platform host answers 501.
|
|
61
|
+
|
|
62
|
+
## `superwall workspaces try <entrypoint>`
|
|
63
|
+
|
|
64
|
+
A metric prints each series' summary: `--app` (required), `--org`, `--dir`, `--from`, `--to`, `--days` (30),
|
|
65
|
+
`--interval` (`day`), `--breakdown`, `--filter key=value` (repeats), `--points`. `--json` adds the draft id, its
|
|
66
|
+
expiry, the scopes it asked for and the series.
|
|
67
|
+
|
|
68
|
+
A frame uploads, prints a link to `/<org>/workspace-drafts/<draft>` on the dashboard and, at a terminal, opens
|
|
69
|
+
it: `--org` or `--app`, `--campaign`, `--user`, `--environment`, `--no-open`. `--json` gives the link as `url`.
|
|
70
|
+
A readout says to use `dev`.
|
|
71
|
+
|
|
72
|
+
If your code throws, `try` shows your own message. A 403 from inside your code is a missing scope.
|
|
73
|
+
|
|
74
|
+
## `superwall workspaces create [dir]`
|
|
75
|
+
|
|
76
|
+
Downloads the starter into `dir` (`my-workspace` by default), names it after the directory and runs
|
|
77
|
+
`npm install`. `--no-install` skips the install. It refuses a directory with files in it.
|
|
78
|
+
|
|
79
|
+
## `superwall workspaces update [dir]`
|
|
80
|
+
|
|
81
|
+
Replaces `vendor/workspace-sdk` with the latest, points `package.json` at it and updates the lockfile. Commit
|
|
82
|
+
both. If yours is newer than the latest published one, it says so and leaves it unless you pass `--force`. `dev` and `try` say when yours is behind, and never stop you if they can't check.
|
|
83
|
+
|
|
84
|
+
## `superwall workspaces push [dir]`
|
|
85
|
+
|
|
86
|
+
`--org` (on the first push), `-m <note>`, `--overwrite-source`, `--accept-merged-commits`, `--json`. The first push creates the workspace from
|
|
87
|
+
the manifest's name, or reuses the one with that slug. It waits for the build, up to 20 minutes, and a build that
|
|
88
|
+
fails or outlasts that exits 1. `--json` gives `version_id`, `status`, `failure`, `steps` and `url` either way, and `visible_to` (`you`, `its_author`, `nobody` or `everyone`) when it builds. The link it prints opens the page: for a workspace with an `app.page@1` and no `org.page@1`, that's the page in the first app, and `open <entrypoint> --app <id>` opens it in another.
|
|
89
|
+
|
|
90
|
+
If a teammate changed the same files, it stops and says to run `pull`. `--overwrite-source` replaces the whole
|
|
91
|
+
source repo with this project, so use it only when you mean to discard what's there.
|
|
92
|
+
|
|
93
|
+
**A pusher's own copy can include teammates' code.** When the source repo has commits this project doesn't,
|
|
94
|
+
`push` merges them, and the version runs them with the pusher's reads. So it lists them and asks: "Your copy
|
|
95
|
+
will run commits from <names> with your reads." Without a terminal it pushes nothing, exits 1 and, with `--json`,
|
|
96
|
+
gives `reason: "needs_accept_merged_commits"` and `merged_commits`. Don't add `--accept-merged-commits` to get past
|
|
97
|
+
this. Read the commits first with `pull`, or ask the person to confirm. This applies to any commit it hasn't seen,
|
|
98
|
+
even one under your own name, because a commit's author is whatever its pusher set. It also applies to a push with
|
|
99
|
+
no changes of your own, whose build would be their commit. It asks once per commit.
|
|
100
|
+
|
|
101
|
+
A build can wait or stop for reasons that aren't your code:
|
|
102
|
+
|
|
103
|
+
- **An organization runs three builds at once.** `push` says so and keeps trying on its own, for up to 20 minutes, with nothing to push again.
|
|
104
|
+
- **A workspace can have 100 new versions a day.** `push` stops and says trying soon won't help. Your source is already pushed, so push again later.
|
|
105
|
+
- **A failure code of `busy` or `unavailable`** means no build machine was free or the platform failed. Run `push` again in a few minutes, and it retries the same version.
|
|
106
|
+
|
|
107
|
+
**Who can do what.** `EDITOR` and `USER` can push. Approving and installing need `OWNER` or `ADMIN`. A member with access to only some projects can't build or approve, because a workspace reaches every project, and the command shows why.
|
|
108
|
+
|
|
109
|
+
## `superwall workspaces pull [dir]`
|
|
110
|
+
|
|
111
|
+
Merges teammates' pushes into this project. `--theirs` takes the source repo's version of files you both changed.
|
|
112
|
+
`--workspace <id>` fills an empty folder with a workspace's source. The next `push` won't ask about what you pulled,
|
|
113
|
+
so read it first: your own copy runs all of it with your reads.
|
|
114
|
+
|
|
115
|
+
## `status`, `logs`, `share`, `list`, `open`
|
|
116
|
+
|
|
117
|
+
`status` shows the state, the latest three versions and the live one, and `--all` lists them all. `logs [version]` prints the last 128 KiB of a build's log once it has
|
|
118
|
+
finished. `share [version]` marks the latest built version for review. Nobody is told automatically, so for someone
|
|
119
|
+
who can't approve it, it names who can, when their role can see that. `list --org` lists an organization's
|
|
120
|
+
workspaces. `open` prints the dashboard link and opens it at a terminal; `open <entrypoint> --app <id>` opens one
|
|
121
|
+
entrypoint inside an app.
|
|
122
|
+
|
|
123
|
+
Each takes `--workspace <id>` (or a slug with `--org`), and otherwise reads this project's `superwall.workspace.json`.
|
|
124
|
+
|
|
125
|
+
## `superwall workspaces approve [version]` (admins)
|
|
126
|
+
|
|
127
|
+
Shows what the version can do and how it differs from what's granted, then asks. **Never run it with flags before
|
|
128
|
+
a person has read that.** Without a terminal it needs `--yes`, and `--accept-changes` too when scopes, hosts,
|
|
129
|
+
secrets, entrypoints, crons, events, storage or the bundle's compatibility date and flags change. `--json` with neither approves nothing, prints `manifest`
|
|
130
|
+
and `diff`, and exits 1, so run that first and show the person the result.
|
|
131
|
+
|
|
132
|
+
## `superwall workspaces install [entrypoint]` (admins)
|
|
133
|
+
|
|
134
|
+
With no entrypoint, lists what's installed. Otherwise installs it from the live version for the whole organization,
|
|
135
|
+
or one app with `--app`. `--disable` turns it off and keeps its row, `--remove` deletes the row and ends open
|
|
136
|
+
sessions (`--yes` without a terminal), and `--position` orders entrypoints in a slot. Every slot but `org.page@1`
|
|
137
|
+
shows only where it's installed and enabled.
|
|
138
|
+
|
|
139
|
+
## What errors mean
|
|
140
|
+
|
|
141
|
+
| You see | It means |
|
|
142
|
+
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
143
|
+
| `needs a browser login` | You're signed in with an API key. Run `superwall login`. |
|
|
144
|
+
| `POSTs here need the header Origin` | You called the dev page's API without its `Origin` header. Add it, as in the examples above. |
|
|
145
|
+
| `… 403 … Dev's token is read-only` | A write, or a route outside what a workspace can read, like `/v2/me`. The real runtime refuses it too. |
|
|
146
|
+
| `You can't mint an Agent Token for organization …` | You aren't a member of it, or your access ended. Check `--org`. |
|
|
147
|
+
| `This dev is running against organization …` | Its token reaches that one only. Restart `dev` with `--org`. |
|
|
148
|
+
| `This would fail on the builder. …` | Your wrangler config has something a workspace can't use: `vars`, a binding, `site`, an `env` section, a build command or a key the builder doesn't know. A workspace needs `name`, `main` and `compatibility_date`, and little else. The date and flags have limits too. |
|
|
149
|
+
| `The bundle reads files outside the repo …` | An import, or a link, reaches past the repo or into `.git`. Move the file into the repo. |
|
|
150
|
+
| `client.entry: … is not in the repo` | The path in `superwall.json` is wrong. |
|
|
151
|
+
| `src/client.tsx:3:14: …` | esbuild's error in your browser code. The builder would say the same. |
|
|
152
|
+
| `Could not resolve "@superwall/workspace-sdk/client-bundle"` | The Worker imports the bundle and `superwall.json` has no `client`. |
|
|
153
|
+
| `The client bundle is … bytes` | Over 8 MiB. It lists the largest files. |
|
|
154
|
+
| `This project's workspace SDK is too old for client.entry` | Run `superwall workspaces update`, then `npm install`. |
|
|
155
|
+
| `bundled with esbuild 0.28.2, not …` | This project's wrangler brings another esbuild. Install the wrangler the starter pins. |
|
|
156
|
+
| `Refused GET https://…: dev runs like a draft` | Outside hosts are off in dev and drafts. |
|
|
157
|
+
| `Someone else pushed changes to …` | A teammate changed the same files. Run `superwall workspaces pull`, then push again. |
|
|
158
|
+
| `The build failed at …` | The builder's own words. `superwall workspaces logs` has the rest. A new push, or the same commit again, retries. |
|
|
159
|
+
| `Your copy would run commits from …` | `push` would merge teammates' commits into your own copy. Run `pull` to read them, then push. |
|
|
160
|
+
| `Only organization owners and admins can …` | Your role can't do this. `share` says who can, when your role can see that. |
|
|
161
|
+
| `Building a workspace needs access to all projects` | An owner or admin has to change your project access. |
|
|
162
|
+
| `… builds running` | Your organization's three builds are taken. `push` waits and retries on its own. |
|
|
163
|
+
| `… pushes in the last day` | The daily limit. Trying soon won't help. |
|
|
164
|
+
| `All the build machines are busy` or `… usually temporary` | Not your code. Run `push` again in a few minutes. |
|
|
165
|
+
| `Nothing was approved …` | `approve` needs a person, or `--yes`, plus `--accept-changes` when what it can do changes. |
|
|
166
|
+
| `… needs projects:read, which superwall.json doesn't declare` | Add it to `scopes`. It answers 403 on the real runtime. |
|
|
167
|
+
| `Workspaces may not call this endpoint.` | The route isn't open to workspaces, or to this slot. A slot tied to one app can't reach `/v2/projects` or SQL, on the real runtime too. Use its app's routes, an `org.page@1` or a metric. |
|
|
168
|
+
| `The environment must be PRODUCTION or SANDBOX` | In capitals, in `--environment`, `--context` and dev's page API. |
|
|
169
|
+
| `The metric handler didn't answer within 10 seconds` | The real limit. Query an aggregated table or a narrower window. A cold first query can be slow, so run it again once. |
|
|
170
|
+
| `A point's t must be an ISO 8601 date-time` | ClickHouse returned `2026-10-01 00:00:00`. Replace the space with `T` and add `Z`, as the example does. |
|
|
171
|
+
| `Port … is already in use` | Something else has that port. Pick another with `--port`; dev takes the one after it too. |
|
|
172
|
+
| `The workspace didn't start … compatibility date is too new` | Your wrangler is older than the platform's date. Run `npm install -D wrangler@latest`. |
|
|
173
|
+
| `exactly one ES module` or `exports …` | A text, data or wasm import, or a named export. Inline it, or export only the default. |
|
|
174
|
+
| `The analytics query didn't finish`, or a 503 about row policies | A passing failure of the query endpoint. Try again. |
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
# Slots, the bridge and scopes
|
|
2
|
+
|
|
3
|
+
A slot is where an entrypoint shows. Every id in its context is authorized for the viewer before your code
|
|
4
|
+
sees it.
|
|
5
|
+
|
|
6
|
+
| Slot | Shows as | Context, besides `organizationId` |
|
|
7
|
+
| ------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------- |
|
|
8
|
+
| `org.page@1` | A full page for the organization | None |
|
|
9
|
+
| `app.page@1` | A full page in an app's sidebar | `applicationId`, `environment` |
|
|
10
|
+
| `app.dashboard.widget@1` | A card on an app's dashboard, 120 to 480 px | `applicationId`, `environment`, `dateRange` |
|
|
11
|
+
| `campaign.tab@1` | A tab on a campaign, 240 to 4000 px | `applicationId`, `campaignId`, `audienceId` (or null), `variantIds`, `environment`, `dateRange` |
|
|
12
|
+
| `user.panel@1` | A panel on a user's page, 80 to 640 px | `applicationId`, `appUserId`, `aliases`, `environment` |
|
|
13
|
+
| `user.action@1` | An action in a user's menu, a modal, 120 to 640 px | The same as `user.panel@1` |
|
|
14
|
+
| `chart.source@1` | A metric in Charts, with no frame | `applicationId`, and the request's window |
|
|
15
|
+
| `campaign.metric@1` | A row in a campaign's results, with no frame | `applicationId`, `campaignId`, `audienceId`, `variantIds`, `environment` |
|
|
16
|
+
|
|
17
|
+
Only `org.page@1`, `chart.source@1` and `campaign.metric@1` can run SQL. The other frames are tied to one app.
|
|
18
|
+
`environment` is `PRODUCTION` or `SANDBOX`. `dateRange` is `{ from, to }`, ISO 8601, `[from, to)`. A rendered
|
|
19
|
+
slot needs a `path` and takes no `metric`; a headless one needs a `metric` and takes no `path`.
|
|
20
|
+
|
|
21
|
+
## Types
|
|
22
|
+
|
|
23
|
+
```ts
|
|
24
|
+
import type { MetricRequest, MetricSeries, ReadoutRequest, ReadoutResult } from "@superwall/workspace-sdk/metrics"
|
|
25
|
+
import type { SlotContext, UserPanelContextV1 } from "@superwall/workspace-sdk/slots"
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## A readout
|
|
29
|
+
|
|
30
|
+
`campaign.metric@1`: one number per variant, for one audience, all-time.
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{
|
|
34
|
+
"id": "lift",
|
|
35
|
+
"slot": "campaign.metric@1",
|
|
36
|
+
"title": "Bayesian lift",
|
|
37
|
+
"metric": { "value_type": "percentage", "lower_is_better": false }
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
import type { ReadoutRequest, ReadoutResult } from "@superwall/workspace-sdk/metrics"
|
|
43
|
+
|
|
44
|
+
const readout = async ({ context }: ReadoutRequest): Promise<ReadoutResult> => ({
|
|
45
|
+
variants: context.variantIds.map((variantId) => ({ variantId, value: 0.42, interval: [0.4, 0.44] })),
|
|
46
|
+
})
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Pass it to `defineWorkspace({ fetch, readout })`. `value` is null when there's nothing to show yet.
|
|
50
|
+
`interval` is optional and must hold `value`. Each variant at most once, and only this audience's; one you
|
|
51
|
+
leave out shows as having no value. Limits: 10 seconds, 32 KB. A readout metric takes no `breakdowns`,
|
|
52
|
+
`filters` or `total`.
|
|
53
|
+
|
|
54
|
+
## The bridge
|
|
55
|
+
|
|
56
|
+
`connect()` waits for the host, then replies `ready`. It trusts Superwall's dashboards, and a localhost host
|
|
57
|
+
when the frame is on localhost too (which is `dev`). Import `@superwall/workspace-sdk/client` from your
|
|
58
|
+
`client.entry`; `client-script` gives you the same thing as `superwallWorkspace.connect` on a plain page.
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
bridge.context // the slot's context
|
|
62
|
+
bridge.theme // { mode: "light" | "dark", tokens }
|
|
63
|
+
bridge.onContext((context) => {})
|
|
64
|
+
bridge.onTheme((theme) => {})
|
|
65
|
+
bridge.onVisibility((visible) => {})
|
|
66
|
+
bridge.send({ _tag: "toast", kind: "success", message: "Saved" }) // kind: info, success or error
|
|
67
|
+
bridge.send({ _tag: "navigate", to: "user", params: { applicationId: "42", appUserId: "alice" } })
|
|
68
|
+
bridge.send({ _tag: "actionResult", status: "success", message: "Done", refresh: ["user"] })
|
|
69
|
+
bridge.send({ _tag: "error", message: "What went wrong, up to 500 characters" })
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
- `navigate` goes to `campaign` (`applicationId`, `campaignId`), `user` (`applicationId`, `appUserId`) or
|
|
73
|
+
`workspace` (`slug`). The host builds the route; it never takes a URL.
|
|
74
|
+
- `actionResult` means something only in `user.action@1`, the modal slot.
|
|
75
|
+
- `resize` is sent for you as the document grows, and clamped to the slot. A page and a widget fill what
|
|
76
|
+
holds them and ignore it, so a widget must handle being narrow and scroll inside itself.
|
|
77
|
+
- Theme tokens: `background`, `foreground`, `card`, `card-foreground`, `popover`, `muted`,
|
|
78
|
+
`muted-foreground`, `border`, `primary`, `primary-foreground`, `secondary`, `secondary-foreground`,
|
|
79
|
+
`destructive`, `success`, `warning`, `info`, `fg-secondary`, `fg-tertiary`, `radius`.
|
|
80
|
+
|
|
81
|
+
## Scopes
|
|
82
|
+
|
|
83
|
+
A manifest can ask for only these, and the viewer's own access still applies:
|
|
84
|
+
|
|
85
|
+
`projects:read`, `applications:read`, `paywalls:read`, `paywalls:write`, `campaigns:read`, `campaigns:write`,
|
|
86
|
+
`products:read`, `products:write`, `entitlements:read`, `entitlements:write`, `webhooks:read`, `charts:read`,
|
|
87
|
+
`users:read`, `customers:read`, `custom_stores:read`, `custom_stores:write`, `custom_store_events:write`,
|
|
88
|
+
`retention_messages:read`, `retention_messages:write`, `notifications:read`, `notifications:write`,
|
|
89
|
+
`assets:read`, `assets:write`, `data:read`, `surveys:read`, `surveys:write`, `onboarding:read`.
|
|
90
|
+
|
|
91
|
+
`SKILL.md` has which route needs which scope. A route whose scope isn't declared answers 403. Writes do nothing
|
|
92
|
+
in `dev` or a draft.
|
|
93
|
+
|
|
94
|
+
Routes a workspace can call: reads under `/v2/projects`, `/v2/applications`, `/v2/charts`, `/v2/users`,
|
|
95
|
+
`/v3/users`, `/v2/onboarding`, `/v2/retention-onboarding` and `/v2/demand-score`; reads and, where the scope
|
|
96
|
+
allows, writes under `/v2/paywalls`, `/v2/campaigns`, `/v2/products`, `/v2/entitlements`, `/v2/grants`,
|
|
97
|
+
`/v2/assets`, `/v2/surveys` and the retention families. Nothing under `/v2/me`, access, tokens or transfers.
|
|
98
|
+
|
|
99
|
+
**A slot tied to one app reaches fewer.** That's every rendered slot but `org.page@1`: `app.page@1`, widgets, tabs,
|
|
100
|
+
panels and actions. They reach `/v2/campaigns`, `/v2/surveys`, the retention families, `/v2/users`, `/v3/users`,
|
|
101
|
+
`/v2/charts`, `/v2/paywalls`, `/v2/applications/<id>/…`, and one product, entitlement or asset by id. They can't reach
|
|
102
|
+
`/v2/projects`, SQL, or a list of products, entitlements or assets, which show sibling apps. Anything else answers 403
|
|
103
|
+
with "Workspaces may not call this endpoint.", in `dev` too. Metrics and readouts aren't held to this list.
|
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { c as CHANNELS, s as CHANNEL, x as VERSION } from "./environment-BWT2S4qC.js";
|
|
2
2
|
import { c as readSkillsSync, g as writeSkillsSync } from "./config-CGcG7GOt.js";
|
|
3
|
-
import { r as track } from "./telemetry-
|
|
3
|
+
import { r as track } from "./telemetry-CXN6f-ZX.js";
|
|
4
4
|
import { r as spawnStream } from "./spawn-DmmmHIP-.js";
|
|
5
|
-
import { n as withSpinner } from "./spinner-
|
|
5
|
+
import { n as withSpinner } from "./spinner-BANVLncC.js";
|
|
6
6
|
import { n as ui } from "./ui-D_qf3Gvw.js";
|
|
7
|
-
import { i as packagedDir, t as AGENT_SKILLS_DIR } from "./paths-
|
|
7
|
+
import { i as packagedDir, t as AGENT_SKILLS_DIR } from "./paths-REb-GrbX.js";
|
|
8
8
|
import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
|
|
9
9
|
import { tmpdir } from "node:os";
|
|
10
10
|
import { join } from "node:path";
|
|
@@ -1,14 +1,14 @@
|
|
|
1
|
-
import "./token-
|
|
1
|
+
import "./token-FmeHywYt.js";
|
|
2
2
|
import "./output-Ggzq5_-t.js";
|
|
3
|
-
import "./environment-
|
|
4
|
-
import "./storage-
|
|
5
|
-
import "./client-
|
|
3
|
+
import "./environment-BWT2S4qC.js";
|
|
4
|
+
import "./storage-DzP22xKn.js";
|
|
5
|
+
import "./client-AI9H4GGB.js";
|
|
6
6
|
import "./config-CGcG7GOt.js";
|
|
7
|
-
import "./telemetry-
|
|
7
|
+
import "./telemetry-CXN6f-ZX.js";
|
|
8
8
|
import "./spawn-DmmmHIP-.js";
|
|
9
|
-
import "./spinner-
|
|
9
|
+
import "./spinner-BANVLncC.js";
|
|
10
10
|
import "./ui-D_qf3Gvw.js";
|
|
11
|
-
import "./paths-
|
|
12
|
-
import { a as bundledSkills, c as knownSkills, d as readBundledSkill, f as runSkills, h as updateSkills, i as SUPERWALL_SKILLS_SOURCE, l as normalizeSkillFrontmatter, m as skillsRefFor, n as SKILLS_INSTALL_SOURCE, o as checkSkillsSync, p as skillSummary, r as SKILLS_REF, s as ensureSkillsCurrent, t as PLAYBOOKS, u as normalizeSkillsDir } from "./skills-
|
|
11
|
+
import "./paths-REb-GrbX.js";
|
|
12
|
+
import { a as bundledSkills, c as knownSkills, d as readBundledSkill, f as runSkills, h as updateSkills, i as SUPERWALL_SKILLS_SOURCE, l as normalizeSkillFrontmatter, m as skillsRefFor, n as SKILLS_INSTALL_SOURCE, o as checkSkillsSync, p as skillSummary, r as SKILLS_REF, s as ensureSkillsCurrent, t as PLAYBOOKS, u as normalizeSkillsDir } from "./skills-2qYaUXGE.js";
|
|
13
13
|
|
|
14
14
|
export { PLAYBOOKS, SKILLS_INSTALL_SOURCE, SKILLS_REF, SUPERWALL_SKILLS_SOURCE, bundledSkills, checkSkillsSync, ensureSkillsCurrent, knownSkills, normalizeSkillFrontmatter, normalizeSkillsDir, readBundledSkill, runSkills, skillSummary, skillsRefFor, updateSkills };
|