@taprootio/site-authoring 0.14.1 → 0.16.0

package/README.md

@@ -119,8 +119,20 @@ dark logo on the rendered dark header at desktop and compact/mobile widths;
 transparent canvas pixels do not count as contrast. Supply separate
 scheme-specific assets when one visible mark cannot satisfy both surfaces.
 
+`taproot-site validate` checks the pulled workspace `taproot-site.json` names,
+with no credential, no network, and no write: every page source (metadata,
+Markdown conversion, media references, content vocabulary, section contexts),
+page paths and templates against the pages the pull recorded, navigation,
+redirects, forms, and the complete theme, appearance, header, brand, and
+footer. Navigation to a generated page (a section, tag or place page) resolves
+against the pages the pull recorded. It reports every problem at once in
+`error.problems`, each with its file, code, and field, instead of one per run.
+Warnings never refuse: `linkWarnings` names a link whose address is only
+`http(s)://` plus its own text (`content.link_autolinked`, left by older editor
+autolinking), and `pages push` reports the same for the pages it sends.
+
 `taproot-site validate <fixture-directory>` checks a complete offline fixture
-with no credential, no network, and no write: a directory laid out like a
+the same way: a directory laid out like a
 pulled workspace — `pages/`, `nav.json`, `redirects.json`, and the four
 `settings/` documents —
 whose `manifest.fixture.json` binds deterministic page, resource, image, and
@@ -143,9 +155,10 @@ taproot-site validate "$(npm root --global)/@taprootio/site-authoring/examples/r
 The fixture is a fictional wellness studio — `example.test` hostnames, a
 reserved `555-01xx` telephone number, an invented street and town — with two
 free-form pages and one each of the article, recipe, album and place-review
-templates, a three-item navigation tree, and all four settings documents. Nothing in it describes a real business. Copy the directory
-somewhere writable before you edit it; `validate` never writes to the fixture
-it reads.
+templates, a three-item navigation tree, all four settings documents, and a
+`.taproot-site-media.json` that maps its one media path to a fixture image id.
+Nothing in it describes a real business. Copy the directory somewhere writable
+before you edit it; `validate` never writes to the fixture it reads.
 
 ## Authorize
 
@@ -285,14 +298,15 @@ each step names the reference it relies on.
 3. **Edit both schemes and the appearance.** `help theme` lists every field,
    the role slots, how anchor references resolve and what wins when a pin and
    a role disagree; `help appearance` covers the default scheme, header, logos
-   and favicon.
+   and favicon; `help fonts` lists the font families, by category, that the
+   font fields can name.
 4. **Prepare media locally.** Raster files only (PNG, JPEG, GIF, WebP),
    relative to the workspace root; make the transparent logo, its `@2x` copy,
    a dark-scheme logo when needed and a square favicon with your own tools,
    upload them with `media upload`, then assign `lightLogoId`, `darkLogoId`
    and `brand.faviconId` from the returned ids. There is no recolor, crop or
    SVG upload command.
-5. **Validate, preview, then push.** `validate` runs offline;
+5. **Validate, preview, then push.** `validate` checks the whole workspace offline;
    `theme push --dry-run` reads the site and lists the JSON paths at which
    each settings file differs from it, and whether the baseline `pull`
    recorded is still current; `theme push` saves both themes, the appearance
@@ -350,13 +364,127 @@ 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.
 
