@taprootio/site-authoring 0.24.0 → 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`.
 
@@ -641,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.24.0",
+  "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/capabilities.js

@@ -24,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,29 @@
 {
   "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.",

package/src/cli.js

@@ -33,8 +33,11 @@ import {
   VERB_FORMS_PUSH,
   VERB_FORMS_VALIDATE,
   VERB_HELP,
+  VERB_LINK_BUILD,
   VERB_LOGIN,
   VERB_LOGOUT,
+  VERB_MARKETING_PULL,
+  VERB_MARKETING_PUSH,
   VERB_MEDIA_UPLOAD,
   VERB_NAV_PUSH,
   VERB_PAGES_DELETE,
@@ -88,12 +91,15 @@ import {
   REFERENCE_VERSION,
 } from "./reference-help.js";
 import { FONT_CATEGORIES, getFontCatalogReference } from "./font-catalog.js";
+import { LINK_SOURCES } from "./marketing-contract.js";
 import { assertCliCurrent } from "./session.js";
 import { ApiError } from "./transport.js";
 import { formatThemeResolve } from "./theme-resolve.js";
 import { MAXIMUM_THEME_OPEN_MAP_KEY_SCALARS } from "./theme-validation.js";
 import { VERB_HANDLERS } from "./verbs/index.js";
 
+const LINK_SOURCE_KEYS = LINK_SOURCES.map((source) => source.key);
+
 /**
  * The verbs the local version gate applies to (TR00703).
  *
@@ -591,6 +597,45 @@ const VERBS = Object.freeze([
       + "that the caller may write forms. "
       + "See 'taproot-site help forms'.",
   },
+  {
+    name: VERB_MARKETING_PULL,
+    surface: SURFACE_STANDARD,
+    // Campaigns and placements ride the content capability, which carries the analytics-view permission that
+    // reads them and the publish permission that changes them (TR01301).
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["marketing", "pull"],
+    summary: "Write the site's live campaigns and placements to marketing/ and record what was read.",
+    note: "Needs a pulled workspace ('pull' first). It replaces marketing/campaigns.json and marketing/placements.json "
+      + "with the site's records, each with its read-only state and the day its key was first counted from, and records "
+      + "a baseline that 'marketing push' fences against. Archived records are listed and not written. "
+      + "See 'taproot-site help marketing'.",
+  },
+  {
+    name: VERB_MARKETING_PUSH,
+    surface: SURFACE_STANDARD,
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["marketing", "push"],
+    archiveOption: true,
+    summary: "Create, update and restore the campaigns and placements the marketing files name.",
+    note: "Every file is validated and compared with the site before anything is written. A key is public URL text "
+      + "and never changes, so a new key is a new record; a record the file leaves out is archived only with "
+      + "--archive, and only if this workspace pulled it. A file that names an archived key restores it. Creating or "
+      + "restoring a key queues the silent release that starts counting it; run 'marketing pull' later to see it live. "
+      + "A quota or key refusal is reported as Taproot returns it. See 'taproot-site help marketing'.",
+  },
+  {
+    name: VERB_LINK_BUILD,
+    surface: SURFACE_STANDARD,
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["link", "build"],
+    linkOptions: true,
+    summary: "Print one tracked address for a page, a source, and an optional campaign and placement.",
+    note: "Saves nothing. The medium is set by the source ('reader' is not offered: a published page's own share "
+      + "action sets it). The host is the signed-in site's public address; pass --domain when only a site credential "
+      + "is available. A campaign or placement is checked against marketing/*.json when the workspace has the file, "
+      + "and otherwise against the live site; one that is not live yet is allowed with a note that page views count "
+      + "under the source only until it is. See 'taproot-site help link'.",
+  },
   {
     name: VERB_THEME_PUSH,
     surface: SURFACE_DOCS_PRESENTATION,
@@ -978,6 +1023,17 @@ function verbHelp(verb) {
   const dryRunOption = verb.dryRun
     ? "\n  --dry-run        Read the site and report what a push would change, without writing."
     : "";
+  const archiveOption = verb.archiveOption
+    ? "\n  --archive        Archive a campaign or placement the file leaves out (never done without this)."
+    : "";
+  const linkOptions = verb.linkOptions
+    ? `\n  --path <page>        The page on this site; / or '' for the home page. A query or #fragment you add is kept (required).
+  --source <key>       Where you will post the link: ${LINK_SOURCE_KEYS.join(", ")} (required).
+  --campaign <key>     A campaign key to group links from one push (optional).
+  --placement <key>    A placement key naming the spot the link will appear (optional).
+                       Write --option=<value> for a value that starts with hyphens.
+  --domain <host>      The site's public host; for a site credential with no sign-in to read it from.`
+    : "";
   const planOption = verb.planHash
     ? "\n  --plan <hash>    The planHash 'plan' reported; required."
     : "";
