@taprootio/site-authoring 0.16.0 → 0.19.0

package/README.md

@@ -464,7 +464,8 @@ moved since this workspace last reconciled with it, naming both revisions;
 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:`.
+album can name its place the same way with `place:`. `places category set
+<placeId> <category>` changes the category this site shows for a 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
@@ -523,6 +524,13 @@ Submissions are never pulled. `help forms` states the file shape and every
 refusal, and placing a form on a page is the free-form `form`
 component.
 
+The optional top-level `notify_owner` boolean opts a form into hourly,
+counts-only owner email. New forms default to false; omitting it on an
+existing form preserves the site's preference. It is independent of the sink
+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.
+
 `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,
@@ -567,8 +575,10 @@ paused; retry later), `credential_rejected` (stop and re-issue),
 not exchanged for a capability the request needs; the refusal carries
 `field: "GrantedCapabilities"`, and the CLI's human progress names the
 granted and required capabilities, so report the verb's declared set rather
-than re-issuing the key), `plan_limit` (the plan's published-page allowance,
-surfaced at deploy), and `throttled` (back off).
+than re-issuing the key), `plan_limit` (the plan's published-page allowance or
+its pages-generated allowance, or the bandwidth pause on deploys,
+surfaced at deploy; the allowance shows its reset time, while the bandwidth pause shows the earliest
+time it can lift, since it lifts only after a month ends under the allowance or on upgrade), and `throttled` (back off).
 
 When `GITHUB_OUTPUT` names the runner's existing output file, every
 operational verb appends the same JSON under `taproot_site_result` through a
@@ -635,17 +645,49 @@ 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
+### Place categories in 0.18.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`.
+A place has one category for every site, taken from Google's types, and a place
+that Taproot could not classify is filed under `Other`. A site can file a place
+under a category of its own:
+
+```
+taproot-site places category list
+taproot-site places category set <placeId> park
+taproot-site places category clear <placeId>
+```
+
+`list` prints the closed list `set` accepts; a name outside it is refused, and
+capitalization is ignored. The category is the site's alone and applies to every
+review of that place on the site: the place itself and other sites do not
+change. Place-review bylines and the `/places/<category>` pages use it from the
+site's next deployment, including reviews nobody has edited. `clear` removes it.
+Both need the same page-editing permission as `places select`.
+
+### Pages generated in 0.18.0
+
+A site's licence allows a number of pages generated per billing period, and
+`deploy --staging` is charged by the pages it generates, not by the deployment.
+The deploy asks Taproot to plan the candidate first and reports the plan before
+it sends anything: `This will generate 74 pages · 940 of 1,000 left this period
+(resets 2026-11-01T00:00:00.000Z)`. The same figures are in `readiness.pageEstimate`
+(`plannedPageCount`, `pagesGeneratedLimit`, `pagesGeneratedRemaining`, `periodEnd`
+and `exceedsAllowance`; a limit and what remains are `null` on an unlimited
+licence). The number shown is the number charged. Promoting a staged release to
+production generates nothing and costs no pages.
+
+A candidate that does not fit stops with `deploy.page_allowance_exceeded`, naming
+the pages it needs, the pages left, and the reset. A deploy refused by the server
+for the same reason, or for the bandwidth pause, reports `plan_limit` with the
+time it can lift (and `requested_pages` and `remaining_pages` for the allowance):
+the allowance's reset, or for the bandwidth pause the earliest month end that can
+clear it (an upgrade clears it at once).
+
+### Deployment allowances in 0.18.0
+
+A deploy refused for the bandwidth pause reports `plan_limit` with the time it
+can lift: the earliest month end that can clear it (an upgrade clears it at
+once).
 
 ### Authoring feedback in 0.16.0
 
@@ -666,6 +708,18 @@ old default, `noopener noreferrer nofollow`, reads as no choice. See
   generated pages navigation links to), and `validate` and `pages push` warn on
   links that look made by autolinking (`content.link_autolinked`).
 