+A `.pm.json` page's title, path, description and author live in the workspace
+manifest rather than the file. `pages meta set <path> --title <text>
+--description <text>` changes the title or description there (a Markdown page
+keeps them in its front matter; `--author` is described under *Page authors*); `pull` keeps that edit until `pages push`
+sends it, and a site edit to the same page is a `pages.pull_conflict`. A
+description over 160 characters is a warning (`descriptionWarnings`), because
+search results cut it off; over 1000 is refused with
+`pages.description_too_long`, by the CLI and by Taproot.
+
+### Page authors
+
+Pages are authorless by default: a page you create with the CLI publishes with
+no byline unless you name an author, and `pages push` lists the pages it created
+that way in `pages.authorless`, with how to credit them. An author is one of two
+kinds of person, named by one string:
+
+- a **site author without a Taproot account** — one of an imported blog's
+  authors, say — named by handle (`jane-doe`: lowercase letters, digits and
+  single hyphens, at most 64 characters, fixed when the author is created). A
+  site author's name appears on the byline and in the page's structured data;
+  there is no profile link or follow button, because there is no account;
+- a **site member who can create pages**, named by email address.
+
+`authors list` prints both and rewrites `authors.json` (`pull` writes it too).
+`authors add jane-doe --name "Jane Doe" [--email jane@example.com]` creates a
+site author; `--email` is kept private (never published, never listed) so the
+person can be linked to a Taproot account later. Adding a handle the site
+already has under the same name succeeds and reports `existing: true`, so a
+script can repeat itself; a different name for a taken handle is refused
+(`authors.handle_taken`), naming the one the site has. `authors.json` holds the
+members' email addresses, so keep it out of a public repository.
+
+A page names its author with `author: jane-doe` in its front matter (any
+template), or, for a `.pm.json` page, `pages meta set <path> --author jane-doe`.
+Only the CLI assigns authors, and only to a page that has none; people editing
+in the app are never asked to name one. `authors.json` is as old as the last
+`pull` or `authors list`, so a name missing from it is not proof the person does
+not exist. `validate` and `pages meta set` run offline: they refuse text that
+is neither a handle nor an address (`pages.author_invalid`) and otherwise only
+warn (`pages.author_unverified`, in `authorWarnings`) about a name `authors.json`
+lacks. `pages push` and `plan` settle it online: on a miss they read the site's
+current list once (`pages push` rewrites `authors.json` with it) and refuse
+(`pages.author_unknown`) only a name the site really lacks. A member who cannot
+create pages is `pages.author_unknown` as well, with the same wording.
+
+The CLI only fills a page that has no author: a page that already has a
+different one is refused (`pages.author_conflict`), by the CLI from what the
+last pull recorded and by Taproot, and naming the author a page already has
+changes nothing. The refusal says how to settle it: for a `.pm.json` page,
+`pages meta set <path> --author <the site's author>` matches the site, and
+`pages meta set <path> --author ""` drops an author that was never sent (it
+never asks the site to remove one, and is refused once the site holds an
+author); for a Markdown page, fix the `author:` line. `pull` keeps a pending
+author the site now disagrees with and says so. The author is recorded on the
+page's manifest entry (`author`, and `baseline.author` for what the site
+held), so a re-push never resends it. The site names a page's author in
+listings only while that person can still be named: a former member's page, or
+a member who can no longer create pages, reports none, and a push that names
+someone else on it is refused as a conflict.
+
+Pages Taproot generates from the site's content — a tag, the tags index, a
+published year or month, a place archive, a folder — are update-only sources.
+`pull` writes each as `pages/<name>.pm.json` with `"template": "generated"`:
+`data` holds what the page is (`kind`, `tagId`, `year`, `month`, `countryCode`,
+`regionCode`, `citySlug`, `categorySlug`, which you leave as pulled) and the four
+things that are yours to author: `customTitle`, `breadcrumbTitle`,
+`customDescription` and `introductionBody`. An empty string means "use the
+generated default"; the description then falls back to the introduction's first
+paragraph, else the system default. The manifest keeps the title and description
+the site reports, for reference. `pages meta set <path> --title/--description`
+edits `customTitle` and `customDescription` in the source (an empty value
+clears it), and `pages push` sends the page back as an unapproved draft. The
+title and description the site stores are derived from `customTitle`,
+`customDescription` and `introductionBody`, so what a push sends for them is
+ignored. A push refuses to create a generated page (`pages.generated_create`),
+move one (`pages.generated_move`) or change its kind or identity
+(`pages.generated_identity`, also when the manifest has no record of what the
+file was pulled as: run `pull`); there is no Markdown form
+(`pages.generated_markdown`). A generated page you did not edit never blocks a
+push of the whole workspace, even when Taproot moved it since the pull (a tag was
+renamed). If the site no longer has the page (its tag, month or folder is gone),
+a whole-workspace push reports the file under `pages.staleGeneratedSources` and
+sends nothing for it, and `pull` says so; delete the file. Naming that path in
+`pages push <page-path>` is refused with `pages.generated_create`. A description over 160 characters is warned about,
+since search results cut it off, and one over 1000 is refused.
+
 `pages push [page-path...]` validates and sends the selected pages, or every
