@taprootio/site-authoring 0.24.0 → 0.27.0

package/src/reference-help.js

@@ -50,6 +50,13 @@ import {
   FORM_SINKS,
   FORMS_DIRECTORY,
 } from "./forms-contract.js";
+import {
+  LINK_SOURCES,
+  MARKETING_KEY_RULE,
+  MARKETING_KINDS,
+  MARKETING_STATES,
+  maximumActive,
+} from "./marketing-contract.js";
 import {
   formatPresentationReference,
   getAppearanceReference,
@@ -88,7 +95,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getSettingsReference, getThemeReference };
 
-export const REFERENCE_VERSION = 42;
+export const REFERENCE_VERSION = 44;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({
@@ -422,6 +429,16 @@ export const REFERENCE_TOPICS = Object.freeze([
     usage: `${CLI_BINARY_NAME} help forms`,
     summary: "Author a form as forms/<key>.json: file shape, field types, validate, pull, push, and placing it on a page.",
   }),
+  Object.freeze({
+    name: "marketing",
+    usage: `${CLI_BINARY_NAME} help marketing`,
+    summary: "Keep a site's campaigns and placements as marketing/*.json: file shape, pull, push, archive, and what an agent may do.",
+  }),
+  Object.freeze({
+    name: "link",
+    usage: `${CLI_BINARY_NAME} help link`,
+    summary: "Build a tracked address: path, source, optional campaign and placement; what counts and when it goes live.",
+  }),
   Object.freeze({
     name: "media",
     usage: `${CLI_BINARY_NAME} help media`,
@@ -866,6 +883,11 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "the visitor saw it, so a response shows what each box agreed to.",
       "Editing a definition appends a version on the site; versions are never changed. A page keeps the form "
       + "version it was published with until the next deploy, and a rollback restores the form it shipped with.",
+      "definition.presentation optionally overrides the site's form appearance: background, border and shadow are "
+      + "optional booleans. Omit a property to inherit the corresponding site preference (formBoxBackground, "
+      + "formBoxBorder, formBoxShadow); false turns that choice off. Omit presentation when all three inherit: an empty "
+      + "object is refused. Site defaults are background on, border off and shadow on. Background can be off while border "
+      + "and shadow remain on. The release freezes both the form choices and the site defaults.",
       "Both verbs write the file in one canonical key order, so a pulled file pushed back unchanged reports "
       + "'unchanged' and leaves the bytes as they were. Write your own files in that order and a push rewrites "
       + "nothing you did not change.",
@@ -903,6 +925,95 @@ const WORKFLOW_REFERENCES = Object.freeze({
       }),
     }),
   }),