@@ -1060,7 +1116,7 @@ function verbHelp(verb) {
 ${verb.summary}
 ${boundary}
 
-${options}${targetOption}${handoffOption}${reviewPathOption}${sinceOption}${deliveryTargetOption}${metaOptions}${authorOptions}${jsonOption}${resolveOptions}${dryRunOption}${planOption}${nameOption}${note}
+${options}${targetOption}${handoffOption}${reviewPathOption}${sinceOption}${deliveryTargetOption}${metaOptions}${authorOptions}${jsonOption}${resolveOptions}${dryRunOption}${archiveOption}${linkOptions}${planOption}${nameOption}${note}
 `;
 }
 
@@ -1077,6 +1133,39 @@ function matchVerb(arguments_) {
   return matched;
 }
 
+/** The `link build` options and the invocation field each fills. */
+const LINK_OPTION_FIELDS = Object.freeze({
+  "--path": "linkPath",
+  "--source": "linkSource",
+  "--campaign": "linkCampaign",
+  "--placement": "linkPlacement",
+  "--domain": "linkDomain",
+});
+
+/**
+ * The value after a `link build` option. An option-like value is refused so a missing value never swallows the
+ * next flag; only --path may be empty, which names the home page.
+ */
+function parseLinkOption(rest, index, argument) {
+  // `--campaign=--launch` is the one way to pass a value that starts with `--`, which a valid key may (a key may
+  // begin with a hyphen); a separated value that looks like an option is refused so a missing value never swallows
+  // the next flag.
+  const [name, inline] = argument.includes("=") ? [argument.slice(0, argument.indexOf("=")), argument.slice(argument.indexOf("=") + 1)] : [argument, undefined];
+  const value = inline ?? rest[index + 1];
+  const field = name.slice(2);
+  if (typeof value !== "string" || (inline === undefined && value.startsWith("--")) || (value === "" && name !== "--path")) {
+    throw usageError("cli.option_value", `${name} requires a value.`, { field });
+  }
+  if (Buffer.byteLength(value, "utf8") > LIMITS.configPathBytes || hasAsciiControl(value)) {
+    throw usageError(
+      "cli.option_value",
+      `${name} must be at most ${LIMITS.configPathBytes} bytes with no control characters.`,
+      { field },
+    );
+  }
+  return { name, value, consumed: inline === undefined ? 1 : 0 };
+}
+
 function usageError(code, message, options = {}) {
   return new SiteAuthoringError(code, message, { ...options, exitCode: 2 });
 }
@@ -1126,6 +1215,8 @@ function parseReferenceArguments(arguments_) {
       || topic === "fixture"
       || topic === "redirects"
       || topic === "forms"
+      || topic === "marketing"
+      || topic === "link"
       || topic === "walkthrough"
       || topic === "delivery"
       || topic === "import"
@@ -1197,6 +1288,8 @@ function referenceResult(parsed) {
     case "nav":
     case "redirects":
     case "forms":
+    case "marketing":
+    case "link":
     case "media":
     case "preview":
     case "fixture":
@@ -1451,6 +1544,8 @@ function parseArguments(arguments_) {
   let fromSite = false;
   let keyName;
   let planHash;
+  let archive = false;
+  const linkValues = {};
   let metaTitle;
   let metaDescription;
   let metaAuthor;
@@ -1553,6 +1648,21 @@ function parseArguments(arguments_) {
       index += 1;
       continue;
     }
+    if (verb.archiveOption && argument === "--archive") {
+      if (archive) throw usageError("cli.duplicate_option", "--archive may be supplied only once.");
+      archive = true;
+      continue;
+    }
+    if (verb.linkOptions && Object.hasOwn(LINK_OPTION_FIELDS, argument.split("=")[0])) {
+      const { name, value, consumed } = parseLinkOption(rest, index, argument);
+      const field = LINK_OPTION_FIELDS[name];
+      if (linkValues[field] !== undefined) {
+        throw usageError("cli.duplicate_option", `${name} may be supplied only once.`, { field: name.slice(2) });
+      }
+      linkValues[field] = value;
+      index += consumed;
+      continue;
+    }
     if (verb.dryRun && argument === "--dry-run") {
       if (dryRun) throw usageError("cli.duplicate_option", "--dry-run may be supplied only once.");
       dryRun = true;
@@ -1796,6 +1906,8 @@ function parseArguments(arguments_) {
     ...(themeContext === undefined ? {} : { themeContext }),
     ...(fromSite ? { fromSite } : {}),
     ...(planHash === undefined ? {} : { planHash }),
+    ...(archive ? { archive } : {}),
+    ...linkValues,
     ...(metaTitle === undefined ? {} : { metaTitle }),
     ...(metaDescription === undefined ? {} : { metaDescription }),
     ...(metaAuthor === undefined ? {} : { metaAuthor }),
@@ -1893,6 +2005,8 @@ export async function runCli({
       ...(parsed.themeContext === undefined ? {} : { themeContext: parsed.themeContext }),
       ...(parsed.fromSite === undefined ? {} : { fromSite: parsed.fromSite }),
       ...(parsed.planHash === undefined ? {} : { planHash: parsed.planHash }),
+      ...(parsed.archive ? { archive: true } : {}),
+      ...Object.fromEntries(Object.values(LINK_OPTION_FIELDS).filter((field) => parsed[field] !== undefined).map((field) => [field, parsed[field]])),
       // Only when given, like the other optional fields, so each verb keeps its default (TR00925).
       ...(parsed.deliveryUrl === undefined ? {} : { deliveryUrl: parsed.deliveryUrl }),
       ...(parsed.propagationWaitSeconds === undefined ? {} : { propagationWaitSeconds: parsed.propagationWaitSeconds }),

package/src/constants.js

@@ -94,6 +94,9 @@ export const VERB_REDIRECTS_PUSH = "redirects push";
 export const VERB_FORMS_PULL = "forms pull";
 export const VERB_FORMS_PUSH = "forms push";
 export const VERB_FORMS_VALIDATE = "forms validate";
+export const VERB_MARKETING_PULL = "marketing pull";
+export const VERB_MARKETING_PUSH = "marketing push";
+export const VERB_LINK_BUILD = "link build";
 export const VERB_THEME_PUSH = "theme push";
 export const VERB_THEME_RESOLVE = "theme resolve";
 export const VERB_FOOTER_PUSH = "footer push";

package/src/marketing-api.js

@@ -0,0 +1,179 @@
+import { sitePath } from "./api.js";
+import { REFUSAL_UNCLASSIFIED } from "./constants.js";
+import { isCanonicalUuid, SiteAuthoringError } from "./errors.js";
+import {
+  isCalendarDate,
+  isMarketingKey,
+  MARKETING_KINDS,
+  MARKETING_STATE_ARCHIVED,
+  marketingStateFromWire,
+} from "./marketing-contract.js";
+import { ApiError } from "./transport.js";
+
+/**
+ * The owner-side campaign and placement routes `marketing pull` and `marketing push` call (TR01301).
+ *
+ * The wire spells a state as a proto enum name and a day as midnight UTC; the workspace file uses a lowercase
+ * word and a plain day. The translation lives here so neither side learns the other's vocabulary. A placement
+ * is stored as a link label, so its routes and wire names say so.
+ */
+
+// A site holds at most a few hundred records of a kind, archived ones included; this bounds the reply size.
+const MARKETING_RESPONSE_BYTES = 2 * 1024 * 1024;
+// gRPC FailedPrecondition, which the transcoder carries as the `code` of the error body.
+const GRPC_FAILED_PRECONDITION = 9;
+const MIDNIGHT_UTC = /^(\d{4}-\d{2}-\d{2})T00:00:00(?:\.0+)?Z$/u;
+
+function contract(message, field) {
+  return new SiteAuthoringError("api.marketing_contract", message, { field });
+}
+
+/** A wire timestamp that is midnight UTC as the day it names, or undefined when it is absent. */
+function dayFromWire(value, field) {
+  if (value === undefined || value === null || value === "") return undefined;
+  const match = typeof value === "string" ? MIDNIGHT_UTC.exec(value) : null;
+  if (match === null || !isCalendarDate(match[1])) {
+    throw contract("Taproot returned a day this workspace cannot store.", field);
+  }
+  return match[1];
+}
+
+/** The UTC day an instant falls on: when a key first went live, page views under it are counted from that day. */
+function dayOfInstant(value, field) {
+  if (value === undefined || value === null || value === "") return undefined;
+  const day = typeof value === "string" ? /^(\d{4}-\d{2}-\d{2})T/u.exec(value)?.[1] : undefined;
+  if (day === undefined || !isCalendarDate(day)) throw contract("Taproot returned a time this workspace cannot store.", field);
+  return day;
+}
+
+function dayToWire(day) {
+  return day === undefined ? undefined : `${day}T00:00:00Z`;
+}
+
+function normalizeRecord(kind, value) {
+  const { noun } = MARKETING_KINDS[kind];
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw contract(`Taproot returned a ${noun} that is not an object.`, noun);
+  }
+  if (!isCanonicalUuid(value.id) || !isMarketingKey(value.key)) {
+    throw contract(`Taproot returned a ${noun} with no usable id or a key this workspace cannot store.`, noun);
+  }
+  const state = marketingStateFromWire(kind, value.state);
+  if (state === undefined) throw contract(`Taproot returned a ${noun} with a state this CLI does not know.`, "state");
+  const record = {
+    id: value.id,
+    key: value.key,
+    name: typeof value.name === "string" ? value.name : "",
+    state,
+    archived: state === MARKETING_STATE_ARCHIVED || (value.archivedAt !== undefined && value.archivedAt !== null),
+  };
+  const countedFrom = dayOfInstant(value.releasedAt, "releasedAt");
+  if (countedFrom !== undefined) record.counted_from = countedFrom;
+  if (MARKETING_KINDS[kind].withLabels) {
+    if (typeof value.note === "string" && value.note !== "") record.note = value.note;
+    const startsOn = dayFromWire(value.startsOn, "startsOn");
+    const endsOn = dayFromWire(value.endsOn, "endsOn");
+    if (startsOn !== undefined) record.starts_on = startsOn;
+    if (endsOn !== undefined) record.ends_on = endsOn;
+  }
+  return record;
+}
+
+/** The fields an author decides, as the body of a create or an update. */
+function writableBody(kind, record) {
+  return {
+    name: record.name,
+    ...(MARKETING_KINDS[kind].withLabels
+      ? { note: record.note ?? "", startsOn: dayToWire(record.starts_on), endsOn: dayToWire(record.ends_on) }
+      : {}),
+  };
+}
+
+/** Every record of this kind on the site, archived ones included, and whether the caller may change them. */
+export async function listMarketingRecords(client, siteId, kind) {
+  const { route, wireList, noun } = MARKETING_KINDS[kind];
+  let response;
+  try {
+    response = await client.request(sitePath(siteId, route), { maximumResponseBytes: MARKETING_RESPONSE_BYTES });
+  } catch (error) {
+    // The site refuses with a precondition when it is not a Standard site or its licence leaves analytics out. The
+    // transport keeps only its own words for a refusal that names no field, so this says what both cases mean.
+    if (error instanceof ApiError && error.grpcCode === GRPC_FAILED_PRECONDITION && error.fields.length === 0) {
+      throw new SiteAuthoringError(
+        "marketing.unavailable",
+        `This site cannot list ${noun}s: they need a Standard site on a licence that includes analytics.`,
+        { status: error.status },
+      );
+    }
+    throw error;
+  }
+  const list = response?.[wireList];
+  if (list !== undefined && !Array.isArray(list)) {
+    throw contract(`Taproot returned a ${MARKETING_KINDS[kind].noun} list that is not an array.`, wireList);
+  }
+  return {
+    records: (list ?? []).map((value) => normalizeRecord(kind, value)),
+    canManage: response?.canManage === true,
+    maxActive: Number.isSafeInteger(response?.maxActive) ? response.maxActive : undefined,
+  };
+}
+
+/**
+ * Makes a record. `id` is chosen by the caller, which the site uses to return the record a repeated request made.
+ * The CLI sends a create once; a lost answer is settled by the next push finding the record already as the file
+ * asks.
+ */
+export async function createMarketingRecord(client, siteId, kind, id, record) {
+  const { route, wireId } = MARKETING_KINDS[kind];
+  return normalizeRecord(
+    kind,
+    await client.request(sitePath(siteId, route), {
+      method: "POST",
+      body: { [wireId]: id, key: record.key, ...writableBody(kind, record) },
+      maximumResponseBytes: MARKETING_RESPONSE_BYTES,
+    }),
+  );
+}
+
+/** Changes a record's private labels. The key never changes. */
+export async function updateMarketingRecord(client, siteId, kind, id, record) {
+  const { route } = MARKETING_KINDS[kind];
+  return normalizeRecord(
+    kind,
+    await client.request(sitePath(siteId, `${route}/${encodeURIComponent(id)}`), {
+      method: "PUT",
+      body: writableBody(kind, record),
+      maximumResponseBytes: MARKETING_RESPONSE_BYTES,
+    }),
+  );
+}
+
+/** Archives or restores a record. Both are idempotent on the site. */
+export async function setMarketingRecordArchived(client, siteId, kind, id, archived) {
+  const { route } = MARKETING_KINDS[kind];
+  return normalizeRecord(
+    kind,
+    await client.request(sitePath(siteId, `${route}/${encodeURIComponent(id)}/${archived ? "archive" : "restore"}`), {
+      method: "POST",
+      body: {},
+      maximumResponseBytes: MARKETING_RESPONSE_BYTES,
+    }),
+  );
+}
+
+/**
+ * Carries the site's own words for a refused record. A key outside the grammar, a key an archived record still
+ * holds, and a quota all arrive as a violated field with a description that names the remedy ("Archive one to
+ * make room"); the default message would say only which field. A refusal that means something else (a missing
+ * capability, a paused platform, a rejected credential) keeps its own classification.
+ */
+export function withSiteWording(error, kind, key) {
+  if (!(error instanceof ApiError) || error.refusalKind() !== REFUSAL_UNCLASSIFIED) return error;
+  const [, description] = [...error.violationDescriptions][0] ?? [];
+  if (description === undefined) return error;
+  const { file } = MARKETING_KINDS[kind];
+  return new SiteAuthoringError("marketing.refused", `${file}: '${key}': ${description}`, {
+    field: `${file}:${key}`,
+    status: error.status,
+  });
+}