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

package/src/types.ts

@@ -1,580 +1,581 @@
-// Site Manager API v1 response shapes. Money is always a decimal string like "1450.00".
-
-export type Money = string;
-export type Hours = Record<"mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun", { closed: true } | { closed: false; open: string; close: string } | { closed: false; byAppointment: true }>;
-export type Image = { url: string; width: number | null; height: number | null; alt: string };
-export type Address = { line1: string; line2: string; city: string; region: string; postalCode: string; country: string };
-
-export type Site = {
-  name: string;
-  kind: "apartment" | "business" | "real_estate";
-  websiteUrl: string | null;
-  timezone: string;
-  modules: string[];
-  business: {
-    displayName: string;
-    legalName: string | null;
-    phone: string | null;
-    email: string | null;
-    address: Address;
-    geo: { lat: number; lng: number } | null;
-    hours: Hours | null;
-    hoursNote: string | null;
-    social: { network: string; url: string }[];
-    showEqualHousing: boolean | null;
-    // Search and maps facts (kit 1.42.0). Optional, so a site still builds against an older Site Manager; null or
-    // empty means not set.
-    /** A schema.org LocalBusiness type like "Plumber" or "ApartmentComplex". Null means LocalBusiness. */
-    schemaType?: string | null;
-    /** The Google Business Profile's main category, as typed there. */
-    primaryCategory?: string | null;
-    secondaryCategories?: string[];
-    /** Cities, towns or neighborhoods the business works in. */
-    serviceAreas?: string[];
-    priceRange?: string | null;
-    foundedYear?: number | null;
-    /** The Google Business Profile Place ID. */
-    googlePlaceId?: string | null;
-  };
-  /** Visitor tracking, set by the agency in Site Manager. Missing from Site Manager versions before it existed. */
-  tracking?: { provider: "stackos"; siteKey: string } | null;
-};
-
-/** A link from Site Manager's Pages. `href` is null when the record it points to is hidden or gone: skip the link. */
-export type CopyLink = { href: string | null; label: string };
-
-/** `pagePath` is the page the value belongs to in Site Manager's Pages, or null when it's shared across pages. */
-export type CopyValue = (
-  // accents: a one-field heading's gold words as [start, end] ranges of text; headingRuns() turns them into runs.
-  // strong: words marked important (Bold), rendered <strong>; em: words emphasized (Italic), rendered <em>;
-  // textRuns() turns every mark into runs.
-  | { kind: "text"; text: string | null; accents?: [number, number][]; strong?: [number, number][]; em?: [number, number][] }
-  | { kind: "rich"; html: string | null }
-  | { kind: "image"; image: Image | null }
-  | { kind: "link"; link: CopyLink | null }
-  | { kind: "records"; module: string | null; items: unknown[] }
-) & { pagePath?: string | null };
-
-/** A review platform from Reviews > Platforms. `url` is its review link, or null when the site has none. */
-export type ReviewPlatform = { key: string; label: string; url: string | null; logo: Image | null };
-
-export type Review = {
-  id: string;
-  authorName: string;
-  /** Where the reviewer is from, such as a city. */
-  authorLocation: string | null;
-  rating: number | null;
-  body: string;
-  /** A short version for cards, in the reviewer's own words. */
-  excerpt: string | null;
-  reviewerType: "client" | "colleague";
-  source: string;
-  /** The review's platform with its logo, or null for one entered by hand or not in the site's list. */
-  platform: ReviewPlatform | null;
-  sourceUrl: string | null;
-  reviewedOn: string | null;
-  response: string | null;
-  isFeatured: boolean;
-};
-
-export type FloorPlan = {
-  slug: string;
-  name: string;
-  beds: number;
-  baths: string;
-  sqftMin: number | null;
-  sqftMax: number | null;
-  startingRent: Money | null;
-  maxRent: Money | null;
-  deposit: Money | null;
-  availableCount: number | null;
-  availabilityUpdatedAt: string | null;
-  descriptionHtml: string;
-  tourUrl: string | null;
-  images: (Image & { kind: "plan" | "photo" })[];
-  source: "manual" | "appfolio" | "yardi" | "rent_roll";
-  // The fields below are missing from Site Manager versions before they existed, so they're optional.
-  /** What to show about availability. `count` is null unless the site chose to show exact numbers. Prefer this over availableCount. */
-  availability?: Availability;
-  /** Short feature labels for comparing plans, for example "Washer and dryer". */
-  features?: string[];
-  layout?: "flat" | "townhome" | "loft" | "penthouse" | null;
-  /** Floors inside the home. */
-  levels?: number | null;
-  /** The running special that gives this plan its lowest effective monthly rent. */
-  concession?: FloorPlanConcession | null;
-};
-
-export type Availability = { status: "available" | "none" | "unknown"; count: number | null };
-
-export type FloorPlanConcession = { specialId: string; title: string; effectiveRent: Money; baseRent: Money; leaseMonths: number | null };
-
-export type Concession = { kind: "weeks_free" | "months_free" | "amount_off" | "monthly_discount"; value: string; leaseMonths: number | null };
-
-export type Unit = { unitNumber: string; building: string | null; floor: number | null; sqft: number | null; rent: Money | null; availableOn: string | null; status: "available" | "on_notice" };
-
-export type Amenity = { id: string; name: string; category: "community" | "apartment"; description: string | null; icon: string | null; image: Image | null };
-
-export type Fee = { id: string; name: string; category: string; frequency: "one_time" | "monthly" | "per_occurrence"; amount: Money | null; amountNote: string | null; isRequired: boolean; notes: string | null };
-
-export type Special = { id: string; title: string; detailsHtml: string; startsOn: string | null; endsOn: string | null; floorPlans: string[]; concession?: Concession | null };
-
-export type PetRule = {
-  id: string;
-  petType: "dog" | "cat" | "bird" | "fish" | "small_animal" | "reptile" | "other";
-  allowed: boolean;
-  maxCount: number | null;
-  maxWeightLbs: number | null;
-  breedRules: string | null;
-  deposit: Money | null;
-  fee: Money | null;
-  monthlyRent: Money | null;
-  notes: string | null;
-};
-export type PetPolicy = { maxPets: number | null; assistanceNote: string | null; notes: string | null; pets: PetRule[] };
-
-export type ParkingOption = {
-  id: string;
-  name: string;
-  kind: "garage" | "covered" | "carport" | "surface" | "street" | "tandem" | "other";
-  price: Money | null;
-  frequency: "monthly" | "one_time" | "included";
-  /** Null means the site hasn't said, never "no". */
-  assigned: boolean | null;
-  evCharging: boolean | null;
-  notes: string | null;
-};
-export type Parking = { guestNote: string | null; notes: string | null; options: ParkingOption[] };
-
-export type Weekday = "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";
-
-export type UtilityProvider = {
-  utility: "electric" | "gas" | "water" | "sewer" | "trash" | "internet" | "cable" | "other";
-  provider: string;
-  phone: string | null;
-  url: string | null;
-  /** Who arranges it. Null means the site hasn't said. */
-  setupBy: "resident" | "property" | null;
-  /** When to set it up, in the site's words. */
-  when: string | null;
-  notes: string | null;
-};
-
-export type Pickup = {
-  stream: "trash" | "recycling" | "compost" | "bulk" | "other";
-  /** In week order. */
-  days: Weekday[];
-  /** 24-hour "HH:MM", or null when there's no set time. */
-  time: string | null;
-  notes: string | null;
-};
-
-export type ResidentDocument = { id: string; name: string; url: string; mimeType: string; sizeBytes: number };
-
-/**
- * One section of the residents page. Only visible sections with something in them are sent. The detail matching
- * the section's kind is set; the others are null.
- */
-export type ResidentSection = {
-  id: string;
-  kind: "move_in" | "rules" | "utilities" | "trash" | "maintenance" | "rent_payment" | "documents" | "custom";
-  title: string;
-  html: string;
-  utilities: UtilityProvider[] | null;
-  trash: Pickup[] | null;
-  maintenance: { requestUrl: string | null; phone: string | null; email: string | null; emergencyPhone: string | null; emergencyNote: string | null } | null;
-  rentPayment: { portalUrl: string | null; portalLabel: string | null } | null;
-  documents: ResidentDocument[];
-};
-
-/** Leasing policies. Every fact is null (or an empty list) until the site enters it. */
-export type Policies = {
-  application: {
-    criteriaHtml: string;
-    /** Monthly income as a multiple of the rent, like "3.00". */
-    incomeMultiple: string | null;
-    incomeNote: string | null;
-    creditNote: string | null;
-    backgroundNote: string | null;
-    fee: Money | null;
-    feeNote: string | null;
-    holdingFee: Money | null;
-    holdingFeeNote: string | null;
-  };
-  /** One amount when `max` is null, otherwise a range. */
-  deposit: { min: Money | null; max: Money | null; note: string | null };
-  lease: { termMonths: number[]; note: string | null };
-  smoking: { policy: "not_allowed" | "designated_areas" | "allowed" | null; note: string | null };
-  guestPolicy: string | null;
-  rentersInsurance: { requirement: "required" | "recommended" | "not_required" | null; minLiability: Money | null; note: string | null };
-  accessibilityStatement: string | null;
-  fairHousingStatement: string | null;
-  extra: { id: string; title: string; html: string }[];
-  /** Whether pet and parking rules have their own sections on this site, to link to instead of repeating. */
-  related: { petPolicy: boolean; parking: boolean };
-};
-
-export type Event = {
-  slug: string;
-  title: string;
-  startsAt: string;
-  endsAt: string | null;
-  startsAtLocal: string;
-  endsAtLocal: string | null;
-  timezone: string;
-  allDay: boolean;
-  locationText: string | null;
-  descriptionHtml: string;
-  image: Image | null;
-  linkUrl: string | null;
-  linkLabel: string | null;
-};
-
-export type ServicePriceKind = "none" | "fixed" | "range" | "starting_at" | "call";
-
-/**
- * A service a business offers. `price.from` and `price.to` are decimal strings ("150.00"), set only for the kinds
- * that use them; `price.label` is ready to show ("Starting at $150", "Call for pricing") and null for "none".
- */
-export type Service = {
-  slug: string;
-  name: string;
-  summary: string | null;
-  descriptionHtml: string;
-  category: string | null;
-  price: { kind: ServicePriceKind; from: string | null; to: string | null; note: string | null; label: string | null };
-  durationText: string | null;
-  /** In the order set in Site Manager; the first is the main photo. */
-  photos: Image[];
-  updatedAt: string;
-};
-
-export type Location = { slug: string; name: string; phone: string | null; email: string | null; address: Address; geo: { lat: number; lng: number } | null; hours: Hours | null; isPrimary: boolean };
-
-export type NearbyPlace = {
-  id: string;
-  name: string;
-  category: string;
-  address: string | null;
-  distanceText: string | null;
-  url: string | null;
-  geo: { lat: number; lng: number } | null;
-  description: string | null;
-  walkMinutes?: number | null;
-  driveMinutes?: number | null;
-  /** Bus or train, door to door. Mostly set for places in the `commute` category (employers, campuses, the airport). */
-  transitMinutes?: number | null;
-  school?: { level: "preschool" | "elementary" | "middle" | "high" | "k12" | "college" | null; grades: string | null; district: string | null; type: "public" | "private" | "charter" | null } | null;
-};
-
-/**
- * A drawing of the property (a site plan or a building) with its open units placed on it. `x` and `y` are percentages
- * of the image's width and height from its top left, so pins stay put at any size. Leased units are never included.
- */
-export type UnitMap = {
-  id: string;
-  name: string;
-  image: Image;
-  units: { unitNumber: string; building: string | null; floorPlan: string; status: "available" | "on_notice"; rent: Money | null; availableOn: string | null; x: number; y: number }[];
-};
-
-export type FormField = { name: string; label: string; type: "text" | "email" | "phone" | "textarea" | "select" | "radio" | "checkbox" | "date" | "number" | "hidden"; required: boolean; options?: string[]; maxLength: number; /** A short line to show under the field. */ help?: string };
-export type Form = {
-  key: string;
-  /** From Site Manager 2026-11 on. A booking form also needs one of getBookingSlots' times, sent as the bp_slot field. */
-  kind?: "standard" | "booking";
-  name: string;
-  description: string | null;
-  fields: FormField[];
-  successMessage: string;
-  booking?: { slotMinutes: number; timezone: string };
-};
-export type BookingSlot = { start: string; end: string; label: string };
-export type BookingDays = { timezone: string; slotMinutes: number; days: { date: string; slots: BookingSlot[] }[] };
-
-export type LegalSummary = { kind: string; title: string; slug: string; effectiveDate: string | null };
-export type LegalDoc = LegalSummary & { html: string };
-
-export type PageMeta = {
-  path: string;
-  title: string;
-  description: string | null;
-  canonical: string | null;
-  noindex: boolean;
-  ogImage: Image | null;
-  siteName: string;
-  titleSuffix: string | null;
-  // From Site Manager's share and robots settings (kit 1.43.0). Optional, so a site still builds against an older
-  // Site Manager. Null share text uses the title and description.
-  ogTitle?: string | null;
-  ogDescription?: string | null;
-  nofollow?: boolean;
-  maxImagePreview?: "large" | "standard" | "none";
-};
-export type SitemapEntry = { url: string; lastModified: string };
-export type Robots = { indexable: boolean; disallow: string[] };
-export type Redirect = { from: string; to: string; status: 301 | 302 | 308 };
-
-// Real estate (Site Manager's Listings and Team sections).
-
-export type TeamMember = { slug: string; name: string; title: string | null; licenseNumber: string | null; phone: string | null; email: string | null; bioHtml: string; photo: Image | null };
-
-export type ListingStatus = "coming_soon" | "active" | "pending" | "sold";
-export type PropertyType = "single_family" | "condo" | "townhouse" | "multi_family" | "manufactured" | "land" | "farm_ranch" | "commercial" | "other";
-export type HoaDues = { amount: Money; frequency: "monthly" | "quarterly" | "yearly" };
-
-export type Listing = {
-  slug: string;
-  status: ListingStatus;
-  statusLabel: string;
-  /** A manual badge, or "Just Listed" while an active listing is new. Null when there's nothing to show. */
-  badge: string | null;
-  headline: string | null;
-  address: { line1: string; line2: string | null; city: string | null; region: string | null; postalCode: string | null; neighborhood: string | null };
-  geo: { lat: number; lng: number } | null;
-  price: Money | null;
-  /** From the sold price once sold. */
-  pricePerSqft: Money | null;
-  soldPrice: Money | null;
-  soldOn: string | null;
-  listedOn: string | null;
-  beds: number | null;
-  /** A decimal string like "2.5". `bathsText` drops a trailing ".0". */
-  baths: string | null;
-  sqft: number | null;
-  lot: { size: string; unit: "acres" | "sqft" } | null;
-  propertyType: PropertyType | null;
-  propertyTypeLabel: string | null;
-  yearBuilt: number | null;
-  stories: number | null;
-  garageSpaces: number | null;
-  hoa: HoaDues | null;
-  mls: { number: string; source: string | null } | null;
-  tourUrl: string | null;
-  isFeatured: boolean;
-  featuredImage: Image | null;
-  imageCount: number;
-  agent: TeamMember | null;
-  source: "manual";
-  updatedAt: string;
-  // From Site Manager's listing details (kit 1.8.0). Optional, so a site still builds against an older Site Manager.
-  // Empty lists and nulls mean not known.
-  propertySubtype?: string | null;
-  originalPrice?: Money | null;
-  /** The day it went under contract. */
-  pendingOn?: string | null;
-  /** From the list date to the pending date (or today while active). Null for coming soon. */
-  daysOnMarket?: number | null;
-  interior?: {
-    bathsFull: number | null;
-    bathsHalf: number | null;
-    rooms: number | null;
-    basement: "none" | "finished" | "partially_finished" | "unfinished" | null;
-    fireplaces: number | null;
-    appliances: string[];
-    flooring: string[];
-    heating: string[];
-    cooling: string[];
-    laundry: string[];
-    features: string[];
-  };
-  exterior?: { construction: string[]; roof: string[]; pool: "none" | "private" | "community" | "private_and_community" | null; views: string[]; features: string[] };
-  lotDetails?: { dimensions: string | null; zoning: string | null; fencing: string[]; water: string[]; sewer: string[]; parcelNumber: string | null; features: string[] };
-  parking?: { garageSpaces: number | null; garageType: "attached" | "detached" | "carport" | "none" | null; spaces: number | null; features: string[] };
-  utilities?: string[];
-  hoaName?: string | null;
-  hoaIncludes?: string[];
-  taxes?: { annual: Money; year: number | null } | null;
-  /** Upcoming open houses, soonest first (kit 1.10.0). Past ones are never sent. */
-  openHouses?: ListingOpenHouse[];
-};
-
-/** An open house: UTC instants, the same times on the site's wall clock, and a ready label like "Open House Sat 1 to 3 pm". */
-export type ListingOpenHouse = { startsAt: string; endsAt: string; startsAtLocal: string; endsAtLocal: string; label: string; note: string | null };
-
-export type ListingFeature = { name: string; value: string };
-export type ListingSchool = { level: "elementary" | "middle" | "high" | "other"; name: string; district: string | null };
-export type ListingHistoryEntry = { date: string; kind: "listed" | "price_change" | "status_change" | "sold" | "note"; label: string; price: Money | null; status: string | null; note: string | null };
-
-/** A past sale of the home. Buyer and seller are null unless the agent chose to show names. */
-export type ListingTransaction = { date: string; amount: Money | null; seller: string | null; buyer: string | null };
-
-export type ListingDetail = Listing & {
-  descriptionHtml: string;
-  images: Image[];
-  features: ListingFeature[];
-  schools: ListingSchool[];
-  history: ListingHistoryEntry[];
-  /** Past sales, newest first (kit 1.8.0). */
-  transactions?: ListingTransaction[];
-};
-
-export type ListingFilters = {
-  status?: ListingStatus | ListingStatus[];
-  minPrice?: string | number;
-  maxPrice?: string | number;
-  beds?: number;
-  type?: PropertyType;
-  featured?: boolean;
-  limit?: number;
-  /** A team member's short name: only the listings they represent (kit 1.10.0). */
-  agent?: string;
-  /** An area guide's short name: only listings whose neighborhood matches the area (kit 1.17.0). */
-  area?: string;
-};
-
-/** An area guide (kit 1.17.0). A listing is in the area when its neighborhood matches `name` or one of `otherNames`, ignoring case. */
-export type Area = {
-  slug: string;
-  name: string;
-  summary: string | null;
-  descriptionHtml: string;
-  /** In the order set in Site Manager; the first is the main photo. */
-  photos: Image[];
-  /** Short lines like "Walk to the river trail". */
-  highlights: string[];
-  schools: ListingSchool[];
-  otherNames: string[];
-  /** Homes on the website in the area now (coming soon, active, pending). Null when the site doesn't use Listings. */
-  listingCount: number | null;
-  updatedAt: string;
-};
-
-/** Each value is null until the site sets it; without a rate, down payment and term there is no estimate. */
-export type PaymentDefaults = { ratePercent: string | null; downPaymentPercent: string | null; termYears: number | null; taxRatePercent: string | null; insuranceYearly: Money | null };
-
-export type PaymentEstimate = { downPayment: Money; loanAmount: Money; principalAndInterest: Money; tax: Money | null; insurance: Money | null; hoa: Money | null; total: Money };
-
-// Every-site sections (kit 1.14.0): FAQ, Announcements and Downloads.
-
-export type FaqCategory = { slug: string; name: string };
-/** `answerHtml` is sanitized HTML for the page and for JSON-LD; `answerText` is the same answer as plain text. `category` is a slug. */
-export type FaqQuestion = { id: string; question: string; answerHtml: string; answerText: string; category: string | null; /** Plain text shown under the answer. */ note: string | null };
-export type Faq = { categories: FaqCategory[]; questions: FaqQuestion[] };
-export type FaqSet = { key: string; name: string; questions: FaqQuestion[] };
-
-/** A site-wide notice that is live now. Instants are UTC ISO; the local fields repeat them in the site's time zone. */
-export type Announcement = {
-  id: string;
-  message: string;
-  linkUrl: string | null;
-  linkLabel: string | null;
-  tone: "info" | "urgent";
-  startsAt: string | null;
-  endsAt: string | null;
-  startsAtLocal: string | null;
-  endsAtLocal: string | null;
-  timezone: string;
-};
-
-export type DownloadCategory = "brochure" | "menu" | "application" | "price_sheet" | "other";
-/** `url` is Site Manager's tracked link: it counts the download and sends the visitor on to the file. */
-export type Download = { id: string; title: string; category: DownloadCategory; description: string | null; url: string; filename: string; mimeType: string; sizeBytes: number };
-export type BlogTerm = { slug: string; name: string };
-/**
- * Who wrote a post. A `team` author is one of the site's Team members: `slug` is theirs, and `url` their page address,
- * null until the site has a Team page pattern in Site Manager. Both are absent for other kinds and older Site Manager.
- */
-export type BlogAuthor = { name: string; kind: "user" | "byline" | "team"; slug?: string; url?: string | null };
-
-/** A post in a list: everything but the body. `url` is null until the site has a blog page pattern in Site Manager. */
-export type BlogPostSummary = {
-  slug: string;
-  title: string;
-  excerpt: string | null;
-  url: string | null;
-  publishedAt: string | null;
-  publishedAtLocal: string | null;
-  updatedAt: string;
-  timezone: string;
-  cover: Image | null;
-  author: BlogAuthor | null;
-  categories: BlogTerm[];
-  tags: BlogTerm[];
-};
-
-export type BlogPost = BlogPostSummary & {
-  /** Short takeaways, in order, up to seven. */
-  keyPoints: string[];
-  bodyHtml: string;
-  wordCount: number;
-  /** The post's search listing from Site Manager, or null while it has no page. */
-  seo: { title: string; description: string | null; canonical: string | null; ogImage: Image | null } | null;
-};
-
-export type BlogCategory = BlogTerm & { description: string | null; postCount: number };
-export type BlogTag = BlogTerm & { postCount: number };
-export type Paging = { page: number; perPage: number; total: number; totalPages: number };
-export type BlogPage = { posts: BlogPostSummary[]; paging: Paging };
-
-export type BlogFeedItem = {
-  guid: string;
-  guidIsPermaLink: boolean;
-  title: string;
-  link: string | null;
-  summary: string | null;
-  contentHtml: string;
-  author: string | null;
-  categories: string[];
-  image: Image | null;
-  publishedAt: string | null;
-  pubDate: string | null;
-};
-
-export type BlogFeed = {
-  title: string;
-  description: string | null;
-  link: string | null;
-  feedUrl: string | null;
-  language: string;
-  updatedAt: string | null;
-  items: BlogFeedItem[];
-};
-
-/** What a waitlist form can offer, from getWaitlistOptions(). `available` is whether the plan has a home open now. */
-export type WaitlistOptions = {
-  floorPlans: { slug: string; name: string; bedrooms: number; available: boolean }[];
-  bedrooms: { value: number; label: string }[];
-};
-
-export type WaitlistResult =
-  | { ok: true; waitingFor: string | null }
-  | { ok: false; error: "invalid"; fields: Record<string, string> }
-  | { ok: false; error: "rate_limited" | "unavailable" };
-
-/** A glossary term in the index: enough to list it and to link the term where it appears in text. */
-export type GlossaryTermSummary = {
-  slug: string;
-  term: string;
-  /** The term's page on the site, or null when Site Manager has no glossary page address set. */
-  url: string | null;
-  shortDefinition: string;
-  category: { slug: string; name: string } | null;
-  /** Works differently in the site's own state. */
-  isLocal: boolean;
-  alsoKnownAs: string[];
-};
-
-export type GlossaryRef = { slug: string; term: string; url: string | null };
-
-export type Glossary = { categories: { slug: string; name: string }[]; terms: GlossaryTermSummary[] };
-
-export type GlossaryTerm = GlossaryTermSummary & {
-  pronunciation: string | null;
-  localNote: string | null;
-  inPracticeHtml: string;
-  steps: { heading: string; body: string }[];
-  confusedWith: GlossaryRef[];
-  confusedNote: string | null;
-  related: GlossaryRef[];
-  /** Pages this term leads to. Skip any whose `href` is null. */
-  relatedLinks: CopyLink[];
-  faqs: { question: string; answerHtml: string }[];
-  reviewStatus: "needs_review" | "reviewed_by_staff" | "reviewed_by_expert";
-  reviewedBy: string | null;
-  reviewedAt: string | null;
-  updatedAt: string;
-  /** The terms before and after this one, alphabetically. */
-  previous: GlossaryRef | null;
-  next: GlossaryRef | null;
-};
+// Site Manager API v1 response shapes. Money is always a decimal string like "1450.00".
+
+export type Money = string;
+export type Hours = Record<"mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun", { closed: true } | { closed: false; open: string; close: string } | { closed: false; byAppointment: true }>;
+export type Image = { url: string; width: number | null; height: number | null; alt: string };
+export type Address = { line1: string; line2: string; city: string; region: string; postalCode: string; country: string };
+
+export type Site = {
+  name: string;
+  kind: "apartment" | "business" | "real_estate";
+  websiteUrl: string | null;
+  timezone: string;
+  modules: string[];
+  business: {
+    displayName: string;
+    legalName: string | null;
+    phone: string | null;
+    email: string | null;
+    address: Address;
+    geo: { lat: number; lng: number } | null;
+    hours: Hours | null;
+    hoursNote: string | null;
+    social: { network: string; url: string }[];
+    showEqualHousing: boolean | null;
+    // Search and maps facts (kit 1.42.0). Optional, so a site still builds against an older Site Manager; null or
+    // empty means not set.
+    /** A schema.org LocalBusiness type like "Plumber" or "ApartmentComplex". Null means LocalBusiness. */
+    schemaType?: string | null;
+    /** The Google Business Profile's main category, as typed there. */
+    primaryCategory?: string | null;
+    secondaryCategories?: string[];
+    /** Cities, towns or neighborhoods the business works in. */
+    serviceAreas?: string[];
+    priceRange?: string | null;
+    foundedYear?: number | null;
+    /** The Google Business Profile Place ID. */
+    googlePlaceId?: string | null;
+  };
+  /** Visitor tracking, set by the agency in Site Manager. Missing from Site Manager versions before it existed. */
+  tracking?: { provider: "stackos"; siteKey: string } | null;
+};
+
+/** A link from Site Manager's Pages. `href` is null when the record it points to is hidden or gone: skip the link. */
+export type CopyLink = { href: string | null; label: string };
+
+/** `pagePath` is the page the value belongs to in Site Manager's Pages, or null when it's shared across pages. */
+export type CopyValue = (
+  // accents: a one-field heading's gold words as [start, end] ranges of text; headingRuns() turns them into runs.
+  // strong: words marked important (Bold), rendered <strong>; em: words emphasized (Italic), rendered <em>;
+  // textRuns() turns every mark into runs.
+  | { kind: "text"; text: string | null; accents?: [number, number][]; strong?: [number, number][]; em?: [number, number][] }
+  | { kind: "rich"; html: string | null }
+  | { kind: "image"; image: Image | null }
+  | { kind: "link"; link: CopyLink | null }
+  | { kind: "records"; module: string | null; items: unknown[] }
+) & { pagePath?: string | null };
+
+/** A review platform from Reviews > Platforms. `url` is its review link, or null when the site has none. */
+export type ReviewPlatform = { key: string; label: string; url: string | null; logo: Image | null };
+
+export type Review = {
+  id: string;
+  authorName: string;
+  /** Where the reviewer is from, such as a city. */
+  authorLocation: string | null;
+  rating: number | null;
+  body: string;
+  /** A short version for cards, in the reviewer's own words. */
+  excerpt: string | null;
+  reviewerType: "client" | "colleague";
+  source: string;
+  /** The review's platform with its logo, or null for one entered by hand or not in the site's list. */
+  platform: ReviewPlatform | null;
+  sourceUrl: string | null;
+  reviewedOn: string | null;
+  response: string | null;
+  isFeatured: boolean;
+};
+
+export type FloorPlan = {
+  slug: string;
+  name: string;
+  beds: number;
+  baths: string;
+  sqftMin: number | null;
+  sqftMax: number | null;
+  startingRent: Money | null;
+  maxRent: Money | null;
+  deposit: Money | null;
+  availableCount: number | null;
+  availabilityUpdatedAt: string | null;
+  descriptionHtml: string;
+  tourUrl: string | null;
+  images: (Image & { kind: "plan" | "photo" })[];
+  source: "manual" | "appfolio" | "yardi" | "rent_roll";
+  // The fields below are missing from Site Manager versions before they existed, so they're optional.
+  /** What to show about availability. `count` is null unless the site chose to show exact numbers. Prefer this over availableCount. */
+  availability?: Availability;
+  /** Short feature labels for comparing plans, for example "Washer and dryer". */
+  features?: string[];
+  layout?: "flat" | "townhome" | "loft" | "penthouse" | null;
+  /** Floors inside the home. */
+  levels?: number | null;
+  /** The running special that gives this plan its lowest effective monthly rent. */
+  concession?: FloorPlanConcession | null;
+};
+
+export type Availability = { status: "available" | "none" | "unknown"; count: number | null };
+
+export type FloorPlanConcession = { specialId: string; title: string; effectiveRent: Money; baseRent: Money; leaseMonths: number | null };
+
+export type Concession = { kind: "weeks_free" | "months_free" | "amount_off" | "monthly_discount"; value: string; leaseMonths: number | null };
+
+export type Unit = { unitNumber: string; building: string | null; floor: number | null; sqft: number | null; rent: Money | null; availableOn: string | null; status: "available" | "on_notice" };
+
+export type Amenity = { id: string; name: string; category: "community" | "apartment"; description: string | null; icon: string | null; image: Image | null };
+
+export type Fee = { id: string; name: string; category: string; frequency: "one_time" | "monthly" | "per_occurrence"; amount: Money | null; amountNote: string | null; isRequired: boolean; notes: string | null };
+
+export type Special = { id: string; title: string; detailsHtml: string; startsOn: string | null; endsOn: string | null; floorPlans: string[]; concession?: Concession | null };
+
+export type PetRule = {
+  id: string;
+  petType: "dog" | "cat" | "bird" | "fish" | "small_animal" | "reptile" | "other";
+  allowed: boolean;
+  maxCount: number | null;
+  maxWeightLbs: number | null;
+  breedRules: string | null;
+  deposit: Money | null;
+  fee: Money | null;
+  monthlyRent: Money | null;
+  notes: string | null;
+};
+export type PetPolicy = { maxPets: number | null; assistanceNote: string | null; notes: string | null; pets: PetRule[] };
+
+export type ParkingOption = {
+  id: string;
+  name: string;
+  kind: "garage" | "covered" | "carport" | "surface" | "street" | "tandem" | "other";
+  price: Money | null;
+  frequency: "monthly" | "one_time" | "included";
+  /** Null means the site hasn't said, never "no". */
+  assigned: boolean | null;
+  evCharging: boolean | null;
+  notes: string | null;
+};
+export type Parking = { guestNote: string | null; notes: string | null; options: ParkingOption[] };
+
+export type Weekday = "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";
+
+export type UtilityProvider = {
+  utility: "electric" | "gas" | "water" | "sewer" | "trash" | "internet" | "cable" | "other";
+  provider: string;
+  phone: string | null;
+  url: string | null;
+  /** Who arranges it. Null means the site hasn't said. */
+  setupBy: "resident" | "property" | null;
+  /** When to set it up, in the site's words. */
+  when: string | null;
+  notes: string | null;
+};
+
+export type Pickup = {
+  stream: "trash" | "recycling" | "compost" | "bulk" | "other";
+  /** In week order. */
+  days: Weekday[];
+  /** 24-hour "HH:MM", or null when there's no set time. */
+  time: string | null;
+  notes: string | null;
+};
+
+export type ResidentDocument = { id: string; name: string; url: string; mimeType: string; sizeBytes: number };
+
+/**
+ * One section of the residents page. Only visible sections with something in them are sent. The detail matching
+ * the section's kind is set; the others are null.
+ */
+export type ResidentSection = {
+  id: string;
+  kind: "move_in" | "rules" | "utilities" | "trash" | "maintenance" | "rent_payment" | "documents" | "custom";
+  title: string;
+  html: string;
+  utilities: UtilityProvider[] | null;
+  trash: Pickup[] | null;
+  maintenance: { requestUrl: string | null; phone: string | null; email: string | null; emergencyPhone: string | null; emergencyNote: string | null } | null;
+  rentPayment: { portalUrl: string | null; portalLabel: string | null } | null;
+  documents: ResidentDocument[];
+};
+
+/** Leasing policies. Every fact is null (or an empty list) until the site enters it. */
+export type Policies = {
+  application: {
+    criteriaHtml: string;
+    /** Monthly income as a multiple of the rent, like "3.00". */
+    incomeMultiple: string | null;
+    incomeNote: string | null;
+    creditNote: string | null;
+    backgroundNote: string | null;
+    fee: Money | null;
+    feeNote: string | null;
+    holdingFee: Money | null;
+    holdingFeeNote: string | null;
+  };
+  /** One amount when `max` is null, otherwise a range. */
+  deposit: { min: Money | null; max: Money | null; note: string | null };
+  lease: { termMonths: number[]; note: string | null };
+  smoking: { policy: "not_allowed" | "designated_areas" | "allowed" | null; note: string | null };
+  guestPolicy: string | null;
+  rentersInsurance: { requirement: "required" | "recommended" | "not_required" | null; minLiability: Money | null; note: string | null };
+  accessibilityStatement: string | null;
+  fairHousingStatement: string | null;
+  extra: { id: string; title: string; html: string }[];
+  /** Whether pet and parking rules have their own sections on this site, to link to instead of repeating. */
+  related: { petPolicy: boolean; parking: boolean };
+};
+
+export type Event = {
+  slug: string;
+  title: string;
+  startsAt: string;
+  endsAt: string | null;
+  startsAtLocal: string;
+  endsAtLocal: string | null;
+  timezone: string;
+  allDay: boolean;
+  locationText: string | null;
+  descriptionHtml: string;
+  image: Image | null;
+  linkUrl: string | null;
+  linkLabel: string | null;
+};
+
+export type ServicePriceKind = "none" | "fixed" | "range" | "starting_at" | "call";
+
+/**
+ * A service a business offers. `price.from` and `price.to` are decimal strings ("150.00"), set only for the kinds
+ * that use them; `price.label` is ready to show ("Starting at $150", "Call for pricing") and null for "none".
+ */
+export type Service = {
+  slug: string;
+  name: string;
+  summary: string | null;
+  descriptionHtml: string;
+  category: string | null;
+  price: { kind: ServicePriceKind; from: string | null; to: string | null; note: string | null; label: string | null };
+  durationText: string | null;
+  /** In the order set in Site Manager; the first is the main photo. */
+  photos: Image[];
+  updatedAt: string;
+};
+
+export type Location = { slug: string; name: string; phone: string | null; email: string | null; address: Address; geo: { lat: number; lng: number } | null; hours: Hours | null; isPrimary: boolean };
+
+export type NearbyPlace = {
+  id: string;
+  name: string;
+  category: string;
+  address: string | null;
+  distanceText: string | null;
+  url: string | null;
+  geo: { lat: number; lng: number } | null;
+  description: string | null;
+  walkMinutes?: number | null;
+  driveMinutes?: number | null;
+  /** Bus or train, door to door. Mostly set for places in the `commute` category (employers, campuses, the airport). */
+  transitMinutes?: number | null;
+  school?: { level: "preschool" | "elementary" | "middle" | "high" | "k12" | "college" | null; grades: string | null; district: string | null; type: "public" | "private" | "charter" | null } | null;
+};
+
+/**
+ * A drawing of the property (a site plan or a building) with its open units placed on it. `x` and `y` are percentages
+ * of the image's width and height from its top left, so pins stay put at any size. Leased units are never included.
+ */
+export type UnitMap = {
+  id: string;
+  name: string;
+  image: Image;
+  units: { unitNumber: string; building: string | null; floorPlan: string; status: "available" | "on_notice"; rent: Money | null; availableOn: string | null; x: number; y: number }[];
+};
+
+export type FormField = { name: string; label: string; type: "text" | "email" | "phone" | "textarea" | "select" | "radio" | "checkbox" | "date" | "number" | "hidden"; required: boolean; options?: string[]; maxLength: number; /** A short line to show under the field. */ help?: string };
+export type Form = {
+  key: string;
+  /** From Site Manager 2026-11 on. A booking form also needs one of getBookingSlots' times, sent as the bp_slot field. */
+  kind?: "standard" | "booking";
+  name: string;
+  description: string | null;
+  fields: FormField[];
+  successMessage: string;
+  booking?: { slotMinutes: number; timezone: string };
+};
+export type BookingSlot = { start: string; end: string; label: string };
+export type BookingDays = { timezone: string; slotMinutes: number; days: { date: string; slots: BookingSlot[] }[] };
+
+export type LegalSummary = { kind: string; title: string; slug: string; effectiveDate: string | null };
+export type LegalDoc = LegalSummary & { html: string };
+
+export type PageMeta = {
+  path: string;
+  title: string;
+  description: string | null;
+  canonical: string | null;
+  noindex: boolean;
+  ogImage: Image | null;
+  siteName: string;
+  titleSuffix: string | null;
+  // From Site Manager's share and robots settings (kit 1.43.0). Optional, so a site still builds against an older
+  // Site Manager. Null share text uses the title and description.
+  ogTitle?: string | null;
+  ogDescription?: string | null;
+  nofollow?: boolean;
+  maxImagePreview?: "large" | "standard" | "none";
+};
+export type SitemapEntry = { url: string; lastModified: string };
+/** blockedBots: AI crawlers the site keeps out, by user agent (Site Manager 2026-11, optional for older servers). */
+export type Robots = { indexable: boolean; disallow: string[]; blockedBots?: string[] };
+export type Redirect = { from: string; to: string; status: 301 | 302 | 308 };
+
+// Real estate (Site Manager's Listings and Team sections).
+
+export type TeamMember = { slug: string; name: string; title: string | null; licenseNumber: string | null; phone: string | null; email: string | null; bioHtml: string; photo: Image | null };
+
+export type ListingStatus = "coming_soon" | "active" | "pending" | "sold";
+export type PropertyType = "single_family" | "condo" | "townhouse" | "multi_family" | "manufactured" | "land" | "farm_ranch" | "commercial" | "other";
+export type HoaDues = { amount: Money; frequency: "monthly" | "quarterly" | "yearly" };
+
+export type Listing = {
+  slug: string;
+  status: ListingStatus;
+  statusLabel: string;
+  /** A manual badge, or "Just Listed" while an active listing is new. Null when there's nothing to show. */
+  badge: string | null;
+  headline: string | null;
+  address: { line1: string; line2: string | null; city: string | null; region: string | null; postalCode: string | null; neighborhood: string | null };
+  geo: { lat: number; lng: number } | null;
+  price: Money | null;
+  /** From the sold price once sold. */
+  pricePerSqft: Money | null;
+  soldPrice: Money | null;
+  soldOn: string | null;
+  listedOn: string | null;
+  beds: number | null;
+  /** A decimal string like "2.5". `bathsText` drops a trailing ".0". */
+  baths: string | null;
+  sqft: number | null;
+  lot: { size: string; unit: "acres" | "sqft" } | null;
+  propertyType: PropertyType | null;
+  propertyTypeLabel: string | null;
+  yearBuilt: number | null;
+  stories: number | null;
+  garageSpaces: number | null;
+  hoa: HoaDues | null;
+  mls: { number: string; source: string | null } | null;
+  tourUrl: string | null;
+  isFeatured: boolean;
+  featuredImage: Image | null;
+  imageCount: number;
+  agent: TeamMember | null;
+  source: "manual";
+  updatedAt: string;
+  // From Site Manager's listing details (kit 1.8.0). Optional, so a site still builds against an older Site Manager.
+  // Empty lists and nulls mean not known.
+  propertySubtype?: string | null;
+  originalPrice?: Money | null;
+  /** The day it went under contract. */
+  pendingOn?: string | null;
+  /** From the list date to the pending date (or today while active). Null for coming soon. */
+  daysOnMarket?: number | null;
+  interior?: {
+    bathsFull: number | null;
+    bathsHalf: number | null;
+    rooms: number | null;
+    basement: "none" | "finished" | "partially_finished" | "unfinished" | null;
+    fireplaces: number | null;
+    appliances: string[];
+    flooring: string[];
+    heating: string[];
+    cooling: string[];
+    laundry: string[];
+    features: string[];
+  };
+  exterior?: { construction: string[]; roof: string[]; pool: "none" | "private" | "community" | "private_and_community" | null; views: string[]; features: string[] };
+  lotDetails?: { dimensions: string | null; zoning: string | null; fencing: string[]; water: string[]; sewer: string[]; parcelNumber: string | null; features: string[] };
+  parking?: { garageSpaces: number | null; garageType: "attached" | "detached" | "carport" | "none" | null; spaces: number | null; features: string[] };
+  utilities?: string[];
+  hoaName?: string | null;
+  hoaIncludes?: string[];
+  taxes?: { annual: Money; year: number | null } | null;
+  /** Upcoming open houses, soonest first (kit 1.10.0). Past ones are never sent. */
+  openHouses?: ListingOpenHouse[];
+};
+
+/** An open house: UTC instants, the same times on the site's wall clock, and a ready label like "Open House Sat 1 to 3 pm". */
+export type ListingOpenHouse = { startsAt: string; endsAt: string; startsAtLocal: string; endsAtLocal: string; label: string; note: string | null };
+
+export type ListingFeature = { name: string; value: string };
+export type ListingSchool = { level: "elementary" | "middle" | "high" | "other"; name: string; district: string | null };
+export type ListingHistoryEntry = { date: string; kind: "listed" | "price_change" | "status_change" | "sold" | "note"; label: string; price: Money | null; status: string | null; note: string | null };
+
+/** A past sale of the home. Buyer and seller are null unless the agent chose to show names. */
+export type ListingTransaction = { date: string; amount: Money | null; seller: string | null; buyer: string | null };
+
+export type ListingDetail = Listing & {
+  descriptionHtml: string;
+  images: Image[];
+  features: ListingFeature[];
+  schools: ListingSchool[];
+  history: ListingHistoryEntry[];
+  /** Past sales, newest first (kit 1.8.0). */
+  transactions?: ListingTransaction[];
+};
+
+export type ListingFilters = {
+  status?: ListingStatus | ListingStatus[];
+  minPrice?: string | number;
+  maxPrice?: string | number;
+  beds?: number;
+  type?: PropertyType;
+  featured?: boolean;
+  limit?: number;
+  /** A team member's short name: only the listings they represent (kit 1.10.0). */
+  agent?: string;
+  /** An area guide's short name: only listings whose neighborhood matches the area (kit 1.17.0). */
+  area?: string;
+};
+
+/** An area guide (kit 1.17.0). A listing is in the area when its neighborhood matches `name` or one of `otherNames`, ignoring case. */
+export type Area = {
+  slug: string;
+  name: string;
+  summary: string | null;
+  descriptionHtml: string;
+  /** In the order set in Site Manager; the first is the main photo. */
+  photos: Image[];
+  /** Short lines like "Walk to the river trail". */
+  highlights: string[];
+  schools: ListingSchool[];
+  otherNames: string[];
+  /** Homes on the website in the area now (coming soon, active, pending). Null when the site doesn't use Listings. */
+  listingCount: number | null;
+  updatedAt: string;
+};
+
+/** Each value is null until the site sets it; without a rate, down payment and term there is no estimate. */
+export type PaymentDefaults = { ratePercent: string | null; downPaymentPercent: string | null; termYears: number | null; taxRatePercent: string | null; insuranceYearly: Money | null };
+
+export type PaymentEstimate = { downPayment: Money; loanAmount: Money; principalAndInterest: Money; tax: Money | null; insurance: Money | null; hoa: Money | null; total: Money };
+
+// Every-site sections (kit 1.14.0): FAQ, Announcements and Downloads.
+
+export type FaqCategory = { slug: string; name: string };
+/** `answerHtml` is sanitized HTML for the page and for JSON-LD; `answerText` is the same answer as plain text. `category` is a slug. */
+export type FaqQuestion = { id: string; question: string; answerHtml: string; answerText: string; category: string | null; /** Plain text shown under the answer. */ note: string | null };
+export type Faq = { categories: FaqCategory[]; questions: FaqQuestion[] };
+export type FaqSet = { key: string; name: string; questions: FaqQuestion[] };
+
+/** A site-wide notice that is live now. Instants are UTC ISO; the local fields repeat them in the site's time zone. */
+export type Announcement = {
+  id: string;
+  message: string;
+  linkUrl: string | null;
+  linkLabel: string | null;
+  tone: "info" | "urgent";
+  startsAt: string | null;
+  endsAt: string | null;
+  startsAtLocal: string | null;
+  endsAtLocal: string | null;
+  timezone: string;
+};
+
+export type DownloadCategory = "brochure" | "menu" | "application" | "price_sheet" | "other";
+/** `url` is Site Manager's tracked link: it counts the download and sends the visitor on to the file. */
+export type Download = { id: string; title: string; category: DownloadCategory; description: string | null; url: string; filename: string; mimeType: string; sizeBytes: number };
+export type BlogTerm = { slug: string; name: string };
+/**
+ * Who wrote a post. A `team` author is one of the site's Team members: `slug` is theirs, and `url` their page address,
+ * null until the site has a Team page pattern in Site Manager. Both are absent for other kinds and older Site Manager.
+ */
+export type BlogAuthor = { name: string; kind: "user" | "byline" | "team"; slug?: string; url?: string | null };
+
+/** A post in a list: everything but the body. `url` is null until the site has a blog page pattern in Site Manager. */
+export type BlogPostSummary = {
+  slug: string;
+  title: string;
+  excerpt: string | null;
+  url: string | null;
+  publishedAt: string | null;
+  publishedAtLocal: string | null;
+  updatedAt: string;
+  timezone: string;
+  cover: Image | null;
+  author: BlogAuthor | null;
+  categories: BlogTerm[];
+  tags: BlogTerm[];
+};
+
+export type BlogPost = BlogPostSummary & {
+  /** Short takeaways, in order, up to seven. */
+  keyPoints: string[];
+  bodyHtml: string;
+  wordCount: number;
+  /** The post's search listing from Site Manager, or null while it has no page. */
+  seo: { title: string; description: string | null; canonical: string | null; ogImage: Image | null } | null;
+};
+
+export type BlogCategory = BlogTerm & { description: string | null; postCount: number };
+export type BlogTag = BlogTerm & { postCount: number };
+export type Paging = { page: number; perPage: number; total: number; totalPages: number };
+export type BlogPage = { posts: BlogPostSummary[]; paging: Paging };
+
+export type BlogFeedItem = {
+  guid: string;
+  guidIsPermaLink: boolean;
+  title: string;
+  link: string | null;
+  summary: string | null;
+  contentHtml: string;
+  author: string | null;
+  categories: string[];
+  image: Image | null;
+  publishedAt: string | null;
+  pubDate: string | null;
+};
+
+export type BlogFeed = {
+  title: string;
+  description: string | null;
+  link: string | null;
+  feedUrl: string | null;
+  language: string;
+  updatedAt: string | null;
+  items: BlogFeedItem[];
+};
+
+/** What a waitlist form can offer, from getWaitlistOptions(). `available` is whether the plan has a home open now. */
+export type WaitlistOptions = {
+  floorPlans: { slug: string; name: string; bedrooms: number; available: boolean }[];
+  bedrooms: { value: number; label: string }[];
+};
+
+export type WaitlistResult =
+  | { ok: true; waitingFor: string | null }
+  | { ok: false; error: "invalid"; fields: Record<string, string> }
+  | { ok: false; error: "rate_limited" | "unavailable" };
+
+/** A glossary term in the index: enough to list it and to link the term where it appears in text. */
+export type GlossaryTermSummary = {
+  slug: string;
+  term: string;
+  /** The term's page on the site, or null when Site Manager has no glossary page address set. */
+  url: string | null;
+  shortDefinition: string;
+  category: { slug: string; name: string } | null;
+  /** Works differently in the site's own state. */
+  isLocal: boolean;
+  alsoKnownAs: string[];
+};
+
+export type GlossaryRef = { slug: string; term: string; url: string | null };
+
+export type Glossary = { categories: { slug: string; name: string }[]; terms: GlossaryTermSummary[] };
+
+export type GlossaryTerm = GlossaryTermSummary & {
+  pronunciation: string | null;
+  localNote: string | null;
+  inPracticeHtml: string;
+  steps: { heading: string; body: string }[];
+  confusedWith: GlossaryRef[];
+  confusedNote: string | null;
+  related: GlossaryRef[];
+  /** Pages this term leads to. Skip any whose `href` is null. */
+  relatedLinks: CopyLink[];
+  faqs: { question: string; answerHtml: string }[];
+  reviewStatus: "needs_review" | "reviewed_by_staff" | "reviewed_by_expert";
+  reviewedBy: string | null;
+  reviewedAt: string | null;
+  updatedAt: string;
+  /** The terms before and after this one, alphabetically. */
+  previous: GlossaryRef | null;
+  next: GlossaryRef | null;
+};