-workspace page when none is named; the homepage is addressed as `/`. It fails
+workspace page when none is named; the homepage is addressed as `/`. Every
+selected page is checked before anything is sent, and a refusal lists every
+problem in `error.problems`. `pages push --dry-run` runs the same checks
+against the live site, lists which pages would be created, updated, or left
+unchanged, and sends nothing. It fails
 closed with `pages.push_conflict` when a page's stored-state revision has
 moved since this workspace last reconciled with it, naming both revisions;
 `pull` first, or push after a refused pull has shown you the site's version.
-`media upload [path...]` uploads raster files and records component-ready
-delivery fields; MP4, MOV, and WebM files are uploaded as videos. Taproot does not
+
+`places search <name and city>` asks Google Places for the place a review
+names and reports predictions with a session token; `places select
+<googlePlaceId> <sessionToken>` records the match as a Taproot place and
+reports the `placeId` a place review's front matter needs. An article or an
+album can name its place the same way with `place:`.
+
+`plan` checks the whole workspace against the live site — pages, the media
+they reference and the images the settings name, the footer and the pages it
+links, the theme, navigation — and orders what is left
+to send: media upload, pages push, footer push (theme push refuses unsaved
+footer content), theme push, nav push, each marked ready, blocked, or nothing
+to do. It writes nothing and reports a `planHash`. `apply --plan <planHash>`
+plans again, refuses with `apply.plan_stale` if the workspace or the site
+moved, and otherwise runs the steps through the ordinary push verbs. While
+they run, a workspace file read differently from the plan (or not read by it)
+stops the step before it writes, naming the file, and so does a page revision
+or the site's navigation that moved. Steps are
+not atomic together: a failure reports in `error.completedWrites` which steps
+completed, which failed, and which did not run, and the next `plan` shows
+finished steps as nothing to do. Redirects, forms, approval, and deployment
+stay separate commands.
+`media upload [path...]` uploads raster files and records each one in
+`.taproot-site-media.json`; Markdown then names an image by its path (such as
+`media/photo.webp`) everywhere an image goes, from body images to component and
+section image fields. MP4, MOV, and WebM files are uploaded as videos. Taproot does not
 encode: the command reads each file with mediabunny, rewrites an H.264 and AAC
 file that is not an MP4 with its index first as one (copying the tracks, never
 re-encoding), declares its codecs, and prints the server's one-line refusal as
@@ -372,7 +500,9 @@ settings, and the closed footer document. `pull` writes each scheme's
 complete effective theme — the stored theme resolved over the same defaults
 every consumer renders — so a fresh workspace validates as pulled, and it
 keeps only authored `semanticMappings` pins (listed in
-`explicitMappingTokens`) because a pinned token shadows its role.
+`explicitMappingTokens` at the root; a pin inside a context needs no marker)
+because a pinned token shadows its role. Contrast and status-color warnings
+name the nearest passing value the CLI found and checked.
 `theme push` — and `theme push --dry-run`, which writes nothing — also runs
 Espalier's fit report over the root and every context in both schemes and
 prints each lint as a warning, such as a filled action that renders the
@@ -505,6 +635,37 @@ Other C0/C1 controls, U+2028/U+2029, U+FEFF, and literal `<br>` tags are rejecte
 with the exact fact field path. A label is optional and stays outside the value's link. See
 `taproot-site help page free-form` and `taproot-site help component cta`.
 
