@stack-mode/site-manager-kit 1.44.0 → 1.45.0

package/src/copy-keys.ts

@@ -1,77 +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 } : {}) },
-  );
-}
+// 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

@@ -1,189 +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") })) ?? [];
+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

@@ -1,7 +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`;
-}
+/** 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

@@ -1,21 +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");
-}
+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");
+}