@taprootio/site-authoring 0.23.1 → 0.26.0

package/README.md

@@ -235,8 +235,8 @@ Which verbs apply depends on the site:
   `pull` snapshots its four settings documents, `theme push`, `footer push`,
   and `media upload` author them, and `deploy` stages and promotes them.
   Its pages, navigation, and redirects come from the Docs artifact, so
-  `pages push`, `nav push`, the `redirects` and `forms` verbs, `approve`, and the
-  `preview` verbs refuse with `surface.presentation_only` before any request.
+  `pages push`, `nav push`, the `redirects`, `forms` and `marketing` verbs, `link build`,
+  `approve`, and the `preview` verbs refuse with `surface.presentation_only` before any request.
 - A **prebuilt Docs** site (`none`) serves its artifact unchanged and takes no
   verb; each refuses with `surface.none`.
 
@@ -246,7 +246,9 @@ answers Not found like any site the account can no longer author, and the
 CLI adds a hint to run `use` again because the recording says the site was
 authorable before.
 
-`logout` discards the stored sign-in locally and revokes nothing; the
+`logout` discards only the stored account sign-in locally. Separately stored
+site legal draft grants remain; select each site and use
+`taproot-site --legal-drafts logout` to discard its grant. Logout revokes nothing; the
 credential stays valid until an owner revokes it under Account → Settings →
 API keys. The secret itself is never displayed, logged, or placed in any
 result: credentials are named by id and display prefix only.
@@ -396,6 +398,12 @@ the site's own document is kept as internal state under
 `.taproot-site-state/`, which is never a page source and never pushed. A page
 edited on the site since the last pull is a `pages.pull_conflict` refusal
 before anything under `pages/` changes, with both recovery paths named.
+Pull before creating a new JSON source. Once a new page is declared with a
+file, title or path but has no server page ID, save it with `pages push` before
+pulling again, or back up both the source and its manifest entry and move them
+out of the workspace. Pull refuses these pending entries rather than dropping
+their metadata. It also refuses an untracked legal or unreadable JSON source
+that would be replaced by a new remote page.
 
 Pages are not only free-form. A source chooses its template with `template:` in
 its front matter — `article`, `recipe`, `album` or `place-review`; free-form is
@@ -406,10 +414,25 @@ its original publication date) and `coverImage`, which the site requires to be a
 image the page itself uses (place it in the body too; `pages.cover_image_unused`). A page's template is fixed when
 it is created: a source for another template is refused with
 `pages.template_immutable`. `taproot-site help page <type>` gives each
-template's fields and one worked example. The structured legal page (a versioned
-privacy policy or terms with an effective date) is created and published in the
-app; the CLI records it as a metadata-only page, and `taproot-site help page
-legal` says what a site-authoring key can and cannot do with one.
+template's fields and one worked example. Pull includes structured legal pages and their
+bodies as `.pm.json` with the usual Content read permission. Create and update
+legal drafts in JSON only; Markdown conversion is not supported. The document
+key, role and path are immutable, and publication assigns the version, effective
+date and superseded version. See `taproot-site help page legal` for the fields.
+
+Select a standard site and run `taproot-site login --legal-drafts`; the owner
+reviews and approves a site-specific grant in the app, valid for at most 24
+hours. Ordinary account login stays separate. Use the global option before the
+verb, for example `taproot-site --legal-drafts pages push`,
+`taproot-site --legal-drafts plan`, or `taproot-site --legal-drafts apply`.
+It also selects the grant for `pull`, although ordinary Content access can read
+legal pages. Changed or new legal drafts require this grant before writes begin;
+unchanged legal pages do not block ordinary work. `TAPROOT_SITE_KEY` still takes
+precedence, and legal writes with an unclassified environment override are
+refused: unset it and use the explicit site login. Saving a draft does not
+approve it. Legal approval, deletion and deployment remain in the app. A bare
+`taproot-site approve` skips legal drafts and stages other tracked drafts; explicitly
+naming a legal page refuses the whole selection.
 A privacy policy or other legal page that names Taproot should link the first
 mention to <https://www.taproot.io>; `help page free-form` and `help page legal`
 give a sample sentence.
@@ -618,6 +641,54 @@ and takes effect without publishing or a new form version. Delivery requires
 Taproot's rollout and email provider readiness; opt-in does not enable either
 or backfill earlier submissions. The CLI never pulls visitor answers.
 
