@stack-mode/site-manager-kit 0.0.0-stage → 1.44.1

package/src/config.ts

@@ -0,0 +1,78 @@
+import type { NextConfig } from "next";
+import { VISUAL_COOKIE } from "./preview";
+
+// For next.config.ts. Use it inside withBotId: withBotId(withSiteManager({ ... })).
+
+type Header = { key: string; value: string };
+type HeaderRule = Awaited<ReturnType<NonNullable<NextConfig["headers"]>>>[number];
+
+export type SiteManagerConfigOptions = {
+  /** Browser features to switch off for every page. Default: camera, microphone and USB. Payment and location stay on for checkout and maps. */
+  disableFeatures?: string[];
+  /** Send HSTS for subdomains too. Only when every subdomain serves HTTPS. Default true. */
+  hstsSubdomains?: boolean;
+  /** Who may show this site in a frame: "SAMEORIGIN" (default) or "DENY". */
+  frameOptions?: "SAMEORIGIN" | "DENY";
+};
+
+/** The baseline security headers, so every website connected to Site Manager sends the same ones. */
+export function securityHeaders(opts: SiteManagerConfigOptions = {}): Header[] {
+  const features = opts.disableFeatures ?? ["camera", "microphone", "usb"];
+  return [
+    { key: "X-Content-Type-Options", value: "nosniff" },
+    { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
+    { key: "X-Frame-Options", value: opts.frameOptions ?? "SAMEORIGIN" },
+    { key: "Permissions-Policy", value: features.map((f) => `${f}=()`).join(", ") },
+    { key: "Strict-Transport-Security", value: `max-age=63072000${opts.hstsSubdomains === false ? "" : "; includeSubDomains"}` },
+  ];
+}
+
+/** Where Site Manager's uploaded media lives, so next/image can resize it. */
+export const MEDIA_REMOTE_PATTERN = { protocol: "https", hostname: "*.public.blob.vercel-storage.com" } as const;
+
+const FRAME_ANCESTORS = /^frame-ancestors(\s|$)/i;
+
+/**
+ * Lets the Visual Editor show the site when the site sets its own Content-Security-Policy here, where there is no
+ * request to read the editor's address from. A browser that opened the page from the Visual Editor (it has the visual
+ * cookie) gets the same policy without its frame-ancestors; visualFrameHeaders in the proxy then adds frame-ancestors
+ * for the signed Site Manager address only. X-Frame-Options stays on every response, so a cookie the proxy doesn't
+ * accept, or a path the proxy doesn't run on, still can't be framed: browsers ignore X-Frame-Options only when a
+ * frame-ancestors is present.
+ */
+export function allowVisualFrames(rules: HeaderRule[]): HeaderRule[] {
+  const cookie = { type: "cookie" as const, key: VISUAL_COOKIE };
+  return rules.flatMap((rule) => {
+    const csp = rule.headers.find(
+      (h) => h.key.toLowerCase() === "content-security-policy" && h.value.split(";").some((d) => FRAME_ANCESTORS.test(d.trim())),
+    );
+    if (!csp) return [rule];
+    const policy = csp.value
+      .split(";")
+      .map((d) => d.trim())
+      .filter((d) => d && !FRAME_ANCESTORS.test(d))
+      .join("; ");
+    return [
+      { ...rule, missing: [...(rule.missing ?? []), cookie] },
+      { ...rule, has: [...(rule.has ?? []), cookie], headers: rule.headers.map((h) => (h === csp ? { key: h.key, value: policy } : h)) },
+    ];
+  });
+}
+
+/**
+ * Adds the baseline security headers to every route, lets next/image resize Site Manager's media, and stops sending
+ * X-Powered-By. Keeps everything already in the config: its own headers come after these, so a site can override one.
+ * A Content-Security-Policy of its own keeps working with the Visual Editor (allowVisualFrames).
+ */
+export function withSiteManager(config: NextConfig = {}, opts: SiteManagerConfigOptions = {}): NextConfig {
+  const own = config.headers;
+  const patterns = config.images?.remotePatterns ?? [];
+  return {
+    ...config,
+    poweredByHeader: false,
+    images: { ...config.images, remotePatterns: [...patterns, MEDIA_REMOTE_PATTERN] },
+    async headers() {
+      return allowVisualFrames([{ source: "/:path*", headers: securityHeaders(opts) }, ...(own ? await own() : [])]);
+    },
+  };
+}

package/src/copy-keys-route.ts

@@ -0,0 +1,21 @@
+import { declaredKeys, declaredLists, type CopyKeyDef, type CopyListRule } from "./copy-keys";
+import { SIGNATURE_HEADER, verify } from "./signature";
+import { KIT_VERSION } from "./version";
+
+/**
+ * Site Manager's Sync from Website reads the site's declared copy keys here. Put in
+ * app/api/blueprint/copy-keys/route.ts:
+ *
+ *   import { copyKeysRoute } from "site-manager-kit/copy-keys-route";
+ *   import { COPY } from "@/copy-keys";
+ *   export const GET = copyKeysRoute(COPY);
+ *
+ * Signed like the health route, over an empty body. Unsigned requests get a 401. Sends the keys and the list rules.
+ */
+export function copyKeysRoute(copy: { __defs: Record<string, CopyKeyDef>; __lists?: Record<string, CopyListRule> }): (req: Request) => Promise<Response> {
+  return async (req) => {
+    const check = verify(process.env.BLUEPRINT_REVALIDATE_SECRET, req.headers.get(SIGNATURE_HEADER), "");
+    if (!check.ok) return Response.json({ error: check.reason }, { status: 401 });
+    return Response.json({ kitVersion: KIT_VERSION, keys: declaredKeys(copy), lists: declaredLists(copy) }, { headers: { "cache-control": "no-store" } });
+  };
+}

package/src/copy-keys.ts

@@ -0,0 +1,77 @@
+// A site's built-in text and photos, declared in its own code so Site Manager can create them as Site Copy keys
+// (Site Copy > Sync from Website). Site Manager checks every definition again when it syncs; this file checks only
+// what would break the site's build.
+
+export const copyKeyPattern = /^[a-z0-9]+([._-][a-z0-9]+)*$/;
+
+// page (1.41.0): the page the value belongs to, like "/about", so Site Manager's Pages files a new key under it.
+// Left out for values shared across pages. Used only when Sync adds the key; Site Manager's own choice wins after.
+export type CopyKeyDef =
+  | { label: string; kind: "text" | "rich"; maxLength?: number; helpText?: string; text: string; page?: string }
+  | { label: string; kind: "image"; helpText?: string; image: string; alt: string; page?: string };
+
+/**
+ * What Site Manager's Pages may do with a list of items (`<path>.1.title`, `<path>.2.title`, ...): move them, and
+ * add or remove them. Adding and removing works on the declared slots, so declare as many items as the page has room
+ * for and show only the ones with something in them. Leave a list out when anything about an item stays in code by
+ * position (an icon, a link), since it would no longer match the words after a move.
+ */
+export type CopyListRule = { reorder?: boolean; addRemove?: boolean };
+
+export type CopyKeys<T extends Record<string, CopyKeyDef>> = { readonly [K in keyof T]: K } & {
+  readonly __defs: T;
+  readonly __lists: Record<string, CopyListRule>;
+};
+
+/**
+ * Returns an object whose properties are the key names (`COPY["home.hero.title"] === "home.hero.title"`), so pages
+ * never type a key string twice, plus the definitions for the copy keys route. Throws at module load on a bad key, a
+ * missing or long label, or an image path outside the site's own files, so a mistake fails the site's build.
+ */
+export function defineCopyKeys<T extends Record<string, CopyKeyDef>>(keys: T, options: { lists?: Record<string, CopyListRule> } = {}): CopyKeys<T> {
+  const out: Record<string, unknown> = {};
+  for (const [key, def] of Object.entries(keys)) {
+    if (key.length > 80 || !copyKeyPattern.test(key)) {
+      throw new Error(`Copy key "${key}": use lowercase letters and numbers separated by dots, dashes or underscores, up to 80 characters.`);
+    }
+    if (!def.label?.trim() || def.label.length > 120) throw new Error(`Copy key "${key}": the label must be 1 to 120 characters.`);
+    if (def.page !== undefined && !/^\/(?!\/)[^?#\\]*$/.test(def.page)) throw new Error(`Copy key "${key}": the page must be a path on the site, like /about.`);
+    if (def.kind === "image" && !/^\/(?!\/)[^?#\\]*$/.test(def.image)) {
+      throw new Error(`Copy key "${key}": the image must be a path under public/, like /images/hero.jpg.`);
+    }
+    out[key] = key;
+  }
+  const lists = options.lists ?? {};
+  for (const path of Object.keys(lists)) {
+    if (path.length > 80 || !copyKeyPattern.test(path)) throw new Error(`Copy list "${path}": use the key rules for a list's path.`);
+    if (!Object.keys(keys).some((k) => k === `${path}.1` || k.startsWith(`${path}.1.`))) {
+      throw new Error(`Copy list "${path}": declare its items as ${path}.1..., ${path}.2... and so on.`);
+    }
+  }
+  Object.defineProperty(out, "__defs", { value: keys, enumerable: false });
+  Object.defineProperty(out, "__lists", { value: lists, enumerable: false });
+  return out as CopyKeys<T>;
+}
+
+export type DeclaredCopyKey =
+  | { key: string; label: string; kind: "text" | "rich"; maxLength: number | null; helpText: string | null; text: string; page?: string }
+  | { key: string; label: string; kind: "image"; maxLength: null; helpText: string | null; image: string; alt: string; page?: string };
+
+/** The list rules as the copy keys route sends them: only lists that allow something. */
+export function declaredLists(copy: { __lists?: Record<string, CopyListRule> }): Record<string, { reorder: boolean; addRemove: boolean }> {
+  const out: Record<string, { reorder: boolean; addRemove: boolean }> = {};
+  for (const [path, r] of Object.entries(copy.__lists ?? {})) {
+    // Adding and removing moves the items after it, so it always allows reordering too.
+    if (r.reorder || r.addRemove) out[path] = { reorder: true, addRemove: !!r.addRemove };
+  }
+  return out;
+}
+
+/** The definitions as the copy keys route sends them. */
+export function declaredKeys(copy: { __defs: Record<string, CopyKeyDef> }): DeclaredCopyKey[] {
+  return Object.entries(copy.__defs).map(([key, d]) =>
+    d.kind === "image"
+      ? { key, label: d.label, kind: "image", maxLength: null, helpText: d.helpText ?? null, image: d.image, alt: d.alt, ...(d.page ? { page: d.page } : {}) }
+      : { key, label: d.label, kind: d.kind, maxLength: d.maxLength ?? null, helpText: d.helpText ?? null, text: d.text, ...(d.page ? { page: d.page } : {}) },
+  );
+}

package/src/data.ts

@@ -0,0 +1,189 @@
+import { bp, bpWithMeta, tagsFor } from "./client";
+import type { CopyLink, Glossary, GlossaryTerm, ReviewPlatform } from "./types";
+import type { Amenity, Announcement, Area, BookingDays, CopyValue, Download, DownloadCategory, Event, Faq, FaqSet, Fee, FloorPlan, Form, Image, LegalDoc, LegalSummary, Listing, ListingDetail, ListingFilters, Location, NearbyPlace, Parking, PaymentDefaults, PetPolicy, Policies, ResidentSection, Review, Service, Site, Special, TeamMember, Unit, UnitMap, WaitlistOptions } from "./types";
+import { announcementsLiveAt, cachedUntilPassed } from "./announcements";
+import { visualMode } from "./visual-mode";
+import { tagCopy } from "./visual-tags";
+
+// Typed reads for every content module. Each is cached under its module's tag, so a change in Site Manager
+// refreshes exactly what it affects. A module that's off for the site answers 403 and throws.
+
+const q = (params: Record<string, string | number | boolean | undefined | null>) => {
+  const sp = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) if (v !== undefined && v !== null && v !== false) sp.set(k, v === true ? "1" : String(v));
+  const s = sp.toString();
+  return s ? `?${s}` : "";
+};
+
+export const getSite = () => bp<Site>("/site", { tags: tagsFor("business_info") });
+
+/** Site Copy as stored, never tagged. The Visual Editor's word matching reads this. */
+export const getCopyUntagged = async () => (await bp<Record<string, CopyValue>>("/copy", { tags: tagsFor("site_copy") })) ?? {};
+
+/**
+ * Every Site Copy value by key. In Site Manager's Visual Editor (and only there) each text and rich value carries an
+ * invisible tag naming it, which the editor removes from the page; see src/visual-tags.ts.
+ */
+export async function getCopy(): Promise<Record<string, CopyValue>> {
+  const all = await getCopyUntagged();
+  return (await visualMode()) ? tagCopy(all) : all;
+}
+
+/** One copy value's text or HTML, or the fallback when it isn't set. */
+export async function copyText(key: string, fallback = ""): Promise<string> {
+  const v = (await getCopy())[key];
+  if (!v) return fallback;
+  if (v.kind === "rich") return v.html ?? fallback;
+  return v.kind === "text" ? (v.text ?? fallback) : fallback;
+}
+
+/** A built-in photo from Site Copy (an image key), or null when it isn't set. */
+export async function copyImage(key: string): Promise<Image | null> {
+  const v = (await getCopy())[key];
+  return v?.kind === "image" ? v.image : null;
+}
+
+/**
+ * Where a link key points (Site Manager's Pages): `{ href, label }`, or null when it isn't set or its record is hidden
+ * or gone, so a button can be left out rather than linking nowhere.
+ */
+export async function copyLink(key: string): Promise<CopyLink | null> {
+  const v = (await getCopy())[key];
+  return v?.kind === "link" && v.link?.href ? v.link : null;
+}
+
+/**
+ * The records a records key picked (which reviews, which FAQ set...), in order, in their module's own shape, such as
+ * `copyRecords<Review>("home.reviews")`. Hidden ones are already left out.
+ */
+export async function copyRecords<T = unknown>(key: string): Promise<T[]> {
+  const v = (await getCopy())[key];
+  return v?.kind === "records" ? (v.items as T[]) : [];
+}
+
+/** The site's review platforms (Reviews > Platforms) in order, with logos, for a badge row or a review link list. */
+export const getReviewPlatforms = async () => {
+  const r = await bpWithMeta<unknown[]>("/reviews", { tags: tagsFor("reviews") });
+  return ((r?.meta as { platforms?: ReviewPlatform[] } | undefined)?.platforms ?? []) as ReviewPlatform[];
+};
+
+/** The glossary index: categories and published terms, alphabetically. */
+export const getGlossary = async () => (await bp<Glossary>("/glossary", { tags: tagsFor("glossary") })) ?? { categories: [], terms: [] };
+
+/** One published term with everything on it and its neighbors, or null for an unknown or hidden one. */
+export const getGlossaryTerm = (slug: string) => bp<GlossaryTerm>(`/glossary/${encodeURIComponent(slug)}`, { tags: tagsFor("glossary") });
+
+/** Published reviews, in the order set in Site Manager (Reviews > Order) or, with `sort: "date"`, newest first. */
+export const getReviews = async (opts: { featured?: boolean; sort?: "custom" | "date" } = {}) =>
+  (await bp<Review[]>(`/reviews${q({ featured: opts.featured, sort: opts.sort === "date" ? "date" : undefined })}`, { tags: tagsFor("reviews") })) ?? [];
+
+export const getFloorPlans = async () => (await bp<FloorPlan[]>("/floor-plans", { tags: tagsFor("floor_plans") })) ?? [];
+
+export const getFloorPlan = (slug: string) => bp<FloorPlan & { units: Unit[] }>(`/floor-plans/${encodeURIComponent(slug)}`, { tags: tagsFor("floor_plans") });
+
+/** Site plan drawings with open units placed on them, cached with floor plans. */
+export const getUnitMaps = async () => (await bp<UnitMap[]>("/unit-maps", { tags: tagsFor("floor_plans") })) ?? [];
+
+/** The plans and bedroom counts a waitlist form can offer. Cached with floor plans, since availability decides it. */
+export const getWaitlistOptions = async () => (await bp<WaitlistOptions>("/waitlist", { tags: tagsFor("floor_plans", "waitlist") })) ?? { floorPlans: [], bedrooms: [] };
+
+export const getAmenities = async (opts: { category?: "community" | "apartment" } = {}) => (await bp<Amenity[]>(`/amenities${q({ category: opts.category })}`, { tags: tagsFor("amenities") })) ?? [];
+
+export const getFees = async () => (await bp<{ fees: Fee[]; requiredMonthlyTotal: string | null }>("/fees", { tags: tagsFor("fees") })) ?? { fees: [], requiredMonthlyTotal: null };
+
+export const getPetPolicy = () => bp<PetPolicy>("/pet-policy", { tags: tagsFor("pet_policy") });
+
+export const getParking = () => bp<Parking>("/parking", { tags: tagsFor("parking") });
+
+/** The residents page: visible sections with something in them, in the order set in Site Manager. */
+export const getResidentResources = async () => (await bp<ResidentSection[]>("/resident-resources", { tags: tagsFor("resident_resources") })) ?? [];
+
+/** Leasing policies: application, fees, deposit, lease lengths, smoking, guests, insurance and extra policies. */
+export const getPolicies = () => bp<Policies>("/policies", { tags: tagsFor("policies") });
+
+export const getSpecials = async () => (await bp<Special[]>("/specials", { tags: tagsFor("specials") })) ?? [];
+
+export const getEvents = async (opts: { from?: string; limit?: number } = {}) => (await bp<Event[]>(`/events${q(opts)}`, { tags: tagsFor("events") })) ?? [];
+
+export const getEvent = (slug: string) => bp<Event>(`/events/${encodeURIComponent(slug)}`, { tags: tagsFor("events") });
+
+/** Published services in the order set in Site Manager, optionally one category (matched without regard to case). */
+export const getServices = async (opts: { category?: string } = {}) => (await bp<Service[]>(`/services${q({ category: opts.category })}`, { tags: tagsFor("services") })) ?? [];
+
+/** One published service, or null when it doesn't exist or is a draft. */
+export const getService = (slug: string) => bp<Service>(`/services/${encodeURIComponent(slug)}`, { tags: tagsFor("services") });
+
+export const getLocations = async () => (await bp<Location[]>("/locations", { tags: tagsFor("locations") })) ?? [];
+
+export const getNearbyPlaces = async (opts: { category?: string } = {}) => (await bp<NearbyPlace[]>(`/nearby-places${q({ category: opts.category })}`, { tags: tagsFor("nearby_places") })) ?? [];
+
+export const getForm = (key: string) => bp<Form>(`/forms/${encodeURIComponent(key)}`, { tags: tagsFor("forms") });
+
+export const getLegal = async () => (await bp<LegalSummary[]>("/legal", { tags: tagsFor("legal") })) ?? [];
+
+export const getLegalDoc = (slug: string) => bp<LegalDoc>(`/legal/${encodeURIComponent(slug)}`, { tags: tagsFor("legal") });
+
+/**
+ * A booking form's open times, never cached: they change with every booking. `from` is a YYYY-MM-DD date in the
+ * site's time zone (default today), `days` up to 60. Null when the form isn't a booking form.
+ */
+export const getBookingSlots = (key: string, opts: { from?: string; days?: number } = {}) =>
+  bp<BookingDays>(`/forms/${encodeURIComponent(key)}/slots${q(opts)}`, { cache: "no-store" });
+
+// Listings show their agent's card, so they refresh when the team changes too.
+const listingTags = () => tagsFor("listings", "team_members");
+
+/**
+ * Listings on the website, active first then newest, each with a cover photo and agent. Every filter is optional;
+ * prices are compared to the sold price for sold listings. Site Manager answers 400 for a filter it can't read.
+ */
+export const getListings = async (filters: ListingFilters = {}) => {
+  const status = Array.isArray(filters.status) ? filters.status.join(",") : filters.status;
+  // Which listings are in an area follows the area's names, so an area filter refreshes when areas change too.
+  const tags = filters.area ? [...listingTags(), ...tagsFor("areas")] : listingTags();
+  return (await bp<Listing[]>(`/listings${q({ ...filters, status })}`, { tags })) ?? [];
+};
+
+/**
+ * Sold listings in the usual list order, newest listed first, for a sold portfolio or "recently sold" section. Each carries
+ * `soldPrice` and `soldOn`; price filters compare the sold price. Same as `getListings({ ...filters, status: "sold" })`.
+ */
+export const getSoldListings = (filters: Omit<ListingFilters, "status"> = {}) => getListings({ ...filters, status: "sold" });
+
+/** Published area guides in Site Manager's order, each with `listingCount` (homes for sale now; null without Listings). */
+export const getAreas = async () => (await bp<Area[]>("/areas", { tags: tagsFor("areas", "listings") })) ?? [];
+
+/** One published area guide. Null when it isn't on the website. Its homes: `getListings({ area: slug })`. */
+export const getArea = (slug: string) => bp<Area>(`/areas/${encodeURIComponent(slug)}`, { tags: tagsFor("areas", "listings") });
+
+/** One listing with every photo, its features, schools and price history. Null when it isn't on the website. */
+export const getListing = (slug: string) => bp<ListingDetail>(`/listings/${encodeURIComponent(slug)}`, { tags: listingTags() });
+
+/** The site's numbers for `estimatePayment`. */
+export const getPaymentDefaults = async () =>
+  (await bp<PaymentDefaults>("/payment-defaults", { tags: tagsFor("listings") })) ?? { ratePercent: null, downPaymentPercent: null, termYears: null, taxRatePercent: null, insuranceYearly: null };
+
+export const getTeam = async () => (await bp<TeamMember[]>("/team", { tags: tagsFor("team_members") })) ?? [];
+
+export const getTeamMember = (slug: string) => bp<TeamMember>(`/team/${encodeURIComponent(slug)}`, { tags: tagsFor("team_members") });
+
+/** Published questions in category order, then their own order. `category` is a category's slug. */
+export const getFaq = async (opts: { category?: string } = {}) => (await bp<Faq>(`/faq${q({ category: opts.category })}`, { tags: tagsFor("faq") })) ?? { categories: [], questions: [] };
+
+/** A named set of questions a page asks for by key (like "leasing-page"), in the set's order. Null for an unknown key. */
+export const getFaqSet = (key: string) => bp<FaqSet>(`/faq/sets/${encodeURIComponent(key)}`, { tags: tagsFor("faq") });
+
+/**
+ * Notices live now, urgent first. Never shown past an end or before a start: the cached copy is used only until the
+ * time Site Manager says the list next changes, then read fresh, and the list is filtered by `now` again. Call it
+ * where the request time is known (after `connection()` with Cache Components), not in a prerendered shell.
+ */
+export async function getAnnouncements(now = new Date()): Promise<Announcement[]> {
+  const tags = tagsFor("announcements");
+  let r = await bpWithMeta<Announcement[]>("/announcements", { tags });
+  if (r && !cachedUntilPassed(r.meta, now)) r = await bpWithMeta<Announcement[]>("/announcements", { tags, cache: "no-store" });
+  return announcementsLiveAt(r?.data ?? [], now);
+}
+
+/** Published downloads in the order set in Site Manager. Link to `url` so each download is counted. */
+export const getDownloads = async (opts: { category?: DownloadCategory } = {}) => (await bp<Download[]>(`/downloads${q({ category: opts.category })}`, { tags: tagsFor("downloads") })) ?? [];

package/src/downloads.ts

@@ -0,0 +1,7 @@
+/** A file size for a download link, like "840 KB" or "2.4 MB". Empty when the size isn't a usable number. */
+export function fileSizeText(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return "";
+  if (bytes < 1024) return `${bytes} bytes`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}

package/src/faq.ts

@@ -0,0 +1,21 @@
+import type { FaqQuestion } from "./types";
+
+type Json = Record<string, unknown>;
+
+/**
+ * schema.org `FAQPage` structured data for the questions a page shows. Use it only on a page that shows these
+ * questions and answers. Answers are Site Manager's sanitized HTML, which search engines accept in `text`.
+ * Render it with `jsonLdScript`, which escapes `<` so an answer can't close the script tag.
+ */
+export function faqJsonLd(questions: Pick<FaqQuestion, "question" | "answerHtml">[]): Json {
+  return {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    mainEntity: questions.map((q) => ({ "@type": "Question", name: q.question, acceptedAnswer: { "@type": "Answer", text: q.answerHtml } })),
+  };
+}
+
+/** JSON-LD as text for `<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: jsonLdScript(data) }} />`. */
+export function jsonLdScript(data: Json): string {
+  return JSON.stringify(data).replace(/</g, "\\u003c");
+}

package/src/floor-plans.ts

@@ -0,0 +1,45 @@
+import { formatMoney } from "./money";
+import type { Availability, FloorPlan } from "./types";
+
+/**
+ * What a plan card should say about availability. Follows the site's setting in Site Manager: the count only when
+ * the site chose to show it. Falls back to availableCount for Site Manager versions without `availability`.
+ */
+export function availabilityText(plan: Pick<FloorPlan, "availability" | "availableCount">, labels: { available?: string; none?: string; unknown?: string } = {}): string | null {
+  const a: Availability = plan.availability ?? (plan.availableCount === null ? { status: "unknown", count: null } : { status: plan.availableCount > 0 ? "available" : "none", count: null });
+  if (a.status === "unknown") return labels.unknown ?? null;
+  if (a.status === "none") return labels.none ?? "Join the waitlist";
+  if (a.count !== null) return `${a.count} available`;
+  return labels.available ?? "Available now";
+}
+
+/** "$2,207.12 effective with 6 weeks free" style copy for a plan with a running concession, or null. */
+export function effectiveRentText(plan: Pick<FloorPlan, "concession">): string | null {
+  const c = plan.concession;
+  if (!c) return null;
+  return `${formatMoney(c.effectiveRent, { cents: true })} effective`;
+}
+
+export type ComparisonRow = { label: string; values: (string | null)[] };
+
+/**
+ * Rows for a side by side table of plans: the facts every plan has, then one row per feature any plan lists, marked
+ * "Yes" or left empty. Values are display text; null means the plan doesn't say.
+ */
+export function comparisonRows(plans: FloorPlan[]): ComparisonRow[] {
+  const sqft = (p: FloorPlan) => (p.sqftMin === null ? null : p.sqftMax && p.sqftMax !== p.sqftMin ? `${p.sqftMin.toLocaleString("en-US")} to ${p.sqftMax.toLocaleString("en-US")}` : p.sqftMin.toLocaleString("en-US"));
+  const layouts = { flat: "Single level", townhome: "Townhome", loft: "Loft", penthouse: "Penthouse" } as const;
+  const rows: ComparisonRow[] = [
+    { label: "Bedrooms", values: plans.map((p) => (p.beds === 0 ? "Studio" : String(p.beds))) },
+    { label: "Bathrooms", values: plans.map((p) => p.baths.replace(/\.0$/, "")) },
+    { label: "Square feet", values: plans.map(sqft) },
+    { label: "Starting at", values: plans.map((p) => formatMoney(p.startingRent)) },
+    { label: "With special", values: plans.map((p) => effectiveRentText(p)) },
+    { label: "Layout", values: plans.map((p) => (p.layout ? layouts[p.layout] : null)) },
+    { label: "Levels", values: plans.map((p) => (p.levels ? String(p.levels) : null)) },
+    { label: "Availability", values: plans.map((p) => availabilityText(p)) },
+  ].filter((r) => r.values.some((v) => v !== null));
+  const features: string[] = [];
+  for (const p of plans) for (const f of p.features ?? []) if (!features.includes(f)) features.push(f);
+  return [...rows, ...features.map((f) => ({ label: f, values: plans.map((p) => ((p.features ?? []).includes(f) ? "Yes" : null)) }))];
+}

package/src/form-guard.tsx

@@ -0,0 +1,37 @@
+import { connection } from "next/server";
+import { Suspense } from "react";
+import { AttributionFields } from "./attribution";
+import { issueFormToken } from "./form-token";
+
+export const HONEYPOT_FIELD = "bp_hp";
+export const TOKEN_FIELD = "bp_ts";
+
+/**
+ * Put inside every form that uses submitForm or formAction. It adds the signed render time and a hidden honeypot
+ * field that people never see but form-filling bots do. A server component: the token is signed on the server, for
+ * each visit, because a token signed once at build time would make every form on a static page "too old" a day
+ * later. The token sits in its own Suspense boundary, so with Cache Components the rest of the page stays static and
+ * only the token is filled in per request. It also carries where the visitor first came from (AttributionFields),
+ * when the layout has <SiteAttribution />.
+ */
+export function FormGuard() {
+  return (
+    <>
+      <Suspense fallback={null}>
+        <FormToken />
+      </Suspense>
+      <AttributionFields />
+      <div aria-hidden="true" style={{ position: "absolute", left: "-10000px", width: 1, height: 1, overflow: "hidden" }}>
+        <label>
+          Leave this empty
+          <input type="text" name={HONEYPOT_FIELD} tabIndex={-1} autoComplete="off" defaultValue="" />
+        </label>
+      </div>
+    </>
+  );
+}
+
+async function FormToken() {
+  await connection();
+  return <input type="hidden" name={TOKEN_FIELD} value={issueFormToken()} />;
+}

package/src/form-token.ts

@@ -0,0 +1,33 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+// A signed render time, so a form posted less than 3 seconds after it was shown (a bot, not a person) is refused.
+export const MIN_AGE_MS = 3000;
+export const MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+function secret(): string {
+  const s = process.env.BLUEPRINT_FORM_SECRET?.trim();
+  if (!s) throw new Error("BLUEPRINT_FORM_SECRET is not set");
+  return s;
+}
+
+const mac = (key: string, t: number) => createHmac("sha256", key).update(`form:${t}`).digest("hex");
+
+export function issueFormToken(now = Date.now(), key = secret()): string {
+  return `${now}.${mac(key, now)}`;
+}
+
+export type TokenCheck = { ok: true } | { ok: false; reason: "missing" | "bad" | "too_fast" | "expired" };
+
+export function checkFormToken(token: string | null | undefined, now = Date.now(), key = secret()): TokenCheck {
+  if (!token) return { ok: false, reason: "missing" };
+  const m = token.match(/^(\d{13})\.([0-9a-f]{64})$/);
+  if (!m) return { ok: false, reason: "bad" };
+  const t = Number(m[1]);
+  const expected = Buffer.from(mac(key, t));
+  const given = Buffer.from(m[2]);
+  if (expected.length !== given.length || !timingSafeEqual(expected, given)) return { ok: false, reason: "bad" };
+  const age = now - t;
+  if (age < MIN_AGE_MS) return { ok: false, reason: "too_fast" };
+  if (age > MAX_AGE_MS) return { ok: false, reason: "expired" };
+  return { ok: true };
+}

package/src/form-types.ts

@@ -0,0 +1,13 @@
+export type SubmitResult =
+  | { ok: true; id: string; successMessage: string }
+  | { ok: false; error: "invalid"; fields: Record<string, string> }
+  // A booking form's time was taken by someone else a moment ago: show the open times again.
+  | { ok: false; error: "slot_taken"; fields: Record<string, string> }
+  | { ok: false; error: "rejected" | "too_fast" | "rate_limited" | "unavailable" };
+
+/** A booking form's chosen time: the `start` of one of getBookingSlots' slots. (Not in forms.ts: a "use server" file
+ * can only export async functions.) */
+export const SLOT_FIELD = "bp_slot";
+
+/** Why the website's own checks thought a submission was spam. */
+export type SpamReason = "honeypot" | "too_fast" | "bot";

package/src/forms.ts

@@ -0,0 +1,76 @@
+"use server";
+
+import { createHash } from "node:crypto";
+import { headers } from "next/headers";
+import { bpRaw } from "./client";
+import { checkFormToken } from "./form-token";
+import { ATTRIBUTION_FIELD_NAMES, attributionFrom } from "./attribution-fields";
+import { SLOT_FIELD, type SpamReason, type SubmitResult } from "./form-types";
+
+const GUARD_FIELDS = new Set(["bp_hp", "bp_ts"]);
+
+async function isBot(): Promise<boolean> {
+  try {
+    const { checkBotId } = await import("botid/server");
+    const r = await checkBotId();
+    return r.isBot && !r.isVerifiedBot;
+  } catch {
+    // BotID isn't set up on this site. The honeypot and time check still apply.
+    return false;
+  }
+}
+
+export type SubmitOptions = {
+  /**
+   * The site checked how long the form was open itself (its own signed timer), or the send has no form at all (a
+   * remembered visitor's one-click download), so there's no FormGuard timer to check. The honeypot (when sent) and
+   * BotID still apply. Use only after the site's own checks; anything else should render FormGuard.
+   */
+  timedBySite?: boolean;
+};
+
+/**
+ * Sends one form to Site Manager from the site's server. Checks BotID, the honeypot and the 3-second render
+ * time first, hashes the visitor's IP (Site Manager never sees it), then forwards the fields.
+ *
+ * It returns the result, so use it from server code, or use formAction with useActionState in a client form.
+ */
+export async function submitForm(formKey: string, formData: FormData, opts: SubmitOptions = {}): Promise<SubmitResult> {
+  // Spam checks: a filled honeypot, a form sent too fast (or with a missing or stale timer), or BotID. Suspected
+  // spam still goes to Site Manager, marked, for its spam folder (where a real person caught by mistake can be
+  // rescued), and the visitor sees the usual thank-you, so bots learn nothing.
+  const token = opts.timedBySite ? { ok: true as const } : checkFormToken(String(formData.get("bp_ts") ?? ""));
+  const spam: SpamReason | null = String(formData.get("bp_hp") ?? "").trim() !== "" ? "honeypot" : !token.ok ? (token.reason === "too_fast" ? "too_fast" : "bot") : (await isBot()) ? "bot" : null;
+
+  const h = await headers();
+  const ip = h.get("x-real-ip") ?? h.get("x-forwarded-for")?.split(",")[0]?.trim() ?? "";
+  const data: Record<string, string> = {};
+  for (const [k, v] of formData.entries()) {
+    if (GUARD_FIELDS.has(k) || ATTRIBUTION_FIELD_NAMES.has(k) || k === SLOT_FIELD || k.startsWith("$ACTION") || typeof v !== "string") continue;
+    data[k] = v;
+  }
+
+  const { status, json } = await bpRaw(`/forms/${encodeURIComponent(formKey)}/submit`, {
+    data,
+    pageUrl: h.get("referer") ?? undefined,
+    ipHash: ip ? createHash("sha256").update(ip).digest("hex") : undefined,
+    userAgent: h.get("user-agent")?.slice(0, 500) ?? undefined,
+    attribution: attributionFrom(formData),
+    slot: typeof formData.get(SLOT_FIELD) === "string" && formData.get(SLOT_FIELD) ? String(formData.get(SLOT_FIELD)) : undefined,
+    // A Site Manager from before the spam folder ignores `spam` but still refuses a filled honeypot, so spam is
+    // never delivered as a lead there either.
+    ...(spam ? { spam, hp: `kit:${spam}` } : {}),
+  });
+  const body = json as { data?: { id: string; successMessage: string }; error?: { code: string; fields?: Record<string, string> } } | null;
+  if (spam) return { ok: true, id: body?.data?.id ?? "", successMessage: body?.data?.successMessage ?? "Thanks! We'll be in touch soon." };
+  if (status === 201 && body?.data) return { ok: true, id: body.data.id, successMessage: body.data.successMessage };
+  if (status === 422) return { ok: false, error: "invalid", fields: body?.error?.fields ?? {} };
+  if (status === 409) return { ok: false, error: "slot_taken", fields: body?.error?.fields ?? {} };
+  if (status === 429) return { ok: false, error: "rate_limited" };
+  return { ok: false, error: "unavailable" };
+}
+
+/** The same, shaped for React's useActionState: `useActionState(formAction.bind(null, "inquiry"), null)`. */
+export async function formAction(formKey: string, _prev: SubmitResult | null, formData: FormData): Promise<SubmitResult> {
+  return submitForm(formKey, formData);
+}

package/src/glossary.ts

@@ -0,0 +1,19 @@
+import type { GlossaryTerm } from "./types";
+
+type Json = Record<string, unknown>;
+
+/**
+ * schema.org `DefinedTerm` structured data for a term's own page, in the glossary named `setName` at `setUrl`.
+ * Render it with `jsonLdScript`.
+ */
+export function definedTermJsonLd(t: Pick<GlossaryTerm, "term" | "shortDefinition" | "url" | "alsoKnownAs">, set: { setName: string; setUrl?: string | null }): Json {
+  return {
+    "@context": "https://schema.org",
+    "@type": "DefinedTerm",
+    name: t.term,
+    description: t.shortDefinition,
+    ...(t.url ? { url: t.url } : {}),
+    ...(t.alsoKnownAs.length ? { alternateName: t.alsoKnownAs } : {}),
+    inDefinedTermSet: { "@type": "DefinedTermSet", name: set.setName, ...(set.setUrl ? { url: set.setUrl } : {}) },
+  };
+}