@taprootio/site-authoring 0.16.0 → 0.19.0

package/src/forms-workspace.js

@@ -1,12 +1,12 @@
 import { SiteAuthoringError } from "./errors.js";
 import {
-  FORM_DEFAULT_SINK,
+  FORM_DEFAULT_NOTIFY_OWNER,
   FORM_FILE_EXTENSION,
-  FORM_RETENTION_DAYS,
   FORM_LIMITS,
   FORMS_DIRECTORY,
   formFileName,
   isFormKey,
+  projectFormSettings,
   validateFormDocument,
 } from "./forms-contract.js";
 import { readWorkspaceJson, walkWorkspaceFiles } from "./workspace.js";
@@ -18,8 +18,9 @@ import { readWorkspaceJson, walkWorkspaceFiles } from "./workspace.js";
  * typo never reads as a successful empty push. With none, every file under
  * `forms/` is read. A file whose name is not a form key is refused rather than
  * skipped: skipping it would report success with one form left behind.
+ * Newsletter admission is strict by default; `forms push` defers it for baseline comparison.
  */
-export async function readWorkspaceForms(workspaceDir, keys) {
+export async function readWorkspaceForms(workspaceDir, keys, validationOptions = {}) {
   const files = await walkWorkspaceFiles(workspaceDir, FORMS_DIRECTORY, [FORM_FILE_EXTENSION]);
   const known = new Map();
   for (const file of files) {
@@ -46,7 +47,7 @@ export async function readWorkspaceForms(workspaceDir, keys) {
       );
     }
     const document_ = await readWorkspaceJson(workspaceDir, file, FORM_LIMITS.fileBytes);
-    forms.push({ key, file, document: validateFormDocument(document_, key) });
+    forms.push({ key, file, document: validateFormDocument(document_, key, validationOptions) });
   }
   return forms;
 }