+### Campaigns, placements and tracked links
+
+A campaign groups the links of one push, and a placement names the spot a
+link appears, such as a newsletter footer. Both are bounded sets of public
+keys the site's release admits, so a page view that carries a matching
+`utm_campaign` or `utm_content` is counted under it. Each is one JSON file:
+`marketing/campaigns.json` is `{ campaigns: [{ key, name, note?, starts_on?,
+ends_on? }] }` and `marketing/placements.json` is `{ placements: [{ key, name
+}] }`.
+
+```bash
+taproot-site marketing pull          # write both files, with a baseline
+# edit marketing/campaigns.json and marketing/placements.json
+taproot-site marketing push          # create, update and restore
+taproot-site marketing push --archive  # also archive what the files leave out
+taproot-site link build --path /recipes/spring-salad --source newsletter \
+  --campaign spring-launch --placement nl-footer
+```
+
+`marketing pull` replaces both files with the site's live records, each with
+the read-only `state` (live, publishing, goes_live_with_first_publish,
+not_in_current_release) and `counted_from`, the day its key first went live.
+Archived records are listed and not written. `marketing push` validates both
+files, compares every record with the site, and then creates a key the site
+lacks, updates the labels of an existing key, and restores an archived key a
+file names. A key is public URL text and never changes or returns to use, so a
+changed key is a new record; the old one is archived only when you pass
+`--archive`, and only if this workspace pulled it. A record that changed on the
+site since the pull is refused (`marketing.concurrent_modification`), as is a
+key the site has that this workspace never pulled (`marketing.pull_required`).
+Quota and key refusals are shown as Taproot words them. Like `forms push`, it
+has no plan step: it reads the site, refuses a stale baseline, and writes.
+Creating or restoring a key queues the silent release that starts counting it;
+nothing is deployed or waited for.
+
+`link build` prints one address and saves nothing. It uses the Marketing link
+builder's own rules, compiled from the app: the source decides the medium
+(`reader` is not offered), a `utm_source`, `utm_medium`, `utm_campaign` or `utm_content` already on the path is replaced (other `utm_` pairs are kept), and a
+campaign or placement is checked against `marketing/*.json` when the workspace
+has them, and otherwise against the live site. A key that is not live yet is
+allowed, with a note that page views count under the source only until it is
+(a note read from a file is as of the last `marketing pull` or push).
+The host is the signed-in site's public address; pass `--domain <host>` when
+only a site credential is available. The `delegation.content` capability
+carries what these verbs need (`site.analytics.view`, plus the publish
+permission to change anything); `whoami` reports whether the last exchange
+held it. `help marketing` and `help link` state the contracts.
+
 `preview page <page-path-or-id>` renders one persisted draft behind the
 staging gate and mints a browser handoff URL, reported only in the final JSON
 result. **Each handoff is single-use.** Opening the URL consumes it; a reused,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.23.1",
+  "version": "0.26.0",
   "description": "Taproot site authoring CLI: sign in once in the browser, then pull, validate, push, preview, approve, and deploy a site from the terminal",
   "type": "module",
   "license": "ISC",
@@ -28,7 +28,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@taprootio/espalier": "6.5.0",
+    "@taprootio/espalier": "6.7.0",
     "mediabunny": "1.61.1"
   },
   "scripts": {

package/src/analytics-campaign.json

@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "keyPattern": "^[a-z0-9-]{3,32}$",
+  "keyMinLength": 3,
+  "keyMaxLength": 32,
+  "maxActivePerSite": 50,
+  "artifactPath": "_taproot/analytics-campaigns.json",
+  "artifactVersion": 1,
+  "collectorMarker": "c1",
+  "maxDigitRun": 8,
+  "maxTotalPerSite": 500,
+  "nameMaxLength": 80,
+  "noteMaxLength": 500,
+  "vectors": [
+    {"value": "spring-26", "valid": true},
+    {"value": "abc", "valid": true},
+    {"value": "ab", "valid": false},
+    {"value": "a-very-long-campaign-key-that-is-over-32", "valid": false},
+    {"value": "Spring-26", "valid": false},
+    {"value": "spring_26", "valid": false},
+    {"value": "spring 26", "valid": false},
+    {"value": "spring|26", "valid": false},
+    {"value": "spring.26", "valid": false},
+    {"value": "", "valid": false},
+    {"value": "-leading", "valid": true},
+    {"value": "x12345678y", "valid": true},
+    {"value": "promo-123456789", "valid": false},
+    {"value": "spring-26\n", "valid": false},
+    {"value": "0123456789", "valid": false}
+  ]
+}

