@the-smithy/hearth 0.21.0 → 0.22.0

package/dist/{chunk-V47RFBJE.js → chunk-RZNKY7HG.js}

@@ -239,6 +239,11 @@ function createCore(options) {
       }
     },
     sitemap: (o = {}) => request("/sitemap", { ...o, resource: "sitemap" }),
+    /**
+     * The site's llms.txt (Markdown for AI tools: the organization, how to reach it, its pages with a line on each),
+     * or null while the site has no domain or is hidden from search engines, and from Hearth versions without it.
+     */
+    llmsTxt: async (o = {}) => await maybe("/llms", { ...o, resource: "llms" }) ?? null,
     redirects: {
       /** Every redirect on the site (old addresses and where they go now). Empty from Hearth versions without them. */
       list: async (o = {}) => await maybe("/redirects", { ...o, resource: "redirects.list" }) ?? []

package/dist/{client-IImehdSM.d.ts → client-BXkB1aKA.d.ts}

@@ -178,6 +178,11 @@ declare function createCore(options: HearthClientOptions): {
         }, o?: CallOptions) => Promise<CollectionPage | EventCollectionPage | null>;
     };
     sitemap: (o?: CallOptions) => Promise<SitemapEntry[]>;
+    /**
+     * The site's llms.txt (Markdown for AI tools: the organization, how to reach it, its pages with a line on each),
+     * or null while the site has no domain or is hidden from search engines, and from Hearth versions without it.
+     */
+    llmsTxt: (o?: CallOptions) => Promise<string | null>;
     redirects: {
         /** Every redirect on the site (old addresses and where they go now). Empty from Hearth versions without them. */
         list: (o?: CallOptions) => Promise<Redirect[]>;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { H as HearthCore, a as HearthClientOptions } from './client-IImehdSM.js';
-export { C as CallOptions, b as CollectionPage, D as DEFAULT_BASE_URL, E as EventCollectionPage, F as FormResult, c as FormValues, d as HearthError, e as HearthErrorCode, f as HearthHooks, N as NextFetchOptions, P as PreviewSession, R as RequestContext, g as RequestOptions, h as findRedirect, i as isHearthError, n as normalizeSlug } from './client-IImehdSM.js';
+import { H as HearthCore, a as HearthClientOptions } from './client-BXkB1aKA.js';
+export { C as CallOptions, b as CollectionPage, D as DEFAULT_BASE_URL, E as EventCollectionPage, F as FormResult, c as FormValues, d as HearthError, e as HearthErrorCode, f as HearthHooks, N as NextFetchOptions, P as PreviewSession, R as RequestContext, g as RequestOptions, h as findRedirect, i as isHearthError, n as normalizeSlug } from './client-BXkB1aKA.js';
 export { AnalyticsReport, AnalyticsRow, Block, BlockOf, CategoryGroup, CategoryRef, Collection, CollectionEntry, CollectionRef, DonationCheckout, DonationInput, EntryDetails, EventCustomFields, EventRegistration, EventTicket, EventVolunteerShift, EventVolunteering, Fundraiser, FundraiserDetail, HearthEvent, HearthEventDetail, ImageRef, KnownBlock, Page, PageMeta, PageSummary, Position, Redirect, RegistrationInput, RegistrationResult, ResolvedBlock, Site, SiteAnalytics, SiteSettings, SitemapEntry, UnknownBlock, VolunteerInput, VolunteerResult, WebhookPayload, directionsUrl, focalPosition, pinned, videoEmbedUrl } from '@the-smithy/hearth-schema';
 
 /** A plugin adds resources (and can use the core's `request`) under its own names. */

package/dist/index.js

@@ -5,7 +5,7 @@ import {
   findRedirect,
   isHearthError,
   normalizeSlug
-} from "./chunk-V47RFBJE.js";
+} from "./chunk-RZNKY7HG.js";
 
 // src/index.ts
 import { videoEmbedUrl } from "@the-smithy/hearth-schema";

package/dist/next.d.ts

@@ -1,4 +1,4 @@
-import { H as HearthCore, b as CollectionPage, E as EventCollectionPage, F as FormResult, c as FormValues } from './client-IImehdSM.js';
+import { H as HearthCore, b as CollectionPage, E as EventCollectionPage, F as FormResult, c as FormValues } from './client-BXkB1aKA.js';
 import * as _the_smithy_hearth_schema from '@the-smithy/hearth-schema';
 import { Site, PageMeta } from '@the-smithy/hearth-schema';
 import { Metadata, MetadataRoute } from 'next';
