@the-smithy/hearth 0.17.0 → 0.19.0

package/dist/analytics.d.ts

@@ -0,0 +1,15 @@
+import { SiteAnalytics } from '@the-smithy/hearth-schema';
+
+/**
+ * Records a named event, such as a sign-up, booking or download, with up to 10 short values. Names are lowercase
+ * letters, digits and `_ . : -`. Does nothing until <HearthAnalytics /> has loaded, or when analytics is off.
+ */
+declare function track(name: string, props?: Record<string, string | number | boolean>): void;
+type HearthAnalyticsProps = {
+    /** `site.analytics` from `getSite()`: null when the site's analytics is off (then render nothing). */
+    config: SiteAnalytics;
+};
+/** Counts a page view on load and on every page change. Renders nothing. */
+declare function HearthAnalytics({ config }: HearthAnalyticsProps): null;
+
+export { HearthAnalytics, type HearthAnalyticsProps, track };

package/dist/analytics.js

@@ -0,0 +1,51 @@
+"use client";
+
+// src/analytics.tsx
+import { useEffect, useRef } from "react";
+import { usePathname } from "next/navigation";
+var current = null;
+function optedOut() {
+  const nav = navigator;
+  return nav.webdriver || nav.globalPrivacyControl === true || nav.doNotTrack === "1" || nav.msDoNotTrack === "1" || /^(localhost|127\.|\[::1\])/.test(location.hostname);
+}
+function send(config, body) {
+  if (optedOut()) return;
+  const payload = JSON.stringify({
+    k: config.key,
+    u: location.href,
+    // Only the browser's time zone, for a country: no location or IP lookup.
+    z: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    // iPads report themselves as Macs; a touch screen tells them apart.
+    m: navigator.maxTouchPoints > 1,
+    ...body
+  });
+  try {
+    if (navigator.sendBeacon?.(config.endpoint, payload)) return;
+    void fetch(config.endpoint, { method: "POST", body: payload, keepalive: true, mode: "no-cors" }).catch(() => {
+    });
+  } catch {
+  }
+}
+function track(name, props) {
+  if (!current || typeof window === "undefined") return;
+  send(current, { t: "event", n: name, ...props ? { p: props } : {} });
+}
+function HearthAnalytics({ config }) {
+  const pathname = usePathname();
+  const first = useRef(true);
+  useEffect(() => {
+    current = config;
+    return () => {
+      current = null;
+    };
+  }, [config]);
+  useEffect(() => {
+    send(config, first.current ? { r: document.referrer } : {});
+    first.current = false;
+  }, [config, pathname]);
+  return null;
+}
+export {
+  HearthAnalytics,
+  track
+};

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

@@ -221,6 +221,19 @@ function createCore(options) {
       /** Every redirect on the site (old addresses and where they go now). Empty from Hearth versions without them. */
       list: async (o = {}) => await maybe("/redirects", { ...o, resource: "redirects.list" }) ?? []
     },