package/src/analytics-link-label.json

@@ -0,0 +1,22 @@
+{
+  "version": 1,
+  "keyGrammar": "campaign",
+  "artifactPath": "_taproot/analytics-links.json",
+  "artifactVersion": 1,
+  "collectorMarker": "c2",
+  "maxActivePerSite": 200,
+  "maxTotalPerSite": 2000,
+  "nameMaxLength": 80,
+  "vectors": [
+    {"value": "nl-footer", "valid": true},
+    {"value": "abc", "valid": true},
+    {"value": "ab", "valid": false},
+    {"value": "NL-footer", "valid": false},
+    {"value": "nl_footer", "valid": false},
+    {"value": "nl footer", "valid": false},
+    {"value": "nl|footer", "valid": false},
+    {"value": "a-label-key-that-is-longer-than-32", "valid": false},
+    {"value": "promo-123456789", "valid": false},
+    {"value": "", "valid": false}
+  ]
+}

package/src/analytics-source-vocabulary.json

@@ -0,0 +1,17 @@
+{
+  "version": 1,
+  "media": ["social", "email", "share"],
+  "sources": [
+    { "key": "linkedin", "name": "LinkedIn", "medium": "social", "aliases": ["linkedin.com", "lnkd.in", "com.linkedin.android"] },
+    { "key": "x", "name": "X", "medium": "social", "aliases": ["x.com", "twitter.com", "t.co", "com.twitter.android"] },
+    { "key": "facebook", "name": "Facebook", "medium": "social", "aliases": ["facebook.com", "fb.com", "fb.me", "com.facebook.katana", "com.facebook.lite"] },
+    { "key": "instagram", "name": "Instagram", "medium": "social", "aliases": ["instagram.com", "com.instagram.android"] },
+    { "key": "threads", "name": "Threads", "medium": "social", "aliases": ["threads.net", "threads.com", "com.instagram.barcelona"] },
+    { "key": "bluesky", "name": "Bluesky", "medium": "social", "aliases": ["bsky.app", "bsky.social", "xyz.blueskyweb.app"] },
+    { "key": "mastodon", "name": "Mastodon", "medium": "social", "aliases": ["mastodon.social", "mastodon.online", "org.joinmastodon.android"] },
+    { "key": "reddit", "name": "Reddit", "medium": "social", "aliases": ["reddit.com", "redd.it", "com.reddit.frontpage"] },
+    { "key": "youtube", "name": "YouTube", "medium": "social", "aliases": ["youtube.com", "youtu.be", "com.google.android.youtube"] },
+    { "key": "newsletter", "name": "Newsletter", "medium": "email", "aliases": [] },
+    { "key": "reader", "name": "Reader shares", "medium": "share", "aliases": [] }
+  ]
+}

package/src/api.js

