@the-smithy/hearth 0.0.0-stage → 0.13.0

package/llms.md

@@ -0,0 +1,79 @@
+# @the-smithy/hearth: reference for AI assistants
+
+Hearth is a headless CMS. This package is a server-only client for its Delivery API. Never import it in
+client components: the API key is secret.
+
+## Setup
+- `pnpm add @the-smithy/hearth` (public on npm; no registry config or token needed). It's useless without a
+  Hearth site's API key. The full guide is in Hearth under API docs (Markdown download).
+- env: `HEARTH_SITE`, `HEARTH_API_KEY`, optionally `HEARTH_WEBHOOK_SECRET`
+- `lib/hearth.ts`:
+  `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`)
+
+## Client (`@the-smithy/hearth`)
+- `site.get(): Site`
+- `pages.list(): PageSummary[]`
+- `pages.get(slug | string[] | undefined): Page | null` (empty means "home")
+- `events.list({ when?: "upcoming" | "past", limit? }): HearthEvent[]`
+- `events.get(slug): HearthEventDetail | null`
+- `sitemap(): SitemapEntry[]`
+- `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}`
+- Errors: `HearthError` with `.code` and `.status`. `isHearthError(e)`.
+- `preview.verify(token): { path, expiresAt, version }` checks a Hearth preview token; `version` changes whenever the site's drafts or content do.
+- Tickets: `events.register(slug, { ticket, name, email, phone?, teamName?, attendees?, notes?, returnUrl }, { ip? })`:
+  `{ ok: true, status: "confirmed" }`, `{ ok: true, status: "pending", checkoutUrl }` or `{ ok: false, message, fieldErrors }`.
+  Events with on-site registration have `registration: { open, closesAt, tickets[], fundraiser }`.
+- Giving (sites with the feature): `fundraisers.list({ status?, category?, limit? }): Fundraiser[]`,
+  `fundraisers.get(slug): FundraiserDetail | null`, `donations.checkout({ amountCents, fundraiser?, name?, email?,
+  anonymous?, message?, returnUrl }, { ip? })`: `{ ok: true, checkoutUrl }` or `{ ok: false, message, fieldErrors }`.
+- Every method takes a last `CallOptions` argument: `{ signal?, cache?, next?: { revalidate?, tags? }, preview? }`.
+  `preview` (a token) makes page and event reads return saved drafts, never cached.
+
+## Page shape
+`Page = { slug, path, title, seo, publishedAt, blocks: ResolvedBlock[], meta: PageMeta }`
+- `PageMeta`: `fullTitle`, `title`, `description`, `canonical`, `robots { index, follow }`,
+  `openGraph`, `twitter`, `image { url, width, height, alt }`, `jsonLd[]`.
+- Each block is `{ id, type, data }`; fields live on `data`. Narrow by `type`; use `BlockOf<"hero">` for one type.
+- Unknown future types arrive as `UnknownBlock`. Always handle a fallback.
+
+## Next.js (`@the-smithy/hearth/next`)
+- `hearthNext.getPage(slug)`, `getPages()`, `getSite()`, `getEvents(opts)`, `getEvent(slug)`:
+  tagged for revalidation. Call `notFound()` on null.
+- `generateMetadata`: `return hearthNext.generatePageMetadata((await params).slug)`
+- Events: `metadataFromMeta(event.meta)`
+- `app/sitemap.ts`: `export default hearthNext.sitemap`
+- `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)`
+  (fields `amount` or `amount=custom` + `customAmount` in dollars, `fundraiser`, `name`, `email`, `anonymous`,
+  `message`; it redirects to the payment page, which returns to `/donate/thank-you`). Ask staff to reserve
+  `donate` and `fundraisers` on the site's Plan card.
+- Tickets: `registerAction(slug)` for a registration form (`ticket`, `name`, `email`, `phone`, `teamName`, `notes`,
+  one `attendee` per name); free tickets resolve to `{ ok: true, message }`, paid ones redirect to checkout and return
+  to `/registered`.
+- Draft preview: `app/api/preview/route.ts`: `export const GET = hearthNext.previewHandler()` and
+  `app/api/preview/exit/route.ts`: `export const GET = hearthNext.exitPreviewHandler()`. While previewing,
+  `getPage`, `getEvent` and `getFundraiser` return drafts. Every site renders the SDK's live preview in its root
+  layout: `import { HearthPreview } from "@the-smithy/hearth/preview"` then
+  `{(await hearthNext.isPreview()) ? <HearthPreview /> : null}`. Hearth's side-by-side preview frames the site, so
+  never send `X-Frame-Options` and allow `frame-ancestors https://hearth.thesmithy.io` in any CSP. It refreshes the page as editors save drafts
+  (Hearth autosaves them); don't build a preview banner of your own.
+- Forms: in a "use server" file:
+  `export async function contact(_: FormResult | null, fd: FormData) { return hearthNext.submitForm("contact", fd) }`
+  Then use it with `useActionState(contact, null)`.
+
+## 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
+- `@the-smithy/hearth/webhooks`: `verifyWebhook(raw, header, secret)`, `parseWebhook(request, secret)`,
+  `tagsForWebhook(payload)`
+- `@the-smithy/hearth/testing`: `createMockHearth({ site, pages, events, sitemap, onForm })` returns
+  `{ fetch, requests }`. Pass `fetch` to `createHearthClient`.

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "@the-smithy/hearth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.13.0",
+  "description": "Typed client for the Hearth Delivery API: content, SEO, forms and publish webhooks.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/The-Smithy/hearth.git",
+    "directory": "packages/sdk"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./preview": {
+      "types": "./dist/preview.d.ts",
+      "import": "./dist/preview.js"
+    },
+    "./webhooks": {
+      "types": "./dist/webhooks.d.ts",
+      "import": "./dist/webhooks.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "llms.md"
+  ],
+  "dependencies": {
+    "@the-smithy/hearth-schema": "^0.13.0"
+  },
+  "peerDependencies": {
+    "next": ">=15",
+    "react": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "@types/react": "^19.3.0",
+    "next": "16.3.8",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }