blume 1.7.3 → 2.0.1

package/src/analytics/hotjar.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+
+/** The tracking-code version (`hjsv`) `hotjar()` uses when `version` is unset. */
+export const HOTJAR_DEFAULT_VERSION = 6;
+
+/** Options for {@link hotjar}. */
+export interface HotjarOptions {
+  /** Site ID (`hjid`), from the site's tracking code. */
+  id: number;
+  /** Tracking-code version (`hjsv`). Defaults to the current one. */
+  version?: number;
+}
+
+export const hotjarOptionsSchema = z.strictObject({
+  id: z.number().int().positive(),
+  version: z.number().int().positive().optional(),
+});
+
+export type HotjarAdapter = AdapterDescriptor<"hotjar", HotjarOptions>;
+
+export const hotjarAdapterSchema = adapterDescriptorSchema(
+  "hotjar",
+  hotjarOptionsSchema
+);
+
+/**
+ * Hotjar heatmaps and recordings. The site ID is public — it's in the tracking
+ * code on every page.
+ */
+export const hotjar = (options: HotjarOptions): HotjarAdapter => ({
+  kind: "hotjar",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});
+
+/** The tracking code as the site's install instructions render it. */
+export const hotjarHead = (options: HotjarOptions): HeadScript[] => [
+  {
+    attributes: {},
+    content: `(function(h,o,t,j,a,r){h.hj=h.hj||function(){(h.hj.q=h.hj.q||[]).push(arguments)};h._hjSettings={hjid:${options.id},hjsv:${options.version ?? HOTJAR_DEFAULT_VERSION}};a=o.getElementsByTagName("head")[0];r=o.createElement("script");r.async=1;r.src=t+h._hjSettings.hjid+j+h._hjSettings.hjsv;a.appendChild(r);})(window,document,"https://static.hotjar.com/c/hotjar-",".js?sv=");`,
+  },
+];

package/src/analytics/index.ts

@@ -0,0 +1,71 @@
+/**
+ * Analytics adapters for `blume.config.ts`:
+ *
+ * ```ts
+ * import { defineConfig } from "blume";
+ * import { plausible, posthog, script, vercel } from "blume/analytics";
+ *
+ * export default defineConfig({
+ *   analytics: [
+ *     posthog({ key: "phc_…" }),
+ *     vercel(),
+ *     plausible({ domain: "docs.example.com" }),
+ *     script({ src: "…" }),
+ *   ],
+ * });
+ * ```
+ *
+ * Each factory returns a plain descriptor (see `core/adapter.ts`) that the
+ * schema validates and the generated site inlines as a literal; nothing here
+ * runs in the browser.
+ */
+export type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+export { adobe } from "./adobe.ts";
+export type { AdobeAdapter, AdobeOptions } from "./adobe.ts";
+export { amplitude } from "./amplitude.ts";
+export type { AmplitudeAdapter, AmplitudeOptions } from "./amplitude.ts";
+export { clarity } from "./clarity.ts";
+export type { ClarityAdapter, ClarityOptions } from "./clarity.ts";
+export { clearbit } from "./clearbit.ts";
+export type { ClearbitAdapter, ClearbitOptions } from "./clearbit.ts";
+export { cloudflare } from "./cloudflare.ts";
+export type { CloudflareAdapter, CloudflareOptions } from "./cloudflare.ts";
+export { fathom } from "./fathom.ts";
+export type { FathomAdapter, FathomOptions } from "./fathom.ts";
+export { googleAnalytics } from "./google-analytics.ts";
+export type {
+  GoogleAnalyticsAdapter,
+  GoogleAnalyticsOptions,
+} from "./google-analytics.ts";
+export { googleTagManager } from "./google-tag-manager.ts";
+export type {
+  GoogleTagManagerAdapter,
+  GoogleTagManagerOptions,
+} from "./google-tag-manager.ts";
+export { heap } from "./heap.ts";
+export type { HeapAdapter, HeapOptions } from "./heap.ts";
+export { hightouch } from "./hightouch.ts";
+export type { HightouchAdapter, HightouchOptions } from "./hightouch.ts";
+export { hotjar } from "./hotjar.ts";
+export type { HotjarAdapter, HotjarOptions } from "./hotjar.ts";
+export { logrocket } from "./logrocket.ts";
+export type { LogrocketAdapter, LogrocketOptions } from "./logrocket.ts";
+export { mixpanel } from "./mixpanel.ts";
+export type {
+  MixpanelAdapter,
+  MixpanelOptions,
+  MixpanelRegion,
+} from "./mixpanel.ts";
+export { pirsch } from "./pirsch.ts";
+export type { PirschAdapter, PirschOptions } from "./pirsch.ts";
+export { plausible } from "./plausible.ts";
+export type { PlausibleAdapter, PlausibleOptions } from "./plausible.ts";
+export { posthog } from "./posthog.ts";
+export type { PosthogAdapter, PosthogOptions } from "./posthog.ts";
+export type { AnalyticsAdapter } from "./schema.ts";
+export { script } from "./script.ts";
+export type { ScriptAdapter, ScriptOptions } from "./script.ts";
+export { segment } from "./segment.ts";
+export type { SegmentAdapter, SegmentOptions } from "./segment.ts";
+export { vercel } from "./vercel.ts";
+export type { VercelAdapter, VercelOptions } from "./vercel.ts";