@@ -54,10 +55,9 @@ export async function readWorkspaceForms(workspaceDir, keys) {
 /**
  * The forms baseline in the pull manifest (TR01061).
  *
- * The site has no compare-and-set for a form, so `forms push` fences itself:
- * it writes a form only when the site's current version is the one the last
- * pull or push recorded here. A form edited in the browser since then makes
- * the push refuse toward pull instead of overwriting it.
+ * A browser edit since the last pull or push makes the next push refuse rather
+ * than overwrite it. Each mutation also sends this baseline so the site can
+ * refuse an edit made after the CLI compared them.
  */
 export const FORMS_MANIFEST_KEY = "forms";
 
@@ -67,15 +67,16 @@ function isObject(value) {
 
 /**
  * The settings half of a baseline, from the form exactly as the site returned
- * it. Name, sink and retention change without appending a version, so the
+ * it. Operational settings change without appending a version, so the
  * version alone cannot say they moved.
  */
 export function siteSettingsBaseline(siteForm) {
-  return {
+  return projectFormSettings({
     name: siteForm.name,
-    sink: siteForm.sink ?? FORM_DEFAULT_SINK,
-    retention_days: siteForm.retentionDays ?? FORM_RETENTION_DAYS.default,
-  };
+    sink: siteForm.sink,
+    retention_days: siteForm.retentionDays,
+    notify_owner: siteForm.notifyOwner,
+  });
 }
 
 /** The recorded baseline for one key, or undefined when this workspace never saw that form. */
@@ -85,7 +86,15 @@ export function recordedForm(manifest, key) {
   const entry = items[key];
   return isObject(entry) && typeof entry.id === "string" && Number.isSafeInteger(entry.version)
       && isObject(entry.settings)
-    ? { id: entry.id, version: entry.version, settings: entry.settings }
+    ? {
+      id: entry.id,
+      version: entry.version,
+      // Old baselines can prove only the default opt-out, never a remote opt-in.
+      settings: {
+        ...entry.settings,
+        notify_owner: Object.hasOwn(entry.settings, "notify_owner") ? entry.settings.notify_owner : FORM_DEFAULT_NOTIFY_OWNER,
+      },
+    }
     : undefined;
 }
 

package/src/reference-help.js

@@ -86,7 +86,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getThemeReference };
 
-export const REFERENCE_VERSION = 35;
+export const REFERENCE_VERSION = 36;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({
@@ -773,14 +773,19 @@ const WORKFLOW_REFERENCES = Object.freeze({
     details: Object.freeze([
       `Run 'pull' once first: 'forms pull' and 'forms push' need the pulled workspace's manifest, which records the `
       + "version of each form this workspace last saw. 'forms validate' needs only taproot-site.json.",
-      `The file is { key, name, sink, retention_days, definition }. key must equal the file's name `
+      `The file is { key, name, sink, retention_days, notify_owner, definition }. key must equal the file's name `
       + `and is lowercase letters, digits, and single hyphens, at most ${FORM_KEY_MAXIMUM_LENGTH} characters. name is `
       + `1 to ${FORM_LIMITS.nameCharacters} characters. sink is one of ${FORM_SINKS.join(", ")} and defaults to `
-      + "'none' (store submissions only); 'newsletter' also subscribes the contact address to the site's newsletter. "
+      + "'none' (store submissions only); 'newsletter' requests double-opt-in confirmation for the contact address. "
+      + "A newsletter sink requires a required email contact field and at least one consent checkbox; every consent checkbox must be checked. "
       + `retention_days is ${FORM_RETENTION_DAYS.minimum} to ${FORM_RETENTION_DAYS.maximum} (a site's plan may cap it lower): `
       + "submissions are deleted that many days after they arrive. Leave it out and the site chooses on creation (its "
       + "plan's default, usually 365) and keeps the current value on an update. Shortening it deletes the submissions that fall outside it, "
       + "so a key cannot do it; the site refuses it, and an owner or admin must make that change.",
+      "notify_owner is an optional top-level boolean, independent of the sink. New forms default to false; omitting it "
+      + "on an existing form preserves the site's preference. It opts into hourly counts-only email to the current site "
+      + "account owner, never visitor answers or addresses. This setting takes effect without a new version or publishing. "
+      + "Delivery also requires Taproot's rollout and email provider readiness; opt-in enables neither, and earlier submissions are not backfilled.",
       `definition is { fields, contact_field?, submit_label?, after_submit? } (contact_field only with several email fields). Each field is { id, type, label, hint?, ...constraints }; the closed `
       + `field types are ${FIELD_TYPES.join(", ")}. hint is optional helper text of up to ${MAX_HINT_LENGTH} `
       + "characters, drawn under the field on the published form; it is the only author-defined text printed there, so a required "
@@ -835,7 +840,7 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "'unchanged' and leaves the bytes as they were. Write your own files in that order and a push rewrites "
       + "nothing you did not change.",
       "'forms push' validates every file and compares every form with the site before the first write. It refuses "
-      + "forms.concurrent_modification when the site's version moved since this workspace last read it, "
+      + "forms.concurrent_modification when the site's version or operational settings moved since this workspace last read it, "
       + "forms.pull_required when the site has a form with that key this workspace never pulled, and forms.archived "
       + "when the form is archived on the site. Reconcile with 'forms pull' and retry; nothing was written.",
       "Submissions are never pulled or pushed. They are visitors' personal data: read, mark, export and delete "
@@ -854,6 +859,7 @@ const WORKFLOW_REFERENCES = Object.freeze({
       name: "Contact",
       sink: "none",
       retention_days: 365,
+      notify_owner: false,
       definition: Object.freeze({
         fields: Object.freeze([
           Object.freeze({ id: "name", type: "text", label: "Your name", required: true, max_length: 120 }),

package/src/transport.js

@@ -1,10 +1,12 @@
 import {
+  BANDWIDTH_ALLOWANCE_REFUSAL_REASON,
   CAPABILITY_REFUSAL_FIELD,
   CAPABILITY_REFUSAL_REASON,
   CLI_NAME,
   CLI_UPGRADE_REFUSAL_FIELD,
   CLI_VERSION,
   CREDENTIAL_REFUSAL_FIELD,
+  DEPLOYMENT_ALLOWANCE_REFUSAL_REASON,
   GRPC_RESOURCE_EXHAUSTED,
   GRPC_UNAUTHENTICATED,
   HTTP_TOO_MANY_REQUESTS,
@@ -21,6 +23,7 @@ import {
   REFUSAL_THROTTLED,
   REFUSAL_UNCLASSIFIED,
   ROLLOUT_REFUSAL_FIELD,
+  SITE_DEPLOYMENT_REFUSAL_DOMAIN,
 } from "./constants.js";
 import { Readable } from "node:stream";
 
@@ -409,15 +412,10 @@ function capabilityNames(value) {
  * keys on it rather than on `@type`, which a future packing could reshape.
  */
 export function capabilityRefusal(value) {
-  const queue = [{ value, depth: 0 }];
-  let work = 0;
-  while (queue.length > 0 && work < 1_000) {
-    const current = queue.shift();
-    work += 1;
-    if (!current || current.depth > 8 || current.value === null || typeof current.value !== "object") continue;
-    const metadata = current.value.metadata;
+  return findErrorInfo(value, (detail) => {
+    const metadata = detail.metadata;
     if (
-      current.value.reason === CAPABILITY_REFUSAL_REASON
+      detail.reason === CAPABILITY_REFUSAL_REASON
       && metadata !== null
       && typeof metadata === "object"
       && !Array.isArray(metadata)
@@ -434,6 +432,61 @@ export function capabilityRefusal(value) {
         });
       }
     }
+    return undefined;
+  });
+}
+
+/**
+ * The pages-generated allowance or bandwidth-pause refusal the deploy API attaches
+ * as a `google.rpc.ErrorInfo` detail (TR00445, TR01201), or undefined. Keyed on the
+ * namespaced domain and reason, never the message sentence. `resetsAt` is the
+ * server's `resets_at` re-serialized as an ISO-8601 UTC instant, or undefined
+ * when it is absent (a licence that grants no deployments has no period) or
+ * does not parse. `requestedPages` and `remainingPages` are present on the
+ * allowance refusal only.
+ */
+export function planLimitRefusal(value) {
+  return findErrorInfo(value, (detail) => {
+    if (
+      detail.domain !== SITE_DEPLOYMENT_REFUSAL_DOMAIN
+      || (detail.reason !== DEPLOYMENT_ALLOWANCE_REFUSAL_REASON && detail.reason !== BANDWIDTH_ALLOWANCE_REFUSAL_REASON)
+    ) {
+      return undefined;
+    }
+    const metadata = detail.metadata !== null && typeof detail.metadata === "object" ? detail.metadata : {};
+    const resetsAt = typeof metadata.resets_at === "string" ? new Date(metadata.resets_at) : undefined;
+    return Object.freeze({
+      reason: detail.reason,
+      resetsAt: resetsAt !== undefined && !Number.isNaN(resetsAt.getTime()) ? resetsAt.toISOString() : undefined,
+      // The pages the refused request needed and the period had left (TR01201).
+      requestedPages: pageCount(metadata.requested_pages),
+      remainingPages: pageCount(metadata.remaining_pages),
+    });
+  });
+}
+
+/** A page count the server reported as a decimal string, or undefined. */
+function pageCount(value) {
+  const count = typeof value === "string" && /^[0-9]{1,9}$/u.test(value) ? Number(value) : undefined;
+  return Number.isSafeInteger(count) ? count : undefined;
+}
+
+/**
+ * The first object in `value`, breadth first, for which `match` returns a
+ * result. Transcoded `details[]` entries are `Any`-packed and nested, so one
+ * pinned path through them would silently empty every extractor on a contract
+ * change; the walk is bounded in depth and in work so a hostile body cannot
+ * stall it.
+ */
+function findErrorInfo(value, match) {
+  const queue = [{ value, depth: 0 }];
+  let work = 0;
+  while (queue.length > 0 && work < 1_000) {
+    const current = queue.shift();
+    work += 1;
+    if (!current || current.depth > 8 || current.value === null || typeof current.value !== "object") continue;
+    const found = match(current.value);
+    if (found !== undefined) return found;
     for (const child of Object.values(current.value)) {
       if (child !== null && typeof child === "object") queue.push({ value: child, depth: current.depth + 1 });
     }
@@ -459,6 +512,7 @@ export class ApiError extends SiteAuthoringError {
     const grpcCode = Number.isSafeInteger(body?.code) ? body.code : undefined;
     const fields = fieldViolations(body);
     const capability = capabilityRefusal(body);
+    const planLimit = planLimitRefusal(body);
     // Only the known upgrade refusal may supply a human message. Other server
     // errors can contain internal diagnostics and retain their generic output.
     const upgradeMessage = fields.includes(CLI_UPGRADE_REFUSAL_FIELD)
@@ -472,6 +526,10 @@ export class ApiError extends SiteAuthoringError {
       "api.request_rejected",
       upgradeMessage || (fields.length > 0
         ? `Taproot rejected the request field '${fields[0]}'.`
+        : planLimit !== undefined
+        ? planLimit.reason === BANDWIDTH_ALLOWANCE_REFUSAL_REASON
+          ? "Taproot paused deployments: the site used more than its monthly bandwidth for two months in a row."
+          : "Taproot refused the request: it generates more pages than the site's allowance for this billing period has left."
         : capability !== undefined
         ? `Taproot refused the request: this credential does not carry a capability granting '${
           capability.permission
@@ -491,6 +549,7 @@ export class ApiError extends SiteAuthoringError {
     this.fields = fields;
     this.violationDescriptions = fieldDescriptions(body);
     this.capability = capability;
+    this.planLimit = planLimit;
     // The `retry-after` trailer (TR00839's deployment throttle, or any other
     // ResourceExhausted refusal that sets it) transcodes to an ordinary
     // response header. Undefined when absent or unparseable — callers must
@@ -545,10 +604,12 @@ export class ApiError extends SiteAuthoringError {
    *   left it unclassified: no `refusal` in the JSON result, and nothing said
    *   on the human channel. The field arrives only from the in-transaction
    *   re-validation, which does attach `ExternalApiKey`.
-   * - `plan_limit` (field `UpgradePrompt`) — a commercial ceiling, surfaced at
+   * - `plan_limit` (field `UpgradePrompt`, or `ErrorInfo` reason
+   *   `DEPLOYMENT_PERIOD_ALLOWANCE_EXCEEDED` / `BANDWIDTH_ALLOWANCE_EXCEEDED`
+   *   with the server's `resets_at`) — a commercial ceiling, surfaced at
    *   deploy time because no pre-flight read of the published-page quota
-   *   exists on the contract. **Upgrade** (or publish fewer pages); the CLI
-   *   never invents the numeric limit.
+   *   exists on the contract. **Upgrade** (or publish fewer pages, or wait for
+   *   the named reset); the CLI never invents the numeric limit.
    * - `throttled` (gRPC `ResourceExhausted` / HTTP 429) — the per-key
    *   throttle. **Back off** and retry with delay.
    * - `capability_missing` (`ErrorInfo` reason `SITE_AUTHORING_CAPABILITY_MISSING`)
@@ -568,7 +629,7 @@ export class ApiError extends SiteAuthoringError {
     if (this.hasField(CLI_UPGRADE_REFUSAL_FIELD)) return REFUSAL_CLI_OUTDATED;
     if (this.hasField(ROLLOUT_REFUSAL_FIELD)) return REFUSAL_PLATFORM_PAUSED;
     if (this.hasField(CREDENTIAL_REFUSAL_FIELD)) return REFUSAL_CREDENTIAL_REJECTED;
-    if (this.hasField(PLAN_LIMIT_REFUSAL_FIELD)) return REFUSAL_PLAN_LIMIT;
+    if (this.hasField(PLAN_LIMIT_REFUSAL_FIELD) || this.planLimit !== undefined) return REFUSAL_PLAN_LIMIT;
     // The named detail ranks with the fields and above the status mappings, for
     // the same reason: it is the specific statement about this refusal.
     if (this.capability !== undefined) return REFUSAL_CAPABILITY_MISSING;

package/src/typed-page-reference.js

@@ -76,7 +76,9 @@ const FIELD_HELP = Object.freeze({
     required: true,
     description:
       "The Taproot place being reviewed. The site fills in its name, address and coordinates from this record. Find "
-      + "it with 'places search <name and city>' and 'places select <googlePlaceId> <sessionToken>'.",
+      + "it with 'places search <name and city>' and 'places select <googlePlaceId> <sessionToken>'. The site publishes the "
+      + "place's category in the byline and files the review under /places/<category>; change it for this site with "
+      + "'places category set <placeId> <category>'.",
   },
   place: {
     type: "UUID",

package/src/verbs/deploy.js

@@ -4,6 +4,7 @@ import {
   DEPLOYMENT_REQUEST_OUTCOME_COALESCED,
   DEPLOYMENT_STATUS_COMPLETED,
   deploySite,
+  describePageEstimate,
   getDeploySelection,
   getPublishingReadiness,
   listDeployments,
@@ -67,9 +68,6 @@ const REDIRECT_ACTIVATION_NOTE =
  */
 
 const MAXIMUM_REPORTED_BLOCKERS = 50;
-// Staged page ids ride in the readiness query string, so a very large candidate
-// is checked at site level instead of pushing an unbounded URL at the API.
-const MAXIMUM_READINESS_PAGE_IDS = 100;
 
 function usageError(code, message, field) {
   return new SiteAuthoringError(code, message, { field, exitCode: 2 });
@@ -157,6 +155,8 @@ function reportReadiness(readiness) {
     redirectsChanged: readiness.redirectsChanged,
     formsChanged: readiness.formsChanged,
     videosChanged: readiness.videosChanged,
+    // The pages this deployment generates and the allowance left: what staging is charged (TR01201).
+    ...(readiness.pageEstimate === null ? {} : { pageEstimate: readiness.pageEstimate }),
     blockers: blockers.items,
     ...(blockers.truncated ? { blockersTruncated: true } : {}),
   };
@@ -341,8 +341,10 @@ export async function deploy(invocation) {
     );
     const readiness = await getPublishingReadiness(client, siteId, {
       ...candidate,
-      stagedPageIds: stagedPageIds.length > MAXIMUM_READINESS_PAGE_IDS ? undefined : stagedPageIds,
       useExactPageSelection: stagedPageIds.length === 0,
+      includePageEstimate: true,
+      // The estimate must recognize the request it is about to be followed by.
+      ...(invocation.allowFailedPreview === true ? { allowFailedPreview: true } : {}),
     });
     if (readiness.blockers.length > 0) {
       throw new SiteAuthoringError(
@@ -368,11 +370,29 @@ export async function deploy(invocation) {
     if (!readiness.hasCandidateChanges) {
       onProgress("Taproot reports this candidate contains no changes; deploying it anyway would be a no-op.");
     }
+    // The plan is the charge: the same page count admission uses, shown before anything is sent.
+    if (readiness.pageEstimate !== null) {
+      onProgress(describePageEstimate(readiness.pageEstimate));
+      if (readiness.pageEstimate.exceedsAllowance) {
+        const estimate = readiness.pageEstimate;
+        throw new SiteAuthoringError(
+          "deploy.page_allowance_exceeded",
+          `This candidate generates ${estimate.plannedPageCount.toLocaleString("en-US")} ${
+            estimate.plannedPageCount === 1 ? "page" : "pages"
+          } but the site has ${(estimate.pagesGeneratedRemaining ?? 0).toLocaleString("en-US")} left for this billing `
+            + `period${estimate.periodEnd === null ? "" : ` (it resets ${estimate.periodEnd})`}. Stage a smaller change, `
+            + "or upgrade the site's plan for a larger allowance. Nothing was sent.",
+          { field: "plannedPageCount" },
+        );
+      }
+    }
 
     const created = await deploySite(client, siteId, {
       siteId,
       environment: DEPLOYMENT_ENVIRONMENT_STAGING,
       ...candidate,
+      // Confirms the number just shown: the server refuses if the plan has grown since.
+      ...(readiness.pageEstimate === null ? {} : { expectedPageCount: readiness.pageEstimate.plannedPageCount }),
       ...(invocation.allowFailedPreview === true ? { allowFailedPreview: true } : {}),
     });
     onProgress(`Staging deployment ${created.id} accepted; waiting for it to complete.`);

package/src/verbs/forms-pull.js

@@ -41,9 +41,7 @@ export async function formsPull(invocation) {
     }
     const document_ = projectFormForWorkspace({
       key: form.key,
-      name: form.name,
-      sink: form.sink,
-      retention_days: form.retentionDays,
+      ...siteSettingsBaseline(form),
       definition: version.definition,
     }, pages?.pathById);
     await writeWorkspaceJson(config.workspaceDir, formFileName(form.key), document_);

package/src/verbs/forms-push.js

@@ -8,19 +8,24 @@ import {
   saveSiteFormVersion,
   updateSiteFormSettings,
 } from "../forms-api.js";
-import { afterSubmitPage, formFileName, projectFormForWorkspace, storedDefinition } from "../forms-contract.js";
+import { afterSubmitPage, formFileName, projectFormForWorkspace, storedDefinition, validateNewsletterDefinition } from "../forms-contract.js";
 import { readWorkspaceForms, recordedForm, siteSettingsBaseline, withRecordedForm } from "../forms-workspace.js";
 import { openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
 import { ApiError } from "../transport.js";
 import { readManifest, writeManifest, writeWorkspaceJson } from "../workspace.js";
 
-function changedOnTheSite(key, cause, settingsApplied) {
+function changedOnTheSite(key, cause, applied) {
+  const outcome = applied.settings && applied.definition
+    ? "Its settings and definition were applied."
+    : applied.settings
+    ? "Its settings were applied; its definition was not."
+    : applied.definition
+    ? "Its definition was applied; its settings were not."
+    : "This form was not changed.";
   return new SiteAuthoringError(
     "forms.concurrent_modification",
     `${formFileName(key)}: the form changed on the site while it was being pushed. Run '${VERB_FORMS_PULL}', `
-      + `reconcile the file, and retry. ${
-        settingsApplied ? "Its settings were applied; its definition was not." : "This form was not changed."
-      }`,
+      + `reconcile the file, and retry. ${outcome}`,
     { field: formFileName(key), status: cause.status },
   );
 }
@@ -44,6 +49,7 @@ function planForm(form, remote, baseline, pages) {
   const desired = projectFormForWorkspace({
     ...form.document,
     retention_days: requestedRetention ?? remote?.form.retentionDays,
+    notify_owner: form.document.notify_owner ?? remote?.form.notifyOwner,
   }, pages?.pathById);
   if (remote === undefined) {
     if (baseline !== undefined) {
@@ -66,28 +72,27 @@ function planForm(form, remote, baseline, pages) {
   if (
     baseline.id !== remote.form.id
     || baseline.version !== remote.version.version
-    // Name, sink and retention change without a new version, so they are
+    // Operational settings change without a new version, so they are
     // fenced separately; a stale file would otherwise revert them.
     || JSON.stringify(baseline.settings) !== JSON.stringify(siteSettings)
   ) {
     throw new SiteAuthoringError(
       "forms.concurrent_modification",
       `${formFileName(form.key)}: the form changed on the site after this workspace read it (recorded version `
-        + `${baseline.version}, site has ${remote.version.version}; its name, sink or retention may also have changed). Run '${VERB_FORMS_PULL}', reconcile the file, `
+        + `${baseline.version}, site has ${remote.version.version}; its settings may also have changed). Run '${VERB_FORMS_PULL}', reconcile the file, `
         + "and retry. Nothing was written.",
       { field: formFileName(form.key) },
     );
   }
   const current = projectFormForWorkspace({
     key: remote.form.key,
-    name: remote.form.name,
-    sink: remote.form.sink,
-    retention_days: remote.form.retentionDays,
+    ...siteSettings,
     definition: remote.version.definition,
   }, pages?.pathById);
   const settingsChanged = current.name !== desired.name
     || current.sink !== desired.sink
-    || current.retention_days !== desired.retention_days;
+    || current.retention_days !== desired.retention_days
+    || current.notify_owner !== desired.notify_owner;
   const versionChanged = JSON.stringify(current.definition) !== JSON.stringify(desired.definition);
   return {
     form,
@@ -114,7 +119,7 @@ export async function formsPush(invocation) {
   const session = await openSession(invocation);
   const { client, config, siteId, onProgress } = session;
   warnIfExternalWritesPaused(session, VERB_FORMS_PUSH);
-  const forms = await readWorkspaceForms(config.workspaceDir, invocation.formKeys);
+  const forms = await readWorkspaceForms(config.workspaceDir, invocation.formKeys, { deferNewsletterSemantics: true });
   onProgress(`Validated ${forms.length} form file${forms.length === 1 ? "" : "s"}.`);
   let manifest = await readManifest(config.workspaceDir, siteId);
 
@@ -132,6 +137,14 @@ export async function formsPush(invocation) {
       pages = await withRefusalGuidance(onProgress, "forms push", async () => await getPageIndex(client, siteId, { onProgress }));
     }
     const plan = planForm(form, remote, recordedForm(manifest, form.key), pages);
+    // Legacy newsletter definitions may stay only after the baseline matches.
+    // New capture or a changed definition must satisfy today's admission rules.
+    if (
+      plan.desired.sink === "newsletter"
+      && (plan.action === "create" || plan.remote.form.sink !== "newsletter" || plan.versionChanged)
+    ) {
+      validateNewsletterDefinition(form.file, plan.desired.definition);
+    }
     // A page_path the site does not have is refused here, with the rest of the checks, not partway
     // through the writes. Only a definition that is going to be sent is resolved: a settings-only
     // update of a form whose page was deleted never sends it.
@@ -151,7 +164,7 @@ export async function formsPush(invocation) {
     // The baseline is what the site stored, not what the file said: the site
     // normalizes some values, and the next push is fenced against its copy.
     let settings = plan.remote === undefined ? undefined : siteSettingsBaseline(plan.remote.form);
-    let settingsApplied = false;
+    const applied = { settings: false, definition: false };
     try {
       if (plan.action === "create") {
         const created = await withRefusalGuidance(
@@ -166,43 +179,48 @@ export async function formsPush(invocation) {
         // and normalized the name.
         desired = projectFormForWorkspace({
           ...desired,
-          name: created.form.name,
-          sink: created.form.sink,
-          retention_days: created.form.retentionDays,
+          ...settings,
         }, pages?.pathById);
       } else if (plan.action === "update") {
-        if (plan.settingsChanged) {
-          settings = siteSettingsBaseline(
-            await withRefusalGuidance(
+        // Enabling newsletter capture checks the stored definition, so its new
+        // email and consent fields must land first. Disabling must do the reverse.
+        const definitionFirst = plan.settingsChanged && plan.versionChanged
+          && settings.sink === "none" && desired.sink === "newsletter";
+        for (const mutation of definitionFirst ? ["definition", "settings"] : ["settings", "definition"]) {
+          if (mutation === "settings") {
+            if (!plan.settingsChanged) continue;
+            settings = siteSettingsBaseline(
+              await withRefusalGuidance(
+                onProgress,
+                "forms push",
+                async () => await updateSiteFormSettings(client, siteId, formId, desired, plan.baseline.settings),
+              ),
+            );
+            desired = projectFormForWorkspace({ ...desired, ...settings }, pages?.pathById);
+          } else {
+            if (!plan.versionChanged) continue;
+            version = (await withRefusalGuidance(
               onProgress,
               "forms push",
-              async () => await updateSiteFormSettings(client, siteId, formId, desired, plan.baseline.settings),
-            ),
-          );
-          settingsApplied = true;
-          // Recorded at once: if the version save below fails, the next push
-          // must not read the settings it just applied as someone else's edit.
+              async () => await saveSiteFormVersion(client, siteId, formId, { ...desired, definition: plan.wireDefinition }, plan.baseline.version),
+            )).version;
+          }
+          applied[mutation] = true;
+          // A retry must recognize either write as its own, even if the next
+          // mutation fails. Keep the other half of the baseline until it lands.
           manifest = withRecordedForm(manifest, form.key, { id: formId, version, settings });
           await writeManifest(config.workspaceDir, manifest);
         }
-        if (plan.versionChanged) {
-          version = (await withRefusalGuidance(
-            onProgress,
-            "forms push",
-            async () => await saveSiteFormVersion(client, siteId, formId, { ...desired, definition: plan.wireDefinition }, plan.baseline.version),
-          )).version;
-        }
       }
     } catch (caught) {
       // The site checks the recorded version and settings under its own lock,
       // which is what closes the gap between the comparison above and the write.
       const error = caught instanceof ApiError && (caught.hasField("ExpectedVersion") || caught.hasField("ExpectedSettings"))
-        ? changedOnTheSite(form.key, caught, settingsApplied)
+        ? changedOnTheSite(form.key, caught, applied)
         : caught;
       if (error instanceof SiteAuthoringError) {
         const completed = results.filter((item) => item.action !== "unchanged").map((item) => item.key);
-        // The settings write stands even though the version save after it failed.
-        if (settingsApplied) completed.push(form.key);
+        if (applied.settings || applied.definition) completed.push(form.key);
         if (completed.length > 0) throw error.withCompletedWrites(completed);
       }
       throw error;
@@ -222,6 +240,6 @@ export async function formsPush(invocation) {
   return successResult(VERB_FORMS_PUSH, siteId, {
     forms: { count: results.length, items: results },
     written: { items: written, count: written.length },
-    ...(written.length > 0 ? { nextStep: "deploy --staging" } : {}),
+    ...(plans.some((plan) => plan.action === "create" || plan.versionChanged) ? { nextStep: "deploy --staging" } : {}),
   });
 }

package/src/verbs/index.js

@@ -16,6 +16,9 @@ import {
   VERB_NAV_PUSH,
   VERB_PAGES_META_SET,
   VERB_PAGES_PUSH,
+  VERB_PLACES_CATEGORY_CLEAR,
+  VERB_PLACES_CATEGORY_LIST,
+  VERB_PLACES_CATEGORY_SET,
   VERB_PLACES_SEARCH,
   VERB_PLACES_SELECT,
   VERB_PLAN,
@@ -48,7 +51,7 @@ import { mediaUpload } from "./media-upload.js";
 import { navPush } from "./nav-push.js";
 import { pagesMetaSet } from "./pages-meta-set.js";
 import { pagesPush } from "./pages-push.js";
-import { placesSearch, placesSelect } from "./places.js";
+import { placesCategoryClear, placesCategoryList, placesCategorySet, placesSearch, placesSelect } from "./places.js";
 import { apply, plan } from "./plan.js";
 import { previewPage } from "./preview-page.js";
 import { previewRevoke } from "./preview-revoke.js";
@@ -106,6 +109,8 @@ import { whoami } from "./whoami.js";
  *                  //   with none, every file under forms/
  *   placeQuery,    // places search: the words of the query
  *   placeSelection, // places select: [googlePlaceId, sessionToken]
+ *   placeCategory, // places category set: [placeId, category]
+ *   placeId,       // places category clear: [placeId]
  *   pagePaths,     // approve: narrow to these page paths; with none, every
  *                  //   draft the workspace manifest tracks is staged
  *   authorHandle,  // authors add: the handle of the site author to create
@@ -148,6 +153,9 @@ export const VERB_HANDLERS = Object.freeze({
   [VERB_PLAN]: plan,
   [VERB_PLACES_SEARCH]: placesSearch,
   [VERB_PLACES_SELECT]: placesSelect,
+  [VERB_PLACES_CATEGORY_SET]: placesCategorySet,
+  [VERB_PLACES_CATEGORY_CLEAR]: placesCategoryClear,
+  [VERB_PLACES_CATEGORY_LIST]: placesCategoryList,
   [VERB_APPLY]: apply,
   [VERB_REDIRECTS_CHECK]: redirectsCheck,
   [VERB_REDIRECTS_PULL]: redirectsPull,

package/src/verbs/media-upload.js

@@ -354,7 +354,6 @@ const VIDEO_REFUSAL_FIELDS = Object.freeze([
   "Video",
   "UpgradePrompt",
   "VideoNotIncluded",
-  "VideoPendingDowngrade",
 ]);
 
 /**