@the-smithy/hearth 0.12.0 → 0.13.1

package/README.md

@@ -9,12 +9,15 @@ nothing without a Hearth account. Developer access is by invitation: request it
 
 ## Getting started
 
-Most sites start from the starter template, which has this package set up already:
+Most sites start from the starter template, which has this package set up already. For example, for a site
+whose address in Hearth is `acme` (the part after `/admin/sites/` in Hearth's address bar):
 
 ```sh
-pnpm create @the-smithy/hearth-site my-site --site <your-site>
+pnpm create @the-smithy/hearth-site@latest acme-website --site acme
 ```
 
+`acme-website` is the folder it creates. Keep `@latest`: pnpm otherwise skips a release in its first day.
+
 To add it to an existing project instead:
 
 ```sh
@@ -22,9 +25,9 @@ pnpm add @the-smithy/hearth
 ```
 
 ```dotenv
-# .env.local
-HEARTH_SITE=<your-site>
-HEARTH_API_KEY=<a key from the site's Settings → Developers in Hearth>
+# .env.local (never committed)
+HEARTH_SITE=acme
+HEARTH_API_KEY=hk_…   # Hearth → the site → Settings → Developers → API keys
 ```
 
 ```ts
@@ -37,6 +40,18 @@ export const hearth = createHearthClient({
 });
 ```
 
+## With an AI coding assistant
+
+The package ships `llms.md`, a short reference written for coding agents: point yours at
+`node_modules/@the-smithy/hearth/llms.md`. Once the key is in `.env.local`, the full API guide can be saved for
+the agent too (sites made from the starter have `pnpm hearth:docs` for this):
+
+```sh
+curl -H "Authorization: Bearer $HEARTH_API_KEY" https://hearth.thesmithy.io/admin/docs/api.md -o hearth-api.md
+```
+
+Keep `hearth-api.md` out of git, and the key out of chat: the agent only needs it in `.env.local`.
+
 ## Documentation
 
 Once you have developer access, the full documentation (every method, Next.js helpers, rendering blocks,

package/dist/{chunk-7ZTQW5QR.js → chunk-ZK7X4FDQ.js}

@@ -240,6 +240,10 @@ 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" })
     },
+    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" })
+    },
     forms: {
       /** One of the site's forms, to render anywhere (a footer, a modal); null if there's no form with that key. */
       get: (formKey, o = {}) => maybe(`/forms/${encodeURIComponent(formKey)}`, { ...o, resource: "forms.get" }),

package/dist/{client-DUEmHcTL.d.ts → client-DCiaDdvu.d.ts}

@@ -187,6 +187,139 @@ 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>;
     };