package/src/analytics/inline.ts

@@ -0,0 +1,21 @@
+import type { JsonValue } from "../core/adapter.ts";
+
+/**
+ * JSON for an inline `<script>` body. `JSON.stringify` leaves `<` alone, so a
+ * value like `</script>` would end the script element early; escape it the way
+ * the layouts do for their JSON.
+ */
+export const inlineJson = (value: JsonValue): string =>
+  JSON.stringify(value).replaceAll("<", "\\u003c");
+
+/**
+ * A snippet that re-sends a pageview on every client-router navigation, for a
+ * provider whose loader only counts real page loads. Keyed off
+ * `astro:page-load` with a path-plus-query guard held in `window[slot]`, so the
+ * initial load (which the loader already counted) and same-page hash moves
+ * aren't double-counted, while a query-only navigation (`?tab=a` → `?tab=b`)
+ * still is. Each adapter passes its own slot: two adapters sharing one would
+ * see the second always match the first's update and never fire.
+ */
+export const spaPageviews = (slot: string, capture: string): string =>
+  `document.addEventListener("astro:page-load",function(){var p=window.${slot},c=location.pathname+location.search;window.${slot}=c;if(p!==undefined&&p!==c){${capture}}});`;

package/src/analytics/logrocket.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+import { inlineJson } from "./inline.ts";
+
+/** The SDK script LogRocket's install snippet loads. */
+export const LOGROCKET_SCRIPT_SRC = "https://cdn.logrocket.io/LogRocket.min.js";
+
+/** The options {@link logrocket} maps itself. */
+export interface LogrocketNamedOptions {
+  /** App ID (`org/app`), from the project's settings. */
+  id: string;
+}
+
+/**
+ * Options for {@link logrocket}: the app ID plus any other `LogRocket.init`
+ * option, forwarded verbatim (`release`, `console`, `network`, `dom`, …). JSON
+ * values only; a sanitizer function can't travel through config — call
+ * `LogRocket.init` yourself from a `script()` adapter for those.
+ */
+export type LogrocketOptions = LogrocketNamedOptions & {
+  [option: string]: JsonValue;
+};
+
+export const logrocketOptionsSchema = z
+  .object({
+    id: z.string().min(1),
+  })
+  .catchall(z.json());
+
+export type LogrocketAdapter = AdapterDescriptor<"logrocket", LogrocketOptions>;
+
+export const logrocketAdapterSchema = adapterDescriptorSchema(
+  "logrocket",
+  logrocketOptionsSchema
+);
+
+/**
+ * LogRocket session replay. The app ID is public — it's what the SDK reports
+ * under.
+ */
+export const logrocket = (options: LogrocketOptions): LogrocketAdapter => ({
+  kind: "logrocket",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});
+
+/**
+ * The two tags from the install snippet: the SDK (synchronous, so
+ * `window.LogRocket` exists for the next tag) and the guarded `init` call,
+ * with `id` mapped and everything else forwarded to `init` verbatim; the
+ * options object is left off when there is nothing to pass, as the snippet
+ * prints it. A session spans client-router navigations on its own.
+ */
+export const logrocketHead = (options: LogrocketOptions): HeadScript[] => {
+  const { id, ...init } = options;
+  const call =
+    Object.keys(init).length === 0
+      ? `window.LogRocket.init(${inlineJson(id)})`
+      : `window.LogRocket.init(${inlineJson(id)},${inlineJson(init)})`;
+  return [
+    {
+      attributes: { crossorigin: "anonymous", src: LOGROCKET_SCRIPT_SRC },
+      content: null,
+    },
+    { attributes: {}, content: `window.LogRocket&&${call};` },
+  ];
+};