@@ -254,6 +254,12 @@ declare function createHearthNext(client: HearthCore, { tag, revalidate }?: Hear
      *   export default hearthNext.sitemapWith(["/events", "/fundraisers"]);
      */
     sitemapWith(paths: string[]): () => Promise<MetadataRoute.Sitemap>;
+    /**
+     * GET handler for app/llms.txt/route.ts, the summary AI tools read (https://llmstxt.org):
+     *   export const GET = hearthNext.llmsTxtHandler();
+     * Not found until the site has a domain in Hearth, while it's hidden from search engines, and on preview deploys.
+     */
+    llmsTxtHandler(): () => Promise<Response>;
     /**
      * POST handler for the site's revalidation webhook (app/api/revalidate/route.ts):
      *   export const POST = hearthNext.revalidateHandler();

package/dist/next.js

@@ -2,7 +2,7 @@ import {
   findRedirect,
   isHearthError,
   normalizeSlug
-} from "./chunk-V47RFBJE.js";
+} from "./chunk-RZNKY7HG.js";
 import {
   parseWebhook,
   tagsForWebhook
@@ -284,6 +284,18 @@ function createHearthNext(client, { tag = "hearth", revalidate = 3600 } = {}) {
         return [...entries.map((e) => ({ url: e.url, ...e.lastModified ? { lastModified: e.lastModified } : {}, priority: e.priority })), ...extra];
       };
     },
+    /**
+     * GET handler for app/llms.txt/route.ts, the summary AI tools read (https://llmstxt.org):
+     *   export const GET = hearthNext.llmsTxtHandler();
+     * Not found until the site has a domain in Hearth, while it's hidden from search engines, and on preview deploys.
+     */
+    llmsTxtHandler() {
+      return async () => {
+        const text = isNonProductionDeploy() ? null : await client.llmsTxt(tags(`${tag}:pages`, `${tag}:events`, `${tag}:site`));
+        if (!text) return new Response("Not found", { status: 404, headers: { "Content-Type": "text/plain; charset=utf-8" } });
+        return new Response(text, { headers: { "Content-Type": "text/markdown; charset=utf-8" } });
+      };
+    },
     /**
      * POST handler for the site's revalidation webhook (app/api/revalidate/route.ts):
      *   export const POST = hearthNext.revalidateHandler();

package/dist/testing.d.ts

@@ -5,6 +5,8 @@ type MockHearthData = {
     pages?: Page[];
     events?: (HearthEvent | HearthEventDetail)[];
     sitemap?: SitemapEntry[];
+    /** The site's llms.txt; null (the default) is a site without one. */
+    llmsTxt?: string | null;
     redirects?: Redirect[];
     /** Collections, with their entries (page collections) keyed by collection slug. */
     collections?: Collection[];

package/dist/testing.js

@@ -46,6 +46,7 @@ function createMockHearth(data = {}) {
       return event ? json({ data: event }) : notFound();
     }
     if (rest === "/sitemap") return json({ data: data.sitemap ?? [] });
+    if (rest === "/llms") return json({ data: data.llmsTxt ?? null });
     if (rest === "/redirects") return json({ data: data.redirects ?? [] });
     if (rest === "/fundraisers" || rest.startsWith("/fundraisers?")) {
       const status = url.searchParams.get("status") ?? "active";

package/llms.md

@@ -37,6 +37,7 @@ client components: the API key is secret.
 - `events.list({ when?: "upcoming" | "past", limit? }): HearthEvent[]`
 - `events.get(slug): HearthEventDetail | null`
 - `sitemap(): SitemapEntry[]`
+- `llmsTxt(): string | null`: the site's llms.txt (Markdown for AI tools), null while it has no domain or is hidden
 - `forms.get(formKey): HearthForm | null`: the site's form (`{ key, name, fields, submitLabel, successMessage }`), to render outside a Form block, e.g. in a footer. Each site has one form, `contact`, and every Form block shows it. Fields are `{ name, label, type, required, options?, placeholder? }`; render `placeholder` in the input (for a select, as the prompt option). A Form block can instead name an Ember form (`data.emberFormId`, `frm_…`): render it with `EmberForm` from `@the-smithy/ember/react`, with the site's form as the fallback.
 - `forms.submit(formKey, FormData | object, { ip? }): { ok: true, message } | { ok: false, message, fieldErrors }`
 - `request<T>(path, opts)`: the raw call for anything else under `/api/v1/sites/{site}`
@@ -78,6 +79,8 @@ client components: the API key is secret.
 - `generateMetadata`: `return hearthNext.generatePageMetadata((await params).slug)`
 - Events: `metadataFromMeta(event.meta)`
 - `app/sitemap.ts`: `export default hearthNext.sitemap`
+- `app/llms.txt/route.ts`: `export const GET = hearthNext.llmsTxtHandler()` (the organization, contact details,
+  hours and every listed page with a line on it, for AI tools; 404 on previews and while the site is hidden)
 - `app/api/revalidate/route.ts`: `export const POST = hearthNext.revalidateHandler()`
 - Giving: `getFundraisers(opts)`, `getFundraiser(slug)`, and a donation form's server action:
   `export const donate = async (prev: FormResult | null, fd: FormData) => hearthNext.donateAction()(prev, fd)`
@@ -113,5 +116,5 @@ client components: the API key is secret.
 ## Other entry points
 - `@the-smithy/hearth/webhooks`: `verifyWebhook(raw, header, secret)`, `parseWebhook(request, secret)`,
   `tagsForWebhook(payload)`
-- `@the-smithy/hearth/testing`: `createMockHearth({ site, pages, events, sitemap, onForm })` returns
+- `@the-smithy/hearth/testing`: `createMockHearth({ site, pages, events, sitemap, llmsTxt, onForm })` returns
   `{ fetch, requests }`. Pass `fetch` to `createHearthClient`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-smithy/hearth",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Typed client for the Hearth Delivery API: content, SEO, forms and publish webhooks.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -49,7 +49,7 @@
     "llms.md"
   ],
   "dependencies": {
-    "@the-smithy/hearth-schema": "^0.21.0"
+    "@the-smithy/hearth-schema": "^0.22.0"
   },
   "peerDependencies": {
     "next": ">=15",