uniweb 1.34.12 → 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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "uniweb",
3
- "version": "1.34.12",
3
+ "version": "1.35.0",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -41,15 +41,15 @@
41
41
  "js-yaml": "^4.3.2",
42
42
  "prompts": "^2.4.2",
43
43
  "tar": "^7.5.21",
44
- "@uniweb/core": "~1.6.13",
44
+ "@uniweb/content-writer": "~1.3.2",
45
45
  "@uniweb/semantic-parser": "~1.13.5",
46
46
  "@uniweb/schemas": "~1.7.4",
47
- "@uniweb/content-writer": "~1.3.2"
47
+ "@uniweb/core": "~1.6.13"
48
48
  },
49
49
  "peerDependencies": {
50
- "@uniweb/build": "~1.23.9",
50
+ "@uniweb/content-reader": "~1.5.11",
51
51
  "@uniweb/semantic-parser": "~1.13.5",
52
- "@uniweb/content-reader": "~1.5.11"
52
+ "@uniweb/build": "~1.24.0"
53
53
  },
54
54
  "peerDependenciesMeta": {
55
55
  "@uniweb/build": {
@@ -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. Step 6 runs `content` or `foundation` before any writing; you will know when you need the rest. `uniweb guide` alone lists them.
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.
@@ -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
+ ![](./tray.jpg)
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`.
@@ -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…`, or `/dev/entities…`,
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`) — which is policy, never an address. Do not
598
- * add a reader for the rest: each one would be a second place a backend's layout is
599
- * pinned. (This named `delivery.siteSubscriptionRequired` until 2026-09-26; that leaf
600
- * went 2026-08-30.)
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