package/src/analytics/mixpanel.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+import { inlineJson } from "./inline.ts";
+
+/** Mixpanel's data residency regions and the ingestion host each one uses. */
+export const MIXPANEL_REGION_HOSTS = {
+  eu: "https://api-eu.mixpanel.com",
+  in: "https://api-in.mixpanel.com",
+  us: "https://api.mixpanel.com",
+} as const;
+
+export type MixpanelRegion = keyof typeof MIXPANEL_REGION_HOSTS;
+
+/** The options {@link mixpanel} maps itself. */
+export interface MixpanelNamedOptions {
+  /** Data residency region of the project. Defaults to US. */
+  region?: MixpanelRegion;
+  /** Project token. */
+  token: string;
+}
+
+/**
+ * Options for {@link mixpanel}: the named options plus any other
+ * `mixpanel.init` option, forwarded verbatim (`persistence`, `autocapture`,
+ * `record_sessions_percent`, `debug`, …). JSON values only.
+ */
+export type MixpanelOptions = MixpanelNamedOptions & {
+  [option: string]: JsonValue;
+};
+
+export const mixpanelOptionsSchema = z
+  .object({
+    region: z.enum(["us", "eu", "in"]).optional(),
+    token: z.string().min(1),
+  })
+  .catchall(z.json());
+
+export type MixpanelAdapter = AdapterDescriptor<"mixpanel", MixpanelOptions>;
+
+export const mixpanelAdapterSchema = adapterDescriptorSchema(
+  "mixpanel",
+  mixpanelOptionsSchema
+);
+
+/**
+ * Mixpanel product analytics. The project token is public — it's what every
+ * browser event carries.
+ */
+export const mixpanel = (options: MixpanelOptions): MixpanelAdapter => ({
+  kind: "mixpanel",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});
+
+// The official loader snippet: a `window.mixpanel` stub that queues calls and
+// injects the library.
+const MIXPANEL_LOADER =
+  '(function(f,b){if(!b.__SV){var e,g,i,h;window.mixpanel=b;b._i=[];b.init=function(e,f,c){function g(a,d){var b=d.split(".");2==b.length&&(a=a[b[0]],d=b[1]);a[d]=function(){a.push([d].concat(Array.prototype.slice.call(arguments,0)))}}var a=b;"undefined"!==typeof c?a=b[c]=[]:c="mixpanel";a.people=a.people||[];a.toString=function(a){var d="mixpanel";"mixpanel"!==c&&(d+="."+c);a||(d+=" (stub)");return d};a.people.toString=function(){return a.toString(1)+".people (stub)"};i="disable time_event track track_pageview track_links track_forms track_with_groups add_group set_group remove_group register register_once alias unregister identify name_tag set_config reset opt_in_tracking opt_out_tracking has_opted_in_tracking has_opted_out_tracking clear_opt_in_out_tracking start_batch_senders people.set people.set_once people.unset people.increment people.append people.union people.track_charge people.clear_charges people.delete_user people.remove".split(" ");for(h=0;h<i.length;h++)g(a,i[h]);var j="set set_once union unset remove delete".split(" ");a.get_group=function(){function b(c){d[c]=function(){call2_args=arguments;call2=[c].concat(Array.prototype.slice.call(call2_args,0));a.push([e,call2])}}for(var d={},e=["get_group"].concat(Array.prototype.slice.call(arguments,0)),c=0;c<j.length;c++)b(j[c]);return d};b._i.push([e,f,c])};b.__SV=1.2;e=f.createElement("script");e.type="text/javascript";e.async=!0;e.src="undefined"!==typeof MIXPANEL_CUSTOM_LIB_URL?MIXPANEL_CUSTOM_LIB_URL:"file:"===f.location.protocol&&"//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js".match(/^\\/\\//)?"https://cdn.mxpnl.com/libs/mixpanel-2-latest.min.js":"//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js";g=f.getElementsByTagName("script")[0];g.parentNode.insertBefore(e,g)}})(document,window.mixpanel||[]);';
+
+/**
+ * The init options `mixpanel()` starts from. The library counts one pageview
+ * per real page load with `track_pageview: true`; this mode has it track each
+ * path-or-query change too, so client-router navigations count without any
+ * extra hook. A passthrough option overrides it.
+ */
+export const MIXPANEL_DEFAULT_INIT = {
+  track_pageview: "url-with-path-and-query-string",
+};
+
+/**
+ * The loader plus `mixpanel.init` with `token` mapped and `region` mapped to
+ * `api_host` (the US host when unset); everything else lands in the init
+ * options verbatim, after the mapped host so a raw `api_host` still wins.
+ */
+export const mixpanelHead = (options: MixpanelOptions): HeadScript[] => {
+  const { region, token, ...init } = options;
+  const initOptions = {
+    ...MIXPANEL_DEFAULT_INIT,
+    api_host: MIXPANEL_REGION_HOSTS[region ?? "us"],
+    ...init,
+  };
+  return [
+    {
+      attributes: {},
+      content: `${MIXPANEL_LOADER}mixpanel.init(${inlineJson(token)},${inlineJson(initOptions)});`,
+    },
+  ];
+};