+  marketing: Object.freeze({
+    title: "Campaigns and placements workspace contract",
+    summary: "A site's campaigns and placements are two JSON files under marketing/. 'marketing pull' reads the site's, "
+      + "'marketing push' creates, updates, restores and (with --archive) archives to match them, and 'link build' prints "
+      + "an address that uses them.",
+    usage: `${CLI_BINARY_NAME} marketing pull | ${CLI_BINARY_NAME} marketing push [--archive]`,
+    details: Object.freeze([
+      "Run 'pull' once first: both verbs need the pulled workspace's manifest, which records what each record looked "
+      + "like when this workspace last read it. The site's licence must include analytics, and the site must be a Standard site.",
+      `A campaign groups links from one push; a placement names the spot a link appears, such as a newsletter footer. `
+      + `Both are public keys the site's release admits, so page views carry them: a campaign as utm_campaign, a placement as `
+      + `utm_content. ${MARKETING_KINDS.campaigns.file} is { campaigns: [ { key, name, note?, starts_on?, ends_on? } ] }; `
+      + `${MARKETING_KINDS.placements.file} is { placements: [ { key, name } ] }. Records are listed by key.`,
+      `A key is ${MARKETING_KEY_RULE}. It is public URL text and never changes or returns to use, even after the record is `
+      + "archived, because page views already counted under it keep the key. A name (at most "
+      + `${MARKETING_KINDS.campaigns.rules.nameMaxLength} characters), a campaign's note (at most ${MARKETING_KINDS.campaigns.rules.noteMaxLength}) `
+      + "and its starts_on and ends_on days (YYYY-MM-DD, labels only) are private and can change.",
+      `A pull also writes two read-only fields: state (${MARKETING_STATES.join(", ")}) and counted_from, the day the key first `
+      + "went live and page views began to count under it. A push ignores both. A record is live once the silent release "
+      + "that carries its key has run; until then page views count under the source only.",
+      "'marketing push' validates both files and compares every record with the site before the first write. "
+      + "A key the file names that the site lacks is created. A record whose labels differ is updated. A key the file "
+      + "names that the site has archived is restored (and updated if its labels differ). Nothing else is touched: a "
+      + "record the file leaves out stays unless you pass --archive, and --archive archives only records this workspace "
+      + "pulled. A changed key is therefore a new record plus, if you want the old one gone, an explicit --archive.",
+      "A record that changed on the site since the last pull is refused as marketing.concurrent_modification, a key "
+      + "the site has that this workspace never pulled as marketing.pull_required; reconcile with 'marketing pull' and "
+      + "retry. Taproot refuses a key outside the grammar, a key already used by an archived record, and a record over "
+      + `the quota (${maximumActive("campaigns")} unarchived campaigns, ${maximumActive("placements")} unarchived placements, and a larger cap on archived ones `
+      + "together); the refusal is shown as Taproot returns it. Archive one to make room, or restore an archived one.",
+      "'marketing pull' reports, per kind, file, total, items ([{ key, state }], at most 200), archived keys (at most 200, "
+      + "with archivedTotal and archivedTruncated), canManage and maxActive. 'marketing push' reports, per kind, the keys it "
+      + "created, updated, restored, archived, left unchanged, left on the site because the file omits them (unlisted) and found "
+      + "on the site but never pulled (unpulled), each list capped at 50 with the true totals in counts and the capped lists "
+      + "named in truncated; written is { items, count } across both kinds.",
+      "Creating or restoring a key queues a silent production release that starts admitting it; no 'deploy' is needed and "
+      + "none is waited for. 'marketing pull' later shows the state. Archiving queues no release: the key stops being admitted from the next one.",
+      "The delegation.content capability carries the permissions this needs: site.analytics.view to read and also "
+      + "site.pages.publish_any to change, because a new key publishes a release. Platform-wide, an administrator can pause external "
+      + "authoring; a push is then refused with the rollout field. A refusal names a missing permission.",
+    ]),
+    example: Object.freeze({
+      campaigns: Object.freeze({
+        campaigns: Object.freeze([
+          Object.freeze({
+            key: "spring-launch",
+            name: "Spring launch",
+            note: "Newsletter and social push",
+            starts_on: "2026-03-01",
+            ends_on: "2026-03-31",
+          }),
+        ]),
+      }),
+      placements: Object.freeze({
+        placements: Object.freeze([Object.freeze({ key: "nl-footer", name: "Newsletter footer" })]),
+      }),
+      commands: Object.freeze([
+        `${CLI_BINARY_NAME} marketing pull`,
+        `${CLI_BINARY_NAME} marketing push`,
+        `${CLI_BINARY_NAME} link build --path /recipes/spring-salad --source newsletter --campaign spring-launch --placement nl-footer`,
+      ]),
+    }),
+  }),
+  link: Object.freeze({
+    title: "Tracked link builder",
+    summary: "'link build' prints one address that counts under a source, and optionally a campaign and a placement. It saves nothing.",
+    usage: `${CLI_BINARY_NAME} link build --path <page> --source <key> [--campaign <key>] [--placement <key>] [--domain <host>]`,
+    details: Object.freeze([
+      "--path is the page on this site, such as /recipes/spring-salad; / or an empty value is the home page. A query or #fragment "
+      + "is kept; a full address is accepted only if it is on this site's own host. --source is where the link will be posted: "
+      + `${LINK_SOURCES.map((source) => source.key).join(", ")}. The medium (social or email) is set by the source and cannot be chosen. 'reader' is not offered: `
+      + "a published page's own share action sets it.",
+      "The address is https://<public host><path>?utm_source=<source>&utm_medium=<medium>[&utm_campaign=<campaign>][&utm_content=<placement>]. "
+      + "A utm_source, utm_medium, utm_campaign or utm_content already on the path is replaced, never duplicated. Page views carry these values into the site's "
+      + "analytics only for campaigns and placements the site admits; anything else is dropped.",
+      "The host is the site's public address, read from the signed-in site; a site credential alone cannot read it, so "
+      + "pass --domain <host> then. A site with no public address yet has nothing to build a link to.",
+      "A campaign or placement is checked first. When the workspace has marketing/campaigns.json or marketing/placements.json "
+      + "(from 'marketing pull'), the file is the record of what exists; otherwise the live site is asked. A key it does not "
+      + "hold, or one the site has archived, is refused, because it would not be counted. A key that exists but is not live yet is "
+      + "allowed, and the result carries a note: 'publishing' while its release runs, 'goes live with your first publish' for a site "
+      + "that has not published, or 'not in the current release' after a rollback. Until it is live, page views count under the source only. A note read from a file says it is as of the last marketing pull or push, so run 'marketing pull' for the current state.",
+      "The result is { link: { address, host, path, source, medium, campaign?, placement? }, notes? }.",
+    ]),
+    example: Object.freeze({
+      command: `${CLI_BINARY_NAME} link build --path /recipes/spring-salad --source newsletter --campaign spring-launch --placement nl-footer`,
+      address: "https://example.com/recipes/spring-salad?utm_source=newsletter&utm_medium=email&utm_campaign=spring-launch&utm_content=nl-footer",
+    }),
+  }),
   media: Object.freeze({
     title: "Media upload contract",
     summary: "Upload workspace-root-relative raster files and videos; images are recorded in .taproot-site-media.json and videos report their ids.",

package/src/session.js

@@ -86,7 +86,7 @@ function keyMissingError() {
  * The exchange's own answer is checked again afterwards, because the
  * recording can be stale.
  */
-function requireRecordedSurface(invocation, config) {
+export function requireRecordedSurface(invocation, config) {
   if (invocation.surface === undefined || config.authoringSurface === undefined) return;
   if (!surfaceAllows(config.authoringSurface, invocation.surface)) {
     throw surfaceRefusal(invocation.verb ?? "This verb", config.authoringSurface, { source: "config" });

package/src/setting-reference.js

@@ -272,6 +272,24 @@ const PREFERENCES_ENTRIES = {
       + "a deployment.",
     false,
   ),
+  formBoxBackground: entry(
+    `${FEATURES} > Form appearance > Background`,
+    "Whether embedded forms have a box background by default. A form's presentation.background overrides this choice.",
+    "Embedded forms, including validation and confirmation. A change applies after deployment.",
+    true,
+  ),
+  formBoxBorder: entry(
+    `${FEATURES} > Form appearance > Border`,
+    "Whether embedded forms have a border by default. A form's presentation.border overrides this choice.",
+    "Embedded forms. Independent of background and shadow; applies after deployment.",
+    false,
+  ),
+  formBoxShadow: entry(
+    `${FEATURES} > Form appearance > Shadow`,
+    "Whether embedded forms have a shadow by default. A form's presentation.shadow overrides this choice.",
+    "Embedded forms. Independent of background and border; applies after deployment.",
+    true,
+  ),
   tiptapImageMaxHeightVh: entry(
     `${FEATURES} > Image height`,
     "The tallest an image in a page body may be, as a percent of the screen height (45, 60, 75 or 90).",

package/src/settings-catalog.js

@@ -130,6 +130,9 @@ export const SETTINGS_GROUPS = Object.freeze([
       // Asks readers before the visit cookie is set (TR01263). Off is what an omitted value means, so a snapshot of
       // an untouched site reads the same as the site behaves.
       { name: "analyticsConsentPrompt", wireType: "boolean" },
+      { name: "formBoxBackground", wireType: "boolean", zero: true },
+      { name: "formBoxBorder", wireType: "boolean" },
+      { name: "formBoxShadow", wireType: "boolean", zero: true },
       { name: "tiptapImageMaxHeightVh", wireType: "int" },
       { name: "tiptapImageMaxImagesPerRow", wireType: "int" },
       { name: "tiptapImageBorderWidth", wireType: "int" },
@@ -146,7 +149,7 @@ export const CANDIDATE_SELECTABLE_SETTINGS_TYPES = Object.freeze(
 );
 
 function zeroValue(field) {
-  if (field.wireType === "boolean") return false;
+  if (field.wireType === "boolean") return field.zero ?? false;
   if (field.wireType === "int" || field.wireType === "double") return 0;
   if (field.wireType === "theme" || field.wireType === "document") return field.zero ?? {};
   return field.zero ?? "";

package/src/site-check-findings.js

@@ -36,7 +36,6 @@ export const SITE_CHECK_WORDING = Object.freeze({
   "redirect.source_invalid": () => "has a source that is not an absolute site path",
   "redirect.source_index_html": () => "has a source ending in index.html",
   "redirect.source_integration_data": () => "has a source under the integration data root",
-  "redirect.source_share_link": () => "has a source under the share-link root",
   "redirect.source_runtime_mirror": () => "has a source under the published-site runtime",
   "redirect.source_generated_file": () => "has a source naming a file the site generates",
   "redirect.source_not_storable": () => "has a source the publisher cannot store",

package/src/site-check-rules.json

@@ -16,7 +16,6 @@
     { "id": "redirect.source_invalid", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "none" },
     { "id": "redirect.source_index_html", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
     { "id": "redirect.source_integration_data", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
-    { "id": "redirect.source_share_link", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
     { "id": "redirect.source_runtime_mirror", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
     { "id": "redirect.source_generated_file", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
     { "id": "redirect.source_not_storable", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },

package/src/site-checks.js

@@ -19,7 +19,6 @@ export const RULE_FORM_KEY_UNKNOWN = "form.key_unknown";
 export const RULE_REDIRECT_SOURCE_INVALID = "redirect.source_invalid";
 export const RULE_REDIRECT_SOURCE_INDEX_HTML = "redirect.source_index_html";
 export const RULE_REDIRECT_SOURCE_INTEGRATION_DATA = "redirect.source_integration_data";
-export const RULE_REDIRECT_SOURCE_SHARE_LINK = "redirect.source_share_link";
 export const RULE_REDIRECT_SOURCE_RUNTIME_MIRROR = "redirect.source_runtime_mirror";
 export const RULE_REDIRECT_SOURCE_GENERATED_FILE = "redirect.source_generated_file";
 export const RULE_REDIRECT_SOURCE_NOT_STORABLE = "redirect.source_not_storable";
@@ -282,7 +281,6 @@ export function normalizeRedirectPath(value) {
 }
 const GENERATED_ROOT_FILES = ["404.html", "sitemap.xml", "robots.txt", "favicon.ico"];
 const INTEGRATION_DATA_ROOT = "integrations";
-const SHARE_LINK_ROOT = "s";
 const MAX_MARKER_SEGMENT_BYTES = 200;
 const MAX_OUTPUT_PATH_LENGTH = 1_024;
 const WINDOWS_DEVICE_STEMS = new Set(["con", "prn", "aux", "nul"]);
@@ -317,10 +315,6 @@ export function redirectSourceRule(edgePath) {
     }
     if (first.toLowerCase() === INTEGRATION_DATA_ROOT)
         return refuse(RULE_REDIRECT_SOURCE_INTEGRATION_DATA);
-    const shareSegments = decoded.replace(/^\/+|\/+$/gu, "").split("/");
-    if (shareSegments.length > 1 && shareSegments[1].length > 0 && shareSegments[0].toLowerCase() === SHARE_LINK_ROOT) {
-        return refuse(RULE_REDIRECT_SOURCE_SHARE_LINK);
-    }
     if (isRuntimeMirrorPath(decoded))
         return refuse(RULE_REDIRECT_SOURCE_RUNTIME_MIRROR);
     if (GENERATED_ROOT_FILES.includes(first.toLowerCase()))

package/src/utm-link.js

@@ -0,0 +1,214 @@
+// Generated from ux/client/src/common/utm-link.ts by scripts/sync-field-validation.mjs. Do not edit.
+/**
+ * UTM parameters on an address, as string work so every byte the creator typed is kept (TR01273). One module
+ * serves the Marketing link builder and the page editor's placement picker, so the two cannot disagree about
+ * what a query string means.
+ *
+ * Parameter names are compared the way the published-site Worker compares them: decoded once and lowercased.
+ */
+/** The parameters the link builder owns; a pasted copy of any is replaced, never duplicated. */
+export const BUILDER_UTM_PARAMETERS = new Set([
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "utm_content",
+]);
+/** A placement rides in `utm_content`. */
+export const PLACEMENT_PARAMETER = "utm_content";
+/**
+ * Outside-link destinations the engagement beacon records: lowercase ASCII host names with a letter-led final
+ * label. A copy of `ENGAGEMENT_HOST_PATTERN` in `generator/src/edge/analytics-engagement.ts`; a test keeps them equal.
+ */
+export const ENGAGEMENT_HOST_PATTERN = /^(?=.{3,100}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/u;
+export function splitAddress(address) {
+    const hash = address.indexOf("#");
+    const beforeFragment = hash < 0 ? address : address.slice(0, hash);
+    const fragment = hash < 0 ? "" : address.slice(hash + 1);
+    const mark = beforeFragment.indexOf("?");
+    return {
+        base: mark < 0 ? beforeFragment : beforeFragment.slice(0, mark),
+        query: mark < 0 ? "" : beforeFragment.slice(mark + 1),
+        fragment,
+    };
+}
+function normalizedName(raw) {
+    try {
+        return decodeURIComponent(raw).toLowerCase();
+    }
+    catch {
+        return raw.toLowerCase();
+    }
+}
+/**
+ * A pair's value as the beacon reads it: `+` as a space, decoded once, then trimmed and lowercased. Empty when it
+ * cannot decode or holds a control character, which the beacon rejects before it trims (so `%0Abio-link` is not
+ * the placement `bio-link`).
+ */
+function normalizedValue(raw) {
+    try {
+        const decoded = decodeURIComponent(raw.replace(/\+/gu, " "));
+        return /[\u0000-\u001f\u007f-\u009f]/u.test(decoded) ? "" : decoded.trim().toLowerCase();
+    }
+    catch {
+        return "";
+    }
+}
+function pairsOf(query) {
+    return query.split("&").filter(pair => pair !== "").map(raw => {
+        const equals = raw.indexOf("=");
+        return {
+            raw,
+            name: normalizedName(equals < 0 ? raw : raw.slice(0, equals)),
+            value: equals < 0 ? "" : normalizedValue(raw.slice(equals + 1)),
+        };
+    });
+}
+/**
+ * Applies a change to an address's query string and returns the address. Pairs the change does not touch are kept
+ * byte for byte and in order; empty pairs are dropped, so a bare `?` or `&&` never leaves a stray separator; no
+ * remaining pair means no `?`; the fragment goes back last.
+ */
+export function rewriteQuery(address, change) {
+    const { base, query, fragment } = splitAddress(address);
+    const kept = pairsOf(query)
+        .filter(pair => !change.remove?.has(pair.name) && !change.removeWhen?.(pair.name, pair.value))
+        .map(pair => pair.raw);
+    const added = (change.append ?? []).map(([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(value)}`);
+    const pairs = [...kept, ...added];
+    return `${base}${pairs.length ? `?${pairs.join("&")}` : ""}${fragment ? `#${fragment}` : ""}`;
+}
+/** Every `utm_content` value in an address, normalized the way the beacon reads one. */
+export function placementValues(address) {
+    return pairsOf(splitAddress(address).query).filter(pair => pair.name === PLACEMENT_PARAMETER).map(pair => pair.value);
+}
+/**
+ * Writes a placement into an address. A key replaces every `utm_content` (the beacon drops a click's label unless
+ * exactly one exists). No key removes a `utm_content` only when it is one of the site's own placement keys, so a
+ * value another tool wrote stays.
+ */
+export function withPlacement(address, key, siteKeys) {
+    return key
+        ? rewriteQuery(address, { remove: new Set([PLACEMENT_PARAMETER]), append: [[PLACEMENT_PARAMETER, key]] })
+        : rewriteQuery(address, {
+            removeWhen: (name, value) => name === PLACEMENT_PARAMETER && siteKeys.has(value),
+        });
+}
+/**
+ * Whether the beacon would record a click on this address as an outbound click from the site: an absolute
+ * `http(s)` address whose host differs from the site's (exact comparison, as the beacon does, so `www.` counts as
+ * different) and fits the host grammar the beacon accepts (dotted, letter-led final label, so IP addresses and
+ * single-label hosts never count). A site with no public address yet has no host to differ from.
+ */
+export function isOutsideLink(address, siteHost) {
+    let url;
+    try {
+        url = new URL(address.trim());
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return false;
+    const host = url.hostname.toLowerCase();
+    return host !== siteHost.trim().toLowerCase() && ENGAGEMENT_HOST_PATTERN.test(host);
+}
+const SITE_AUTHORITY = /^(?:https?:)?\/\/([^/?#]*)([\s\S]*)$/iu;
+/** Lowercased, a leading `www.` dropped. It does not trim: a space inside a pasted address is not part of a host. */
+function bareHost(host) {
+    return host.toLowerCase().replace(/^www\./u, "");
+}
+/**
+ * Reads an address that starts with `http(s)://` or `//` and names the site's own host: no userinfo, no port,
+ * a leading `www.` ignored on either side. Returns what follows the authority, or undefined for anything else.
+ * One rule for the builder's path box and for a link in an email (TR01302), judged on the raw authority so an
+ * explicit default port is refused the same way in both.
+ */
+export function ownSiteAuthority(address, siteHost) {
+    const match = SITE_AUTHORITY.exec(address.trim());
+    if (!match)
+        return undefined;
+    const host = match[1].toLowerCase();
+    if (host === "" || /[@:]/u.test(host) || bareHost(host) !== bareHost(siteHost.trim()))
+        return undefined;
+    return { rest: match[2] };
+}
+/** Whether an address is an absolute `http(s)` link to the site's own host (an email link the toggle applies to). */
+export function isOwnSiteLink(address, siteHost) {
+    return /^https?:\/\//iu.test(address.trim()) && ownSiteAuthority(address, siteHost) !== undefined;
+}
+export const OTHER_SITE_ERROR = "Enter a path on this site.";
+/**
+ * Turns what a creator typed into a path on their own site: starting with `/`, with an existing query and
+ * fragment kept. A pasted address must be on the site's own host (a leading `www.` on either side is ignored,
+ * with no userinfo or port); its host is removed so a pasted address can never point the result elsewhere.
+ * Spaces, control characters and non-ASCII characters are percent-encoded; every other byte is kept.
+ */
+export function normalizeSitePath(input, siteHost) {
+    let rest = input.trim();
+    if (SITE_AUTHORITY.test(rest)) {
+        const own = ownSiteAuthority(rest, siteHost);
+        if (!own)
+            return { ok: false, error: OTHER_SITE_ERROR };
+        rest = own.rest;
+    }
+    else if (/^[a-z][a-z0-9+.-]*:/iu.test(rest)) {
+        return { ok: false, error: OTHER_SITE_ERROR };
+    }
+    else {
+        // An address pasted without its scheme ("example.com/blog") is the site's own host followed by a path.
+        const lead = /^([^/?#]+)([\s\S]*)$/u.exec(rest);
+        if (lead && bareHost(lead[1]) === bareHost(siteHost.trim()))
+            rest = lead[2];
+    }
+    const { base, query, fragment } = splitAddress(rest);
+    const path = base === "" ? "/" : base.startsWith("/") ? base : `/${base}`;
+    // A lone surrogate (a truncated emoji) cannot be percent-encoded and would throw; it becomes U+FFFD first.
+    const wellFormed = (value) => value.replace(/[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/gu, "\ufffd");
+    const encode = (value) => wellFormed(value).replace(/[^\x21-\x7e]/gu, character => encodeURIComponent(character));
+    return {
+        ok: true,
+        path: encode(`${path}${query ? `?${query}` : ""}${fragment ? `#${fragment}` : ""}`),
+    };
+}
+/** The medium and source the builder appends, then the optional campaign and placement. */
+export function trackedAddress(siteHost, path, parts) {
+    const append = [["utm_source", parts.source], ["utm_medium", parts.medium]];
+    if (parts.campaign)
+        append.push(["utm_campaign", parts.campaign]);
+    if (parts.placement)
+        append.push([PLACEMENT_PARAMETER, parts.placement]);
+    return `https://${siteHost.trim().toLowerCase()}${rewriteQuery(path, { remove: BUILDER_UTM_PARAMETERS, append })}`;
+}
+/** What an address carries of a tracking, read the way the Worker reads it. `on` needs exactly one source and one medium that match. */
+export function readEmailTracking(address, tracking) {
+    const pairs = pairsOf(splitAddress(address).query);
+    const values = (name) => pairs.filter(pair => pair.name === name).map(pair => pair.value);
+    const sources = values("utm_source"), mediums = values("utm_medium");
+    return {
+        on: sources.length === 1 && sources[0] === tracking.source && mediums.length === 1
+            && mediums[0] === tracking.medium,
+        campaigns: values("utm_campaign"),
+        placements: values(PLACEMENT_PARAMETER),
+    };
+}
+/** Writes an email tracking into an address, replacing any source, medium, campaign or placement already on it. */
+export function withEmailTracking(address, tracking) {
+    const append = [["utm_source", tracking.source], ["utm_medium", tracking.medium]];
+    if (tracking.campaign)
+        append.push(["utm_campaign", tracking.campaign]);
+    if (tracking.placement)
+        append.push([PLACEMENT_PARAMETER, tracking.placement]);
+    return rewriteQuery(address, { remove: BUILDER_UTM_PARAMETERS, append });
+}
+/**
+ * Takes an email tracking back out: only what the switch writes. The source and medium go when they are the
+ * Newsletter pair, a campaign or placement goes when it is one of the site's own keys, and any other value stays.
+ */
+export function withoutEmailTracking(address, tracking, siteKeys) {
+    return rewriteQuery(address, {
+        removeWhen: (name, value) => (name === "utm_source" && value === tracking.source)
+            || (name === "utm_medium" && value === tracking.medium)
+            || (name === "utm_campaign" && siteKeys.campaigns.has(value))
+            || (name === PLACEMENT_PARAMETER && siteKeys.placements.has(value)),
+    });
+}

package/src/verbs/index.js

@@ -11,8 +11,11 @@ import {
   VERB_FORMS_PULL,
   VERB_FORMS_PUSH,
   VERB_FORMS_VALIDATE,
+  VERB_LINK_BUILD,
   VERB_LOGIN,
   VERB_LOGOUT,
+  VERB_MARKETING_PULL,
+  VERB_MARKETING_PUSH,
   VERB_MEDIA_UPLOAD,
   VERB_NAV_PUSH,
   VERB_PAGES_DELETE,
@@ -49,8 +52,11 @@ import { footerPush } from "./footer-push.js";
 import { formsPull } from "./forms-pull.js";
 import { formsPush } from "./forms-push.js";
 import { formsValidate } from "./forms-validate.js";
+import { linkBuild } from "./link-build.js";
 import { login } from "./login.js";
 import { logout } from "./logout.js";
+import { marketingPull } from "./marketing-pull.js";
+import { marketingPush } from "./marketing-push.js";
 import { mediaUpload } from "./media-upload.js";
 import { navPush } from "./nav-push.js";
 import { pagesDelete } from "./pages-delete.js";
@@ -91,6 +97,9 @@ import { whoami } from "./whoami.js";
  *   quiet,         // --quiet; suppresses progress, never the JSON result
  *   keyName,       // --name; `login` only, undefined everywhere else
  *   planHash,      // --plan; `apply` only: the plan it may run
+ *   archive,       // --archive; `marketing push` only: archive a record the file leaves out
+ *   linkPath, linkSource, linkCampaign, linkPlacement, linkDomain,
+ *                  // --path, --source, --campaign, --placement, --domain; `link build` only
  *   onProgress,    // human progress sink (stderr, or a no-op when quiet)
  *   fetch,         // injectable fetch, for tests
  *   signal,        // optional AbortSignal
@@ -174,6 +183,9 @@ export const VERB_HANDLERS = Object.freeze({
   [VERB_FORMS_PULL]: formsPull,
   [VERB_FORMS_PUSH]: formsPush,
   [VERB_FORMS_VALIDATE]: formsValidate,
+  [VERB_MARKETING_PULL]: marketingPull,
+  [VERB_MARKETING_PUSH]: marketingPush,
+  [VERB_LINK_BUILD]: linkBuild,
   [VERB_MEDIA_UPLOAD]: mediaUpload,
   [VERB_APPROVE]: approve,
   [VERB_DEPLOY]: deploy,