@@ -25,6 +25,7 @@ import {
 // must equal acceptance on save — a prefix admitted here but refused there
 // would turn a successful mint into an orphaned key.
 import { KEY_PREFIX } from "./credentials.js";
+import { CAPABILITY_LEGAL_DRAFTS, SITE_AUTHORING_CAPABILITIES } from "./capabilities.js";
 import { isCanonicalUuid, normalizePreviewDiagnostic, sanitizeDiagnostic, SiteAuthoringError } from "./errors.js";
 import { normalizeAuthorListing, parseAuthorReference } from "./authors-contract.js";
 import { docsPublicationModeFromWire, siteKindFromWire, surfaceFromWire } from "./surface.js";
@@ -2238,7 +2239,7 @@ function requireBoundedSeconds(value, minimum, maximum, field) {
  * caller from the already-allowlisted API origin, so a compromised or
  * misconfigured server cannot steer the owner somewhere else to approve.
  */
-export async function startCliAuthorization(client, { keyName }, requestOptions = {}) {
+export async function startCliAuthorization(client, { keyName, legalDraftSiteId }, requestOptions = {}) {
   const response = requireObject(
     // No site: TR00645 made the account-level sign-in the front door, so the
     // CLI no longer has to know a site id before it can authorize at all.
@@ -2248,7 +2249,7 @@ export async function startCliAuthorization(client, { keyName }, requestOptions
     await client.request(CLI_AUTHORIZATION_PATH, {
       ...requestOptions,
       method: "POST",
-      body: { keyName, cliVersion: CLI_VERSION },
+      body: { keyName, cliVersion: CLI_VERSION, ...(legalDraftSiteId === undefined ? {} : { legalDraftSiteId }) },
     }),
     "login.start_contract",
     "CLI authorization",
@@ -2263,9 +2264,13 @@ export async function startCliAuthorization(client, { keyName }, requestOptions
       field: "userCode",
     });
   }
+  if (legalDraftSiteId !== undefined && response.legalDraftSiteId !== legalDraftSiteId) {
+    throw new SiteAuthoringError("login.start_contract", "Taproot did not confirm the selected legal draft site. Update the server and try again.", { field: "legalDraftSiteId" });
+  }
   return {
     deviceCode: response.deviceCode,
     userCode: response.userCode,
+    ...(legalDraftSiteId === undefined ? {} : { legalDraftSiteId }),
     expiresInSeconds: requireBoundedSeconds(
       response.expiresInSeconds,
       1,
@@ -2387,7 +2392,7 @@ export async function exchangeSiteAuthoringToken(client, { siteId, capabilities
   };
 }
 
-function normalizeIssuedCredential(response) {
+function normalizeIssuedCredential(response, legalDraftSiteId) {
   if (!isWellFormedCredential(response.rawKey)) {
     // The value is never quoted, here or anywhere: it is the secret.
     throw new SiteAuthoringError("login.claim_unusable", "Taproot returned an invalid issued key.", {
@@ -2411,7 +2416,24 @@ function normalizeIssuedCredential(response) {
       || response.keyExpiresAt === ""
     ? undefined
     : requireCanonicalTimestamp(response.keyExpiresAt, "login.claim_unusable", "keyExpiresAt").value;
+  if (legalDraftSiteId !== undefined) {
+    const capabilities = response.capabilities;
+    if (response.legalDraftSiteId !== legalDraftSiteId || !Array.isArray(capabilities)
+      || capabilities.length !== SITE_AUTHORING_CAPABILITIES.length + 1
+      || new Set(capabilities).size !== capabilities.length
+      || ![...SITE_AUTHORING_CAPABILITIES, CAPABILITY_LEGAL_DRAFTS].every((value) => capabilities.includes(value))
+      || (response.legalDraftPlatformSite !== undefined && typeof response.legalDraftPlatformSite !== "boolean")
+      || keyExpiresAt === undefined) {
+      throw new SiteAuthoringError("login.claim_unusable", "Taproot returned an invalid legal draft grant.");
+    }
+  } else if (response.legalDraftSiteId || (Array.isArray(response.capabilities) && response.capabilities.length > 0)) {
+    throw new SiteAuthoringError("login.claim_unusable", "Taproot returned an unexpected site grant.");
+  }
   return {
+    ...(legalDraftSiteId === undefined ? {} : {
+      purpose: "legal-drafts", siteId: legalDraftSiteId, capabilities: [...response.capabilities],
+      legalDraftPlatformSite: response.legalDraftPlatformSite ?? false,
+    }),
     key: response.rawKey,
     keyId,
     keyPrefix: response.keyPrefix,
@@ -2427,7 +2449,7 @@ function normalizeIssuedCredential(response) {
  * `..._CONSUMED`, and the caller reports the orphaned credential honestly
  * rather than hiding it behind a network error.
  */
-export async function claimCliAuthorization(client, deviceCode, requestOptions = {}) {
+export async function claimCliAuthorization(client, deviceCode, requestOptions = {}, { legalDraftSiteId } = {}) {
   // Every `login.claim_contract` raised here — a non-object envelope, an
   // absent status, a status string this vocabulary does not know — is an
   // answer this client could not read, not proof the claim was refused. A
@@ -2451,7 +2473,7 @@ export async function claimCliAuthorization(client, deviceCode, requestOptions =
     );
   }
   if (status === CLI_AUTHORIZATION_CLAIM_STATUS_ISSUED) {
-    return { status, credential: normalizeIssuedCredential(response) };
+    return { status, credential: normalizeIssuedCredential(response, legalDraftSiteId) };
   }
   if (status === CLI_AUTHORIZATION_CLAIM_STATUS_CONSUMED) {
     // A consumed answer names the credential an earlier claim minted, so the

package/src/capabilities.js

@@ -14,6 +14,7 @@
 export const CAPABILITY_CONTENT = "delegation.content";
 export const CAPABILITY_DESIGN = "delegation.design";
 export const CAPABILITY_DEPLOYMENTS = "delegation.deployments";
+export const CAPABILITY_LEGAL_DRAFTS = "delegation.legal-drafts";
 
 export const SITE_AUTHORING_CAPABILITIES = Object.freeze([
   CAPABILITY_CONTENT,
@@ -23,7 +24,7 @@ export const SITE_AUTHORING_CAPABILITIES = Object.freeze([
 
 /** What each capability lets an exchanged credential do, for help and `whoami`. */
 export const SITE_AUTHORING_CAPABILITY_SUMMARIES = Object.freeze({
-  "delegation.content": "write pages, media, and form definitions",
+  "delegation.content": "write pages, media, form definitions, campaigns, and placements",
   "delegation.design": "set the theme, navigation, and footer",
   "delegation.deployments": "stage and deploy",
 });

package/src/changelog.json

@@ -1,5 +1,43 @@
 {
   "entries": [
+    {
+      "version": "0.26.0",
+      "note": "marketing pull and marketing push keep a site's campaigns and placements as files, and link build prints a tracked address, so an agent can run a site's attribution over the CLI.",
+      "behavior": [
+        "New verbs: taproot-site marketing pull, marketing push [--archive] and link build --path <page> --source <key> [--campaign <key>] [--placement <key>] [--domain <host>]. A key now carries the permissions they need: delegation.content includes site.analytics.view, so a credential minted before this release gains read access to the site's campaigns and placements and, with the publish permission it already held, may change them.",
+        "marketing pull writes marketing/campaigns.json and marketing/placements.json (key, name, a campaign's note, starts_on and ends_on, and the read-only state and counted_from) and records a baseline in the pull manifest; a plain pull carries it forward. marketing push validates both files, compares every record with the site, and creates a new key, updates the labels of an existing one, or restores an archived key the file names. A key is public and never changes, so a changed key is a new record; a record the file leaves out is archived only with --archive, and only if the workspace pulled it. A record that changed on the site since the pull is refused (marketing.concurrent_modification, marketing.pull_required). Quota and key refusals are shown as Taproot returns them. There is no plan or apply step, as with forms push.",
+        "link build prints one address and saves nothing, with the Marketing link builder's own rules: the source decides the medium, the reader source is not offered, a utm_source, utm_medium, utm_campaign or utm_content on the path is replaced, and a campaign or placement is checked against marketing/*.json when the workspace has it, otherwise against the site. One that is not live yet is allowed with the builder's note that page views count under the source only until it is. The host is the signed-in site's public address; pass --domain when only a site credential is available.",
+        "whoami reports whether the last exchange allows campaigns and placements (marketing.access).",
+        "The help reference version is 43.",
+        "Built against Espalier 6.7.0. The default site theme is rebuilt against it and its content is unchanged except for the recorded Espalier version, so pulled and validated themes behave as before."
+      ],
+      "help": [
+        "marketing",
+        "link"
+      ]
+    },
+    {
+      "version": "0.25.0",
+      "note": "Redirects from /s/ addresses are ordinary redirects now that tracked share links are retired.",
+      "behavior": [
+        "A redirect whose source is /s/<anything> saves and validates like any other source. The redirect.source_share_link site-check rule is gone, so offline checks and the server no longer refuse it."
+      ],
+      "help": []
+    },
+    {
+      "version": "0.24.0",
+      "note": "Site-specific consent enables legal draft authoring through JSON; legal approval and publication remain in the app.",
+      "behavior": [
+        "Select a standard site, then run login --legal-drafts and approve the pinned site grant in the app. It lasts at most 24 hours and is separate from ordinary account login. Use the global --legal-drafts option before pull, pages push, plan or apply to select that grant.",
+        "Pull includes legal bodies as .pm.json with ordinary Content read access. Legal create and update accept JSON only; document key, role and path are immutable, and version, effective date and superseded version are assigned by publication. A changed or new legal draft needs the explicit grant before writes begin.",
+        "TAPROOT_SITE_KEY takes precedence; legal writes with an unclassified environment key are refused. Legal approval, deletion and deployment remain app-only. Saving a draft does not approve it.",
+        "The help reference version is 42."
+      ],
+      "help": [
+        "page",
+        "pages"
+      ]
+    },
     {
       "version": "0.23.1",
       "note": "Image uploads support Taproot’s single-use upload gateway and send an operation key with each upload request.",