+    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<{
+            key: string;
+            name: string;
+            description: string;
+            fields: ({
+                kind: "text";
+                name: string;
+                label: string;
+                hint?: string | undefined;
+                optional?: boolean | undefined;
+            } | {
+                kind: "textarea";
+                name: string;
+                label: string;
+                hint?: string | undefined;
+                optional?: boolean | undefined;
+            } | {
+                kind: "markdown";
+                name: string;
+                label: string;
+                hint?: string | undefined;
+                optional?: boolean | undefined;
+            } | {
+                kind: "url";
+                name: string;
+                label: string;
+                hint?: string | undefined;
+                optional?: boolean | undefined;
+            } | {
+                kind: "image";
+                name: string;
+                label: string;
+                hint?: string | undefined;
+                optional?: boolean | undefined;
+            } | {
+                kind: "link";
+                name: string;
+                label: string;
+                hint?: string | undefined;
+                optional?: boolean | undefined;
+            } | {
+                kind: "number";
+                name: string;
+                label: string;
+                hint?: string | undefined;
+                optional?: boolean | undefined;
+            } | {
+                kind: "boolean";
+                name: string;
+                label: string;
+                hint?: string | undefined;
+                optional?: boolean | undefined;
+            } | {
+                kind: "select";
+                options: {
+                    value: string;
+                    label: string;
+                }[];
+                name: string;
+                label: string;
+                hint?: string | undefined;
+                optional?: boolean | undefined;
+            } | {
+                kind: "list";
+                itemLabel: string;
+                fields: ({
+                    kind: "text";
+                    name: string;
+                    label: string;
+                    hint?: string | undefined;
+                    optional?: boolean | undefined;
+                } | {
+                    kind: "textarea";
+                    name: string;
+                    label: string;
+                    hint?: string | undefined;
+                    optional?: boolean | undefined;
+                } | {
+                    kind: "markdown";
+                    name: string;
+                    label: string;
+                    hint?: string | undefined;
+                    optional?: boolean | undefined;
+                } | {
+                    kind: "url";
+                    name: string;
+                    label: string;
+                    hint?: string | undefined;
+                    optional?: boolean | undefined;
+                } | {
+                    kind: "image";
+                    name: string;
+                    label: string;
+                    hint?: string | undefined;
+                    optional?: boolean | undefined;
+                } | {
+                    kind: "link";
+                    name: string;
+                    label: string;
+                    hint?: string | undefined;
+                    optional?: boolean | undefined;
+                } | {
+                    kind: "number";
+                    name: string;
+                    label: string;
+                    hint?: string | undefined;
+                    optional?: boolean | undefined;
+                } | {
+                    kind: "boolean";
+                    name: string;
+                    label: string;
+                    hint?: string | undefined;
+                    optional?: boolean | undefined;
+                } | {
+                    kind: "select";
+                    options: {
+                        value: string;
+                        label: string;
+                    }[];
+                    name: string;
+                    label: string;
+                    hint?: string | undefined;
+                    optional?: boolean | undefined;
+                })[];
+                name: string;
+                label: string;
+                hint?: string | undefined;
+                optional?: boolean | undefined;
+            })[];
+        }[]>;
+    };
     forms: {
         /** One of the site's forms, to render anywhere (a footer, a modal); null if there's no form with that key. */
         get: (formKey: string, o?: CallOptions) => Promise<HearthForm | null>;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { H as HearthCore, a as HearthClientOptions } from './client-DUEmHcTL.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, i as isHearthError, n as normalizeSlug } from './client-DUEmHcTL.js';
+import { H as HearthCore, a as HearthClientOptions } from './client-DCiaDdvu.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, i as isHearthError, n as normalizeSlug } from './client-DCiaDdvu.js';
 export { Block, BlockOf, CategoryGroup, CategoryRef, Collection, CollectionEntry, CollectionRef, DonationCheckout, DonationInput, EntryDetails, EventCustomFields, EventRegistration, EventTicket, Fundraiser, FundraiserDetail, HearthEvent, HearthEventDetail, KnownBlock, Page, PageMeta, PageSummary, RegistrationInput, RegistrationResult, ResolvedBlock, Site, SiteSettings, SitemapEntry, UnknownBlock, WebhookPayload, 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

@@ -4,7 +4,7 @@ import {
   createCore,
   isHearthError,
   normalizeSlug
-} from "./chunk-7ZTQW5QR.js";
+} from "./chunk-ZK7X4FDQ.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-DUEmHcTL.js';
+import { H as HearthCore, b as CollectionPage, E as EventCollectionPage, F as FormResult, c as FormValues } from './client-DCiaDdvu.js';
 import * as _the_smithy_hearth_schema from '@the-smithy/hearth-schema';
 import { PageMeta } from '@the-smithy/hearth-schema';
 import { Metadata, MetadataRoute } from 'next';
@@ -31,6 +31,136 @@ declare function createHearthNext(client: HearthCore, { tag, revalidate }?: Hear
         category?: string;
     }) => Promise<_the_smithy_hearth_schema.HearthEvent[]>;
     getCategories: () => Promise<_the_smithy_hearth_schema.CategoryGroup[]>;
