@the-smithy/hearth 0.19.0 → 0.21.0

package/dist/{chunk-62OMCVBE.js → chunk-V47RFBJE.js}

@@ -196,6 +196,28 @@ function createCore(options) {
           }
           throw err;
         }
+      },
+      /**
+       * Sign up to volunteer at an event that asks for volunteers (its `volunteering` is set). Post `shifts` when
+       * `volunteering.pickShifts` isn't "none", and each answer under its field's `name`. Validation problems
+       * (including a full shift or closed sign-up) resolve to { ok: false, fieldErrors }; network and auth failures throw.
+       */
+      volunteer: async (slug, input, opts = {}) => {
+        try {
+          const data = await request(`/events/${encodeURIComponent(slug)}/volunteers`, {
+            method: "POST",
+            body: input,
+            headers: opts.ip ? { "X-Forwarded-For": opts.ip } : void 0,
+            signal: opts.signal,
+            resource: "events.volunteer"
+          });
+          return { ok: true, ...data };
+        } catch (err) {
+          if (isHearthError(err) && (err.code === "bad_request" || err.code === "rate_limited" || err.code === "feature_disabled" || err.code === "not_found")) {
+            return { ok: false, message: err.message, fieldErrors: err.details ?? {} };
+          }
+          throw err;
+        }
       }
     },
     categories: {

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

@@ -1,4 +1,4 @@
-import { Collection, CollectionEntry, HearthEvent, Site, PageSummary, Page, HearthEventDetail, RegistrationInput, RegistrationResult, 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, 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. */
@@ -142,6 +142,21 @@ declare function createCore(options: HearthClientOptions): {
             message: string;
             fieldErrors: Record<string, string>;
         }>;
+        /**
+         * Sign up to volunteer at an event that asks for volunteers (its `volunteering` is set). Post `shifts` when
+         * `volunteering.pickShifts` isn't "none", and each answer under its field's `name`. Validation problems
+         * (including a full shift or closed sign-up) resolve to { ok: false, fieldErrors }; network and auth failures throw.
+         */
+        volunteer: (slug: string, input: VolunteerInput, opts?: {
+            ip?: string | null;
+            signal?: AbortSignal;
+        }) => Promise<({
+            ok: true;
+        } & VolunteerResult) | {
+            ok: false;
+            message: string;
+            fieldErrors: Record<string, string>;
+        }>;
     };
     categories: {
         /** The site's category groups, each with its categories. */

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { H as HearthCore, a as HearthClientOptions } from './client-B3n7p9lK.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-B3n7p9lK.js';
-export { AnalyticsReport, AnalyticsRow, Block, BlockOf, CategoryGroup, CategoryRef, Collection, CollectionEntry, CollectionRef, DonationCheckout, DonationInput, EntryDetails, EventCustomFields, EventRegistration, EventTicket, Fundraiser, FundraiserDetail, HearthEvent, HearthEventDetail, KnownBlock, Page, PageMeta, PageSummary, Redirect, RegistrationInput, RegistrationResult, ResolvedBlock, Site, SiteAnalytics, SiteSettings, SitemapEntry, UnknownBlock, WebhookPayload, videoEmbedUrl } from '@the-smithy/hearth-schema';
+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';
 
 /** 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,10 +5,12 @@ import {
   findRedirect,
   isHearthError,
   normalizeSlug
-} from "./chunk-62OMCVBE.js";
+} from "./chunk-V47RFBJE.js";
 
 // src/index.ts
 import { videoEmbedUrl } from "@the-smithy/hearth-schema";
+import { focalPosition } from "@the-smithy/hearth-schema";
+import { directionsUrl, pinned } from "@the-smithy/hearth-schema";
 function definePlugin(setup) {
   return { setup };
 }
@@ -27,8 +29,11 @@ export {
   HearthError,
   createHearthClient,
   definePlugin,
+  directionsUrl,
   findRedirect,
+  focalPosition,
   isHearthError,
   normalizeSlug,
+  pinned,
   videoEmbedUrl
 };

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-B3n7p9lK.js';
+import { H as HearthCore, b as CollectionPage, E as EventCollectionPage, F as FormResult, c as FormValues } from './client-IImehdSM.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';
@@ -204,6 +204,14 @@ declare function createHearthNext(client: HearthCore, { tag, revalidate }?: Hear
     registerAction: (slug: string, { returnPath }?: {
         returnPath?: string;
     }) => (_prev: FormResult | null, formData: FormData) => Promise<FormResult>;
+    /**
+     * A volunteer sign-up form's server action, for `useActionState(action, null)`:
+     *   export const volunteer = async (slug: string, prev: FormResult | null, fd: FormData) => volunteerAction(slug)(prev, fd);
+     * Fields: `name`, `email`, one `shift` per chosen shift id, the honeypot `_gotcha`, and every other field as an
+     * answer under its name (a ticked checkbox posts "on"). Resolves to { ok: true, message } with the
+     * event's thank-you message.
+     */
+    volunteerAction: (slug: string) => (_prev: FormResult | null, formData: FormData) => Promise<FormResult>;
     /** Whether this request is a draft preview (to show a "Preview" banner with an exit link). */
     isPreview: () => Promise<boolean>;
     /**

package/dist/next.js

@@ -2,7 +2,7 @@ import {
   findRedirect,
   isHearthError,
   normalizeSlug
-} from "./chunk-62OMCVBE.js";
+} from "./chunk-V47RFBJE.js";
 import {
   parseWebhook,
   tagsForWebhook
@@ -129,6 +129,33 @@ function createHearthNext(client, { tag = "hearth", revalidate = 3600 } = {}) {
       if (result.status === "pending") redirect(result.checkoutUrl);
       return { ok: true, message: "You're registered. A confirmation is on its way to your email." };
     },
+    /**
+     * A volunteer sign-up form's server action, for `useActionState(action, null)`:
+     *   export const volunteer = async (slug: string, prev: FormResult | null, fd: FormData) => volunteerAction(slug)(prev, fd);
+     * Fields: `name`, `email`, one `shift` per chosen shift id, the honeypot `_gotcha`, and every other field as an
+     * answer under its name (a ticked checkbox posts "on"). Resolves to { ok: true, message } with the
+     * event's thank-you message.
+     */
+    volunteerAction: (slug) => async (_prev, formData) => {
+      const h = await headers();
+      const answers = {};
+      for (const [key, value] of formData.entries()) {
+        if (typeof value !== "string" || key.startsWith("$") || ["name", "email", "shift", "_gotcha"].includes(key)) continue;
+        answers[key] = value;
+      }
+      const result = await client.events.volunteer(
+        slug,
+        {
+          name: String(formData.get("name") ?? "").trim(),
+          email: String(formData.get("email") ?? "").trim(),
+          shifts: formData.getAll("shift").map(String),
+          answers,
+          _gotcha: String(formData.get("_gotcha") ?? "") || void 0
+        },
+        { ip: clientIp(h) }
+      );
+      return result.ok ? { ok: true, message: result.message } : { ok: false, message: result.message, fieldErrors: result.fieldErrors };
+    },
     /** Whether this request is a draft preview (to show a "Preview" banner with an exit link). */
     isPreview: async () => Boolean(await previewToken()),
     /**

package/llms.md

@@ -4,6 +4,10 @@ Hearth is a headless CMS. This package is a server-only client for its Delivery
 client components: the API key is secret.
 
 ## Setup
+- Sites made with `pnpm create @the-smithy/hearth-site` already have all of this, and every block, page and form,
+  in `src/hearth/` (the client is `@/hearth/client`). Don't rebuild them: style the site in `src/theme/` (tokens,
+  and Tailwind classes per slot; `src/hearth/theme/defaults.ts` lists the slots) and read the site's `CLAUDE.md`.
+  `pnpm hearth:update` brings in new releases. The rest of this section is for other Next.js apps.
 - `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`
@@ -41,6 +45,11 @@ client components: the API key is secret.
 - 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 }`.
+- Volunteers: `events.volunteer(slug, { name, email, shifts?, answers? }, { ip? })`: `{ ok: true, signupId, message }` or
+  `{ ok: false, message, fieldErrors }`. Events asking for volunteers have `volunteering: { open, closesAt, intro, fields,
+  pickShifts: "none" | "one" | "many", shifts[], submitLabel, successMessage, fundraiser }`.
+  The `volunteerSignup` block places that form anywhere: its `data.event` is the Event (no `blocks`, `volunteering` always set);
+  without `eventSlug` it stands for the event whose page it's on, and an event page with one leaves out its own form.
 - 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 }`.
@@ -53,6 +62,15 @@ client components: the API key is secret.
   `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.
+- Images are `ImageRef = { src, alt, width?, height?, focal?: { x, y } }`. `focal` is the spot to keep in view when the
+  image is cropped (percentages across and down, set in Hearth's media library). For an image with `object-fit: cover`,
+  set `style={{ objectPosition: focalPosition(image, frameRatio) }}` (`focalPosition` from `@the-smithy/hearth`; the
+  frame's width / height centres the spot as far as the crop allows, omit it for frames whose shape changes). Don't
+  apply it to uncropped images (`object-contain`, logos).
+- Places (`location`, and each of `locations`' `items`) carry `position?: Position = { lat, lng }`, the map pin set in
+  Hearth. Draw maps from it, never by looking addresses up: the template uses MapLibre GL with OpenFreeMap tiles (free,
+  no key, no cookies). `pinned(places)` keeps the places with a pin; `directionsUrl(place)` links to directions by
+  name and address. Without a pin, show no map.
 
 ## Next.js (`@the-smithy/hearth/next`)
 - `hearthNext.getPage(slug)`, `getPages()`, `getSite()`, `getEvents(opts)`, `getEvent(slug)`:
@@ -69,6 +87,8 @@ client components: the API key is secret.
 - 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`.
+- Volunteers: `volunteerAction(slug)` for a sign-up form (`name`, `email`, one `shift` per chosen shift, every other
+  field as an answer under its name); resolves to `{ ok: true, message }` with the event's thank-you message.
 - 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-smithy/hearth",
-  "version": "0.19.0",
+  "version": "0.21.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.19.0"
+    "@the-smithy/hearth-schema": "^0.21.0"
   },
   "peerDependencies": {
     "next": ">=15",