@the-smithy/hearth 0.21.0 → 0.23.0

package/dist/{chunk-V47RFBJE.js → chunk-QDCU7YWV.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" }) ?? []
@@ -292,6 +297,18 @@ function createCore(options) {
       /** Check a preview token from a Hearth preview link. Throws (unauthorized) if it's expired or for another site. */
       verify: (token, o = {}) => request("/preview", { ...o, preview: token, resource: "preview.verify" })
     },
+    globalBlocks: {
+      /**
+       * The site's global blocks (Global blocks in Hearth), resolved: pop-ups (`popup` set), menu dropdowns (a menu
+       * item's `dropdown` names one) and any others the site's code places by key. Empty from Hearth versions without them.
+       */
+      list: async (o = {}) => await maybe("/global-blocks", { ...o, resource: "globalBlocks.list" }) ?? [],
+      /** One global block by key, or null. */
+      get: async (key, o = {}) => {
+        const list = await maybe("/global-blocks", { ...o, resource: "globalBlocks.list" }) ?? [];
+        return list.find((g) => g.key === key) ?? null;
+      }
+    },
     customBlocks: {
       /** The site's own block types (Custom blocks in Hearth): each one's key, name and fields, for rendering `custom` blocks. */
       list: (o = {}) => request("/custom-blocks", { ...o, resource: "customBlocks.list" })

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

@@ -1,4 +1,4 @@
-import { Collection, CollectionEntry, HearthEvent, Site, PageSummary, Page, HearthEventDetail, RegistrationInput, RegistrationResult, VolunteerInput, VolunteerResult, CategoryGroup, SitemapEntry, Redirect, AnalyticsReport, Fundraiser, FundraiserDetail, DonationInput, DonationCheckout, HearthForm } from '@the-smithy/hearth-schema';
+import { Collection, CollectionEntry, HearthEvent, Site, PageSummary, Page, HearthEventDetail, RegistrationInput, RegistrationResult, VolunteerInput, VolunteerResult, CategoryGroup, SitemapEntry, Redirect, AnalyticsReport, Fundraiser, FundraiserDetail, DonationInput, DonationCheckout, GlobalBlock, HearthForm } from '@the-smithy/hearth-schema';
 
 type HearthErrorCode = "unauthorized" | "not_found" | "bad_request" | "feature_disabled" | "rate_limited" | "server_error" | "network" | "timeout" | "invalid_response";
 /** Any failure talking to Hearth. Messages never contain the API key. */
@@ -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[]>;
@@ -222,6 +227,15 @@ declare function createCore(options: HearthClientOptions): {
         /** Check a preview token from a Hearth preview link. Throws (unauthorized) if it's expired or for another site. */
         verify: (token: string, o?: Omit<CallOptions, "preview">) => Promise<PreviewSession>;
     };
+    globalBlocks: {
+        /**
+         * The site's global blocks (Global blocks in Hearth), resolved: pop-ups (`popup` set), menu dropdowns (a menu
+         * item's `dropdown` names one) and any others the site's code places by key. Empty from Hearth versions without them.
+         */
+        list: (o?: CallOptions) => Promise<GlobalBlock[]>;
+        /** One global block by key, or null. */
+        get: (key: string, o?: CallOptions) => Promise<GlobalBlock | null>;
+    };
     customBlocks: {
         /** The site's own block types (Custom blocks in Hearth): each one's key, name and fields, for rendering `custom` blocks. */
         list: (o?: CallOptions) => Promise<{

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-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';
-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';
+import { H as HearthCore, a as HearthClientOptions } from './client-Deumm7No.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-Deumm7No.js';
+export { AnalyticsReport, AnalyticsRow, Block, BlockOf, CategoryGroup, CategoryRef, Collection, CollectionEntry, CollectionRef, DonationCheckout, DonationInput, EntryDetails, EventCustomFields, EventRegistration, EventTicket, EventVolunteerShift, EventVolunteering, Fundraiser, FundraiserDetail, GlobalBlock, GlobalPopup, HearthEvent, HearthEventDetail, ImageRef, KnownBlock, Page, PageMeta, PageSummary, Position, Redirect, RegistrationInput, RegistrationResult, ResolvedBlock, SharedFrom, 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. */
 type HearthPlugin<T extends object = object> = {

package/dist/index.js

@@ -5,7 +5,7 @@ import {
   findRedirect,
   isHearthError,
   normalizeSlug
-} from "./chunk-V47RFBJE.js";
+} from "./chunk-QDCU7YWV.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-Deumm7No.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';
@@ -170,6 +170,8 @@ declare function createHearthNext(client: HearthCore, { tag, revalidate }?: Hear
             optional?: boolean | undefined;
         })[];
     }[]>;
+    /** Global blocks (pop-ups, menu dropdowns, ones the site places by key); drafts while previewing. */
+    getGlobalBlocks: () => Promise<_the_smithy_hearth_schema.GlobalBlock[]>;
     getCollections: () => Promise<_the_smithy_hearth_schema.Collection[]>;
     getCollection: (slug: string, opts?: {
         limit?: number;
@@ -254,6 +256,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-QDCU7YWV.js";
 import {
   parseWebhook,
   tagsForWebhook
@@ -60,6 +60,8 @@ function createHearthNext(client, { tag = "hearth", revalidate = 3600 } = {}) {
     getEvents: (opts) => client.events.list(opts, tags(`${tag}:events`)),
     getCategories: () => client.categories.list(tags(`${tag}:site`)),
     getCustomBlocks: () => client.customBlocks.list(tags(`${tag}:site`)),
+    /** Global blocks (pop-ups, menu dropdowns, ones the site places by key); drafts while previewing. */
+    getGlobalBlocks: async () => client.globalBlocks.list(await read(`${tag}:global`)),
     getCollections: () => client.collections.list(tags(`${tag}:site`, `${tag}:pages`)),
     getCollection: (slug, opts) => client.collections.get(slug, opts, tags(`${tag}:pages`, `${tag}:events`)),
     getEvent: async (slug) => client.events.get(slug, await read(`${tag}:events`)),
@@ -284,6 +286,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

@@ -1,11 +1,15 @@
-import { Site, Page, HearthEvent, HearthEventDetail, SitemapEntry, Redirect, Collection, CollectionEntry, CategoryGroup, Fundraiser, FundraiserDetail, HearthForm } from '@the-smithy/hearth-schema';
+import { Site, Page, HearthEvent, HearthEventDetail, SitemapEntry, Redirect, GlobalBlock, Collection, CollectionEntry, CategoryGroup, Fundraiser, FundraiserDetail, HearthForm } from '@the-smithy/hearth-schema';
 
 type MockHearthData = {
     site?: Partial<Site>;
     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[];
+    /** The site's global blocks (pop-ups, menu dropdowns). */
+    globalBlocks?: GlobalBlock[];
     /** Collections, with their entries (page collections) keyed by collection slug. */
     collections?: Collection[];
     entries?: Record<string, CollectionEntry[]>;

package/dist/testing.js

@@ -46,7 +46,9 @@ 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 === "/global-blocks") return json({ data: data.globalBlocks ?? [] });
     if (rest === "/fundraisers" || rest.startsWith("/fundraisers?")) {
       const status = url.searchParams.get("status") ?? "active";
       return json({ data: (data.fundraisers ?? []).filter((f) => status === "all" || f.status === status) });

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.23.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.23.0"
   },
   "peerDependencies": {
     "next": ">=15",