+    getCustomBlocks: () => Promise<{
+        key: string;
+        name: string;
+        description: string;
+        fields: ({
+            kind: "text";
+            name: string;
+            label: string;
+            hint?: string | undefined;
+            optional?: boolean | undefined;
+        } | {
+            kind: "textarea";
+            name: string;
+            label: string;
+            hint?: string | undefined;
+            optional?: boolean | undefined;
+        } | {
+            kind: "markdown";
+            name: string;
+            label: string;
+            hint?: string | undefined;
+            optional?: boolean | undefined;
+        } | {
+            kind: "url";
+            name: string;
+            label: string;
+            hint?: string | undefined;
+            optional?: boolean | undefined;
+        } | {
+            kind: "image";
+            name: string;
+            label: string;
+            hint?: string | undefined;
+            optional?: boolean | undefined;
+        } | {
+            kind: "link";
+            name: string;
+            label: string;
+            hint?: string | undefined;
+            optional?: boolean | undefined;
+        } | {
+            kind: "number";
+            name: string;
+            label: string;
+            hint?: string | undefined;
+            optional?: boolean | undefined;
+        } | {
+            kind: "boolean";
+            name: string;
+            label: string;
+            hint?: string | undefined;
+            optional?: boolean | undefined;
+        } | {
+            kind: "select";
+            options: {
+                value: string;
+                label: string;
+            }[];
+            name: string;
+            label: string;
+            hint?: string | undefined;
+            optional?: boolean | undefined;
+        } | {
+            kind: "list";
+            itemLabel: string;
+            fields: ({
+                kind: "text";
+                name: string;
+                label: string;
+                hint?: string | undefined;
+                optional?: boolean | undefined;
+            } | {
+                kind: "textarea";
+                name: string;
+                label: string;
+                hint?: string | undefined;
+                optional?: boolean | undefined;
+            } | {
+                kind: "markdown";
+                name: string;
+                label: string;
+                hint?: string | undefined;
+                optional?: boolean | undefined;
+            } | {
+                kind: "url";
+                name: string;
+                label: string;
+                hint?: string | undefined;
+                optional?: boolean | undefined;
+            } | {
+                kind: "image";
+                name: string;
+                label: string;
+                hint?: string | undefined;
+                optional?: boolean | undefined;
+            } | {
+                kind: "link";
+                name: string;
+                label: string;
+                hint?: string | undefined;
+                optional?: boolean | undefined;
+            } | {
+                kind: "number";
+                name: string;
+                label: string;
+                hint?: string | undefined;
+                optional?: boolean | undefined;
+            } | {
+                kind: "boolean";
+                name: string;
+                label: string;
+                hint?: string | undefined;
+                optional?: boolean | undefined;
+            } | {
+                kind: "select";
+                options: {
+                    value: string;
+                    label: string;
+                }[];
+                name: string;
+                label: string;
+                hint?: string | undefined;
+                optional?: boolean | undefined;
+            })[];
+            name: string;
+            label: string;
+            hint?: string | undefined;
+            optional?: boolean | undefined;
+        })[];
+    }[]>;
     getCollections: () => Promise<_the_smithy_hearth_schema.Collection[]>;
     getCollection: (slug: string, opts?: {
         limit?: number;

package/dist/next.js

@@ -1,7 +1,7 @@
 import {
   isHearthError,
   normalizeSlug
-} from "./chunk-7ZTQW5QR.js";
+} from "./chunk-ZK7X4FDQ.js";
 import {
   parseWebhook,
   tagsForWebhook
@@ -51,6 +51,7 @@ function createHearthNext(client, { tag = "hearth", revalidate = 3600 } = {}) {
     getPage,
     getEvents: (opts) => client.events.list(opts, tags(`${tag}:events`)),
     getCategories: () => client.categories.list(tags(`${tag}:site`)),
+    getCustomBlocks: () => client.customBlocks.list(tags(`${tag}:site`)),
     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`)),

package/dist/react.d.ts

@@ -29,5 +29,17 @@ declare function HearthBlocks({ blocks, components, fallback, }: {
 declare function JsonLd({ data }: {
     data: Record<string, unknown>[];
 }): react.JSX.Element;
+/**
+ * An Embed block's HTML in a sandboxed iframe: scripts run, but sealed off from your page (its own origin, no
+ * access to your cookies or DOM). Give it the block; style the wrapper yourself.
+ *
+ *   embed: ({ block }) => <HearthEmbed block={block} className="mx-auto max-w-3xl" />
+ */
+declare function HearthEmbed({ block, className }: {
+    block: Extract<KnownBlock, {
+        type: "embed";
+    }>;
+    className?: string;
+}): react.JSX.Element;
 
-export { type BlockComponents, HearthBlocks, JsonLd };
+export { type BlockComponents, HearthBlocks, HearthEmbed, JsonLd };

package/dist/react.js

@@ -1,5 +1,6 @@
 // src/react.tsx
 import { Fragment } from "react";
+import { EMBED_ALLOW, EMBED_SANDBOX, embedDocument } from "@the-smithy/hearth-schema";
 import { Fragment as Fragment2, jsx } from "react/jsx-runtime";
 function HearthBlocks({
   blocks,
@@ -18,7 +19,24 @@ function HearthBlocks({
 function JsonLd({ data }) {
   return /* @__PURE__ */ jsx(Fragment2, { children: data.map((item, i) => /* @__PURE__ */ jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(item).replace(/</g, "\\u003c") } }, i)) });
 }
+function HearthEmbed({ block, className }) {
+  return /* @__PURE__ */ jsx(
+    "iframe",
+    {
+      srcDoc: embedDocument(block.data.html),
+      sandbox: EMBED_SANDBOX,
+      allow: EMBED_ALLOW,
+      title: block.data.title,
+      height: block.data.height,
+      loading: "lazy",
+      referrerPolicy: "strict-origin-when-cross-origin",
+      className,
+      style: { width: "100%", border: 0, display: "block" }
+    }
+  );
+}
 export {
   HearthBlocks,
+  HearthEmbed,
   JsonLd
 };

package/llms.md

@@ -11,6 +11,21 @@ client components: the API key is secret.
   `export const hearth = createHearthClient({ site: process.env.HEARTH_SITE!, apiKey: process.env.HEARTH_API_KEY! })`
   `export const hearthNext = createHearthNext(hearth)` (from `@the-smithy/hearth/next`)
 
+## Working with the developer (read first)
+- Start by confirming the setup, and say what you found. In a site made from the starter: `pnpm hearth:check`
+  (connection, published pages, block types in use and any without a component). Elsewhere: call
+  `hearth.site.get()` and `hearth.pages.list()` from a server-side script.
+- Full guide (every block's fields, events, forms, previews, SEO): `pnpm hearth:docs` in the starter, or
+  `GET https://hearth.thesmithy.io/admin/docs/api.md` with `Authorization: Bearer $HEARTH_API_KEY`. Save it to
+  a gitignored file and read the parts you need.
+- Never print, log or commit the API key, and don't ask the developer to paste it into chat. Read it only from
+  env. If it's missing or rejected (`HearthError` code `unauthorized`), ask them to create one in Hearth → the
+  site → Settings → Developers → API keys and put it in `.env.local`.
+- Only published content comes back. A new site whose pages are drafts returns no pages, so every route 404s:
+  that's expected. Tell the developer to publish in Hearth; never add placeholder content to the code.
+- Content (text, menus, contact details, SEO) is edited in Hearth. The code owns design: tokens, layout and one
+  component per block type.
+
 ## Client (`@the-smithy/hearth`)
 - `site.get(): Site`
 - `pages.list(): PageSummary[]`
@@ -68,6 +83,8 @@ client components: the API key is secret.
 ## React (`@the-smithy/hearth/react`)
 - `<HearthBlocks blocks={page.blocks} components={{ hero: Hero, ... }} fallback={...} />`
   Each component receives `{ block }`. The map is typed by `BlockComponents`.
+- `<HearthEmbed block={block} />`: renders an Embed block's `html` in a sandboxed iframe. Never inject `html` into the page.
+- Custom blocks: `{ type: "custom", data: { block: "<key>", values } }`, the site's own block types; map keys to components, skip unknown ones. `customBlocks.list()` / `hearthNext.getCustomBlocks()` describe their fields.
 - `<JsonLd data={page.meta.jsonLd} />`
 
 ## Other entry points

package/package.json

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