package/src/analytics/pirsch.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+
+/** The script Pirsch's dashboard snippet loads. */
+export const PIRSCH_SCRIPT_SRC = "https://api.pirsch.io/pa.js";
+
+/** The options {@link pirsch} maps itself. */
+export interface PirschNamedOptions {
+  /** Identification code, from Settings → Developer → Identification Code. */
+  code: string;
+}
+
+/**
+ * Options for {@link pirsch}: the identification code plus any other script
+ * setting, forwarded as a `data-` attribute on the tag (`dev` → `data-dev`,
+ * `exclude`, `include`, `domain`, `endpoint`, …).
+ */
+export type PirschOptions = PirschNamedOptions & {
+  [setting: string]: string;
+};
+
+export const pirschOptionsSchema = z
+  .object({
+    code: z.string().min(1),
+  })
+  .catchall(z.string());
+
+export type PirschAdapter = AdapterDescriptor<"pirsch", PirschOptions>;
+
+export const pirschAdapterSchema = adapterDescriptorSchema(
+  "pirsch",
+  pirschOptionsSchema
+);
+
+/**
+ * Pirsch Analytics. The identification code is public — it's in the tag on
+ * every page.
+ */
+export const pirsch = (options: PirschOptions): PirschAdapter => ({
+  kind: "pirsch",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});
+
+/**
+ * The deferred tag from the dashboard, with `code` as `data-code`, every other
+ * option as its own `data-` attribute, and the `pianjs` id the script finds
+ * itself by. Pirsch's script tracks history changes on its own, so
+ * client-router navigations need no extra hook.
+ */
+export const pirschHead = (options: PirschOptions): HeadScript[] => {
+  const { code, ...settings } = options;
+  const attributes: HeadScript["attributes"] = {};
+  for (const [setting, value] of Object.entries(settings)) {
+    attributes[`data-${setting}`] = value;
+  }
+  attributes["data-code"] = code;
+  attributes.defer = true;
+  attributes.id = "pianjs";
+  attributes.src = PIRSCH_SCRIPT_SRC;
+  return [{ attributes, content: null }];
+};

