@the-smithy/hearth 0.0.0-stage → 0.13.0

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) The Smithy. All rights reserved.
+
+You may use this package to build software that works with The Smithy's services (Hearth and Ember), with an
+account on the service it connects to. It's provided as is, without warranty of any kind.
+
+Questions: hello@thesmithy.io

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @the-smithy/hearth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The typed client for [Hearth](https://hearth.thesmithy.io), The Smithy's headless CMS: a site's frontend
+uses it to read its pages, events and settings, render SEO tags, submit forms and show live previews.
+
+**It needs API access to Hearth.** Every request is made with a Hearth site's API key, so the package does
+nothing without a Hearth account. Developer access is by invitation: request it at
+[hearth.thesmithy.io/developers](https://hearth.thesmithy.io/developers).
+
+## Getting started
+
+Most sites start from the starter template, which has this package set up already:
+
+```sh
+pnpm create @the-smithy/hearth-site my-site --site <your-site>
+```
+
+To add it to an existing project instead:
+
+```sh
+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>
+```
+
+```ts
+// lib/hearth.ts (server only: the key is secret)
+import { createHearthClient } from "@the-smithy/hearth";
+
+export const hearth = createHearthClient({
+  site: process.env.HEARTH_SITE!,
+  apiKey: process.env.HEARTH_API_KEY!,
+});
+```
+
+## Documentation
+
+Once you have developer access, the full documentation (every method, Next.js helpers, rendering blocks,
+previews, forms and webhooks) is in your Hearth account under **API docs**, with a Markdown version to give
+an AI coding assistant.
+
+## License
+
+For use with Hearth. See [LICENSE](./LICENSE).

package/dist/chunk-4VLAG4JX.js

@@ -0,0 +1,39 @@
+// src/webhooks.ts
+var encoder = new TextEncoder();
+function hexToBytes(hex) {
+  if (!/^[0-9a-f]+$/i.test(hex) || hex.length % 2) return null;
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+async function verifyWebhook(rawBody, signatureHeader, secret) {
+  if (!secret || !signatureHeader?.startsWith("sha256=")) return false;
+  const given = hexToBytes(signatureHeader.slice(7));
+  if (!given) return false;
+  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
+  return crypto.subtle.verify("HMAC", key, given, encoder.encode(rawBody));
+}
+async function parseWebhook(request, secret) {
+  const raw = await request.text();
+  if (!await verifyWebhook(raw, request.headers.get("x-hearth-signature"), secret)) return null;
+  try {
+    const payload = JSON.parse(raw);
+    return typeof payload?.site === "string" && typeof payload?.kind === "string" ? payload : null;
+  } catch {
+    return null;
+  }
+}
+function tagsForWebhook(payload, base = "hearth") {
+  const tags = [base];
+  if (payload.kind === "page" && payload.slug) tags.push(`${base}:page:${payload.slug}`);
+  if (payload.kind === "event" || payload.kind === "scheduled") tags.push(`${base}:events`);
+  if (payload.kind === "settings") tags.push(`${base}:site`);
+  if (payload.kind === "giving") tags.push(`${base}:giving`);
+  return tags;
+}
+
+export {
+  verifyWebhook,
+  parseWebhook,
+  tagsForWebhook
+};

package/dist/chunk-ZK7X4FDQ.js

@@ -0,0 +1,284 @@
+// src/errors.ts
+var HearthError = class extends Error {
+  status;
+  code;
+  details;
+  constructor(code, message, { status = 0, details, cause } = {}) {
+    super(message, { cause });
+    this.name = "HearthError";
+    this.code = code;
+    this.status = status;
+    this.details = details;
+  }
+};
+var isHearthError = (error) => error instanceof HearthError;
+var codeForStatus = (status) => {
+  if (status === 401) return "unauthorized";
+  if (status === 403) return "feature_disabled";
+  if (status === 404) return "not_found";
+  if (status === 400 || status === 422) return "bad_request";
+  if (status === 429) return "rate_limited";
+  return "server_error";
+};
+async function errorFromResponse(res) {
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+  }
+  const known = ["unauthorized", "not_found", "bad_request", "feature_disabled", "rate_limited", "server_error"];
+  const code = known.includes(body?.error?.code) ? body.error.code : codeForStatus(res.status);
+  return new HearthError(code, body?.error?.message ?? `Hearth responded with ${res.status}`, { status: res.status, details: body?.error?.details });
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://hearth.thesmithy.io";
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function normalizeSlug(slug) {
+  const joined = Array.isArray(slug) ? slug.join("/") : slug ?? "";
+  const clean = joined.split("/").map((s) => s.trim()).filter(Boolean).join("/").toLowerCase();
+  return clean || "home";
+}
+function timeoutSignal(ms, outer) {
+  const timeout = AbortSignal.timeout(ms);
+  if (!outer) return timeout;
+  if (typeof AbortSignal.any === "function") return AbortSignal.any([outer, timeout]);
+  return outer;
+}
+function toBody(values) {
+  if (typeof FormData !== "undefined" && values instanceof FormData) {
+    const out = {};
+    for (const [k, v] of values.entries()) if (typeof v === "string") out[k] = v;
+    return out;
+  }
+  return values;
+}
+function createCore(options) {
+  if (!options.site) throw new Error("Hearth: `site` is required.");
+  if (!options.apiKey) throw new Error("Hearth: `apiKey` is required.");
+  if (typeof window !== "undefined" && typeof document !== "undefined" && !options.allowBrowser) {
+    throw new Error("Hearth: the API key is secret, so the client only runs on the server. Fetch content in server code, or pass allowBrowser: true if you understand the risk.");
+  }
+  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  const retries = options.retries ?? 2;
+  const hooks = options.hooks ?? {};
+  const sitePath = `/api/v1/sites/${encodeURIComponent(options.site)}`;
+  async function request(path, init = {}) {
+    const method = init.method ?? "GET";
+    const resource = init.resource ?? `${method} ${path}`;
+    const attempts = method === "GET" ? retries + 1 : 1;
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+      const ctx = { resource, method, path, attempt };
+      let req = new Request(`${baseUrl}${sitePath}${path}`, {
+        method,
+        headers: {
+          Accept: "application/json",
+          Authorization: `Bearer ${options.apiKey}`,
+          ...init.body !== void 0 ? { "Content-Type": "application/json" } : {},
+          ...init.preview ? { "X-Hearth-Preview": init.preview } : {},
+          ...init.headers
+        },
+        body: init.body !== void 0 ? JSON.stringify(init.body) : void 0
+      });
+      req = await hooks.beforeRequest?.(req, ctx) ?? req;
+      try {
+        let res = await doFetch(req, {
+          signal: timeoutSignal(timeoutMs, init.signal),
+          ...init.preview ? { cache: "no-store" } : init.cache ? { cache: init.cache } : {},
+          ...init.next && !init.preview ? { next: init.next } : {}
+        });
+        res = await hooks.afterResponse?.(res, ctx) ?? res;
+        if (res.ok) {
+          const json = await res.json().catch(() => {
+            throw new HearthError("invalid_response", "Hearth returned a response that isn't JSON.", { status: res.status });
+          });
+          return json.data;
+        }
+        const error = await errorFromResponse(res);
+        const retryable = res.status === 429 || res.status >= 500;
+        if (!retryable || attempt === attempts) throw error;
+        lastError = error;
+        const retryAfter = Number(res.headers.get("retry-after"));
+        await sleep(Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(retryAfter * 1e3, 1e4) : backoff(attempt));
+      } catch (err) {
+        const error = isHearthError(err) ? err : err?.name === "TimeoutError" ? new HearthError("timeout", `Hearth didn't respond within ${timeoutMs} ms.`, { cause: err }) : err?.name === "AbortError" ? new HearthError("network", "The request was cancelled.", { cause: err }) : new HearthError("network", "Couldn't reach Hearth.", { cause: err });
+        const retryable = error.code === "network" || error.code === "timeout" || error.code === "rate_limited" || error.code === "server_error";
+        if (init.signal?.aborted || !retryable || attempt === attempts) {
+          hooks.onError?.(error, ctx);
+          throw error;
+        }
+        lastError = error;
+        await sleep(backoff(attempt));
+      }
+    }
+    throw lastError ?? new HearthError("network", "Couldn't reach Hearth.");
+  }
+  async function maybe(path, init) {
+    try {
+      return await request(path, init);
+    } catch (err) {
+      if (isHearthError(err) && err.code === "not_found") return null;
+      throw err;
+    }
+  }
+  async function check(value, kind) {
+    if (!options.validate || !value) return value;
+    const { blockSchema, blockTypes } = await import("@the-smithy/hearth-schema");
+    const blocks = value.blocks ?? [];
+    const problems = blocks.filter((b) => blockTypes.includes(b.type) && b.type !== "upcomingEvents" && b.type !== "eventSpotlight").map((b) => ({ b, r: blockSchema.safeParse(b) })).filter((x) => !x.r.success);
+    if (problems.length) {
+      const message = `Hearth ${kind} has ${problems.length} block(s) that don't match the schema: ${problems.map((p) => p.b.type).join(", ")}`;
+      if (options.validate === "warn") console.warn(message);
+      else throw new HearthError("invalid_response", message, { details: problems.map((p) => p.r.error?.issues) });
+    }
+    return value;
+  }
+  return {
+    /** The site's address in Hearth. */
+    siteSlug: options.site,
+    request,
+    site: {
+      get: (o = {}) => request("", { ...o, resource: "site.get" })
+    },
+    pages: {
+      list: (o = {}) => request("/pages", { ...o, resource: "pages.list" }),
+      get: async (slug, o = {}) => {
+        const s = normalizeSlug(slug);
+        const page = await maybe(`/pages/${s.split("/").map(encodeURIComponent).join("/")}`, { ...o, resource: "pages.get" });
+        return check(page, "page");
+      }
+    },
+    events: {
+      /** `category` is "group/category", e.g. "status/featured". */
+      list: (opts = {}, o = {}) => {
+        const q = new URLSearchParams();
+        if (opts.when) q.set("when", opts.when);
+        if (opts.limit) q.set("limit", String(opts.limit));
+        if (opts.collection) q.set("collection", opts.collection);
+        if (opts.category) q.set("category", opts.category);
+        return request(`/events${q.size ? `?${q}` : ""}`, { ...o, resource: "events.list" });
+      },
+      get: async (slug, o = {}) => check(await maybe(`/events/${encodeURIComponent(slug)}`, { ...o, resource: "events.get" }), "event"),
+      /**
+       * Register for an event with on-site registration (sites with Tickets). Free tickets come back confirmed; paid
+       * ones come back pending with a `checkoutUrl` to send the buyer to. Validation problems (including sold out or
+       * closed) resolve to { ok: false, fieldErrors }; network and auth failures throw.
+       */
+      register: async (slug, input, opts = {}) => {
+        try {
+          const data = await request(`/events/${encodeURIComponent(slug)}/registrations`, {
+            method: "POST",
+            body: input,
+            headers: opts.ip ? { "X-Forwarded-For": opts.ip } : void 0,
+            signal: opts.signal,
+            resource: "events.register"
+          });
+          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: {
+      /** The site's category groups, each with its categories. */
+      list: (o = {}) => request("/categories", { ...o, resource: "categories.list" })
+    },
+    collections: {
+      /** The site's collections: page groups (a blog) and event types (Talks). */
+      list: (o = {}) => request("/collections", { ...o, resource: "collections.list" }),
+      /**
+       * One collection by address ("blog", or nested "resources/case-studies") with its entries, or null.
+       * Page collections take limit/offset/tag; event collections take when/limit.
+       */
+      get: (slug, opts = {}, o = {}) => {
+        const q = new URLSearchParams();
+        for (const [k, v] of Object.entries(opts)) if (v !== void 0 && v !== "") q.set(k, String(v));
+        const path = normalizeSlug(slug).split("/").map(encodeURIComponent).join("/");
+        return maybe(`/collections/${path}${q.size ? `?${q}` : ""}`, { ...o, resource: "collections.get" });
+      }
+    },
+    sitemap: (o = {}) => request("/sitemap", { ...o, resource: "sitemap" }),
+    fundraisers: {
+      /** Fundraisers with progress (sites with Giving). `category` is "group/category". */
+      list: (opts = {}, o = {}) => {
+        const q = new URLSearchParams();
+        for (const [k, v] of Object.entries(opts)) if (v !== void 0 && v !== "") q.set(k, String(v));
+        return request(`/fundraisers${q.size ? `?${q}` : ""}`, { ...o, resource: "fundraisers.list" });
+      },
+      get: async (slug, o = {}) => check(await maybe(`/fundraisers/${encodeURIComponent(slug)}`, { ...o, resource: "fundraisers.get" }), "page")
+    },
+    donations: {
+      /**
+       * Start a donation; send the donor to `checkoutUrl`. Validation problems resolve to { ok: false, fieldErrors };
+       * network and auth failures throw. Pass the visitor's IP so Hearth can rate-limit per visitor.
+       */
+      checkout: async (input, opts = {}) => {
+        try {
+          const data = await request("/donations/checkout", {
+            method: "POST",
+            body: input,
+            headers: opts.ip ? { "X-Forwarded-For": opts.ip } : void 0,
+            signal: opts.signal,
+            resource: "donations.checkout"
+          });
+          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;
+        }
+      }
+    },
+    preview: {
+      /** 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" }),
+      /**
+       * Store a form submission. Validation problems resolve to { ok: false, fieldErrors };
+       * network and auth failures throw. Pass the visitor's IP so Hearth can rate-limit per visitor.
+       */
+      submit: async (formKey, values, opts = {}) => {
+        try {
+          const data = await request(`/forms/${encodeURIComponent(formKey)}`, {
+            method: "POST",
+            body: toBody(values),
+            headers: opts.ip ? { "X-Forwarded-For": opts.ip } : void 0,
+            signal: opts.signal,
+            resource: "forms.submit"
+          });
+          return { ok: true, message: data.message };
+        } catch (err) {
+          if (isHearthError(err) && (err.code === "bad_request" || err.code === "rate_limited")) {
+            return { ok: false, message: err.message, fieldErrors: err.details ?? {} };
+          }
+          throw err;
+        }
+      }
+    }
+  };
+}
+function backoff(attempt) {
+  return 300 * 2 ** (attempt - 1) + Math.floor(Math.random() * 150);
+}
+
+export {
+  HearthError,
+  isHearthError,
+  DEFAULT_BASE_URL,
+  normalizeSlug,
+  createCore
+};