@the-smithy/hearth 0.0.0-stage → 0.13.0

package/dist/client-DCiaDdvu.d.ts

@@ -0,0 +1,338 @@
+import { Collection, CollectionEntry, HearthEvent, Site, PageSummary, Page, HearthEventDetail, RegistrationInput, RegistrationResult, CategoryGroup, SitemapEntry, 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. */
+declare class HearthError extends Error {
+    readonly status: number;
+    readonly code: HearthErrorCode;
+    readonly details?: unknown;
+    constructor(code: HearthErrorCode, message: string, { status, details, cause }?: {
+        status?: number;
+        details?: unknown;
+        cause?: unknown;
+    });
+}
+declare const isHearthError: (error: unknown) => error is HearthError;
+
+/** One page of a page collection's entries. */
+type CollectionPage = {
+    collection: Collection & {
+        kind: "pages";
+    };
+    total: number;
+    entries: CollectionEntry[];
+};
+/** An event collection (e.g. Talks) with its upcoming or past events. */
+type EventCollectionPage = {
+    collection: Collection & {
+        kind: "events";
+    };
+    events: HearthEvent[];
+};
+
+declare const DEFAULT_BASE_URL = "https://hearth.thesmithy.io";
+/** Next.js's extra fetch options (passed through untouched on other runtimes). */
+type NextFetchOptions = {
+    revalidate?: number | false;
+    tags?: string[];
+};
+type CallOptions = {
+    signal?: AbortSignal;
+    cache?: RequestCache;
+    next?: NextFetchOptions;
+    /**
+     * A preview token from Hearth (draft preview links). Page and event reads then return saved drafts, and the
+     * request is never cached.
+     */
+    preview?: string;
+};
+/** What a preview token allows (the path to open first, when the preview ends) and `version`: when the site's
+ * content, drafts included, last changed. */
+type PreviewSession = {
+    path: string;
+    expiresAt: string;
+    version: string;
+};
+type RequestContext = {
+    resource: string;
+    method: string;
+    path: string;
+    attempt: number;
+};
+type HearthHooks = {
+    /** Change or replace the request (headers, tracing). The API key is already set. */
+    beforeRequest?(request: Request, ctx: RequestContext): Request | void | Promise<Request | void>;
+    /** Inspect or replace the response before it's read. */
+    afterResponse?(response: Response, ctx: RequestContext): Response | void | Promise<Response | void>;
+    onError?(error: HearthError, ctx: RequestContext): void;
+};
+type HearthClientOptions = {
+    /** The site's address in Hearth. */
+    site: string;
+    /** A Delivery API key (hk_…). Server-side only. */
+    apiKey: string;
+    baseUrl?: string;
+    /** Custom transport: tests, proxies, instrumentation. */
+    fetch?: typeof fetch;
+    /** Per-attempt timeout. Default 10 s. */
+    timeoutMs?: number;
+    /** Retries for reads on network errors, 429 and 5xx. Default 2. */
+    retries?: number;
+    /** Check responses against the content schemas: true throws, "warn" logs. Default false. */
+    validate?: boolean | "warn";
+    hooks?: HearthHooks;
+    /** Allow use in a browser (the key would be exposed). Default false. */
+    allowBrowser?: boolean;
+};
+type FormValues = Record<string, string | boolean | number | null | undefined> | FormData;
+type FormResult = {
+    ok: true;
+    message: string;
+} | {
+    ok: false;
+    message: string;
+    fieldErrors: Record<string, string>;
+};
+type RequestOptions = CallOptions & {
+    method?: "GET" | "POST";
+    body?: unknown;
+    headers?: Record<string, string>;
+    /** Name for hooks and errors, e.g. "pages.get". */
+    resource?: string;
+};
+/** "home", "about/team", ["about", "team"], "/about/" → "about/team"-style slug; empty means "home". */
+declare function normalizeSlug(slug: string | string[] | undefined | null): string;
+declare function createCore(options: HearthClientOptions): {
+    /** The site's address in Hearth. */
+    siteSlug: string;
+    request: <T>(path: string, init?: RequestOptions) => Promise<T>;
+    site: {
+        get: (o?: CallOptions) => Promise<Site>;
+    };
+    pages: {
+        list: (o?: CallOptions) => Promise<PageSummary[]>;
+        get: (slug?: string | string[] | null, o?: CallOptions) => Promise<Page | null>;
+    };
+    events: {
+        /** `category` is "group/category", e.g. "status/featured". */
+        list: (opts?: {
+            when?: "upcoming" | "past";
+            limit?: number;
+            collection?: string;
+            category?: string;
+        }, o?: CallOptions) => Promise<HearthEvent[]>;
+        get: (slug: string, o?: CallOptions) => Promise<HearthEventDetail | null>;
+        /**
+         * 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: (slug: string, input: RegistrationInput, opts?: {
+            ip?: string | null;
+            signal?: AbortSignal;
+        }) => Promise<({
+            ok: true;
+        } & RegistrationResult) | {
+            ok: false;
+            message: string;
+            fieldErrors: Record<string, string>;
+        }>;
+    };
+    categories: {
+        /** The site's category groups, each with its categories. */
+        list: (o?: CallOptions) => Promise<CategoryGroup[]>;
+    };
+    collections: {
+        /** The site's collections: page groups (a blog) and event types (Talks). */
+        list: (o?: CallOptions) => Promise<Collection[]>;
+        /**
+         * 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: string, opts?: {
+            limit?: number;
+            offset?: number;
+            tag?: string;
+            category?: string;
+            when?: "upcoming" | "past";
+        }, o?: CallOptions) => Promise<CollectionPage | EventCollectionPage | null>;
+    };
+    sitemap: (o?: CallOptions) => Promise<SitemapEntry[]>;
+    fundraisers: {
+        /** Fundraisers with progress (sites with Giving). `category` is "group/category". */
+        list: (opts?: {
+            status?: "active" | "completed" | "all";
+            category?: string;
+            limit?: number;
+        }, o?: CallOptions) => Promise<Fundraiser[]>;
+        get: (slug: string, o?: CallOptions) => Promise<FundraiserDetail | null>;
+    };
+    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: (input: DonationInput, opts?: {
+            ip?: string | null;
+            signal?: AbortSignal;
+        }) => Promise<({
+            ok: true;
+        } & DonationCheckout) | {
+            ok: false;
+            message: string;
+            fieldErrors: Record<string, string>;
+        }>;
+    };
+    preview: {
+        /** 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>;
+        /**
+         * 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: (formKey: string, values: FormValues, opts?: {
+            ip?: string | null;
+            signal?: AbortSignal;
+        }) => Promise<FormResult>;
+    };
+};
+type HearthCore = ReturnType<typeof createCore>;
+
+export { type CallOptions as C, DEFAULT_BASE_URL as D, type EventCollectionPage as E, type FormResult as F, type HearthCore as H, type NextFetchOptions as N, type PreviewSession as P, type RequestContext as R, type HearthClientOptions as a, type CollectionPage as b, type FormValues as c, HearthError as d, type HearthErrorCode as e, type HearthHooks as f, type RequestOptions as g, isHearthError as i, normalizeSlug as n };

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+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. */
+type HearthPlugin<T extends object = object> = {
+    setup(client: HearthCore): T;
+};
+/** Define a plugin with typed resources, e.g. `definePlugin((c) => ({ products: { list: () => c.request("/products") } }))`. */
+declare function definePlugin<T extends object>(setup: (client: HearthCore) => T): HearthPlugin<T>;
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+type PluginResources<P extends readonly HearthPlugin[]> = P extends readonly [] ? unknown : UnionToIntersection<P[number] extends HearthPlugin<infer T> ? T : never>;
+type HearthClient<P extends readonly HearthPlugin[] = []> = HearthCore & PluginResources<P>;
+/**
+ * Create a Hearth client for one site. Server-side only: the API key is secret.
+ *
+ *   const hearth = createHearthClient({ site: process.env.HEARTH_SITE!, apiKey: process.env.HEARTH_API_KEY! });
+ *   const page = await hearth.pages.get("about");
+ */
+declare function createHearthClient<const P extends readonly HearthPlugin[] = []>(options: HearthClientOptions & {
+    plugins?: P;
+}): HearthClient<P>;
+
+export { type HearthClient, HearthClientOptions, type HearthPlugin, createHearthClient, definePlugin };

package/dist/index.js

@@ -0,0 +1,32 @@
+import {
+  DEFAULT_BASE_URL,
+  HearthError,
+  createCore,
+  isHearthError,
+  normalizeSlug
+} from "./chunk-ZK7X4FDQ.js";
+
+// src/index.ts
+import { videoEmbedUrl } from "@the-smithy/hearth-schema";
+function definePlugin(setup) {
+  return { setup };
+}
+function createHearthClient(options) {
+  const core = createCore(options);
+  const extras = (options.plugins ?? []).map((p) => p.setup(core));
+  for (const extra of extras) {
+    for (const key of Object.keys(extra)) {
+      if (key in core) throw new Error(`Hearth: plugin resource "${key}" would replace a built-in one.`);
+    }
+  }
+  return Object.assign(core, ...extras);
+}
+export {
+  DEFAULT_BASE_URL,
+  HearthError,
+  createHearthClient,
+  definePlugin,
+  isHearthError,
+  normalizeSlug,
+  videoEmbedUrl
+};

package/dist/next.d.ts

@@ -0,0 +1,235 @@
+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';
+
+/** Holds the preview token while Next.js draft mode is on. */
+declare const PREVIEW_COOKIE = "hearth-preview";
+/** Next.js metadata from a page's or event's `meta`. */
+declare function metadataFromMeta(meta: PageMeta): Metadata;
+type HearthNextOptions = {
+    /** Base cache tag; every request is tagged with it (default "hearth"). */
+    tag?: string;
+    /**
+     * Longest time (seconds) content stays cached if a publish webhook is missed. Publishing
+     * refreshes the cache straight away through the webhook. Default 3600; false caches until then.
+     */
+    revalidate?: number | false;
+};
+/**
+ * Next.js helpers bound to a client: tagged reads (so publish webhooks refresh exactly
+ * what changed), metadata, sitemap, the revalidation route, and form submission.
+ */
+declare function createHearthNext(client: HearthCore, { tag, revalidate }?: HearthNextOptions): {
+    getSite: () => Promise<_the_smithy_hearth_schema.Site>;
+    getPages: () => Promise<_the_smithy_hearth_schema.PageSummary[]>;
+    getPage: (slug?: string | string[] | null) => Promise<_the_smithy_hearth_schema.Page | null>;
+    getEvents: (opts?: {
+        when?: "upcoming" | "past";
+        limit?: number;
+        collection?: string;
+        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;
+        offset?: number;
+        tag?: string;
+        category?: string;
+        when?: "upcoming" | "past";
+    }) => Promise<CollectionPage | EventCollectionPage | null>;
+    getEvent: (slug: string) => Promise<_the_smithy_hearth_schema.HearthEventDetail | null>;
+    /** Fundraisers with progress (sites with Giving). Refreshed after every donation. */
+    getFundraisers: (opts?: {
+        status?: "active" | "completed" | "all";
+        category?: string;
+        limit?: number;
+    }) => Promise<_the_smithy_hearth_schema.Fundraiser[]>;
+    getFundraiser: (slug: string) => Promise<_the_smithy_hearth_schema.FundraiserDetail | null>;
+    /**
+     * A donation form's server action, shaped for `useActionState(action, null)`. Export it from a "use server" file:
+     *   export const donate = async (prev: FormResult | null, fd: FormData) => donateAction()(prev, fd);
+     * Fields: `amount` (dollars, or "custom" with `customAmount`), `fundraiser`, `name`, `email`, `anonymous`,
+     * `message`. On success it redirects the donor to the payment page; afterwards they return to `returnPath`.
+     */
+    donateAction: ({ returnPath }?: {
+        returnPath?: string;
+    }) => (_prev: FormResult | null, formData: FormData) => Promise<FormResult>;
+    /**
+     * An event registration form's server action (sites with Tickets), for `useActionState(action, null)`:
+     *   export const register = async (slug: string, prev: FormResult | null, fd: FormData) => registerAction(slug)(prev, fd);
+     * Fields: `ticket`, `name`, `email`, `phone`, `teamName`, `notes`, and one `attendee` per name. A free ticket
+     * resolves to { ok: true, message }; a paid one redirects to the payment page, which returns to `returnPath`.
+     */
+    registerAction: (slug: string, { returnPath }?: {
+        returnPath?: 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>;
+    /**
+     * GET handler for the site's preview route (app/api/preview/route.ts):
+     *   export const GET = hearthNext.previewHandler();
+     * Hearth's "Preview on the website" button opens it with a token; it checks the token with Hearth, turns on
+     * draft mode and opens the page. Page and event reads then return saved drafts until the preview ends.
+     * Hearth's side-by-side preview adds `embed=1`, which makes the cookies work inside its editor's frame.
+     */
+    previewHandler(): (request: Request) => Promise<Response>;
+    /** GET handler that ends a preview (app/api/preview/exit/route.ts); `?path=` says where to go next. */
+    exitPreviewHandler(): (request: Request) => Promise<never>;
+    /** For `generateMetadata`: the page's title, description, canonical, robots and share tags ({} when not found). */
+    generatePageMetadata(slug?: string | string[] | null): Promise<Metadata>;
+    /** `export default sitemap` from app/sitemap.ts. */
+    sitemap(): Promise<MetadataRoute.Sitemap>;
+    /**
+     * POST handler for the site's revalidation webhook (app/api/revalidate/route.ts):
+     *   export const POST = hearthNext.revalidateHandler();
+     * Verifies the signature with HEARTH_WEBHOOK_SECRET and expires the matching tags.
+     */
+    revalidateHandler({ secret }?: {
+        secret?: string;
+    }): (request: Request) => Promise<Response>;
+    /**
+     * Submit a form from your own server action, forwarding the visitor's IP:
+     *   "use server";
+     *   export async function contact(_: unknown, formData: FormData) { return hearthNext.submitForm("contact", formData); }
+     */
+    submitForm: (formKey: string, values: FormValues) => Promise<FormResult>;
+    /**
+     * The same, shaped for `useActionState(action, null)`. Export it from a "use server" file:
+     *   export const contact = async (prev: FormResult | null, fd: FormData) => submitFormAction("contact")(prev, fd);
+     */
+    submitFormAction: (formKey: string) => (_prev: FormResult | null, formData: FormData) => Promise<FormResult>;
+};
+
+export { type HearthNextOptions, PREVIEW_COOKIE, createHearthNext, metadataFromMeta };