package/src/analytics/plausible.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+
+/** Plausible Cloud, the origin `plausible()` loads the script from when `host` is unset. */
+export const PLAUSIBLE_DEFAULT_HOST = "https://plausible.io";
+
+/** The options {@link plausible} maps itself. */
+export interface PlausibleNamedOptions {
+  /** The site's domain as added in Plausible, e.g. `docs.example.com`. */
+  domain: string;
+  /**
+   * Origin of a self-hosted (or proxied) Plausible instance, e.g.
+   * `https://plausible.example.com`. Defaults to Plausible Cloud.
+   */
+  host?: string;
+}
+
+/**
+ * Options for {@link plausible}: the named options plus any other script
+ * setting, forwarded as a `data-` attribute on the tag (`api` → `data-api`,
+ * `"exclude"`, `"include"`, …).
+ */
+export type PlausibleOptions = PlausibleNamedOptions & {
+  [setting: string]: string;
+};
+
+export const plausibleOptionsSchema = z
+  .object({
+    domain: z.string().min(1),
+    host: z.string().min(1).optional(),
+  })
+  .catchall(z.string());
+
+export type PlausibleAdapter = AdapterDescriptor<"plausible", PlausibleOptions>;
+
+export const plausibleAdapterSchema = adapterDescriptorSchema(
+  "plausible",
+  plausibleOptionsSchema
+);
+
+/**
+ * Plausible Analytics. Nothing here is secret: the tag names the site and
+ * where to send events.
+ */
+export const plausible = (options: PlausibleOptions): PlausibleAdapter => ({
+  kind: "plausible",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});
+
+/**
+ * The queue stub from Plausible's custom-events guide: `plausible()` calls
+ * made before the deferred script lands are buffered on `plausible.q` and
+ * replayed once it loads, so an early `track()` isn't lost.
+ */
+export const PLAUSIBLE_QUEUE =
+  "window.plausible=window.plausible||function(){(window.plausible.q=window.plausible.q||[]).push(arguments)}";
+
+/**
+ * The deferred tag from the site's install instructions, with `domain` as
+ * `data-domain`, `host` as the script origin, and every other option as its
+ * own `data-` attribute, followed by the custom-event queue stub. Plausible's
+ * script tracks history changes on its own, so client-router navigations
+ * need no extra hook.
+ */
+export const plausibleHead = (options: PlausibleOptions): HeadScript[] => {
+  const { domain, host, ...settings } = options;
+  const attributes: HeadScript["attributes"] = {};
+  for (const [setting, value] of Object.entries(settings)) {
+    attributes[`data-${setting}`] = value;
+  }
+  attributes["data-domain"] = domain;
+  attributes.defer = true;
+  attributes.src = `${(host ?? PLAUSIBLE_DEFAULT_HOST).replace(/\/+$/u, "")}/js/script.js`;
+  return [
+    { attributes, content: null },
+    { attributes: {}, content: PLAUSIBLE_QUEUE },
+  ];
+};