+### Link rel in 0.15.0
+
+A link publishes followed unless its author chooses otherwise. A link mark's
+`rel` takes space-separated link types (`nofollow`, `sponsored`, `ugc`, `me`,
+and the other standard types except `opener`), on any link; `target: "_blank"`
+opens a new tab with `noopener noreferrer` added. In Markdown, write
+`[Shop](https://shop.example){rel="sponsored nofollow" target="_blank"}`
+(either attribute alone works). Other tokens and
+targets are refused (`content.link_rel`, `content.link_target`). The editor's
+old default, `noopener noreferrer nofollow`, reads as no choice. See
+`taproot-site help page free-form`.
+
+### Authoring feedback in 0.16.0
+
+- `pages meta set <path> --title/--description/--author` edits a `.pm.json`
+  page's title, description or author; `pull` keeps the edit until `pages push`
+  sends it. Descriptions are warned about over 160 characters and refused over
+  1000, here and by Taproot.
+- Generated pages (tags, archives, places, folders) pull as update-only sources
+  whose custom title, breadcrumb, description and introduction you can edit.
+- Pages are authorless by default. `authors list`, `authors add` and
+  `authors.json` name a member who can create pages or a site author without a
+  Taproot account; `author:` front matter or `pages meta set --author` credits
+  one on a page that has none, and an author is never replaced from the CLI.
+- `redirects check` and `deploy --staging` report `routeCheck`, `redirects` and
+  `stagingPreview` at the top level; result paths spell the home page `/`;
+  `approve` skips a page with nothing to approve instead of failing the batch.
+- `validate` checks a real pulled workspace offline (`validate --init` keeps the
+  generated pages navigation links to), and `validate` and `pages push` warn on
+  links that look made by autolinking (`content.link_autolinked`).
+
 ### Staging verification and deployment evidence
 
 `deploy --staging` selects the same changed pages, settings groups and navigation
@@ -527,13 +688,15 @@ only error class and known page/node/attribute labels, never renderer messages.
 Staging deploys check the current redirect map through the real staging edge.
 Run `taproot-site redirects check` to repeat once the deployment has completed; a redirect is a file inside the release, so it is live exactly when its release is served.
 The Node CLI consumes a separate handoff, retains its short staging cookie in
-memory, and requests each map path without following redirects. Results report
-path, HTTP status and Location; `verified` requires all entries to match and the
+memory, and requests each map path without following redirects. Both
+`redirects check` and `deploy --staging` report `routeCheck` and `redirects` at
+the top level of their result: `redirects.items` lists each path, HTTP status
+and Location, and `redirects.verified` requires all entries to match and the
 map revision to remain unchanged. A mismatch is evidence to investigate, not a
 failed deployment. Checks describe the current map, not a historical release.
 Requests have a 90-second deadline with eight concurrent requests; large JSON
-lists have explicit truncation, prioritizing failures. Human output reports each
-entry. A gate/transport failure never counts as verified.
+lists have explicit truncation, prioritizing failures. Progress output reports
+each entry. A gate/transport failure never counts as verified.
 
 `stagingPreview.url` is a fresh single-use two-minute handoff minted **after**
 checks. Opening it consumes it and establishes a five-minute staging cookie.
@@ -588,8 +751,10 @@ The destination must be new, outside the source workspace, and its parent must e
 to select another source configuration. Initialization needs no credential or
 network. It exports editable pages of every template as workspace documents with navigation,
 redirects, settings, and version-7 appearance/footer metadata, validates the
-result, and leaves the source unchanged. Excluded metadata-only pages are
-counted; unresolved references to them fail validation.
+result, and leaves the source unchanged. A metadata-only page that navigation,
+the footer or a page links to, such as a generated section page, is kept as a
+metadata-only entry (`initialized.linkedPages`); other metadata-only pages are
+left out (`initialized.skippedPages`).
 
 Exported UUIDs and HTTP(S) origins are deterministic fixture values under
 `example.test`; URL credentials, query strings and fragments are removed.

package/examples/riverbend-wellness/.taproot-site-media.json

@@ -0,0 +1,23 @@
+{
+  "mediaManifestVersion": 2,
+  "siteId": "a0000000-0000-4000-8000-000000000001",
+  "media": {
+    "media/riverbend-studio.webp": {
+      "imageId": "a0000000-0000-4000-8000-0000000000a2",
+      "src": "https://static.example.test/site/img/riverbend-studio-1280.webp",
+      "urls": [
+        {
+          "minWidth": 640,
+          "url": "https://static.example.test/site/img/riverbend-studio-640.webp"
+        },
+        {
+          "minWidth": 1280,
+          "url": "https://static.example.test/site/img/riverbend-studio-1280.webp"
+        }
+      ],
+      "width": 1600,
+      "height": 1067,
+      "alt": "An example photograph placeholder for the fixture studio"
+    }
+  }
+}

package/examples/riverbend-wellness/pages/index.md

@@ -19,23 +19,7 @@ description: An example home page for the offline authoring fixture.
     "url": "https://schedule.example.test/riverbend"
   },
   "alignment": "start",
