@sonordev/contracts 2.12.0 → 2.15.0

package/dist/llms.d.ts

@@ -6,6 +6,13 @@
  * `@sonordev/site-kit/seo/llms/contract`.
  *
  * @see LLM_GEO_CONTRACT.md in this folder
+ *
+ * It is also where llms.txt's page notes, page titles and page order are
+ * decided, so the Sonor API's index, its fallback file and site-kit's local
+ * generator can't disagree: `pickLlmsPageDescription` (summary, curated meta,
+ * the page's own meta, the schema description, then a cleaned scrape),
+ * `llmsPageTitle`, `isLlmsListablePage`, `selectLlmsPages`, `groupLlmsPages`,
+ * `llmsPageListNote` and `llmsContactLines`.
  */
 /** Increment when public LLMs payload shape changes incompatibly. */
 export declare const LLM_GEO_CONTRACT_VERSION: 1;
@@ -29,8 +36,27 @@ export interface LLMsPayloadMeta {
     llms_disclaimer?: string | null;
 }
 export declare function clipAtWordBoundary(text: string, max: number): string;
+/**
+ * The text with its phone numbers and email addresses taken out. The business's
+ * Contact Information block already carries them, and a page's note is no place
+ * for either.
+ *
+ * Works a sentence at a time: a sentence with a detail in it keeps what comes
+ * before the detail (and before a "call" or "email us at" in front of it) when
+ * that is still a sentence of four words or more, and is dropped otherwise.
+ * "Family-owned HVAC in Cincinnati, call 513-555-1234 today." becomes
+ * "Family-owned HVAC in Cincinnati."; "Call 513-555-1234 for a quote." goes.
+ * Cutting out only the number would leave "for a quote." behind.
+ */
+export declare function stripContactDetails(text: string): string;
+export declare function stripPageFiller(note: string): string;
 /**
  * Public-safe summary for llms.txt `[title](url): notes` — never CRM-only or internal copy.
+ *
+ * A summary that mentions a phone number or an email address loses that part
+ * (`stripContactDetails`) and is still used. It used to be thrown away whole,
+ * and a page with no summary is described by its scrape, so a well-meant
+ * "...call 555-1234" summary made the page's note worse, not safer.
  */
 export declare function sanitizeLlmsPublicSummary(raw: unknown): string | null;
 /**
@@ -53,3 +79,177 @@ export declare function sanitizePrimaryLanguageTag(raw: unknown): string | null;
 export declare function isEmittableReviewNode(node: Record<string, unknown>): boolean;
 /** Pick JSON-LD-safe subset of managed_llm_schema for script injection. */
 export declare function pickManagedLlmSchemaForJsonLd(schema: Record<string, unknown> | null | undefined): Record<string, unknown> | null;
