uniweb 1.34.11 → 1.35.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/package.json +6 -6
- package/partials/agents.md +2 -1
- package/partials/guides/backend.md +60 -5
- package/partials/guides/index.json +5 -0
- package/partials/guides/promote.md +142 -0
- package/src/backend/client.js +140 -7
- package/src/backend/promote-drafts.js +992 -0
- package/src/backend/site-published.js +142 -0
- package/src/backend/site-sync.js +2 -1
- package/src/commands/dev.js +42 -3
- package/src/commands/doctor.js +21 -5
- package/src/commands/promote.js +1598 -0
- package/src/commands/pull.js +72 -2
- package/src/commands/site.js +1 -1
- package/src/commands/status.js +169 -2
- package/src/framework-index.json +5 -5
- package/src/index.js +17 -1
- package/src/utils/flag-guard.js +7 -1
- package/src/utils/status-next.js +2 -2
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "uniweb",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.35.0",
|
|
4
4
|
"description": "Create structured Vite + React sites with content/code separation",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -42,14 +42,14 @@
|
|
|
42
42
|
"prompts": "^2.4.2",
|
|
43
43
|
"tar": "^7.5.21",
|
|
44
44
|
"@uniweb/content-writer": "~1.3.2",
|
|
45
|
-
"@uniweb/
|
|
45
|
+
"@uniweb/semantic-parser": "~1.13.5",
|
|
46
46
|
"@uniweb/schemas": "~1.7.4",
|
|
47
|
-
"@uniweb/
|
|
47
|
+
"@uniweb/core": "~1.6.13"
|
|
48
48
|
},
|
|
49
49
|
"peerDependencies": {
|
|
50
|
-
"@uniweb/
|
|
51
|
-
"@uniweb/
|
|
52
|
-
"@uniweb/
|
|
50
|
+
"@uniweb/content-reader": "~1.5.11",
|
|
51
|
+
"@uniweb/semantic-parser": "~1.13.5",
|
|
52
|
+
"@uniweb/build": "~1.24.0"
|
|
53
53
|
},
|
|
54
54
|
"peerDependenciesMeta": {
|
|
55
55
|
"@uniweb/build": {
|
package/partials/agents.md
CHANGED
|
@@ -322,7 +322,7 @@ Where a value lives: a **param** when JS branches on it; a **component var** (`m
|
|
|
322
322
|
|
|
323
323
|
## 6. Guides
|
|
324
324
|
|
|
325
|
-
Every guide ships with the CLI this project pins, so it describes the version in front of you.
|
|
325
|
+
Every guide ships with the CLI this project pins, so it describes the version in front of you. `uniweb guide` alone lists them.
|
|
326
326
|
|
|
327
327
|
| When you… | Run |
|
|
328
328
|
|---|---|
|
|
@@ -335,6 +335,7 @@ Every guide ships with the CLI this project pins, so it describes the version in
|
|
|
335
335
|
| the site has accounts or member data (`services.backend`, `blueprint.yml`, `@uniweb/api`) | `uniweb guide backend` |
|
|
336
336
|
| add a language | `uniweb guide i18n` |
|
|
337
337
|
| publish, deploy, push/pull, register, CI, workspaces, updates | `uniweb guide ship` |
|
|
338
|
+
| get the site found, post or advertise for it | `uniweb guide promote` |
|
|
338
339
|
| port a React / Next / generated design | `uniweb guide migrate` |
|
|
339
340
|
|
|
340
341
|
**The documentation index is `https://uniweb.io/llms.txt`** — each page, a line on it, and its link. Go there for anything not answered here, above all whether a feature exists, and follow its links rather than build them. For several lookups: `git clone --depth 1 https://github.com/uniweb/docs .uniweb-docs` (gitignore it) and grep; bare paths above resolve as index keys, files in the clone, or `https://raw.githubusercontent.com/uniweb/docs/main/{path}`. The docs describe the **latest** release: when `uniweb status` says this project is behind, the fix is `npx uniweb@latest update --yes`, not older docs. Syntax the docs no longer show is listed under *Retired forms* in `uniweb guide ship`. `docs.uniweb.app` is for authors in the visual editor, not framework questions.
|
|
@@ -43,6 +43,16 @@ await writer.remove(itemId)
|
|
|
43
43
|
- Ordering is the server's; never compute an order number.
|
|
44
44
|
- `writer.conflict` is reported, not retried — a retry would overwrite a change nobody looked at. Tell the person.
|
|
45
45
|
|
|
46
|
+
## Rich text a member writes
|
|
47
|
+
|
|
48
|
+
```jsx
|
|
49
|
+
import { useRichTextEditor, RichTextContent } from '@uniweb/api/rich-text' // TipTap 3.x, an optional peer: install it, load the editor lazily
|
|
50
|
+
const editor = useRichTextEditor({ value, onChange }) // onChange(doc): each change as a backend stores it
|
|
51
|
+
<RichTextContent editor={editor} /> // your toolbar: editor.chain().focus().toggleBold().run()
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Its document model is the stored vocabulary: it edits what TipTap's kit does, with a divider for the rule and no underline, and keeps everything else a stored text holds. Don't configure TipTap yourself for a rich-text field: what it makes beyond the vocabulary is left out when saved, which the mock prints.
|
|
55
|
+
|
|
46
56
|
## Translated fields
|
|
47
57
|
|
|
48
58
|
A `localized` field holds `{ en: '…', fr: '…' }` or one plain value for every language; a read answers in the page's language. Never write that one value back as the whole field — it becomes every language's value.
|
|
@@ -56,7 +66,7 @@ await writer.update(item.id, { ...item.data, bio: 'Bonjour' }, { language: 'fr'
|
|
|
56
66
|
|
|
57
67
|
## Permissions are the server's; your UI is a courtesy
|
|
58
68
|
|
|
59
|
-
Gate controls on what the viewer may do — a record
|
|
69
|
+
Gate controls on what the viewer may do — `mayDo(entry, 'edit' | 'delete' | 'share')` on a record or a list row, `useMayCreate({ schemas })` for a type, each `'now'`, `'once-elevated'` (confirm it is them first, then act), `'no'` or `null` (not told: offer it) — but never rely on that for safety: a foundation runs with the viewer's authority, so hiding a button hides a button. Not on `viewer.roles` alone: a session holds its roles as a reader's until elevated, so a gate on `system_admin` shows the operator nothing until then. Draw a role-acting control from `useElevation().rolesInFull` and let the record answer.
|
|
60
70
|
|
|
61
71
|
What protects content is the **entry**: a member writes their own entries and not another's, enforced by the store. **Every type starts closed**: the operator adds its entries, and anyone else only where the site's `blueprint.yml` opens it (below). A schema protects how an item changes and who reads an entry:
|
|
62
72
|
|
|
@@ -107,6 +117,44 @@ integrations: # by a mapping the foundation declares in src/mappi
|
|
|
107
117
|
- A team's `all: edit` reaches the entries once the member confirms it is them (below); a team's `add` and `members: edit` need no confirming. Who is in a team, and roles, are never the file's.
|
|
108
118
|
- A static build carries none of it. A pull writes it back here, never into `site.yml`.
|
|
109
119
|
|
|
120
|
+
## Your admin area, and the admin app
|
|
121
|
+
|
|
122
|
+
A site with a backend is a solution: public pages, a members' area for each role, and an **admin area** for the people who run it — its staff, its instructors. You build the admin area: section types of your foundation, branded, in the solution's own words, with what follows. The **admin app** is the backend's own administration, the same for every site: the payment account, the teams and who is in them, roles, an integration's address and keys, the store's offerings and coupons. Never rebuild those; link to it (`adminHref`, below). The docs' Building a Solution page walks the whole path.
|
|
123
|
+
|
|
124
|
+
## Selling
|
|
125
|
+
|
|
126
|
+
```jsx
|
|
127
|
+
import { useStore, offeringState, useEntitlements, useHolders } from '@uniweb/api'
|
|
128
|
+
const { status, store, offerings, checkout, checking } = useStore({ entity: course.uuid }) // 'none': the site sells nothing
|
|
129
|
+
offeringState(offering, store) // 'owned' · 'take' (a free one-off) · 'not-ready' (payments not connected) · 'buy'
|
|
130
|
+
await checkout(offering) // sends the buyer to pay; a free one-off is held at once: { url: null, held: true }
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
- The owner sets the offerings, and connects their own Stripe account, in the admin app. `price` is in the currency's smallest unit. Nobody signed in → `absent`: the store is a signed-in member's to read.
|
|
134
|
+
- After paying, the buyer lands on `successUrl` (this page by default). The purchase is written when the payment's notice arrives, so the page there calls `refresh()` until the offering reads `owned`.
|
|
135
|
+
- A purchase lets the buyer read the record, and through it what its `sold_with` references point to: `useEntity({ schema: '@/lesson', uuid, via: course.uuid })`.
|
|
136
|
+
- `useEntitlements()` — what the viewer holds, for "My courses". `useHolders({ schema, uuid })` — who holds a record, for a roster: its owner's or an `admin`'s to read, `forbidden` for anyone else, so draw nothing.
|
|
137
|
+
- Why a checkout was refused: `error.extensions.reason` — `payments_not_ready`, `coupon_not_applicable` (with `cause`), `not_for_sale`.
|
|
138
|
+
|
|
139
|
+
## The inbox
|
|
140
|
+
|
|
141
|
+
```jsx
|
|
142
|
+
const { unread } = useNotifications({ every: 60_000, list: false }) // a badge, polled lightly
|
|
143
|
+
const { notifications, markRead, dismiss, markAllRead } = useNotifications() // the rows, when opened
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Each row is as the backend sends it (`kind`, `payload`, `read_at`, …). For `kind: 'entity_shared'`, `payload` is `{ entity_uuid, entity_model, permission, actor_handle }`. The kinds grow: draw those you know, pass over the rest. There is no push: poll the count, and read the list when it is opened.
|
|
147
|
+
|
|
148
|
+
## Signing in and up
|
|
149
|
+
|
|
150
|
+
```jsx
|
|
151
|
+
const { options } = useSignInOptions() // providers, signup, email_sign_in; password: { min_length } and email_code: { length, lifetime_minutes }, each present only while offered
|
|
152
|
+
const { signIn, completeChallenge, resendVerification } = useSignIn() // username, @handle or address
|
|
153
|
+
const code = useEmailSignIn() // where options.email_code: request({ email }) → confirm(code); one door for new and returning members
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Draw each way only where `options` states it. After a provider, `useSignIn().returned` says what came back (`signed-in`, `link`, `error` with its `reason`); after signing in, go to `signInReturnPath()` — the `?next=` path, never another site — or your default. `useFeedback().send({ message, kind, rating })` sends a member's feedback to the site's administrators. The backend answers an emailed code's request alike for every address, and the confirming code makes the account of an address that has none. Every refusal names `error.extensions.reason` with the values a message needs (`password_too_short` and `min_length`, `email_code_wrong` and `tries_left`, `email_code_throttled` and `retry_after_seconds`, …): `ACCOUNT_REASON` in `@uniweb/api/wire` lists them. The words are the foundation's, from content.
|
|
157
|
+
|
|
110
158
|
## Acting as an administrator
|
|
111
159
|
|
|
112
160
|
An administrator's session reads what their role reaches and changes nothing through the role until they confirm it is them; their own records they edit as always.
|
|
@@ -116,6 +164,7 @@ const { available, elevated, until, elevate, lower, error } = useElevation()
|
|
|
116
164
|
// available: the account holds a role that does more than read — offer it only then
|
|
117
165
|
// elevate({ password, code }) — code when the account has a second factor; refusal: error.kind === 'auth'
|
|
118
166
|
// elevated turns false at `until`; lower() ends early; elevateWithProvider(provider) for a passwordless account
|
|
167
|
+
// ways: { password, emailCode } — an account made by an emailed code: requestCode(), then elevateWithCode({ code })
|
|
119
168
|
```
|
|
120
169
|
|
|
121
170
|
While elevated, `viewer.roles` names the role and every record read before is read again. Nothing says whether the account has a second factor — offer the code field. It does not open the backend's administration — the Admin link does:
|
|
@@ -129,14 +178,14 @@ const { adminHref } = useSession()
|
|
|
129
178
|
|
|
130
179
|
## Mailed links, invitations, access, units
|
|
131
180
|
|
|
132
|
-
**Mailed links** (sign-up confirmation `?verify=`, password reset `?reset=`, invitation `?offer=`) arrive at the site's root; the landing page finishes the step:
|
|
181
|
+
**Mailed links** (sign-up confirmation `?verify=`, password reset `?reset=`, invitation `?offer=`, an emailed code's sign-in `?signin=`) arrive at the site's root; the landing page finishes the step:
|
|
133
182
|
|
|
134
183
|
```jsx
|
|
135
184
|
const { step, status, result, error, confirm } = useMailedLink()
|
|
136
|
-
// step: null | 'verify' | 'reset' | 'offer' status: 'idle' | 'working' | 'done' | 'error'
|
|
185
|
+
// step: null | 'verify' | 'reset' | 'offer' | 'signin' status: 'idle' | 'working' | 'done' | 'error'
|
|
137
186
|
```
|
|
138
187
|
|
|
139
|
-
`verify` finishes by itself. `reset` waits for `confirm({ new_password })` (`error.extensions.reason === 'password_too_short'`; the link works again). `offer` waits for a sign-in then claims; `result` is counts `{ invitations, grants }`; `error.kind === 'absent'` means unknown, revoked or used, alike — one sentence, no cause. Render it where the root renders (a header or layout). Never copy the token anywhere.
|
|
188
|
+
`verify` finishes by itself. `reset` waits for `confirm({ new_password })` (`error.extensions.reason === 'password_too_short'`; the link works again). `offer` waits for a sign-in then claims; `result` is counts `{ invitations, grants }`; `error.kind === 'absent'` means unknown, revoked or used, alike — one sentence, no cause. `signin` waits for a click: `confirm()` signs in — never on load, which a mail scanner's prefetch would spend. Render it where the root renders (a header or layout). Never copy the token anywhere.
|
|
140
189
|
|
|
141
190
|
**Invitations** wait for the member's answer, mailed link or not:
|
|
142
191
|
|
|
@@ -165,6 +214,8 @@ const { units } = useUnits() // [{ unit, id, handle?, name?, parent?, depth, p
|
|
|
165
214
|
await createEntity({ schema: '@/submission', unit: course.unit, items: [...] })
|
|
166
215
|
```
|
|
167
216
|
|
|
217
|
+
**A unit's staff**, for its administrator on an elevated session (`absent` before): `useUnitStaff({ unit })` lists the roles and `give({ account, role })` / `take(…)` them (`content_reader`, `content_editor`, `unit_admin` — the last only to someone placed in the unit, with a second factor), and `archive()` / `restore()` the unit, whose content then reads and changes for no one (`unit_archived`). `useUnitEntryGrants({ unit, schema })` gives a type's entries there to `{ account }`, `{ team }` or `{ members: true }`.
|
|
218
|
+
|
|
168
219
|
Nested items in one create: give an item `uuid: uuidv7()` and a later item names it as `parent` (`{ section: 'degrees/thesis', parent: degree, data }`); those uuids serve the write alone.
|
|
169
220
|
|
|
170
221
|
## A backend on your machine
|
|
@@ -185,4 +236,8 @@ const blueprint = readBlueprint(fileURLToPath(new URL('..', import.meta.url)))
|
|
|
185
236
|
export default createMockBackend({ seed, blueprint }).fetch
|
|
186
237
|
```
|
|
187
238
|
|
|
188
|
-
`uniweb dev` answers the `backend` service with it at an address on its own origin (cookies behave as in production). Write no address of your own: under `services:` an address means a backend you run. The mock begins as a backend started from the site does: every type closed until the blueprint opens it, its `signup`, its teams (a seeded account names its own, `teams: ['sales']`). It **enforces** those, entry ownership and `append_only
|
|
239
|
+
`uniweb dev` answers the `backend` service with it at an address on its own origin (cookies behave as in production). Write no address of your own: under `services:` an address means a backend you run. The mock begins as a backend started from the site does: every type closed until the blueprint opens it, its `signup`, its teams (a seeded account names its own, `teams: ['sales']`). It **enforces** those, entry ownership and `append_only`, and lets a buyer read through what they hold to what its `sold_with` references point to. It gives the backend's refusal reasons, holds passwords to 8 characters, signs in by emailed code, keeps rich text to the stored vocabulary, and staffs and archives units; it doesn't model public queries, `readable_with` or second factors (a seeded `twoFactor: true` stands for one). Mail it would send prints in the terminal with its link on the site's root. Seed `offers: [{ email, invitations: 1 }]` to try an invitation; a seeded entity takes `grants: { member: 'read' }`; `units: [{ handle, parent?, members, floor? }]` gives a create somewhere to land. `store: { info, offerings: [{ entry: <a seeded uuid>, price }] }`, `coupons`, `entitlements: [{ username, entity }]` and `notifications: [{ to, from?, payload }]` try selling and the inbox: a priced checkout opens a payment page of the mock's own, which takes no payment, and giving someone access adds a row to their inbox. The seed names your own types `@/track`. State is in memory; restart to reset, or `getClient().request('POST', '/_mock/reset')` for a demo's "start over" (the mock's own route). `uniweb create my-event --template conference` is a worked example.
|
|
240
|
+
|
|
241
|
+
## Against the site as published
|
|
242
|
+
|
|
243
|
+
The mock is for working with no backend at hand; where it and the backend differ, the backend is right. Once the site is published to the backend you are logged in to, a local one included, `uniweb dev --published` serves this copy (its foundation and pages, with live reload) against the published site's services. Members sign in to its real backend and may do what it enforces, and pages show the records its visitors see, the entries its public queries open included. The dev server reads the service addresses from the published page and forwards each request, so the page talks to one origin and sign-in cookies behave as on the published site; `$devBackend` is not mounted. Under `--published` the copy sends its own types in full (`@acme/track`), as a build does, so the backend answers for the types it holds: one you add reaches it when you publish again. Record files reach the page through `uniweb push`, which a published site serves at once. It is the published site's real data, members' entries included, and the output says so.
|
|
@@ -44,6 +44,11 @@
|
|
|
44
44
|
"title": "Shipping",
|
|
45
45
|
"description": "publish, deploy, push/pull, register, CI, workspaces, updates"
|
|
46
46
|
},
|
|
47
|
+
{
|
|
48
|
+
"name": "promote",
|
|
49
|
+
"title": "Promoting a site",
|
|
50
|
+
"description": "get the site found, post or advertise for it, read what that brought"
|
|
51
|
+
},
|
|
47
52
|
{
|
|
48
53
|
"name": "migrate",
|
|
49
54
|
"title": "Migrating",
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
# Promote: getting a site found, and its posts and ads
|
|
2
|
+
|
|
3
|
+
On-demand guide (`uniweb guide promote`); AGENTS.md is assumed read. For a site published on Uniweb Cloud. Its Promote is kept by the backend you are logged in to, beside the site's Analytics in the app, and comes with that Analytics. A site on another host has no Promote; the docs' Advertising guide (`marketing/advertising.md`) is its manual path.
|
|
4
|
+
|
|
5
|
+
## Who does what
|
|
6
|
+
|
|
7
|
+
- **The person** connects each account at its network, in a browser signed in to the app; you hand them the address `uniweb promote connect <network>` prints. They turn on the site's Analytics, which carries Promote, in the app. They reconnect an account that needs it, and an admin hands on one whose person left. They decide what goes out and what is spent.
|
|
8
|
+
- **You** draft posts and campaigns, check the pages they link to, send and start what your person agreed to, and read what it brought. You act with their session, at the access they have; an account's tokens never pass through the CLI.
|
|
9
|
+
|
|
10
|
+
## On one screen
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
uniweb promote status # getting found, accounts, posts and campaigns by id, and what needs the person
|
|
14
|
+
uniweb promote status --json # the same, to read
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Run it first. Its *Ask the person first* lines are theirs alone. It names the networks this backend can connect: claim no other. `uniweb status` carries the short form for a site that uses Promote: what needs the person, a post that failed, the posts going out this week, and each running campaign's spend.
|
|
18
|
+
|
|
19
|
+
## Getting found
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
uniweb promote check sitemap
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
It checks that the live site's `robots.txt` names its sitemap, and says `todo` until the site's first publish. A step the CLI can't check (Search Console, a business listing) the person does at the service and marks in the app.
|
|
26
|
+
|
|
27
|
+
## A post
|
|
28
|
+
|
|
29
|
+
A post is a file. In Markdown, its frontmatter holds its fields and its body its words. A line of `---` separates the parts of a thread (X takes several, the others one), and a picture stands alone on its line.
|
|
30
|
+
|
|
31
|
+
```markdown
|
|
32
|
+
---
|
|
33
|
+
via: x # the network it goes out on
|
|
34
|
+
page: /holiday # the page it links to: a route, or page:<id>
|
|
35
|
+
language: en # the site's own language if left out
|
|
36
|
+
send_at: 2026-11-24T09:00-05:00 # optional: when `send` posts it
|
|
37
|
+
---
|
|
38
|
+
Our holiday trays are here.
|
|
39
|
+
|
|
40
|
+

|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
Order by Dec 20.
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
uniweb promote post holiday.md # the draft; the file gets its id and version back
|
|
49
|
+
uniweb promote send holiday.md # now, or at its send_at; --at <time> sets one, --now posts now anyway
|
|
50
|
+
uniweb promote unschedule holiday.md # a draft again, its time kept
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
- **`via`** names a network, and the post goes out through the site's account there. The first time, the CLI chooses it from your one account on that network. With several, give `via: { network: x, connection: <id> }`; the refusal lists them.
|
|
54
|
+
- **`page`** is a page of the site as pushed, so push a new page first. The live site must serve it in the post's language, or the send fails: publish first.
|
|
55
|
+
- **A picture** given as a file is uploaded as one of the site's own, in its format. An address is kept as written.
|
|
56
|
+
- **The words go out as written**, as plain text: Markdown formatting shows as typed.
|
|
57
|
+
- YAML and JSON work too: `text` and `pictures` for one part, or `parts: [{ text, pictures }]`.
|
|
58
|
+
|
|
59
|
+
## A campaign
|
|
60
|
+
|
|
61
|
+
A campaign is YAML or JSON, with its ad groups and their ads nested in it:
|
|
62
|
+
|
|
63
|
+
```yaml
|
|
64
|
+
name: Holiday
|
|
65
|
+
goal: conversions # conversions, visits or reach
|
|
66
|
+
devices: all # all, desktop or mobile
|
|
67
|
+
starts: 2026-12-01
|
|
68
|
+
ends: 2026-12-14
|
|
69
|
+
via: facebook # the ad accounts it runs in: one, or a list
|
|
70
|
+
ad_groups:
|
|
71
|
+
- name: Trays
|
|
72
|
+
daily_budget: 10.00 # in the ad account's currency
|
|
73
|
+
ads:
|
|
74
|
+
- page: /holiday
|
|
75
|
+
headlines: [Holiday trays, Order by Dec 20]
|
|
76
|
+
descriptions: [Fresh from our ovens]
|
|
77
|
+
text: Our holiday trays are here. # a social ad's words, with pictures beside them
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
uniweb promote campaign holiday.yml
|
|
82
|
+
uniweb promote start holiday --yes # once your person has agreed to what it says it will spend
|
|
83
|
+
uniweb promote pause holiday
|
|
84
|
+
uniweb promote resume holiday --yes
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
- **An ad runs in one of its campaign's accounts.** Name it with the ad's own `via`, or leave it out when the campaign has only one.
|
|
88
|
+
- **`start` and `resume` say what they will spend before they spend it:** the dates, each account's daily budgets and the most they come to, and the pages. At a terminal they ask. Without one they refuse unless given `--yes`, so show your person that summary and pass `--yes` only after they agree. The network bills the owner's ad account.
|
|
89
|
+
- **Once a campaign starts in an account, what runs there is fixed.** An edit to it is refused, and nothing changes. Add another ad account to its `via`, or draft a new campaign.
|
|
90
|
+
|
|
91
|
+
## Drafts stay right
|
|
92
|
+
|
|
93
|
+
- **Every command reads the site's Promote fresh.** The CLI keeps no copy, and the file keeps the `id` and `version` of what it wrote. A second run updates the same draft, and so does a teammate's copy of the file.
|
|
94
|
+
- **A change made since then is never written over.** If the app or another run changed the draft, your write is refused and nothing is written. `uniweb promote show <id> > file` gives you the draft as it stands, to put your change into.
|
|
95
|
+
- **Nothing is deleted by leaving it out.** An ad group or an ad the file doesn't hold is kept, and named. `uniweb promote delete <id>` deletes. A post's parts are its words, so the parts the file gives are the post's.
|
|
96
|
+
- **A post that went out isn't edited or deleted.** To post again, drop `id` and `version` and make a new draft.
|
|
97
|
+
- **Changing a scheduled post makes it a draft again,** its time kept, and `send` schedules it again.
|
|
98
|
+
- **An `<id>`** is the short one `status` shows, the file a draft was written from, or a campaign's name.
|
|
99
|
+
|
|
100
|
+
## The page it lands on
|
|
101
|
+
|
|
102
|
+
A post or an ad is only as good as the page it brings people to:
|
|
103
|
+
|
|
104
|
+
- the page carries on from what the post promised, within its first screen;
|
|
105
|
+
- it has its own share card: `description` and `seo.image` in its `page.yml` (content guide, *SEO and social cards*);
|
|
106
|
+
- a page that belongs to one campaign alone takes `hideIn: ['*']`, which keeps it out of menus.
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
uniweb promote check /holiday # its card, and what the site reports for a network to hear
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
It reads the site's files, so it works on any site, a static one too, with no login. Run in the site's project, `post`, `campaign`, `start` and `resume` print the same notes for the pages they link to. Each is a note, never a gate.
|
|
113
|
+
|
|
114
|
+
## What counts, and the network hearing it
|
|
115
|
+
|
|
116
|
+
A campaign with `goal: conversions` optimizes for what its network hears back. The site reports its own conversions (services guide, *what counts*). On Uniweb Cloud, the host sends X and Meta theirs from its servers, each mapped to the network's event (`services.x`, `services.meta`, services guide). A network that hears no conversion optimizes for clicks.
|
|
117
|
+
|
|
118
|
+
## What each brought
|
|
119
|
+
|
|
120
|
+
`uniweb promote status` shows what each running campaign has spent in each ad account, as the network last reported it, in that account's currency. A day it hasn't reported is unknown, not zero. The site's Analytics, in the app, shows its visits by where they came from. When you read them:
|
|
121
|
+
|
|
122
|
+
- judge by conversions, not clicks;
|
|
123
|
+
- change one thing at a time;
|
|
124
|
+
- decide what counts as working before the first number comes in;
|
|
125
|
+
- read the result once, at the end.
|
|
126
|
+
|
|
127
|
+
## Every command
|
|
128
|
+
|
|
129
|
+
| command | does |
|
|
130
|
+
|---|---|
|
|
131
|
+
| `status` | the site's Promote, and what needs the person |
|
|
132
|
+
| `check <step>` · `check <route>` | one getting-found step (`sitemap`), or a page as a landing page |
|
|
133
|
+
| `connect <network>` | the address where the person connects an account |
|
|
134
|
+
| `post <file>` · `campaign <file>` | a draft, made or updated; `-` reads stdin |
|
|
135
|
+
| `show <id>` | one post or campaign as its file holds it; its state goes to stderr |
|
|
136
|
+
| `delete <id>` | a post, a campaign, an ad group or an ad |
|
|
137
|
+
| `send <post> [--at <time> \| --now]` | post it now, or at its time |
|
|
138
|
+
| `unschedule <post>` | a scheduled post a draft again |
|
|
139
|
+
| `start <campaign>` · `resume <campaign>` | spend, after saying what; `--yes` answers |
|
|
140
|
+
| `pause <campaign>` | wherever it runs |
|
|
141
|
+
|
|
142
|
+
All of them take `--json`; `--site <uuid>` for a site this project isn't synced to; `--org @x` or `--personal` for the workspace. A time carries its offset: `2026-11-24T09:00-05:00`.
|
package/src/backend/client.js
CHANGED
|
@@ -134,8 +134,10 @@ export const SOURCE_HEADER = 'x-uniweb-source'
|
|
|
134
134
|
const sourceHeaders = (source) => (source ? { [SOURCE_HEADER]: source } : {})
|
|
135
135
|
|
|
136
136
|
/**
|
|
137
|
-
* Whether a request works IN a workspace — a site route, `/dev/site
|
|
138
|
-
* which acts on entities of the workspace it names (an entity outside it is refused, `409`)
|
|
137
|
+
* Whether a request works IN a workspace — a site route, `/dev/site…`; `/dev/entities…`,
|
|
138
|
+
* which acts on entities of the workspace it names (an entity outside it is refused, `409`);
|
|
139
|
+
* or `/dev/connections…`, the network connections the caller reaches in the workspace it
|
|
140
|
+
* names, where a consent started is recorded too.
|
|
139
141
|
*
|
|
140
142
|
* Only those name one. Every `/dev` route accepts the header, but registration reads
|
|
141
143
|
* none (the `@scope` in the name decides, membership-gated), `/dev/assets` reads none
|
|
@@ -148,7 +150,7 @@ const sourceHeaders = (source) => (source ? { [SOURCE_HEADER]: source } : {})
|
|
|
148
150
|
* @returns {boolean}
|
|
149
151
|
*/
|
|
150
152
|
export function namesWorkspace(path) {
|
|
151
|
-
return /^\/dev\/(site|entities)(\/|$)/.test(String(path))
|
|
153
|
+
return /^\/dev\/(site|entities|connections)(\/|$)/.test(String(path))
|
|
152
154
|
}
|
|
153
155
|
|
|
154
156
|
/**
|
|
@@ -594,10 +596,11 @@ export class BackendClient {
|
|
|
594
596
|
* is not read either — the login path is a hardcoded constant
|
|
595
597
|
* (`utils/registry-auth.js`). What is actually consumed is the key lists under
|
|
596
598
|
* `siteContent` — `queryFields`, `pageFields`, `settingsFields`, the keys the deployment's
|
|
597
|
-
* Sections declare (`site-sync.js::deploymentFields`) —
|
|
598
|
-
*
|
|
599
|
-
*
|
|
600
|
-
*
|
|
599
|
+
* Sections declare (`site-sync.js::deploymentFields`) — and `promote.networks`, the networks
|
|
600
|
+
* Promote can connect on this deployment (`commands/promote.js`). Both are policy, never an
|
|
601
|
+
* address. Do not add a reader for the rest: each one would be a second place a backend's
|
|
602
|
+
* layout is pinned. (This named `delivery.siteSubscriptionRequired` until 2026-09-26; that
|
|
603
|
+
* leaf went 2026-08-30.)
|
|
601
604
|
*
|
|
602
605
|
* @returns {Promise<object>}
|
|
603
606
|
*/
|
|
@@ -989,6 +992,136 @@ export class BackendClient {
|
|
|
989
992
|
})
|
|
990
993
|
}
|
|
991
994
|
|
|
995
|
+
// ── Promote ─────────────────────────────────────────────────────────────────
|
|
996
|
+
//
|
|
997
|
+
// The site's Promote, as the backend holds it: the networks it goes out through, its
|
|
998
|
+
// getting-found steps, its posts and its campaigns. The CLI is a second client of it,
|
|
999
|
+
// beside the app, and keeps no copy: each command reads fresh, and a write names the
|
|
1000
|
+
// version of each item it read, so a change made since is refused, never written over.
|
|
1001
|
+
|
|
1002
|
+
/**
|
|
1003
|
+
* GET /dev/site/promotion/{site} — `{ promotion: { uuid, items } }`, each item
|
|
1004
|
+
* `{ uuid, section, parent?, data, updated_at }` with `section` the path from the root
|
|
1005
|
+
* (`posts`, `posts/delivery`, …), or `{ promotion: null }` before the site first uses it.
|
|
1006
|
+
*
|
|
1007
|
+
* @param {string} siteUuid - the site-content uuid
|
|
1008
|
+
* @param {{ locale?: string }} [opts]
|
|
1009
|
+
* @returns {Promise<Response>}
|
|
1010
|
+
*/
|
|
1011
|
+
async readPromotion(siteUuid, { locale } = {}) {
|
|
1012
|
+
return this.request(`/dev/site/promotion/${encodeURIComponent(siteUuid)}`, { query: { locale } })
|
|
1013
|
+
}
|
|
1014
|
+
|
|
1015
|
+
/**
|
|
1016
|
+
* POST /dev/site/promotion/{site}/items — write the owner's fields, as one transaction:
|
|
1017
|
+
* `create` (`section`, `parent?`, `uuid?`, `data`, `position?`), `update` (`uuid`, `data`,
|
|
1018
|
+
* `if_unmodified_since?`) and `delete` (`uuid`, `if_unmodified_since?`). An update
|
|
1019
|
+
* replaces the item's data. Answers `{ uuid, results: [{ uuid, updated_at }] }` in op
|
|
1020
|
+
* order; one stale op refuses the whole batch `409`.
|
|
1021
|
+
*
|
|
1022
|
+
* @param {string} siteUuid
|
|
1023
|
+
* @param {object[]} batch
|
|
1024
|
+
* @returns {Promise<Response>}
|
|
1025
|
+
*/
|
|
1026
|
+
async writePromotionItems(siteUuid, batch) {
|
|
1027
|
+
return this.request(`/dev/site/promotion/${encodeURIComponent(siteUuid)}/items`, {
|
|
1028
|
+
method: 'POST',
|
|
1029
|
+
body: JSON.stringify({ batch })
|
|
1030
|
+
})
|
|
1031
|
+
}
|
|
1032
|
+
|
|
1033
|
+
/**
|
|
1034
|
+
* POST /dev/site/promotion/{site}/steps/{step}/check — check one getting-found step, named
|
|
1035
|
+
* by the step itself (`sitemap`). The backend finds the step's item, or makes it on its first
|
|
1036
|
+
* check. Answers `{ reading }`: `state`, `checked_at`, `found`, `detail?`, `address?`. A step
|
|
1037
|
+
* the backend cannot check is `400`, with nothing made.
|
|
1038
|
+
*
|
|
1039
|
+
* @param {string} siteUuid
|
|
1040
|
+
* @param {string} step - the step's token
|
|
1041
|
+
* @returns {Promise<Response>}
|
|
1042
|
+
*/
|
|
1043
|
+
async checkPromotionStep(siteUuid, step) {
|
|
1044
|
+
return this.request(
|
|
1045
|
+
`/dev/site/promotion/${encodeURIComponent(siteUuid)}/steps/${encodeURIComponent(step)}/check`,
|
|
1046
|
+
{ method: 'POST' }
|
|
1047
|
+
)
|
|
1048
|
+
}
|
|
1049
|
+
|
|
1050
|
+
/**
|
|
1051
|
+
* POST /dev/site/promotion/{site}/posts/{post}/{act} — a post's doors: `publish` (now),
|
|
1052
|
+
* `schedule` (at its `send_at`) and `unschedule` (a draft again, its `send_at` kept). Each
|
|
1053
|
+
* answers `{ delivery }`; `unschedule`'s is `null` once a draft. Publishing and scheduling
|
|
1054
|
+
* take `admin` on the site and `edit` on the account it goes out through; unscheduling takes
|
|
1055
|
+
* `edit` on the site.
|
|
1056
|
+
*
|
|
1057
|
+
* @param {string} siteUuid
|
|
1058
|
+
* @param {string} postUuid
|
|
1059
|
+
* @param {'publish'|'schedule'|'unschedule'} act
|
|
1060
|
+
* @returns {Promise<Response>}
|
|
1061
|
+
*/
|
|
1062
|
+
async postAction(siteUuid, postUuid, act) {
|
|
1063
|
+
return this.request(
|
|
1064
|
+
`/dev/site/promotion/${encodeURIComponent(siteUuid)}/posts/${encodeURIComponent(postUuid)}/${act}`,
|
|
1065
|
+
{ method: 'POST' }
|
|
1066
|
+
)
|
|
1067
|
+
}
|
|
1068
|
+
|
|
1069
|
+
/**
|
|
1070
|
+
* POST /dev/site/promotion/{site}/campaigns/{campaign}/{act} — `start` (in each ad account
|
|
1071
|
+
* of its `via` it doesn't run in yet), `pause` and `resume`, wherever it runs. Each answers
|
|
1072
|
+
* `{ deliveries }`, one per ad account. Starting and resuming spend in the owner's ad
|
|
1073
|
+
* accounts: they take `admin` on the site and `edit` on each account; pausing takes `admin`.
|
|
1074
|
+
*
|
|
1075
|
+
* @param {string} siteUuid
|
|
1076
|
+
* @param {string} campaignUuid
|
|
1077
|
+
* @param {'start'|'pause'|'resume'} act
|
|
1078
|
+
* @returns {Promise<Response>}
|
|
1079
|
+
*/
|
|
1080
|
+
async campaignAction(siteUuid, campaignUuid, act) {
|
|
1081
|
+
return this.request(
|
|
1082
|
+
`/dev/site/promotion/${encodeURIComponent(siteUuid)}/campaigns/${encodeURIComponent(campaignUuid)}/${act}`,
|
|
1083
|
+
{ method: 'POST' }
|
|
1084
|
+
)
|
|
1085
|
+
}
|
|
1086
|
+
|
|
1087
|
+
/**
|
|
1088
|
+
* GET /dev/site/promotion/{site}/campaigns/{campaign}/spend — `{ spend: [{ via, day, amount,
|
|
1089
|
+
* currency, read_at }] }`, as the backend last read it from each network. A day absent is
|
|
1090
|
+
* unknown, never zero.
|
|
1091
|
+
*
|
|
1092
|
+
* @param {string} siteUuid
|
|
1093
|
+
* @param {string} campaignUuid
|
|
1094
|
+
* @returns {Promise<Response>}
|
|
1095
|
+
*/
|
|
1096
|
+
async campaignSpend(siteUuid, campaignUuid) {
|
|
1097
|
+
return this.request(
|
|
1098
|
+
`/dev/site/promotion/${encodeURIComponent(siteUuid)}/campaigns/${encodeURIComponent(campaignUuid)}/spend`
|
|
1099
|
+
)
|
|
1100
|
+
}
|
|
1101
|
+
|
|
1102
|
+
/**
|
|
1103
|
+
* GET /dev/connections — `{ connections: [{ uuid, owner?, unit?, card }] }`: the network
|
|
1104
|
+
* connections the caller reaches in the workspace the request names. A card holds the
|
|
1105
|
+
* account's `network`, `name`, `handle`, `state`, never a token.
|
|
1106
|
+
*
|
|
1107
|
+
* @returns {Promise<Response>}
|
|
1108
|
+
*/
|
|
1109
|
+
async listConnections() {
|
|
1110
|
+
return this.request('/dev/connections')
|
|
1111
|
+
}
|
|
1112
|
+
|
|
1113
|
+
/**
|
|
1114
|
+
* POST /dev/connections/consent — `{ network, return_to? }` → `{ address }`, the network's
|
|
1115
|
+
* consent page. The browser that finishes it must be signed in to the app as the same
|
|
1116
|
+
* person; it comes back to `return_to`, an app page, or to the app's own origin.
|
|
1117
|
+
*
|
|
1118
|
+
* @param {{ network: string, return_to?: string }} body
|
|
1119
|
+
* @returns {Promise<Response>}
|
|
1120
|
+
*/
|
|
1121
|
+
async startConnectionConsent(body) {
|
|
1122
|
+
return this.request('/dev/connections/consent', { method: 'POST', body: JSON.stringify(body) })
|
|
1123
|
+
}
|
|
1124
|
+
|
|
992
1125
|
/**
|
|
993
1126
|
* Whether the backend holds the site `uuid` names — `live`, `gone` or `unknown`, kept
|
|
994
1127
|
* apart — for a script that must decide, before any push, whether a binding still
|