-  "media": {
-    "imageId": "a0000000-0000-4000-8000-0000000000a2",
-    "src": "https://static.example.test/site/img/riverbend-studio-1280.webp",
-    "urls": [
-      {
-        "minWidth": 640,
-        "url": "https://static.example.test/site/img/riverbend-studio-640.webp"
-      },
-      {
-        "minWidth": 1280,
-        "url": "https://static.example.test/site/img/riverbend-studio-1280.webp"
-      }
-    ],
-    "width": 1600,
-    "height": 1067,
-    "alt": "An example photograph placeholder for the fixture studio"
-  },
+  "media": "media/riverbend-studio.webp",
   "mediaArrangement": "split",
   "mediaPosition": "after",
   "mediaWidth": "equal"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.14.1",
+  "version": "0.16.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": "5.0.0",
+    "@taprootio/espalier": "6.2.0",
     "mediabunny": "1.61.1"
   },
   "scripts": {

package/src/api.js

@@ -23,6 +23,7 @@ import {
 // would turn a successful mint into an orphaned key.
 import { KEY_PREFIX } from "./credentials.js";
 import { isCanonicalUuid, normalizePreviewDiagnostic, sanitizeDiagnostic, SiteAuthoringError } from "./errors.js";
+import { normalizeAuthorListing, parseAuthorReference } from "./authors-contract.js";
 import { docsPublicationModeFromWire, siteKindFromWire, surfaceFromWire } from "./surface.js";
 import {
   DEFAULT_REDIRECT_STATUS,
@@ -178,7 +179,8 @@ const AUTHORING_PREVIEW_FIELD_ERRORS = Object.freeze({
   ],
   [AUTHORING_PREVIEW_FIELDS.staging]: [
     "preview.staging_unavailable",
-    "The site does not have an available staging hostname for authoring previews.",
+    "The site's staging address is not ready for previews. If the site has never deployed to staging, run "
+      + "'deploy --staging' once; otherwise check its staging host with 'taproot-site status'.",
   ],
   [AUTHORING_PREVIEW_FIELDS.expiry]: ["preview.expired", "The authoring preview has expired."],
   [AUTHORING_PREVIEW_FIELDS.readiness]: ["preview.not_ready", "The authoring preview is not ready for a handoff."],
@@ -233,6 +235,11 @@ function requireIdentifier(value, code, field) {
   return value;
 }
 
+/** A Google place id as Taproot stores it: the server's characters and its 256-character column. */
+export function isGooglePlaceId(value) {
+  return typeof value === "string" && value.length <= 256 && /^[A-Za-z0-9_-]+$/u.test(value);
+}
+
 function requireCanonicalUuid(value, code, field) {
   if (!isCanonicalUuid(value)) {
     throw new SiteAuthoringError(code, `Taproot returned an invalid ${field}.`, { field });
@@ -493,6 +500,14 @@ export function normalizePageSummary(value) {
     // The page's calendar date, empty when it has none. It is not part of
     // `bodyRevision`, so a typed page's push guard compares it separately.
     displayDate: typeof summary.displayDate === "string" ? summary.displayDate : "",
+    // The name the page's author goes by in a write: a site author's handle or
+    // a member's email address, folded. Empty for a page with no author, for a
+    // former member's page, and against a Taproot that predates authors
+    // (TR01196). Never the author's display name, which is not a reference.
+    authorRef: typeof summary.authorRef === "string" ? parseAuthorReference(summary.authorRef)?.value ?? "" : "",
+    // Whether the page credits anyone at all, which an empty authorRef cannot
+    // say: it is also empty for an author this credential may not name.
+    hasAuthor: typeof summary.authorDisplayName === "string" && summary.authorDisplayName.trim() !== "",
   };
 }
 
@@ -539,6 +554,62 @@ export async function updatePage(client, pageId, body) {
   );
 }
 
+/**
+ * Gives the site's two author refusals the stable codes the CLI documents
+ * (TR01196). The site answers an unknown name and one that cannot be named with
+ * the same field and wording on purpose; this keeps them one code too.
+ */
+export function translateAuthorRefusal(error, file) {
+  if (!(error instanceof ApiError)) return error;
+  for (const [field, code, fallback] of [
+    ["AuthorUnknown", "pages.author_unknown", "No site author or member who can create pages has that name."],
+    ["AuthorConflict", "pages.author_conflict", "The page already has a different author, which is never replaced."],
+  ]) {
+    if (error.hasField(field)) {
+      const detail = sanitizeDiagnostic(error.descriptionFor(field) ?? fallback, fallback);
+      // The workspace only learns who the site credits from a pull, and a
+      // conflict means someone gave the page an author after the last one.
+      const hint = field === "AuthorConflict"
+        ? " Run 'taproot-site pull' to learn who the site credits, then match it with 'pages meta set <path> --author "
+          + "<author>' (a .pm.json page) or the author: front matter line (Markdown)."
+        : "";
+      return new SiteAuthoringError(code, `'${file}': ${detail}${hint}`, { field: file });
+    }
+  }
+  return error;
+}
+
+/**
+ * Reads who a page can be credited to: the site's authors without an account
+ * and the members who can create pages (TR01196).
+ */
+export async function listSiteAuthors(client, siteId) {
+  return normalizeAuthorListing(
+    requireObject(await client.request(sitePath(siteId, "authors")), "api.authors_contract", "site authors"),
+  );
+}
+
+/** Creates a site author. The site folds the handle and the address. */
+export async function createSiteAuthor(client, siteId, { handle, displayName, email }) {
+  const created = requireObject(
+    await client.request(sitePath(siteId, "authors"), {
+      method: "POST",
+      body: { handle, displayName, ...(email === undefined ? {} : { email }) },
+    }),
+    "api.authors_contract",
+    "site author",
+  );
+  const listing = normalizeAuthorListing({ authors: [created], members: [] });
+  if (listing.authors.length !== 1) {
+    throw new SiteAuthoringError(
+      "api.authors_contract",
+      "Taproot returned a site author this CLI could not read.",
+      { field: "handle" },
+    );
+  }
+  return listing.authors[0];
+}
+
 export async function publishDrafts(client, pageIds) {
   const response = requireObject(
     await client.request("v1/pages/publish_drafts", { method: "POST", body: { pageIds } }),
@@ -874,6 +945,57 @@ export async function listVideos(client, siteId, requestOptions = {}) {
   return { videos, truncated: true };
 }
 
+/**
+ * Google Places autocomplete for a place review (TR01003). A key searches for
+ * the site it was issued for; every search and the select that follows share
+ * `sessionToken`, which is what groups them into one billed session.
+ */
+export async function searchPlaces(client, siteId, { text: searchText, sessionToken }) {
+  const search = query([["query", searchText], ["siteId", siteId], ["sessionToken", sessionToken]]);
+  const response = requireObject(
+    await client.request(`v1/places/search${search}`),
+    "api.place_contract",
+    "place search",
+  );
+  return (Array.isArray(response.predictions) ? response.predictions : []).map((value) => {
+    const prediction = requireObject(value, "api.place_contract", "place prediction");
+    return {
+      googlePlaceId: requireGooglePlaceId(prediction.googlePlaceId),
+      name: text(prediction.name),
+      formattedAddress: text(prediction.formattedAddress),
+    };
+  });
+}
+
+function requireGooglePlaceId(value) {
+  if (!isGooglePlaceId(value)) {
+    throw new SiteAuthoringError("api.place_contract", "Taproot returned an invalid googlePlaceId.", { field: "googlePlaceId" });
+  }
+  return value;
+}
+
+/** Records a prediction as a Taproot place, ending the search's billed session, and returns its id. */
+export async function selectPlace(client, siteId, { googlePlaceId, sessionToken }) {
+  const place = requireObject(
+    await client.request("v1/places/select", {
+      method: "POST",
+      body: { siteId, googlePlaceId, sessionToken },
+    }),
+    "api.place_contract",
+    "selected place",
+  );
+  return {
+    // Any UUID version: the server mints place ids.
+    placeId: requireIdentifier(place.id, "api.place_contract", "id"),
+    name: text(place.name),
+    category: text(place.category),
+    address: text(place.address),
+    city: text(place.city),
+    region: text(place.region),
+    country: text(place.country),
+  };
+}
+
 /**
  * Processing is observed through `ListSiteImages`; `GetImageById` is
  * session-only under TR00602's read list, so a key-authorized client watches