package/src/analytics/posthog.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+import { inlineJson, spaPageviews } from "./inline.ts";
+
+/** PostHog Cloud US, the ingestion host `posthog()` uses when `host` is unset. */
+export const POSTHOG_DEFAULT_HOST = "https://us.i.posthog.com";
+
+/** The options {@link posthog} maps itself. */
+export interface PosthogNamedOptions {
+  /** API host (for self-hosted / EU). Defaults to PostHog Cloud US. */
+  host?: string;
+  /** Project API key. */
+  key: string;
+}
+
+/**
+ * Options for {@link posthog}: the named options plus any other `posthog.init`
+ * option, forwarded verbatim (`persistence`, `capture_pageview`,
+ * `autocapture`, …). JSON values only.
+ */
+export type PosthogOptions = PosthogNamedOptions & {
+  [option: string]: JsonValue;
+};
+
+export const posthogOptionsSchema = z
+  .object({
+    host: z.string().optional(),
+    key: z.string().min(1),
+  })
+  .catchall(z.json());
+
+export type PosthogAdapter = AdapterDescriptor<"posthog", PosthogOptions>;
+
+export const posthogAdapterSchema = adapterDescriptorSchema(
+  "posthog",
+  posthogOptionsSchema
+);
+
+/**
+ * PostHog product analytics. The project API key is public and write-only, so
+ * it is safe to ship to the browser.
+ */
+export const posthog = (options: PosthogOptions): PosthogAdapter => ({
+  kind: "posthog",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});
+
+// The official array.js loader snippet.
+const POSTHOG_LOADER =
+  '!function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="init capture register register_once register_for_session unregister unregister_for_session getFeatureFlag getFeatureFlagPayload isFeatureEnabled reloadFeatureFlags updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures on onFeatureFlags onSessionId getSurveys getActiveMatchingSurveys renderSurvey canRenderSurvey getNextSurveyStep identify setPersonProperties group resetGroups setPersonPropertiesForFlags resetPersonPropertiesForFlags setGroupPropertiesForFlags resetGroupPropertiesForFlags reset get_distinct_id getGroups get_session_id get_session_replay_url alias set_config startSessionRecording stopSessionRecording sessionRecordingStarted captureException loadToolbar get_property getSessionProperty createPersonProfile opt_in_capturing opt_out_capturing has_opted_in_capturing has_opted_out_capturing clear_opt_in_out_capturing debug getPageViewId captureTraceFeedback captureTraceMetric".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);';
+
+// PostHog's loader only captures a pageview per real page load, so the client
+// router's in-place swaps are captured here.
+const POSTHOG_SPA_PAGEVIEWS = spaPageviews(
+  "__blumePosthogPath",
+  'posthog.capture("$pageview");'
+);
+
+/**
+ * The inline loader-plus-init snippet. `key` and `host` are the options Blume
+ * maps (`host` becomes `api_host`); everything else lands in `posthog.init`'s
+ * options verbatim, after the mapped host so a raw `api_host` still wins.
+ */
+export const posthogHead = (options: PosthogOptions): HeadScript[] => {
+  const { host, key, ...init } = options;
+  const initOptions = { api_host: host ?? POSTHOG_DEFAULT_HOST, ...init };
+  return [
+    {
+      attributes: {},
+      content: `${POSTHOG_LOADER}posthog.init(${inlineJson(key)},${inlineJson(initOptions)});${POSTHOG_SPA_PAGEVIEWS}`,
+    },
+  ];
+};

