@superwall/cli 2.5.0 → 2.5.2
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/README.md +7 -0
- package/dist/{apple-Dyr7OFBx.js → apple-D2z3tALE.js} +14 -14
- package/dist/{approve-Czs1-JO9.js → approve-I-lvTanp.js} +35 -28
- package/dist/{assets-BrB9jQPQ.js → assets-oo93EFou.js} +3 -3
- package/dist/auth.d.ts +1 -1
- package/dist/auth.js +3 -3
- package/dist/{session-D3fgXQBt.js → base-Cft9NZfU.js} +35 -35
- package/dist/{billing-D5qqIlVb.js → billing-Bo1UEKqV.js} +3 -3
- package/dist/{bind-B3eEcRyp.js → bind-BvScWziR.js} +4 -4
- package/dist/{build-DD9pSwHX.js → build-Co487gha.js} +11 -9
- package/dist/{client-AI9H4GGB.js → client-Tp6iD66_.js} +55 -5
- package/dist/create-CHIPz5vb.js +20 -0
- package/dist/{create-ChfgWpiM.js → create-G3HuOHZ4.js} +31 -31
- package/dist/{create-B4m-IKlr.js → create-uA3nrMIa.js} +6 -6
- package/dist/design-lint-CiFc78aM.js +158 -0
- package/dist/{doctor-XtXW6tKE.js → doctor-CHF9aNFc.js} +6 -6
- package/dist/{drivers-CMEL13gp.js → drivers-YZEcBiSV.js} +3 -3
- package/dist/entry.js +20 -20
- package/dist/{environment-BWT2S4qC.js → environment-EU7Mrk7j.js} +3 -3
- package/dist/{existing-b0GxFcnc.js → existing-DV_6NLfW.js} +2 -2
- package/dist/{selection-BltBpyp5.js → framework-b-Yf8sP1.js} +50 -50
- package/dist/held-Dd19AduK.js +17 -0
- package/dist/{held-D3PUNky2.js → held-L0vz0_hA.js} +6 -6
- package/dist/install-CXfLcLhU.js +109 -0
- package/dist/{integrate-qvKd9pVW.js → integrate-DS2YGLsM.js} +23 -23
- package/dist/{types-JdxmnCko.js → lock-DgSx-p8Y.js} +79 -79
- package/dist/login-C0BjJmFy.js +17 -0
- package/dist/{login-PMoXUGqq.js → login-Ca6FhI6R.js} +6 -6
- package/dist/{login-COmGHrU5.js → login-DoMmU3Bq.js} +1 -1
- package/dist/{lookup-gjcKIZvh.js → lookup-DhMLZmdW.js} +3 -3
- package/dist/{migrate-SkkLLdmr.js → migrate-CoQWqzhJ.js} +29 -29
- package/dist/{migration-DS44-3Zr.js → migration-C22iQzAW.js} +29 -11
- package/dist/{notification-url-BjQPLf4-.js → notification-url-CqnXE9yB.js} +2 -2
- package/dist/{open-DQpm2yVs.js → open-DriuY3di.js} +2 -2
- package/dist/{org-C04eAO-j.js → org-D7LQrg3k.js} +3 -3
- package/dist/{organization-BOECL3vZ.js → organization-DDidaGRK.js} +8 -8
- package/dist/{orgs-D6Kk96mG.js → orgs-CYXjVdxM.js} +1 -1
- package/dist/{paths-REb-GrbX.js → paths-Bf3othB-.js} +1 -1
- package/dist/{playbook-Du4Oydbf.js → playbook-K7vmAUsu.js} +10 -10
- package/dist/{project-CP6hiHra.js → project-NoMtbMyl.js} +9 -9
- package/dist/{promote-Dm2_b1WK.js → promote-DXxxj4BU.js} +23 -22
- package/dist/pull-Bfa3_SBt.js +106 -0
- package/dist/pull-DGrlBSAG.js +36 -0
- package/dist/{pull-F6pvO4To.js → pull-DuFUkP7t.js} +8 -8
- package/dist/{push-D_l9KJZN.js → push-CrowxhpU.js} +54 -48
- package/dist/push-DPZdch2W.js +30 -0
- package/dist/push-DV-kJZdw.js +22 -0
- package/dist/{push-BIFLhAiO.js → push-Dk5x2xP3.js} +122 -22
- package/dist/{registry-DIJB0mJa.js → registry-HhZVRBqY.js} +178 -155
- package/dist/resolve-D3RBtfkI.js +242 -0
- package/dist/{resources-BaP3p_LY.js → resources-CkG6SCia.js} +2 -2
- package/dist/{run-C5OPwhvS.js → run-CL5ZnujW.js} +2 -2
- package/dist/{run-CgLmD2vR.js → run-Co8u_BkN.js} +93 -70
- package/dist/scan-BQmjhs3g.js +4 -0
- package/dist/{scan-Bj5y0zTZ.js → scan-DhmGH1rF.js} +1 -1
- package/dist/{scope-Bp_zwJOo.js → scope-D0XpYMn4.js} +5 -5
- package/dist/{scope-CCb_7UvN.js → scope-ehZ7L1nj.js} +25 -11
- package/dist/{sdk-TvT0p_nO.js → sdk-DEfQttek.js} +7 -7
- package/dist/{series-TAixFBWW.js → series-D2ZpZ8cx.js} +96 -63
- package/dist/server-4ZK_1Off.js +29 -0
- package/dist/{server-CdVIboQn.js → server-DamMN_ig.js} +9 -9
- package/dist/session-4F_YWSul.js +6 -0
- package/dist/{session-Ywim-P8M.js → session-G1uwJI8L.js} +1 -1
- package/dist/{setup-zzjtTy8k.js → setup-BFTSxEWU.js} +9 -9
- package/dist/skills/index.json +2 -2
- package/dist/skills/superwall/workflows/integrate/flutter.md +9 -7
- package/dist/skills/{superwall-workspaces → superwall-artifacts}/SKILL.md +47 -32
- package/dist/skills/{superwall-workspaces → superwall-artifacts}/references/cli.md +35 -29
- package/dist/skills/{superwall-workspaces → superwall-artifacts}/references/slots.md +9 -9
- package/dist/{skills-2qYaUXGE.js → skills-CE4c9eHX.js} +4 -4
- package/dist/{skills-8um2fBPS.js → skills-ClEVgXUB.js} +8 -8
- package/dist/{git-D7AVdugb.js → source-BccdO4aL.js} +111 -102
- package/dist/{source-push-kAep4gPe.js → source-push-EyF02ekO.js} +43 -26
- package/dist/{spinner-BANVLncC.js → spinner-mWZnJCkN.js} +3 -3
- package/dist/{starter-CiLrp1cN.js → starter-BtUUQWhd.js} +38 -28
- package/dist/{status-CoYMK7QL.js → status-SAZxltzW.js} +42 -39
- package/dist/{storage-DzP22xKn.js → storage-R5-qDvHq.js} +1 -1
- package/dist/{storekit-n1x0bWkQ.js → storekit-CQHVFTOC.js} +3 -3
- package/dist/storekit-DK3xXKoY.js +17 -0
- package/dist/{telemetry-CXN6f-ZX.js → telemetry-B-uKuu49.js} +1 -1
- package/dist/{token-FmeHywYt.js → token-C2kzntVM.js} +1 -1
- package/dist/tools.d.ts +6 -1
- package/dist/tools.js +208 -130
- package/dist/{try-BWbzgelb.js → try-BrJJyXgq.js} +32 -32
- package/dist/{upgrade-CoWCEnoi.js → upgrade-g_Bd9oJe.js} +2 -2
- package/dist/{upgrade-Bk5boOgW.js → upgrade-zOXTIaAZ.js} +2 -2
- package/package.json +2 -2
- package/dist/create-CJljlkJK.js +0 -20
- package/dist/held-CX7Zf8u-.js +0 -17
- package/dist/install-CVUXsx8c.js +0 -103
- package/dist/login-ClnJi1Ea.js +0 -17
- package/dist/pull-DsdOoG-D.js +0 -36
- package/dist/pull-zYAbqo9n.js +0 -106
- package/dist/push-CJVfvFZq.js +0 -29
- package/dist/push-SVzv7fzE.js +0 -22
- package/dist/resolve--GsHj0Q1.js +0 -171
- package/dist/scan-v_WTE722.js +0 -4
- package/dist/server-CvJVusw3.js +0 -29
- package/dist/session-B8JNXkwN.js +0 -6
- package/dist/storekit-D5eopLM0.js +0 -17
- /package/dist/{download-2Zu2I_Og.js → download-DhGd4hOB.js} +0 -0
- /package/dist/{reports-CuhB1_ub.js → reports-HYVp169R.js} +0 -0
- /package/dist/{storage-BjQCiTuz.d.ts → storage-Bdz5AmqS.d.ts} +0 -0
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
---
|
|
2
|
-
name: superwall-
|
|
3
|
-
description: Build and ship a Superwall
|
|
2
|
+
name: superwall-artifacts
|
|
3
|
+
description: Build and ship a Superwall artifact, a small Cloudflare Worker that adds to the Superwall dashboard, from your own machine with the `superwall artifacts` 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
4
|
user-invocable: true
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
# Superwall
|
|
7
|
+
# Superwall artifacts
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
An artifact is a small Cloudflare Worker that adds to the Superwall dashboard. It holds no credential:
|
|
10
10
|
it calls Superwall as whoever is viewing it. You can build a page, a panel, a tab, a card, an action, a
|
|
11
11
|
metric in Charts or a row in a campaign's results.
|
|
12
12
|
|
|
@@ -16,12 +16,14 @@ The commands need `SUPERWALL_CHANNEL=next`, and Node 20 or later. `dev` and `try
|
|
|
16
16
|
## The loop
|
|
17
17
|
|
|
18
18
|
```bash
|
|
19
|
-
superwall
|
|
20
|
-
cd my-
|
|
21
|
-
superwall
|
|
22
|
-
superwall
|
|
23
|
-
superwall
|
|
24
|
-
superwall
|
|
19
|
+
superwall artifacts create my-artifact # downloads the starter and installs
|
|
20
|
+
cd my-artifact
|
|
21
|
+
superwall artifacts dev --app <app> # http://localhost:8790, real data, read-only
|
|
22
|
+
superwall artifacts try transactions --app <app> # a metric on the real runtime
|
|
23
|
+
superwall artifacts try home --org <org> # a page in the dashboard
|
|
24
|
+
superwall artifacts push --org <org> # build it; only you see it until an admin approves it
|
|
25
|
+
superwall artifacts approve # an admin approves it; every slot but org.page then needs install
|
|
26
|
+
superwall artifacts install transactions --app <app> # a metric shows in Charts only once installed
|
|
25
27
|
```
|
|
26
28
|
|
|
27
29
|
1. **`dev`** bundles it the way the builder does and runs it in workerd. A local page plays the
|
|
@@ -34,8 +36,12 @@ superwall workspaces push --org <org> # build it; only you see it until an
|
|
|
34
36
|
3. Nothing is saved by either. **`push`** is what saves it: it sends the source over git, and the builder
|
|
35
37
|
makes a version from the commit. `push` waits for the build and shows the builder's message if it fails.
|
|
36
38
|
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.
|
|
38
|
-
|
|
39
|
+
nobody can see what it pushes until then, and `push` and `share` say which. After approval, the author keeps a
|
|
40
|
+
copy marked "Not installed" until an entrypoint has an install. `share` asks for review,
|
|
41
|
+
an admin runs `approve`, and `install` chooses where it shows. `org.page@1` needs no install; every other
|
|
42
|
+
entrypoint does, a `chart.source@1` metric included: it isn't in Charts until
|
|
43
|
+
`superwall artifacts install <entrypoint> --app <app>` has run. `push` and `approve` print that command for
|
|
44
|
+
each entrypoint that has no install yet (`not_installed` in `--json`), so run it or tell the person to.
|
|
39
45
|
5. **A pusher's own copy can include teammates' merged code, and it runs with the pusher's reads.** `push` lists
|
|
40
46
|
those commits and asks first. Without a terminal it stops unless `--accept-merged-commits` is passed. That flag
|
|
41
47
|
is for a person who has read them, so don't add it to get past the refusal.
|
|
@@ -51,8 +57,8 @@ scope it knows is missing; a draft holds only the manifest's read scopes ∩ you
|
|
|
51
57
|
| `src/worker.ts` | The code. One default export and no other exports. |
|
|
52
58
|
| `wrangler.jsonc` | `name`, `main` and `compatibility_date`. No bindings of any kind. |
|
|
53
59
|
| `package-lock.json` | Required, from npm. The builder installs exactly this. |
|
|
54
|
-
| `superwall.
|
|
55
|
-
| `vendor/
|
|
60
|
+
| `superwall.artifact.json` | Written by the first push: `artifact_id`, `organization_id` and `slug`, so commands know which artifact this is, plus `synced_commit` (where this copy last matched the artifact's source) and `reviewed_commit` (the newest teammates' commit `push` already asked you about), which stay out of the artifact's own source. Commit it, so teammates push to the same one. Never edit it. |
|
|
61
|
+
| `vendor/artifact-sdk` | Generated, never edited. `superwall artifacts update` refreshes it. There is no npm package. |
|
|
56
62
|
|
|
57
63
|
## A metric
|
|
58
64
|
|
|
@@ -94,8 +100,8 @@ Ids and keys are lowercase letters, digits and dashes, starting with a letter. `
|
|
|
94
100
|
`src/worker.ts`:
|
|
95
101
|
|
|
96
102
|
```ts
|
|
97
|
-
import type { MetricRequest, MetricSeries } from "@superwall/
|
|
98
|
-
import {
|
|
103
|
+
import type { MetricRequest, MetricSeries } from "@superwall/artifact-sdk/metrics"
|
|
104
|
+
import { defineArtifact, superwallFetch } from "@superwall/artifact-sdk/server"
|
|
99
105
|
|
|
100
106
|
const UNITS = { hour: "HOUR", day: "DAY", week: "WEEK", month: "MONTH" }
|
|
101
107
|
const dateTime = (iso: string) => iso.slice(0, 19).replace("T", " ")
|
|
@@ -158,7 +164,7 @@ const metric = async ({
|
|
|
158
164
|
}
|
|
159
165
|
}
|
|
160
166
|
|
|
161
|
-
export default
|
|
167
|
+
export default defineArtifact({
|
|
162
168
|
fetch: () => new Response("Not found", { status: 404 }),
|
|
163
169
|
metric,
|
|
164
170
|
})
|
|
@@ -191,11 +197,11 @@ No build script of yours runs. The starter's page is the worked example.
|
|
|
191
197
|
|
|
192
198
|
```ts
|
|
193
199
|
// src/worker.ts. Browser code holds no credential, so it asks this Worker, which calls Superwall as the viewer.
|
|
194
|
-
import client from "@superwall/
|
|
195
|
-
import { clientPage,
|
|
196
|
-
import type { OrgPageContextV1 } from "@superwall/
|
|
200
|
+
import client from "@superwall/artifact-sdk/client-bundle"
|
|
201
|
+
import { clientPage, defineArtifact, superwallFetch, type ArtifactRequest } from "@superwall/artifact-sdk/server"
|
|
202
|
+
import type { OrgPageContextV1 } from "@superwall/artifact-sdk/slots"
|
|
197
203
|
|
|
198
|
-
const serve = ({ request, context }:
|
|
204
|
+
const serve = ({ request, context }: ArtifactRequest) => {
|
|
199
205
|
const { pathname } = new URL(request.url)
|
|
200
206
|
if (pathname === "/") return clientPage(client, { title: "Projects" })
|
|
201
207
|
if (pathname === "/api/projects") {
|
|
@@ -205,13 +211,13 @@ const serve = ({ request, context }: WorkspaceRequest) => {
|
|
|
205
211
|
return new Response("Not found", { status: 404 })
|
|
206
212
|
}
|
|
207
213
|
|
|
208
|
-
export default
|
|
214
|
+
export default defineArtifact({ client, fetch: serve })
|
|
209
215
|
```
|
|
210
216
|
|
|
211
217
|
```tsx
|
|
212
218
|
// src/client.tsx
|
|
213
|
-
import type { Theme } from "@superwall/
|
|
214
|
-
import { connect } from "@superwall/
|
|
219
|
+
import type { Theme } from "@superwall/artifact-sdk/bridge"
|
|
220
|
+
import { connect } from "@superwall/artifact-sdk/client"
|
|
215
221
|
import { useEffect, useState } from "react"
|
|
216
222
|
import { createRoot } from "react-dom/client"
|
|
217
223
|
import "./styles.css"
|
|
@@ -238,36 +244,45 @@ const Home = () => {
|
|
|
238
244
|
createRoot(document.getElementById("root")!).render(<Home />)
|
|
239
245
|
```
|
|
240
246
|
|
|
241
|
-
`
|
|
247
|
+
`defineArtifact({ client })` serves the bundle at `/_client/<hash>.js` and `.css`, and `clientPage` writes the
|
|
242
248
|
document that loads them, with an empty `<div id="root">`. The Worker also needs the import: with no `client` in the
|
|
243
249
|
manifest, it doesn't bundle.
|
|
244
250
|
|
|
245
251
|
**What the build does.** React's automatic JSX, TypeScript, CSS imports, images and fonts as data URLs, one script
|
|
246
252
|
and at most one stylesheet, 8 MiB together. `dev` rebuilds on any change in the project.
|
|
247
253
|
|
|
254
|
+
**`@/` imports work in both.** `baseUrl` and `paths` in the root `tsconfig.json` (or `jsconfig.json` when there's
|
|
255
|
+
none) apply to browser code and the Worker alike:
|
|
256
|
+
|
|
257
|
+
```json
|
|
258
|
+
{ "compilerOptions": { "jsx": "react-jsx", "paths": { "@/*": ["./src/*"] } } }
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
Keep them in that one file. With browser code, the build refuses `extends`, a `tsconfig.json` or `jsconfig.json` in a
|
|
262
|
+
subfolder that covers files it bundles, a `tsconfig` key in the wrangler config, and paths outside the repo, because
|
|
263
|
+
each would make the Worker and the browser resolve imports differently. `dev` and `try` refuse the same.
|
|
264
|
+
|
|
248
265
|
**What it doesn't do yet, because no customer script runs:**
|
|
249
266
|
|
|
250
267
|
- 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
268
|
- Web Workers from `new URL(...)`.
|
|
254
269
|
|
|
255
270
|
**A draft can be 1 MiB at most,** so a large page works in `dev` and `push` and is refused by `try`.
|
|
256
271
|
|
|
257
272
|
A page with no npm packages can skip all of this: answer HTML from `fetch` and load the bridge from
|
|
258
|
-
`@superwall/
|
|
273
|
+
`@superwall/artifact-sdk/client-script` in a `<script>`.
|
|
259
274
|
|
|
260
275
|
```json
|
|
261
276
|
{ "id": "home", "slot": "org.page@1", "title": "Projects", "path": "/" }
|
|
262
277
|
```
|
|
263
278
|
|
|
264
|
-
With scopes `["projects:read"]`, and connect within
|
|
279
|
+
With scopes `["projects:read"]`, and connect within 20 seconds of the page being visible or the dashboard shows the load error. The
|
|
265
280
|
context comes from the platform, already authorized for the viewer. Never trust a user's id from the URL
|
|
266
281
|
over it. If you write HTML yourself, escape everything that came from the API or an end user.
|
|
267
282
|
|
|
268
283
|
## What it can reach
|
|
269
284
|
|
|
270
|
-
`https://api.
|
|
285
|
+
`https://api.artifact.internal` is the Superwall API (`superwallFetch` is a `fetch` to it). The viewer's
|
|
271
286
|
own access still applies on every call, narrowed by the manifest's `scopes`.
|
|
272
287
|
|
|
273
288
|
**Declare a scope for every API you call.** A route whose scope isn't declared answers a bare 403 at run
|
|
@@ -305,8 +320,8 @@ them, and an admin can't approve a version that declares secrets. If the user's
|
|
|
305
320
|
- Any binding in `wrangler.jsonc`: KV, R2, D1, services, vars, AI, assets, Durable Objects, Workflows,
|
|
306
321
|
Containers, cron triggers. Everything goes through `fetch`.
|
|
307
322
|
- A custom `build.command`, `no_bundle` or `find_additional_modules`, and text, data or wasm modules. A
|
|
308
|
-
|
|
309
|
-
- `@superwall/
|
|
323
|
+
artifact is exactly one bundled ES module, at most 10 MiB, exporting only its default handlers.
|
|
324
|
+
- `@superwall/artifact-sdk` from anywhere but `file:vendor/artifact-sdk`.
|
|
310
325
|
- A lockfile with a package from outside `registry.npmjs.org`, or without an integrity hash.
|
|
311
326
|
|
|
312
327
|
`dev` applies the bundle rules as it builds. `references/cli.md` lists what `dev` doesn't copy from the
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# The commands
|
|
2
2
|
|
|
3
|
-
## `superwall
|
|
3
|
+
## `superwall artifacts dev [dir]`
|
|
4
4
|
|
|
5
5
|
| Flag | What it fills in |
|
|
6
6
|
| ---------------------------- | ------------------------------------------------------------------ |
|
|
@@ -45,7 +45,7 @@ Different, so run `try` before believing these:
|
|
|
45
45
|
draft holds only the manifest's read scopes, and answers 403. Against an API that hasn't deployed limited tokens,
|
|
46
46
|
`dev` warns that its token reaches everything you can read.
|
|
47
47
|
- **App narrowing.** `dev` refuses the same routes the runtime does, for the slot's narrowing, with the same 403:
|
|
48
|
-
"
|
|
48
|
+
"Artifacts may not call this endpoint." It doesn't narrow data: on a route the slot can reach, the real runtime
|
|
49
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
50
|
from the wrong app.
|
|
51
51
|
- **Frames** have one session per dev server, so two tabs of it share the last one opened. The local dashboard is
|
|
@@ -59,33 +59,33 @@ Different, so run `try` before believing these:
|
|
|
59
59
|
only flags allowed are `nodejs_compat`, `nodejs_compat_v2` and `nodejs_als`.
|
|
60
60
|
- **Storage, cron, events, jobs and secrets** aren't available anywhere yet. The platform host answers 501.
|
|
61
61
|
|
|
62
|
-
## `superwall
|
|
62
|
+
## `superwall artifacts try <entrypoint>`
|
|
63
63
|
|
|
64
64
|
A metric prints each series' summary: `--app` (required), `--org`, `--dir`, `--from`, `--to`, `--days` (30),
|
|
65
65
|
`--interval` (`day`), `--breakdown`, `--filter key=value` (repeats), `--points`. `--json` adds the draft id, its
|
|
66
66
|
expiry, the scopes it asked for and the series.
|
|
67
67
|
|
|
68
|
-
A frame uploads, prints a link to `/<org>/
|
|
68
|
+
A frame uploads, prints a link to `/<org>/artifact-drafts/<draft>` on the dashboard and, at a terminal, opens
|
|
69
69
|
it: `--org` or `--app`, `--campaign`, `--user`, `--environment`, `--no-open`. `--json` gives the link as `url`.
|
|
70
70
|
A readout says to use `dev`.
|
|
71
71
|
|
|
72
72
|
If your code throws, `try` shows your own message. A 403 from inside your code is a missing scope.
|
|
73
73
|
|
|
74
|
-
## `superwall
|
|
74
|
+
## `superwall artifacts create [dir]`
|
|
75
75
|
|
|
76
|
-
Downloads the starter into `dir` (`my-
|
|
76
|
+
Downloads the starter into `dir` (`my-artifact` by default), names it after the directory and runs
|
|
77
77
|
`npm install`. `--no-install` skips the install. It refuses a directory with files in it.
|
|
78
78
|
|
|
79
|
-
## `superwall
|
|
79
|
+
## `superwall artifacts update [dir]`
|
|
80
80
|
|
|
81
|
-
Replaces `vendor/
|
|
81
|
+
Replaces `vendor/artifact-sdk` with the latest, points `package.json` at it and updates the lockfile. Commit
|
|
82
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
83
|
|
|
84
|
-
## `superwall
|
|
84
|
+
## `superwall artifacts push [dir]`
|
|
85
85
|
|
|
86
|
-
`--org` (on the first push), `-m <note>`, `--overwrite-source`, `--accept-merged-commits`, `--json`. The first push creates the
|
|
86
|
+
`--org` (on the first push), `-m <note>`, `--overwrite-source`, `--accept-merged-commits`, `--json`. The first push creates the artifact from
|
|
87
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
|
|
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 is where the artifact opens, in the org's first app when it needs one: its own page for an `org.page@1`, the app's page for an `app.page@1`, Embeds for widgets, tabs, panels and actions, and Charts for metrics. `open <entrypoint> --app <id>` opens one in another app.
|
|
89
89
|
|
|
90
90
|
If a teammate changed the same files, it stops and says to run `pull`. `--overwrite-source` replaces the whole
|
|
91
91
|
source repo with this project, so use it only when you mean to discard what's there.
|
|
@@ -101,15 +101,15 @@ no changes of your own, whose build would be their commit. It asks once per comm
|
|
|
101
101
|
A build can wait or stop for reasons that aren't your code:
|
|
102
102
|
|
|
103
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
|
-
- **
|
|
104
|
+
- **An artifact 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
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
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
|
|
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 an artifact reaches every project, and the command shows why.
|
|
108
108
|
|
|
109
|
-
## `superwall
|
|
109
|
+
## `superwall artifacts pull [dir]`
|
|
110
110
|
|
|
111
111
|
Merges teammates' pushes into this project. `--theirs` takes the source repo's version of files you both changed.
|
|
112
|
-
`--
|
|
112
|
+
`--artifact <id>` fills an empty folder with an artifact's source. The next `push` won't ask about what you pulled,
|
|
113
113
|
so read it first: your own copy runs all of it with your reads.
|
|
114
114
|
|
|
115
115
|
## `status`, `logs`, `share`, `list`, `open`
|
|
@@ -117,24 +117,27 @@ so read it first: your own copy runs all of it with your reads.
|
|
|
117
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
118
|
finished. `share [version]` marks the latest built version for review. Nobody is told automatically, so for someone
|
|
119
119
|
who can't approve it, it names who can, when their role can see that. `list --org` lists an organization's
|
|
120
|
-
|
|
120
|
+
artifacts. `open` prints the dashboard link and opens it at a terminal; `open <entrypoint> --app <id>` opens one
|
|
121
121
|
entrypoint inside an app.
|
|
122
122
|
|
|
123
|
-
Each takes `--
|
|
123
|
+
Each takes `--artifact <id>` (or a slug with `--org`), and otherwise reads this project's `superwall.artifact.json`.
|
|
124
124
|
|
|
125
|
-
## `superwall
|
|
125
|
+
## `superwall artifacts approve [version]` (admins)
|
|
126
126
|
|
|
127
127
|
Shows what the version can do and how it differs from what's granted, then asks. **Never run it with flags before
|
|
128
128
|
a person has read that.** Without a terminal it needs `--yes`, and `--accept-changes` too when scopes, hosts,
|
|
129
129
|
secrets, entrypoints, crons, events, storage or the bundle's compatibility date and flags change. `--json` with neither approves nothing, prints `manifest`
|
|
130
130
|
and `diff`, and exits 1, so run that first and show the person the result.
|
|
131
131
|
|
|
132
|
-
## `superwall
|
|
132
|
+
## `superwall artifacts install [entrypoint]` (admins)
|
|
133
133
|
|
|
134
134
|
With no entrypoint, lists what's installed. Otherwise installs it from the live version for the whole organization,
|
|
135
135
|
or one app with `--app`. `--disable` turns it off and keeps its row, `--remove` deletes the row and ends open
|
|
136
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.
|
|
137
|
+
shows only where it's installed and enabled, so a metric isn't in Charts until it's installed for that app.
|
|
138
|
+
`push` and `approve` print one line per entrypoint with no install yet, for example
|
|
139
|
+
`Charts won't show "Transactions" until you install it: superwall artifacts install transactions --app 42`
|
|
140
|
+
(`--app <app-id>` when the organization has more than one app), and list them as `not_installed` in `--json`.
|
|
138
141
|
|
|
139
142
|
## What errors mean
|
|
140
143
|
|
|
@@ -142,33 +145,36 @@ shows only where it's installed and enabled.
|
|
|
142
145
|
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
143
146
|
| `needs a browser login` | You're signed in with an API key. Run `superwall login`. |
|
|
144
147
|
| `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
|
|
148
|
+
| `… 403 … Dev's token is read-only` | A write, or a route outside what an artifact can read, like `/v2/me`. The real runtime refuses it too. |
|
|
146
149
|
| `You can't mint an Agent Token for organization …` | You aren't a member of it, or your access ended. Check `--org`. |
|
|
147
150
|
| `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
|
|
151
|
+
| `This would fail on the builder. …` | Your wrangler config has something an artifact can't use: `vars`, a binding, `site`, an `env` section, a build command or a key the builder doesn't know. An artifact needs `name`, `main` and `compatibility_date`, and little else. The date and flags have limits too. |
|
|
149
152
|
| `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. |
|
|
153
|
+
| `tsconfig.json: "extends" isn't supported …` | Put `baseUrl` and `paths` in the root `tsconfig.json` itself. |
|
|
154
|
+
| `… applies to … in the Worker's build but not in browser code` | A `tsconfig.json` in a subfolder covers browser code. Keep one at the repo root. |
|
|
155
|
+
| `The wrangler config's \`tsconfig\` isn't supported …` | Remove it: with browser code, both builds read the root `tsconfig.json`. |
|
|
150
156
|
| `client.entry: … is not in the repo` | The path in `superwall.json` is wrong. |
|
|
151
157
|
| `src/client.tsx:3:14: …` | esbuild's error in your browser code. The builder would say the same. |
|
|
152
|
-
| `Could not resolve "@superwall/
|
|
158
|
+
| `Could not resolve "@superwall/artifact-sdk/client-bundle"` | The Worker imports the bundle and `superwall.json` has no `client`. |
|
|
153
159
|
| `The client bundle is … bytes` | Over 8 MiB. It lists the largest files. |
|
|
154
|
-
| `This project's
|
|
160
|
+
| `This project's artifact SDK is older than the builder's browser build` | Run `superwall artifacts update`, then `npm install`. |
|
|
155
161
|
| `bundled with esbuild 0.28.2, not …` | This project's wrangler brings another esbuild. Install the wrangler the starter pins. |
|
|
156
162
|
| `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
|
|
158
|
-
| `The build failed at …` | The builder's own words. `superwall
|
|
163
|
+
| `Someone else pushed changes to …` | A teammate changed the same files. Run `superwall artifacts pull`, then push again. |
|
|
164
|
+
| `The build failed at …` | The builder's own words. `superwall artifacts logs` has the rest. A new push, or the same commit again, retries. |
|
|
159
165
|
| `Your copy would run commits from …` | `push` would merge teammates' commits into your own copy. Run `pull` to read them, then push. |
|
|
160
166
|
| `Only organization owners and admins can …` | Your role can't do this. `share` says who can, when your role can see that. |
|
|
161
|
-
| `Building
|
|
167
|
+
| `Building an artifact needs access to all projects` | An owner or admin has to change your project access. |
|
|
162
168
|
| `… builds running` | Your organization's three builds are taken. `push` waits and retries on its own. |
|
|
163
169
|
| `… pushes in the last day` | The daily limit. Trying soon won't help. |
|
|
164
170
|
| `All the build machines are busy` or `… usually temporary` | Not your code. Run `push` again in a few minutes. |
|
|
165
171
|
| `Nothing was approved …` | `approve` needs a person, or `--yes`, plus `--accept-changes` when what it can do changes. |
|
|
166
172
|
| `… needs projects:read, which superwall.json doesn't declare` | Add it to `scopes`. It answers 403 on the real runtime. |
|
|
167
|
-
| `
|
|
173
|
+
| `Artifacts may not call this endpoint.` | The route isn't open to artifacts, 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
174
|
| `The environment must be PRODUCTION or SANDBOX` | In capitals, in `--environment`, `--context` and dev's page API. |
|
|
169
175
|
| `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
176
|
| `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
177
|
| `Port … is already in use` | Something else has that port. Pick another with `--port`; dev takes the one after it too. |
|
|
172
|
-
| `The
|
|
178
|
+
| `The artifact didn't start … compatibility date is too new` | Your wrangler is older than the platform's date. Run `npm install -D wrangler@latest`. |
|
|
173
179
|
| `exactly one ES module` or `exports …` | A text, data or wasm import, or a named export. Inline it, or export only the default. |
|
|
174
180
|
| `The analytics query didn't finish`, or a 503 about row policies | A passing failure of the query endpoint. Try again. |
|
|
@@ -21,8 +21,8 @@ slot needs a `path` and takes no `metric`; a headless one needs a `metric` and t
|
|
|
21
21
|
## Types
|
|
22
22
|
|
|
23
23
|
```ts
|
|
24
|
-
import type { MetricRequest, MetricSeries, ReadoutRequest, ReadoutResult } from "@superwall/
|
|
25
|
-
import type { SlotContext, UserPanelContextV1 } from "@superwall/
|
|
24
|
+
import type { MetricRequest, MetricSeries, ReadoutRequest, ReadoutResult } from "@superwall/artifact-sdk/metrics"
|
|
25
|
+
import type { SlotContext, UserPanelContextV1 } from "@superwall/artifact-sdk/slots"
|
|
26
26
|
```
|
|
27
27
|
|
|
28
28
|
## A readout
|
|
@@ -39,14 +39,14 @@ import type { SlotContext, UserPanelContextV1 } from "@superwall/workspace-sdk/s
|
|
|
39
39
|
```
|
|
40
40
|
|
|
41
41
|
```ts
|
|
42
|
-
import type { ReadoutRequest, ReadoutResult } from "@superwall/
|
|
42
|
+
import type { ReadoutRequest, ReadoutResult } from "@superwall/artifact-sdk/metrics"
|
|
43
43
|
|
|
44
44
|
const readout = async ({ context }: ReadoutRequest): Promise<ReadoutResult> => ({
|
|
45
45
|
variants: context.variantIds.map((variantId) => ({ variantId, value: 0.42, interval: [0.4, 0.44] })),
|
|
46
46
|
})
|
|
47
47
|
```
|
|
48
48
|
|
|
49
|
-
Pass it to `
|
|
49
|
+
Pass it to `defineArtifact({ fetch, readout })`. `value` is null when there's nothing to show yet.
|
|
50
50
|
`interval` is optional and must hold `value`. Each variant at most once, and only this audience's; one you
|
|
51
51
|
leave out shows as having no value. Limits: 10 seconds, 32 KB. A readout metric takes no `breakdowns`,
|
|
52
52
|
`filters` or `total`.
|
|
@@ -54,8 +54,8 @@ leave out shows as having no value. Limits: 10 seconds, 32 KB. A readout metric
|
|
|
54
54
|
## The bridge
|
|
55
55
|
|
|
56
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/
|
|
58
|
-
`client.entry`; `client-script` gives you the same thing as `
|
|
57
|
+
when the frame is on localhost too (which is `dev`). Import `@superwall/artifact-sdk/client` from your
|
|
58
|
+
`client.entry`; `client-script` gives you the same thing as `superwallArtifact.connect` on a plain page.
|
|
59
59
|
|
|
60
60
|
```ts
|
|
61
61
|
bridge.context // the slot's context
|
|
@@ -70,7 +70,7 @@ bridge.send({ _tag: "error", message: "What went wrong, up to 500 characters" })
|
|
|
70
70
|
```
|
|
71
71
|
|
|
72
72
|
- `navigate` goes to `campaign` (`applicationId`, `campaignId`), `user` (`applicationId`, `appUserId`) or
|
|
73
|
-
`
|
|
73
|
+
`artifact` (`slug`). The host builds the route; it never takes a URL.
|
|
74
74
|
- `actionResult` means something only in `user.action@1`, the modal slot.
|
|
75
75
|
- `resize` is sent for you as the document grows, and clamped to the slot. A page and a widget fill what
|
|
76
76
|
holds them and ignore it, so a widget must handle being narrow and scroll inside itself.
|
|
@@ -91,7 +91,7 @@ A manifest can ask for only these, and the viewer's own access still applies:
|
|
|
91
91
|
`SKILL.md` has which route needs which scope. A route whose scope isn't declared answers 403. Writes do nothing
|
|
92
92
|
in `dev` or a draft.
|
|
93
93
|
|
|
94
|
-
Routes
|
|
94
|
+
Routes an artifact can call: reads under `/v2/projects`, `/v2/applications`, `/v2/charts`, `/v2/users`,
|
|
95
95
|
`/v3/users`, `/v2/onboarding`, `/v2/retention-onboarding` and `/v2/demand-score`; reads and, where the scope
|
|
96
96
|
allows, writes under `/v2/paywalls`, `/v2/campaigns`, `/v2/products`, `/v2/entitlements`, `/v2/grants`,
|
|
97
97
|
`/v2/assets`, `/v2/surveys` and the retention families. Nothing under `/v2/me`, access, tokens or transfers.
|
|
@@ -100,4 +100,4 @@ allows, writes under `/v2/paywalls`, `/v2/campaigns`, `/v2/products`, `/v2/entit
|
|
|
100
100
|
panels and actions. They reach `/v2/campaigns`, `/v2/surveys`, the retention families, `/v2/users`, `/v3/users`,
|
|
101
101
|
`/v2/charts`, `/v2/paywalls`, `/v2/applications/<id>/…`, and one product, entitlement or asset by id. They can't reach
|
|
102
102
|
`/v2/projects`, SQL, or a list of products, entitlements or assets, which show sibling apps. Anything else answers 403
|
|
103
|
-
with "
|
|
103
|
+
with "Artifacts may not call this endpoint.", in `dev` too. Metrics and readouts aren't held to this list.
|
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
import { c as CHANNELS, s as CHANNEL, x as VERSION } from "./environment-
|
|
1
|
+
import { c as CHANNELS, s as CHANNEL, x as VERSION } from "./environment-EU7Mrk7j.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-B-uKuu49.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-mWZnJCkN.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-Bf3othB-.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-C2kzntVM.js";
|
|
2
2
|
import "./output-Ggzq5_-t.js";
|
|
3
|
-
import "./environment-
|
|
4
|
-
import "./storage-
|
|
5
|
-
import "./client-
|
|
3
|
+
import "./environment-EU7Mrk7j.js";
|
|
4
|
+
import "./storage-R5-qDvHq.js";
|
|
5
|
+
import "./client-Tp6iD66_.js";
|
|
6
6
|
import "./config-CGcG7GOt.js";
|
|
7
|
-
import "./telemetry-
|
|
7
|
+
import "./telemetry-B-uKuu49.js";
|
|
8
8
|
import "./spawn-DmmmHIP-.js";
|
|
9
|
-
import "./spinner-
|
|
9
|
+
import "./spinner-mWZnJCkN.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-Bf3othB-.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-CE4c9eHX.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 };
|