blume 1.7.3 → 2.0.0

package/dist/types/analytics/hotjar.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+/** The tracking-code version (`hjsv`) `hotjar()` uses when `version` is unset. */
+export declare 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 declare const hotjarOptionsSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    version: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type HotjarAdapter = AdapterDescriptor<"hotjar", HotjarOptions>;
+export declare const hotjarAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"hotjar">;
+    options: z.ZodObject<{
+        id: z.ZodNumber;
+        version: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Hotjar heatmaps and recordings. The site ID is public — it's in the tracking
+ * code on every page.
+ */
+export declare const hotjar: (options: HotjarOptions) => HotjarAdapter;
+/** The tracking code as the site's install instructions render it. */
+export declare const hotjarHead: (options: HotjarOptions) => HeadScript[];

package/dist/types/analytics/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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/dist/types/analytics/inline.d.ts

@@ -0,0 +1,17 @@
+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 declare const inlineJson: (value: JsonValue) => string;
+/**
+ * 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 declare const spaPageviews: (slot: string, capture: string) => string;

package/dist/types/analytics/logrocket.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+/** The SDK script LogRocket's install snippet loads. */
+export declare 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 declare const logrocketOptionsSchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$catchall<z.ZodJSONSchema>>;
+export type LogrocketAdapter = AdapterDescriptor<"logrocket", LogrocketOptions>;
+export declare const logrocketAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"logrocket">;
+    options: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$catchall<z.ZodJSONSchema>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * LogRocket session replay. The app ID is public — it's what the SDK reports
+ * under.
+ */
+export declare const logrocket: (options: LogrocketOptions) => LogrocketAdapter;
+/**
+ * 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 declare const logrocketHead: (options: LogrocketOptions) => HeadScript[];

package/dist/types/analytics/mixpanel.d.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+/** Mixpanel's data residency regions and the ingestion host each one uses. */
+export declare const MIXPANEL_REGION_HOSTS: {
+    readonly eu: "https://api-eu.mixpanel.com";
+    readonly in: "https://api-in.mixpanel.com";
+    readonly us: "https://api.mixpanel.com";
+};
+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 declare const mixpanelOptionsSchema: z.ZodObject<{
+    region: z.ZodOptional<z.ZodEnum<{
+        in: "in";
+        eu: "eu";
+        us: "us";
+    }>>;
+    token: z.ZodString;
+}, z.core.$catchall<z.ZodJSONSchema>>;
+export type MixpanelAdapter = AdapterDescriptor<"mixpanel", MixpanelOptions>;
+export declare const mixpanelAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"mixpanel">;
+    options: z.ZodObject<{
+        region: z.ZodOptional<z.ZodEnum<{
+            in: "in";
+            eu: "eu";
+            us: "us";
+        }>>;
+        token: z.ZodString;
+    }, z.core.$catchall<z.ZodJSONSchema>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Mixpanel product analytics. The project token is public — it's what every
+ * browser event carries.
+ */
+export declare const mixpanel: (options: MixpanelOptions) => MixpanelAdapter;
+/**
+ * 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 declare const MIXPANEL_DEFAULT_INIT: {
+    track_pageview: 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 declare const mixpanelHead: (options: MixpanelOptions) => HeadScript[];

package/dist/types/analytics/pirsch.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+/** The script Pirsch's dashboard snippet loads. */
+export declare 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 declare const pirschOptionsSchema: z.ZodObject<{
+    code: z.ZodString;
+}, z.core.$catchall<z.ZodString>>;
+export type PirschAdapter = AdapterDescriptor<"pirsch", PirschOptions>;
+export declare const pirschAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"pirsch">;
+    options: z.ZodObject<{
+        code: z.ZodString;
+    }, z.core.$catchall<z.ZodString>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Pirsch Analytics. The identification code is public — it's in the tag on
+ * every page.
+ */
+export declare const pirsch: (options: PirschOptions) => PirschAdapter;
+/**
+ * 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 declare const pirschHead: (options: PirschOptions) => HeadScript[];

package/dist/types/analytics/plausible.d.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+/** Plausible Cloud, the origin `plausible()` loads the script from when `host` is unset. */
+export declare 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 declare const plausibleOptionsSchema: z.ZodObject<{
+    domain: z.ZodString;
+    host: z.ZodOptional<z.ZodString>;
+}, z.core.$catchall<z.ZodString>>;
+export type PlausibleAdapter = AdapterDescriptor<"plausible", PlausibleOptions>;
+export declare const plausibleAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"plausible">;
+    options: z.ZodObject<{
+        domain: z.ZodString;
+        host: z.ZodOptional<z.ZodString>;
+    }, z.core.$catchall<z.ZodString>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Plausible Analytics. Nothing here is secret: the tag names the site and
+ * where to send events.
+ */
+export declare const plausible: (options: PlausibleOptions) => PlausibleAdapter;
+/**
+ * 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 declare 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 declare const plausibleHead: (options: PlausibleOptions) => HeadScript[];

package/dist/types/analytics/posthog.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+/** PostHog Cloud US, the ingestion host `posthog()` uses when `host` is unset. */
+export declare 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 declare const posthogOptionsSchema: z.ZodObject<{
+    host: z.ZodOptional<z.ZodString>;
+    key: z.ZodString;
+}, z.core.$catchall<z.ZodJSONSchema>>;
+export type PosthogAdapter = AdapterDescriptor<"posthog", PosthogOptions>;
+export declare const posthogAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"posthog">;
+    options: z.ZodObject<{
+        host: z.ZodOptional<z.ZodString>;
+        key: z.ZodString;
+    }, z.core.$catchall<z.ZodJSONSchema>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * PostHog product analytics. The project API key is public and write-only, so
+ * it is safe to ship to the browser.
+ */
+export declare const posthog: (options: PosthogOptions) => PosthogAdapter;
+/**
+ * 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 declare const posthogHead: (options: PosthogOptions) => HeadScript[];