package/src/analytics/schema.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+
+import { adobeAdapterSchema } from "./adobe.ts";
+import { amplitudeAdapterSchema } from "./amplitude.ts";
+import { clarityAdapterSchema } from "./clarity.ts";
+import { clearbitAdapterSchema } from "./clearbit.ts";
+import { cloudflareAdapterSchema } from "./cloudflare.ts";
+import { fathomAdapterSchema } from "./fathom.ts";
+import { googleAnalyticsAdapterSchema } from "./google-analytics.ts";
+import { googleTagManagerAdapterSchema } from "./google-tag-manager.ts";
+import { heapAdapterSchema } from "./heap.ts";
+import { hightouchAdapterSchema } from "./hightouch.ts";
+import { hotjarAdapterSchema } from "./hotjar.ts";
+import { logrocketAdapterSchema } from "./logrocket.ts";
+import { mixpanelAdapterSchema } from "./mixpanel.ts";
+import { pirschAdapterSchema } from "./pirsch.ts";
+import { plausibleAdapterSchema } from "./plausible.ts";
+import { posthogAdapterSchema } from "./posthog.ts";
+import { scriptAdapterSchema } from "./script.ts";
+import { segmentAdapterSchema } from "./segment.ts";
+import { vercelAdapterSchema } from "./vercel.ts";
+
+/** One configured analytics adapter, as its factory returned it. */
+export const analyticsAdapterSchema = z.discriminatedUnion("kind", [
+  adobeAdapterSchema,
+  amplitudeAdapterSchema,
+  clarityAdapterSchema,
+  clearbitAdapterSchema,
+  cloudflareAdapterSchema,
+  fathomAdapterSchema,
+  googleAnalyticsAdapterSchema,
+  googleTagManagerAdapterSchema,
+  heapAdapterSchema,
+  hightouchAdapterSchema,
+  hotjarAdapterSchema,
+  logrocketAdapterSchema,
+  mixpanelAdapterSchema,
+  pirschAdapterSchema,
+  plausibleAdapterSchema,
+  posthogAdapterSchema,
+  scriptAdapterSchema,
+  segmentAdapterSchema,
+  vercelAdapterSchema,
+]);
+
+export type AnalyticsAdapter = z.output<typeof analyticsAdapterSchema>;
+
+const ARRAY_HINT =
+  'analytics is a list of adapters — e.g. `analytics: [posthog({ key }), vercel(), plausible({ domain }), script({ src })]`, imported from "blume/analytics".';
+
+/**
+ * `blume.config.analytics`: the adapters to emit, in order. Unset means none.
+ * A non-array (the pre-adapter object form, say) fails with the list hint;
+ * element errors keep their own messages.
+ */
+export const analyticsConfigSchema = z
+  .array(analyticsAdapterSchema, {
+    error: (issue) => (issue.code === "invalid_type" ? ARRAY_HINT : undefined),
+  })
+  .default([]);

package/src/analytics/script.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+
+/** Options for {@link script}; set exactly one of `src` or `content`. */
+export interface ScriptOptions {
+  /** Extra attributes spread onto the `<script>` (e.g. `data-domain`, `id`). */
+  attributes?: Record<string, string>;
+  /** Inline script body. Mutually exclusive with `src`. */
+  content?: string;
+  /** External script URL. Mutually exclusive with `content`. */
+  src?: string;
+  /** Load strategy for an external script. */
+  strategy?: "async" | "defer";
+}
+
+export const scriptOptionsSchema = z
+  .strictObject({
+    attributes: z.record(z.string(), z.string()).optional(),
+    content: z.string().optional(),
+    src: z.string().optional(),
+    strategy: z.enum(["async", "defer"]).optional(),
+  })
+  .refine((value) => Boolean(value.src) !== Boolean(value.content), {
+    message: "An analytics script must set exactly one of `src` or `content`.",
+  });
+
+export type ScriptAdapter = AdapterDescriptor<"script", ScriptOptions>;
+
+export const scriptAdapterSchema = adapterDescriptorSchema(
+  "script",
+  scriptOptionsSchema
+);
+
+/**
+ * Any other provider (Plausible, Fathom, GA, Umami, …) as one `<script>` tag:
+ * external via `src`, inline via `content`. `attributes` is the verbatim
+ * passthrough here — every entry lands on the tag as-is.
+ */
+export const script = (options: ScriptOptions): ScriptAdapter => ({
+  kind: "script",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});
+
+/** The tag. Explicit `src`/`strategy` win over a same-named spread attribute. */
+export const scriptHead = (options: ScriptOptions): HeadScript[] => {
+  const attributes: HeadScript["attributes"] = { ...options.attributes };
+  if (!options.src) {
+    return [{ attributes, content: options.content ?? "" }];
+  }
+  if (options.strategy) {
+    attributes[options.strategy] = true;
+  }
+  attributes.src = options.src;
+  return [{ attributes, content: null }];
+};