+/** The longest note a page line carries. */
+export declare const LLMS_DESCRIPTION_MAX_LENGTH = 500;
+/**
+ * A page's scraped text (seo_pages.content_text) made fit to describe it.
+ *
+ * The DOM scrape joins elements with nothing between them: a heading, its
+ * tagline and the first paragraph arrive as "Getting paid for the
+ * workIncome, spending, budgets.Track expenses by vendor", a contact page as
+ * "First Name*Last Name*Email*PhoneMessage*Send Message". This puts the
+ * whitespace back, drops what is not about the page (form labels, menu items,
+ * skip links, cookie banners, "Eyebrow · Section" lines) and returns what is
+ * left. It may return '' when nothing worth a note is.
+ *
+ * It does not cut to a length: the caller clips (`clipAtWordBoundary`). It
+ * does not strip phone numbers: that is `stripContactDetails`. `knownTerms`
+ * are words written with a capital inside them that must stay whole.
+ */
+export declare function cleanScrapedPageText(raw: string | null | undefined, options?: {
+    knownTerms?: readonly string[];
+}): string;
+/** Where a page's note came from, best source first. */
+export type LlmsDescriptionSource = 'summary' | 'managed_meta' | 'meta' | 'schema' | 'scrape';
+export interface LlmsDescriptionInput {
+    /** The page's own name: a note that only repeats it says nothing. */
+    title?: string | null;
+    /** seo_pages.llms_public_summary: written for this file. */
+    llms_public_summary?: string | null;
+    /** seo_pages.managed_meta_description: the curated meta description. */
+    managed_meta_description?: string | null;
+    /** seo_pages.meta_description: the meta description the page serves. */
+    meta_description?: string | null;
+    /** The `description` of the page's managed LLM schema. */
+    llm_schema_description?: string | null;
+    /** seo_pages.content_text: the DOM scrape. */
+    content_text?: string | null;
+    /**
+     * True when the page's managed copy says the page itself is missing
+     * (describesErrorPage). That copy, the schema and the page's own meta
+     * description are then not used.
+     */
+    copyWithheld?: boolean;
+}
+/**
+ * The note a page's line in llms.txt carries, and where it came from.
+ *
+ * One rule for every llms.txt Sonor builds, best source first:
+ *
+ *  1. `llms_public_summary`, written for this file, with a phone number or an
+ *     email address taken out rather than the whole summary thrown away;
+ *  2. `managed_meta_description`, the curated meta description;
+ *  3. `meta_description`, the one the page serves;
+ *  4. the managed schema's description;
+ *  5. the cleaned scrape (`cleanScrapedPageText`), last, because it is the
+ *     least written of the five.
+ *
+ * Until 2026-10 the scrape was FIRST: llms.txt, the one file handed straight
+ * to AI crawlers, described a contact page as "First Name*Last Name*Email*".
+ * Every note is cut at a sentence or word boundary at 500 characters. A scrape
+ * that is an error page is not used (`usablePageText`). Returns null when
+ * nothing says anything about the page.
+ */
+export declare function pickLlmsPageDescription(input: LlmsDescriptionInput): {
+    text: string;
+    source: LlmsDescriptionSource;
+} | null;
+/** `pickLlmsPageDescription`'s text. */
+export declare function resolveLlmsPageDescription(input: LlmsDescriptionInput): string | null;
+/**
+ * The note on a page's line, from what the payload carries: its
+ * `llms_public_summary`, then its `description`. With `publicSummaryOnly`
+ * (a site that wants strict notes) only the summary counts. Single source of
+ * truth for the Sonor API's fallback file and site-kit's local generator, which
+ * each had their own copy.
+ */
+export declare function llmsPageListNote(page: {
+    description?: string | null;
+    llms_public_summary?: string | null;
+}, publicSummaryOnly?: boolean): string | undefined;
+export interface LlmsListablePage {
+    path: string;
+    http_status?: number | null;
+    has_noindex?: boolean | null;
+    robots_meta?: string | null;
+    managed_robots_meta?: string | null;
+}
+/**
+ * Whether a live seo_pages row belongs in llms.txt. A page the last visit saw
+ * answer with an error (404, 5xx), a page that asks search engines to leave it
+ * out, and a utility page (a thank-you page, a cart, a login) are not listed:
+ * llms.txt is the index of what a site is, and every dead or unwanted link in
+ * it is one a model may follow and cite. Retired pages never get here
+ * (LIVE_SEO_PAGE_FILTER).
+ */
+export declare function isLlmsListablePage(page: LlmsListablePage): boolean;
+/**
+ * What a page is called in llms.txt: its curated title, else the title it
+ * serves, else its h1, each with the brand suffix off and only when it is a
+ * name and not an address; the home page is `homeName`; else the last segment
+ * of its path as a label. Never the path itself: "[/features/accounting]" was
+ * what a page with no title got.
+ */
+export declare function llmsPageTitle(page: {
+    path: string;
+    managed_title?: string | null;
+    title?: string | null;
+    h1?: string | null;
+}, homeName?: string | null): string;
+/**
+ * Choose which pages survive a page cap.
+ *
+ * A round-robin across top-level sections, not a truncation: cutting an
+ * alphabetical list amputates its tail. On a 191-page site a cap of 50 kept 37
+ * `/industries/*` pages and dropped `/work`, `/pricing`, `/services`,
+ * `/web-design` and `/resources` entirely. Every section is represented at any
+ * cap, and the survivors keep their original order, because the round-robin
+ * decides membership, not presentation. Sections are taken most valuable first
+ * (the order `groupLlmsPages` lists them in, legal pages last), so a cap smaller
+ * than the number of sections drops the least valuable one.
+ *
+ * Single source of truth: the Sonor API caps its index with it, and site-kit's
+ * local generator caps with it instead of `slice(0, max)`.
+ */
+export declare function selectLlmsPages<T extends {
+    path: string;
+}>(pages: T[], cap: number): T[];
+export interface LlmsPageGroup<T> {
+    /** null for the one list of a small site. */
+    heading: string | null;
+    pages: T[];
+}
+/**
+ * The page index in the order and groups an answer engine reads best: the
+ * home page, then the site's top-level pages by value (what it does, where,
+ * the proof, who, the cost, contact), then one group per section of the site
+ * (`/services/*` is "Services"), biggest unlisted sections last, and the legal
+ * pages at the very end. Nothing is dropped or renamed; a list of 12 pages or
+ * fewer is one ungrouped list in the same order.
+ *
+ * Single source of truth for the Sonor API's fallback file and site-kit's
+ * local generator.
+ */
+export declare function groupLlmsPages<T extends {
+    path: string;
+}>(pages: readonly T[]): Array<LlmsPageGroup<T>>;
+/**
+ * The one-line summary under the business name: its tagline, else the first
+ * sentence of its description, else its name. The first sentence comes from
+ * `splitSentences`, not `description.split('.')[0]`, which ends "Smith &
+ * Sons, Inc. is a roofing company" at "Inc".
+ */
+export declare function llmsBlockquoteSummary(business: {
+    name?: string | null;
+    tagline?: string | null;
+    description?: string | null;
+}): string;
+export interface LlmsContactLike {
+    phone?: string | null;
+    email?: string | null;
+    address?: string | null;
+    city?: string | null;
+    state?: string | null;
+    postal_code?: string | null;
+    country?: string | null;
+    hours?: unknown;
+}
+/**
+ * The bullets of the Contact Information block, none for a field that is
+ * empty. An address reads "1 Main St, Springfield, OH 45501", and a
+ * default "US" is not printed. Empty array when there is nothing to show, so a
+ * caller leaves the whole section out rather than print a bare heading.
+ */
+export declare function llmsContactLines(contact: LlmsContactLike | null | undefined): string[];
+/** A page or service link as an absolute URL on the site, so a crawler never resolves it against llms.txt's own address. */
+export declare function llmsAbsoluteUrl(baseUrl: string | null | undefined, pathOrUrl: string): string;