+### 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`.
+
 ### Staging verification and deployment evidence
 
 `deploy --staging` selects the same changed pages, settings groups and navigation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.16.0",
+  "version": "0.19.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",

package/src/api.js

@@ -1,5 +1,6 @@
 import { normalizeLatestCliVersion } from "./cli-release.js";
 import {
+  BANDWIDTH_ALLOWANCE_REFUSAL_REASON,
   CANONICAL_TIMESTAMP,
   CAPABILITY_REFUSAL_FIELD,
   CLI_UPGRADE_COMMAND,
@@ -437,6 +438,34 @@ export function announceRefusal(error, onProgress, action = "request") {
   }
   if (kind === REFUSAL_PLAN_LIMIT) {
     onProgress("");
+    if (error.planLimit !== undefined) {
+      // The allowance and bandwidth refusals ride an ErrorInfo detail, not the
+      // UpgradePrompt field, and name when they can next lift on their own.
+      const bandwidth = error.planLimit.reason === BANDWIDTH_ALLOWANCE_REFUSAL_REASON;
+      onProgress(`PLAN LIMIT (refusal=plan_limit, reason=${error.planLimit.reason})`);
+      onProgress(
+        bandwidth
+          ? `  Taproot paused this ${action}: the site's measured bandwidth was over its monthly allowance for two `
+            + "months in a row. The published site keeps serving; only new deployments wait."
+          : error.planLimit.requestedPages === undefined
+          ? `  Taproot refused this ${action}: it generates more pages than the site's allowance for this billing period has left.`
+          : `  Taproot refused this ${action}: it generates ${pagesLabel(error.planLimit.requestedPages)} and the site has ${
+            (error.planLimit.remainingPages ?? 0).toLocaleString("en-US")
+          } left for this billing period.`,
+      );
+      // The bandwidth pause is not an unconditional reset: it lifts only after
+      // a month ends under the allowance (or on upgrade), so the instant is
+      // the earliest that can happen.
+      onProgress(
+        error.planLimit.resetsAt === undefined
+          ? "  Upgrade the site's plan, then run the request again."
+          : bandwidth
+          ? `  Upgrade the site's plan, or deployments resume after a month ends under the allowance (no earlier than ${error.planLimit.resetsAt}).`
+          : `  Resets at: ${error.planLimit.resetsAt}. Upgrade the site's plan to continue sooner.`,
+      );
+      onProgress("");
+      return;
+    }
     onProgress("PLAN LIMIT (refusal=plan_limit, field=UpgradePrompt)");
     onProgress(
       `  Taproot refused this ${action} against a plan ceiling rather than a content problem.`,
@@ -996,6 +1025,45 @@ export async function selectPlace(client, siteId, { googlePlaceId, sessionToken
   };
 }
 
+function normalizeSiteCategory(value) {
+  const state = requireObject(value, "api.place_contract", "site place category");
+  return {
+    placeId: requireIdentifier(state.placeId, "api.place_contract", "placeId"),
+    category: text(state.category),
+    placeCategory: text(state.placeCategory),
+    isOverride: state.isOverride === true,
+  };
+}
+
+/** Sets this site's own category for a place; the place itself and other sites are unchanged. */
+export async function setPlaceCategory(client, siteId, { placeId, category }) {
+  return normalizeSiteCategory(
+    await client.request(sitePath(siteId, `places/${encodeURIComponent(placeId)}/category`), {
+      method: "PUT",
+      body: { siteId, placeId, category },
+    }),
+  );
+}
+
+/** Removes this site's category for a place, so the place's own category applies again. */
+export async function clearPlaceCategory(client, siteId, { placeId }) {
+  return normalizeSiteCategory(
+    await client.request(sitePath(siteId, `places/${encodeURIComponent(placeId)}/category`), { method: "DELETE" }),
+  );
+}
+
+/** The closed list of place categories, in Taproot's order. */
+export async function listPlaceCategories(client) {
+  const response = requireObject(
+    await client.request(`v1/standard-types${query([["typeGroup", "place_category"], ["maxResults", 1000]])}`),
+    "api.place_contract",
+    "place categories",
+  );
+  return (Array.isArray(response.standardTypes) ? response.standardTypes : [])
+    .map((type) => text(requireObject(type, "api.place_contract", "place category").name))
+    .filter((name) => name !== "");
+}
+
 /**
  * Processing is observed through `ListSiteImages`; `GetImageById` is
  * session-only under TR00602's read list, so a key-authorized client watches
@@ -1122,18 +1190,20 @@ export async function getDeploySelection(client, siteId) {
 }
 
 export async function getPublishingReadiness(client, siteId, selection = {}) {
+  // A body, not a query: the exact selection can run past a URL's limit, and the
+  // estimate must plan the pages the deploy will stage (TR01201).
   const response = requireObject(
-    await client.request(sitePath(
-      siteId,
-      `publishing/readiness${
-        query([
-          ["stagedPageIds", selection.stagedPageIds],
-          ["selectedSettingsTypes", selection.selectedSettingsTypes],
-          ["includeNavigation", selection.includeNavigation],
-          ["useExactPageSelection", selection.useExactPageSelection],
-        ])
-      }`,
-    )),
+    await client.request(sitePath(siteId, "publishing/readiness"), {
+      method: "POST",
+      body: {
+        stagedPageIds: selection.stagedPageIds,
+        selectedSettingsTypes: selection.selectedSettingsTypes,
+        includeNavigation: selection.includeNavigation,
+        useExactPageSelection: selection.useExactPageSelection,
+        includePageEstimate: selection.includePageEstimate,
+        allowFailedPreview: selection.allowFailedPreview,
+      },
+    }),
     "api.readiness_contract",
     "publishing readiness",
   );
@@ -1154,10 +1224,50 @@ export async function getPublishingReadiness(client, siteId, selection = {}) {
     redirectsChanged: response.redirectsChanged === true,
     formsChanged: response.formsChanged === true,
     videosChanged: response.videosChanged === true,
+    // The pages staging this candidate would generate, which is the number charged (TR01201).
+    // Absent unless asked for and the candidate could be planned.
+    pageEstimate: pageEstimate(response),
     blockers,
   };
 }
 
+/**
+ * The server's plan for a candidate: the pages staging it generates, the
+ * allowance left this period and when it resets. The CLI never computes any of
+ * it; limit, remaining and period end are null for an unlimited licence.
+ */
+function pageEstimate(response) {
+  if (!Number.isSafeInteger(response.plannedPageCount) || response.plannedPageCount < 0) return null;
+  const periodEnd = typeof response.pagesGeneratedPeriodEnd === "string"
+    ? new Date(response.pagesGeneratedPeriodEnd)
+    : undefined;
+  return {
+    plannedPageCount: response.plannedPageCount,
+    pagesGeneratedLimit: Number.isSafeInteger(response.pagesGeneratedLimit) ? response.pagesGeneratedLimit : null,
+    pagesGeneratedRemaining: Number.isSafeInteger(response.pagesGeneratedRemaining)
+      ? response.pagesGeneratedRemaining
+      : null,
+    periodEnd: periodEnd !== undefined && !Number.isNaN(periodEnd.getTime()) ? periodEnd.toISOString() : null,
+    exceedsAllowance: response.plannedPagesExceedAllowance === true,
+  };
+}
+
+const pagesLabel = (count) => `${count.toLocaleString("en-US")} ${count === 1 ? "page" : "pages"}`;
+
+/**
+ * The one line that states a candidate's plan in pages (TR01201), shared by the
+ * progress output and the refusal so the two never word it differently.
+ */
+export function describePageEstimate(estimate) {
+  const generates = `This will generate ${pagesLabel(estimate.plannedPageCount)}`;
+  if (estimate.pagesGeneratedLimit === null || estimate.pagesGeneratedRemaining === null) return generates;
+  const left = `${estimate.pagesGeneratedRemaining.toLocaleString("en-US")} of ${
+    estimate.pagesGeneratedLimit.toLocaleString("en-US")
+  } left this period`;
+  const resets = estimate.periodEnd === null ? "" : ` (resets ${estimate.periodEnd})`;
+  return `${generates} · ${left}${resets}`;
+}
+
 export async function getStagingPreviewStatus(client, siteId) {
   const response = requireObject(
     await client.request(sitePath(siteId, "staging-preview/status")),
@@ -1353,6 +1463,14 @@ export async function deploySite(client, siteId, body) {
         { field: "AuthoringPreviewFailed", status: error.status },
       );
     }
+    if (error instanceof ApiError && error.hasField("ExpectedPageCount")) {
+      throw new SiteAuthoringError(
+        "deploy.page_estimate_changed",
+        `${error.descriptionFor("ExpectedPageCount") ?? "The pages this publish generates have grown since the estimate."} `
+          + "Nothing was staged; run the command again to confirm the new count.",
+        { field: "ExpectedPageCount", status: error.status },
+      );
+    }
     throw error;
   }
   const deployment = normalizeDeployment(response.deployment);

package/src/cli.js

@@ -34,6 +34,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,
@@ -350,6 +353,39 @@ const VERBS = Object.freeze([
       + "once for every site, so selecting it again returns the same placeId. Use it as placeId in a place review, "
       + "or as place in an article or album.",
   },
+  {
+    name: VERB_PLACES_CATEGORY_SET,
+    surface: SURFACE_STANDARD,
+    // Changes what the site's place reviews publish, so it needs page editing.
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["places", "category", "set"],
+    positionals: "placeCategory",
+    summary: "Set this site's category for a place, from the closed category list.",
+    note: "Takes the placeId from 'places select' (or a page's front matter), then one category from "
+      + "'places category list', which prints the closed list; a name outside it is refused, and capitalization is "
+      + "ignored. Use it when Google's own category for a place is not the one this site wants, such as a park filed "
+      + "under Other. The category is this site's alone and applies to every review of that place here: the place "
+      + "itself and other sites do not change. Place-review bylines and the /places/<category> pages use it from the "
+      + "next deployment, which a changed category alone is enough to start. Undo it with 'places category clear'.",
+  },
+  {
+    name: VERB_PLACES_CATEGORY_CLEAR,
+    surface: SURFACE_STANDARD,
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["places", "category", "clear"],
+    positionals: "placeId",
+    summary: "Remove this site's category for a place, so the place's own category applies again.",
+    note: "Takes the placeId. Clearing a place this site never set succeeds and changes nothing. Pages use the "
+      + "place's own category from the next deployment.",
+  },
+  {
+    name: VERB_PLACES_CATEGORY_LIST,
+    surface: SURFACE_STANDARD,
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["places", "category", "list"],
+    summary: "List the place categories 'places category set' accepts.",
+    note: "The list is closed: a category outside it is refused.",
+  },
   {
     name: VERB_PLAN,
     surface: SURFACE_STANDARD,
@@ -713,7 +749,7 @@ upgrade. Once a run has recorded a newer release, help, validate, and whoami
 refuse the same way offline. --version and --help always answer.
 
 Verbs:
-${VERBS.map((verb) => `  ${verb.tokens.join(" ").padEnd(14)} ${verb.summary}`).join("\n")}
+${VERBS.map((verb) => `  ${verb.tokens.join(" ").padEnd(20)} ${verb.summary}`).join("\n")}
 
 Configuration:
   Site verbs read taproot-site.json, found by walking up from the current
@@ -756,6 +792,10 @@ function verbHelp(verb) {
     ? " <query...>"
     : verb.positionals === "placeSelection"
     ? " <google-place-id> <session-token>"
+    : verb.positionals === "placeCategory"
+    ? " <place-id> <category>"
+    : verb.positionals === "placeId"
+    ? " <place-id>"
     : verb.positionals === "metaPagePath"
     ? " <page-path> [--title <text>] [--description <text>] [--author <handle-or-email>]"
     : verb.positionals === "authorHandle"

package/src/constants.js

@@ -110,6 +110,9 @@ export const VERB_PLAN = "plan";
 export const VERB_APPLY = "apply";
 export const VERB_PLACES_SEARCH = "places search";
 export const VERB_PLACES_SELECT = "places select";
+export const VERB_PLACES_CATEGORY_SET = "places category set";
+export const VERB_PLACES_CATEGORY_CLEAR = "places category clear";
+export const VERB_PLACES_CATEGORY_LIST = "places category list";
 /** The identity `plan` reports and `apply --plan` requires. */
 export const PLAN_HASH = /^sha256:[0-9a-f]{64}$/u;
 export const VERB_ENV = "env";
@@ -204,6 +207,19 @@ export const CAPABILITY_REFUSAL_REASON = "SITE_AUTHORING_CAPABILITY_MISSING";
  */
 export const CAPABILITY_REFUSAL_FIELD = "GrantedCapabilities";
 
+/**
+ * The `google.rpc.ErrorInfo` reasons a deploy carries when the site has hit a
+ * commercial ceiling that no retry can clear (TR00445): the deployments-per-
+ * billing-period allowance, or the bandwidth pause. Wire identities matched
+ * exactly, within {@link SITE_DEPLOYMENT_REFUSAL_DOMAIN}. The refusal is
+ * classified `plan_limit`, the same class as the page-count `UpgradePrompt`
+ * field, because the right next move is the same: upgrade, or wait for the
+ * reset the server names in `resets_at`.
+ */
+export const DEPLOYMENT_ALLOWANCE_REFUSAL_REASON = "DEPLOYMENT_PERIOD_ALLOWANCE_EXCEEDED";
+export const BANDWIDTH_ALLOWANCE_REFUSAL_REASON = "BANDWIDTH_ALLOWANCE_EXCEEDED";
+export const SITE_DEPLOYMENT_REFUSAL_DOMAIN = "sites.taproot.io";
+
 // gRPC `ResourceExhausted`. Transcoded responses carry the numeric code in the
 // body; the HTTP mapping is 429.
 export const GRPC_RESOURCE_EXHAUSTED = 8;

package/src/field-schema.json

@@ -17,6 +17,11 @@
       "description": "The id of the email field whose value the API copies to subject_email. It must name an email field. Omit it when the form has one email field (that field is the contact); it is required with two or more.",
       "$ref": "#/$defs/id"
     },
+    "newsletter_audience_id": {
+      "description": "The active manual newsletter audience on the form's site that receives the reader after email confirmation. Omit it for newsletter only. The server checks ownership and availability when saving.",
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    },
     "submit_label": {
       "description": "The text on the submit button. Omit it for Taproot's default. Must contain more than whitespace; the validator also rejects a blank label, which a schema cannot express.",
       "type": "string",

package/src/field-validation.js

@@ -106,7 +106,7 @@ export function contactFieldId(definition) {
     const emails = definition.fields.filter((field) => field.type === "email");
     return emails.length === 1 ? emails[0].id : undefined;
 }
-const DEFINITION_KEYS = ["fields", "contact_field", "submit_label", "after_submit"];
+const DEFINITION_KEYS = ["fields", "contact_field", "submit_label", "after_submit", "newsletter_audience_id"];
 const BASE_FIELD_KEYS = ["id", "type", "label", "hint"];
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const isInteger = (value) => typeof value === "number" && Number.isInteger(value);
@@ -427,6 +427,10 @@ export function validateDefinition(definition) {
 }
 /** The button text and the after-submit choice, which sit beside the fields in a definition. */
 function validateFormSettings(definition, errors) {
+    const audience = definition.newsletter_audience_id;
+    if (audience !== undefined && (typeof audience !== "string" || !isResourceId(audience))) {
+        errors.push({ path: "newsletter_audience_id", code: "invalid_newsletter_audience" });
+    }
     const label = definition.submit_label;
     if (label !== undefined && (typeof label !== "string" || isBlank(label) || label.length > MAX_SUBMIT_LABEL_LENGTH)) {
         errors.push({ path: "submit_label", code: "invalid_submit_label" });

package/src/forms-api.js

@@ -1,7 +1,7 @@
 import { listSitePages, sitePath } from "./api.js";
 import { HTTP_NOT_FOUND } from "./constants.js";
 import { isCanonicalUuid, SiteAuthoringError } from "./errors.js";
-import { FORM_DEFAULT_SINK, FORM_SINKS, isFormKey, normalizePagePath } from "./forms-contract.js";
+import { FORM_DEFAULT_NOTIFY_OWNER, FORM_DEFAULT_SINK, FORM_SINKS, isFormKey, normalizePagePath } from "./forms-contract.js";
 import { ApiError } from "./transport.js";
 
 /**
@@ -38,12 +38,16 @@ function normalizeForm(value) {
   if (!isCanonicalUuid(value.id) || !isFormKey(value.key)) {
     throw contract("Taproot returned a form with no usable id or a key this workspace cannot store.", "form");
   }
+  if (Object.hasOwn(value, "notifyOwner") && typeof value.notifyOwner !== "boolean") {
+    throw contract("Taproot returned an owner notification setting that is not a boolean.", "notifyOwner");
+  }
   return {
     id: value.id,
     key: value.key,
     name: typeof value.name === "string" ? value.name : "",
     sink: sinkFromWire(value.sink),
     retentionDays: Number.isSafeInteger(value.retentionDays) ? value.retentionDays : undefined,
+    notifyOwner: value.notifyOwner ?? FORM_DEFAULT_NOTIFY_OWNER,
     archived: value.status === STATUS_ARCHIVED_WIRE,
     currentVersion: Number.isSafeInteger(value.currentVersion) ? value.currentVersion : 0,
   };
@@ -140,6 +144,7 @@ export async function createSiteForm(client, siteId, form) {
         name: form.name,
         sink: SINK_WIRE[form.sink],
         retentionDays: form.retention_days,
+        notifyOwner: form.notify_owner,
         definition: JSON.stringify(form.definition),
       },
       maximumResponseBytes: FORMS_RESPONSE_BYTES,
@@ -160,12 +165,14 @@ export async function updateSiteFormSettings(client, siteId, formId, form, expec
         name: form.name,
         sink: SINK_WIRE[form.sink],
         retentionDays: form.retention_days,
+        notifyOwner: form.notify_owner,
         ...(expected === undefined
           ? {}
           : {
             expectedName: expected.name,
             expectedSink: SINK_WIRE[expected.sink],
             expectedRetentionDays: expected.retention_days,
+            expectedNotifyOwner: expected.notify_owner,
           }),
       },
       maximumResponseBytes: FORMS_RESPONSE_BYTES,

package/src/forms-contract.js

@@ -5,7 +5,7 @@ import { contactFieldId, validateDefinition } from "./field-validation.js";
  * The workspace contract for a form (TR01061).
  *
  * A form is one JSON file, `forms/<key>.json`, holding what an author decides:
- * its key, name, sink, retention and definition. The definition holds the fields
+ * its key, name, sink, retention, owner-notification preference and definition. The definition holds the fields
  * and the form's own settings (`contact_field`, `submit_label`, `after_submit`),
  * exactly as the site stores it, so one validator reads one shape. The
  * definition's own rules belong to `shared/field-validation.ts` and are run
@@ -27,6 +27,7 @@ export const FORM_KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
 export const FORM_KEY_MAXIMUM_LENGTH = 64;
 export const FORM_SINKS = Object.freeze(["none", "newsletter"]);
 export const FORM_DEFAULT_SINK = "none";
+export const FORM_DEFAULT_NOTIFY_OWNER = false;
 export const FORM_RETENTION_DAYS = Object.freeze({ minimum: 30, maximum: 730, default: 365 });
 export const FORM_LIMITS = Object.freeze({
   nameCharacters: 120,
@@ -35,7 +36,7 @@ export const FORM_LIMITS = Object.freeze({
   fileBytes: 256 * 1024,
 });
 
-const FORM_FILE_KEYS = ["key", "name", "sink", "retention_days", "definition"];
+const FORM_FILE_KEYS = ["key", "name", "sink", "retention_days", "notify_owner", "definition"];
 // The order `forms pull` writes, which `forms push` writes back after a save.
 // Fixed rather than inherited from the response so the same form is always the
 // same bytes.
@@ -101,14 +102,24 @@ function describeDefinitionErrors(errors) {
   return `${shown.join("; ")}${more}`;
 }
 
+/** Checks newsletter admission after the definition has passed shared validation. */
+export function validateNewsletterDefinition(file, definition) {
+  const fields = definition.fields;
+  const contact = fields.find((field) => field.id === contactFieldId(definition));
+  if (contact?.type !== "email" || contact.required !== true || !fields.some((field) => field.type === "consent")) {
+    throw invalid(file, "a newsletter sink requires a required email contact field and at least one consent checkbox.", "definition");
+  }
+}
+
 /**
  * Validates one parsed form file and returns it unchanged in meaning.
  *
  * `expectedKey` is the key the file's name promises; a mismatch is refused
  * because a rename on disk would otherwise push a different form than the one
  * the author thinks they are editing.
+ * Only `forms push` defers newsletter admission until it compares the site's baseline.
  */
-export function validateFormDocument(document_, expectedKey) {
+export function validateFormDocument(document_, expectedKey, { deferNewsletterSemantics = false } = {}) {
   const file = formFileName(expectedKey);
   if (!isPlainObject(document_)) throw invalid(file, "the file must contain one JSON object.", "$");
   for (const name of Object.keys(document_)) {
@@ -138,6 +149,9 @@ export function validateFormDocument(document_, expectedKey) {
   if (document_.sink !== undefined && !FORM_SINKS.includes(document_.sink)) {
     throw invalid(file, `sink must be one of: ${FORM_SINKS.join(", ")}.`, "sink");
   }
+  if (Object.hasOwn(document_, "notify_owner") && typeof document_.notify_owner !== "boolean") {
+    throw invalid(file, "notify_owner must be true or false.", "notify_owner");
+  }
   const days = document_.retention_days;
   if (
     days !== undefined
@@ -156,6 +170,7 @@ export function validateFormDocument(document_, expectedKey) {
   if (errors.length > 0) {
     throw invalid(file, `the definition is invalid: ${describeDefinitionErrors(errors)}`, "definition");
   }
+  if (document_.sink === "newsletter" && !deferNewsletterSemantics) validateNewsletterDefinition(file, document_.definition);
   if (anyUnstorableString(document_.definition)) {
     throw invalid(file, "the definition cannot contain NUL or unpaired surrogate characters.", "definition");
   }
@@ -238,6 +253,16 @@ function rejectNonTarget(file, pages, id, field, name) {
   );
 }
 
+/** Operational settings in the same order for workspace files and saved baselines. */
+export function projectFormSettings(form) {
+  return {
+    name: form.name,
+    sink: form.sink ?? FORM_DEFAULT_SINK,
+    retention_days: form.retention_days ?? FORM_RETENTION_DAYS.default,
+    notify_owner: form.notify_owner ?? FORM_DEFAULT_NOTIFY_OWNER,
+  };
+}
+
 function canonicalField(field) {
   const ordered = {};
   for (const name of FIELD_KEY_ORDER) if (field[name] !== undefined) ordered[name] = field[name];
@@ -266,9 +291,7 @@ export function projectFormForWorkspace(form, pathById) {
   }
   return {
     key: form.key,
-    name: form.name,
-    sink: form.sink ?? FORM_DEFAULT_SINK,
-    retention_days: form.retention_days ?? FORM_RETENTION_DAYS.default,
+    ...projectFormSettings(form),
     definition,
   };
 }