+    analytics: {
+      /**
+       * Visitor analytics between two days (inclusive, `YYYY-MM-DD`; default the last 30 days): daily numbers, totals
+       * and the top pages, sources, campaigns, devices and countries. `null` from Hearth versions without analytics.
+       */
+      get: (query = {}, o = {}) => {
+        const q = new URLSearchParams();
+        if (query.from) q.set("from", query.from);
+        if (query.to) q.set("to", query.to);
+        if (query.limit !== void 0) q.set("limit", String(query.limit));
+        return maybe(`/analytics${q.size ? `?${q}` : ""}`, { ...o, resource: "analytics.get" });
+      }
+    },
     fundraisers: {
       /** Fundraisers with progress (sites with Giving). `category` is "group/category". */
       list: (opts = {}, o = {}) => {

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

@@ -1,4 +1,4 @@
-import { Collection, CollectionEntry, HearthEvent, Site, PageSummary, Page, HearthEventDetail, RegistrationInput, RegistrationResult, CategoryGroup, SitemapEntry, Redirect, Fundraiser, FundraiserDetail, DonationInput, DonationCheckout, HearthForm } from '@the-smithy/hearth-schema';
+import { Collection, CollectionEntry, HearthEvent, Site, PageSummary, Page, HearthEventDetail, RegistrationInput, RegistrationResult, 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. */
@@ -167,6 +167,17 @@ declare function createCore(options: HearthClientOptions): {
         /** Every redirect on the site (old addresses and where they go now). Empty from Hearth versions without them. */
         list: (o?: CallOptions) => Promise<Redirect[]>;
     };
+    analytics: {
+        /**
+         * Visitor analytics between two days (inclusive, `YYYY-MM-DD`; default the last 30 days): daily numbers, totals
+         * and the top pages, sources, campaigns, devices and countries. `null` from Hearth versions without analytics.
+         */
+        get: (query?: {
+            from?: string;
+            to?: string;
+            limit?: number;
+        }, o?: CallOptions) => Promise<AnalyticsReport | null>;
+    };
     fundraisers: {
         /** Fundraisers with progress (sites with Giving). `category` is "group/category". */
         list: (opts?: {

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { H as HearthCore, a as HearthClientOptions } from './client-CnIniG4N.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-CnIniG4N.js';
-export { 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, SiteSettings, SitemapEntry, UnknownBlock, WebhookPayload, videoEmbedUrl } from '@the-smithy/hearth-schema';
+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';
 
 /** 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,7 +5,7 @@ import {
   findRedirect,
   isHearthError,
   normalizeSlug
-} from "./chunk-RYCXMQM2.js";
+} from "./chunk-62OMCVBE.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-CnIniG4N.js';
+import { H as HearthCore, b as CollectionPage, E as EventCollectionPage, F as FormResult, c as FormValues } from './client-B3n7p9lK.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';
@@ -190,7 +190,7 @@ declare function createHearthNext(client: HearthCore, { tag, revalidate }?: Hear
      * 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`.
+     * `message`, `updates` (a checkbox: "Send me updates about this fundraiser", unticked by default). On success it redirects the donor to the payment page; afterwards they return to `returnPath`.
      */
     donateAction: ({ returnPath }?: {
         returnPath?: string;

package/dist/next.js

@@ -2,7 +2,7 @@ import {
   findRedirect,
   isHearthError,
   normalizeSlug
-} from "./chunk-RYCXMQM2.js";
+} from "./chunk-62OMCVBE.js";
 import {
   parseWebhook,
   tagsForWebhook
@@ -70,7 +70,7 @@ function createHearthNext(client, { tag = "hearth", revalidate = 3600 } = {}) {
      * 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`.
+     * `message`, `updates` (a checkbox: "Send me updates about this fundraiser", unticked by default). On success it redirects the donor to the payment page; afterwards they return to `returnPath`.
      */
     donateAction: ({ returnPath = "/donate/thank-you" } = {}) => async (_prev, formData) => {
       const h = await headers();
@@ -87,6 +87,7 @@ function createHearthNext(client, { tag = "hearth", revalidate = 3600 } = {}) {
           name: text("name"),
           email: text("email"),
           anonymous: formData.get("anonymous") === "on" || formData.get("anonymous") === "true",
+          updates: formData.get("updates") === "on" || formData.get("updates") === "true",
           message: text("message"),
           returnUrl: `${proto}://${host}${safePath(returnPath)}`
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-smithy/hearth",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Typed client for the Hearth Delivery API: content, SEO, forms and publish webhooks.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -30,6 +30,10 @@
       "types": "./dist/preview.d.ts",
       "import": "./dist/preview.js"
     },
+    "./analytics": {
+      "types": "./dist/analytics.d.ts",
+      "import": "./dist/analytics.js"
+    },
     "./webhooks": {
       "types": "./dist/webhooks.d.ts",
       "import": "./dist/webhooks.js"
@@ -45,7 +49,7 @@
     "llms.md"
   ],
   "dependencies": {
-    "@the-smithy/hearth-schema": "^0.17.0"
+    "@the-smithy/hearth-schema": "^0.19.0"
   },
   "peerDependencies": {
     "next": ">=15",