@heyramzi/utils 0.0.0-stage → 1.13.0

package/src/analytics/client.ts

@@ -0,0 +1,129 @@
+/**
+ * Umami in the browser: one init call, then track, trackRevenue and setProfileId.
+ * Nothing fires before `initAnalytics` or after its cleanup.
+ */
+
+/*
+ * initAnalytics({ websiteId: env.PUBLIC_UMAMI_WEBSITE_ID, host: env.PUBLIC_UMAMI_HOST, disabled: import.meta.env.DEV });
+ */
+
+import "#src/analytics/types.js";
+
+export type EventData = Record<string, string | number | boolean | null | undefined>;
+
+export type RevenueArgs = {
+  /** purchase_completed | subscription_started | subscription_renewed */
+  event: string;
+  /** In dollars (not cents). */
+  value: number;
+  /** ISO 4217 (e.g. USD, EUR). */
+  currency: string;
+  /** Plan name when relevant. */
+  plan?: string;
+  /** Stripe id for backend dedupe. */
+  transactionId?: string;
+};
+
+export type UmamiOptions = {
+  /** Umami website ID. */
+  websiteId: string;
+  /** Umami host without trailing slash. */
+  host: string;
+  /**
+   * Inject the Umami script tag from the adapter. Default true. Set false if
+   * the script is already in `app.html` or otherwise loaded.
+   */
+  autoInjectScript?: boolean;
+  /** Collect Core Web Vitals (LCP, INP, CLS, FCP, TTFB). Umami v3.1+. Default false. */
+  performance?: boolean;
+  /** Group events under a named tag for filtering. Umami v2.11+. */
+  tag?: string;
+  /** Window function name to inspect/modify payloads before sending. Umami v2.18+. */
+  beforeSend?: string;
+  /** Restrict tracking to listed hostnames. Umami v2.0+. */
+  domains?: string[];
+  /** Honor the browser's Do-Not-Track signal. Umami v2.17+. Default false. */
+  doNotTrack?: boolean;
+  /** Disable automatic pageview/event tracking and call `umami.track()` manually. Default true. */
+  autoTrack?: boolean;
+  /** Strip URL search params from tracked URLs. Umami v2.11+. Default false. */
+  excludeSearch?: boolean;
+  /** Strip URL hash from tracked URLs. Umami v2.16+. Default false. */
+  excludeHash?: boolean;
+};
+
+export type AnalyticsConfig = UmamiOptions & {
+  /** Skip tracking entirely (e.g., import.meta.env.DEV). */
+  disabled?: boolean;
+};
+
+let active = false;
+
+/**
+ * Start tracking. Returns a cleanup function safe to return directly from a SvelteKit
+ * `onMount` callback.
+ */
+export function initAnalytics(config: AnalyticsConfig): () => void {
+  stop();
+  if (config.disabled || typeof window === "undefined") return stop;
+
+  active = true;
+  injectScript(config);
+  return stop;
+}
+
+function stop(): void {
+  active = false;
+}
+
+/** Track a custom event. */
+export function track(event: string, meta?: EventData): void {
+  if (!active || typeof window === "undefined" || !window.umami) return;
+  try {
+    if (meta) {
+      window.umami.track(event, meta);
+    } else {
+      window.umami.track(event);
+    }
+  } catch {
+    // WHY: analytics must never break the app
+  }
+}
+
+/** Fire a revenue event. */
+export function trackRevenue(args: RevenueArgs): void {
+  const meta: EventData = { revenue: args.value, currency: args.currency };
+  if (args.plan) meta.plan = args.plan;
+  if (args.transactionId) meta.transaction_id = args.transactionId;
+  track(args.event, meta);
+}
+
+/** Set the cookieless profile id. */
+export function setProfileId(id?: string): void {
+  if (!active || typeof window === "undefined" || !window.umami?.identify) return;
+  try {
+    window.umami.identify(id ? { profileId: id } : {});
+  } catch {
+    // WHY: analytics must never break the app
+  }
+}
+
+function injectScript(umami: UmamiOptions): void {
+  if (typeof document === "undefined") return;
+  if (!(umami.autoInjectScript ?? true)) return;
+  if (document.querySelector(`script[data-website-id="${umami.websiteId}"]`)) return;
+
+  const script = document.createElement("script");
+  script.defer = true;
+  script.src = `${umami.host.replace(/\/+$/, "")}/script.js`;
+  script.dataset.websiteId = umami.websiteId;
+  if (umami.performance) script.dataset.performance = "true";
+  if (umami.tag) script.dataset.tag = umami.tag;
+  if (umami.beforeSend) script.dataset.beforeSend = umami.beforeSend;
+  if (umami.domains?.length) script.dataset.domains = umami.domains.join(",");
+  if (umami.doNotTrack) script.dataset.doNotTrack = "true";
+  if (umami.autoTrack === false) script.dataset.autoTrack = "false";
+  if (umami.excludeSearch) script.dataset.excludeSearch = "true";
+  if (umami.excludeHash) script.dataset.excludeHash = "true";
+  document.head.appendChild(script);
+}

package/src/analytics/server.test.ts

@@ -0,0 +1,165 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vite-plus/test";
+
+// The server module holds its config at module level, so each test re-imports it.
+
+async function freshImport() {
+  vi.resetModules();
+  return import("#src/analytics/server.js");
+}
+
+const fetchMock = vi.fn();
+
+function answer(body: string, status = 200) {
+  fetchMock.mockResolvedValue(new Response(body, { status }));
+}
+
+function sent() {
+  const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+  return {
+    url,
+    headers: init.headers as Record<string, string>,
+    body: JSON.parse(init.body as string) as { type: string; payload: Record<string, unknown> },
+  };
+}
+
+beforeEach(() => {
+  fetchMock.mockReset();
+  answer('{"cache":"x"}');
+  vi.stubGlobal("fetch", fetchMock);
+  vi.spyOn(console, "error").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+const config = {
+  hostUrl: "https://umami.example.com",
+  websiteId: "abc-123",
+  hostname: "example.com",
+};
+
+describe("trackServer", () => {
+  it("awaits the POST to /api/send and resolves true", async () => {
+    const { initServer, trackServer } = await freshImport();
+    initServer(config);
+
+    await expect(trackServer("signup")).resolves.toBe(true);
+
+    const { url, headers, body } = sent();
+    expect(url).toBe("https://umami.example.com/api/send");
+    expect(headers["User-Agent"]).toMatch(/^Mozilla\/5\.0/);
+    expect(body).toEqual({
+      type: "event",
+      payload: { website: "abc-123", hostname: "example.com", url: "/", name: "signup" },
+    });
+  });
+
+  it("sends data, url and id", async () => {
+    const { initServer, trackServer } = await freshImport();
+    initServer(config);
+
+    await trackServer("click", { label: "CTA" }, { url: "/home", id: "cs_123" });
+
+    expect(sent().body.payload).toEqual({
+      website: "abc-123",
+      hostname: "example.com",
+      url: "/home",
+      name: "click",
+      data: { label: "CTA" },
+      id: "cs_123",
+    });
+  });
+
+  it("still takes the url as a plain string", async () => {
+    const { initServer, trackServer } = await freshImport();
+    initServer(config);
+
+    await trackServer("page_view", undefined, "/pricing");
+
+    expect(sent().body.payload.url).toBe("/pricing");
+    expect(sent().body.payload).not.toHaveProperty("id");
+  });
+
+  it("strips a trailing slash from hostUrl and forwards a custom userAgent", async () => {
+    const { initServer, trackServer } = await freshImport();
+    initServer({
+      ...config,
+      hostUrl: "https://umami.example.com/",
+      userAgent: "Mozilla/5.0 Seam/1.0",
+    });
+
+    await trackServer("ua_test");
+
+    expect(sent().url).toBe("https://umami.example.com/api/send");
+    expect(sent().headers["User-Agent"]).toBe("Mozilla/5.0 Seam/1.0");
+  });
+
+  // Umami rejects an event with HTTP 200 and the body `beep`.
+  it("resolves false when Umami answers beep", async () => {
+    answer("beep");
+    const { initServer, trackServer } = await freshImport();
+    initServer(config);
+
+    await expect(trackServer("dropped")).resolves.toBe(false);
+    expect(console.error).toHaveBeenCalled();
+  });
+
+  it("resolves false on an HTTP error", async () => {
+    answer("nope", 500);
+    const { initServer, trackServer } = await freshImport();
+    initServer(config);
+
+    await expect(trackServer("server_error")).resolves.toBe(false);
+  });
+
+  it("resolves false and never throws when fetch rejects", async () => {
+    fetchMock.mockRejectedValue(new Error("network failure"));
+    const { initServer, trackServer } = await freshImport();
+    initServer(config);
+
+    await expect(trackServer("risky_event")).resolves.toBe(false);
+  });
+
+  it("resolves false without initServer and sends nothing", async () => {
+    const { trackServer } = await freshImport();
+
+    await expect(trackServer("orphan_event")).resolves.toBe(false);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});
+
+describe("trackServerRevenue", () => {
+  it("merges revenue and currency into data and forwards url and id", async () => {
+    const { initServer, trackServerRevenue } = await freshImport();
+    initServer(config);
+
+    await expect(
+      trackServerRevenue(
+        "Purchase Complete",
+        9.99,
+        "EUR",
+        { plan: "pro" },
+        { url: "/buy", id: "cs_1" },
+      ),
+    ).resolves.toBe(true);
+
+    expect(sent().body.payload).toMatchObject({
+      name: "Purchase Complete",
+      url: "/buy",
+      id: "cs_1",
+      data: { plan: "pro", revenue: 9.99, currency: "EUR" },
+    });
+  });
+
+  it("resolves false when the send fails", async () => {
+    answer("beep");
+    const { initServer, trackServerRevenue } = await freshImport();
+    initServer(config);
+
+    await expect(
+      trackServerRevenue("checkout", 19.99, "USD", undefined, "/checkout"),
+    ).resolves.toBe(false);
+  });
+});

package/src/analytics/server.ts

@@ -0,0 +1,88 @@
+/**
+ * Server-side Umami tracking. A Worker cancels a fetch still in flight once the response
+ * returns, so await each tracker or hand it to `waitUntil`.
+ */
+
+import type { EventData } from "#src/analytics/types.js";
+import { buildSendBody, UMAMI_ENDPOINTS } from "#src/analytics/umami/protocol.js";
+
+type ServerConfig = {
+  hostUrl: string;
+  websiteId: string;
+  /** Site hostname, such as `getseam.app`. Without it Umami logs the event under `localhost`. */
+  hostname?: string;
+  /** Umami answers a non-browser user agent with `beep` and drops the event. */
+  userAgent?: string;
+};
+
+/** Per-event options. A string is the url, as in 3.0. */
+export type ServerEventOptions = {
+  url?: string;
+  /** Umami keys the session on it. Without one, every event shares the Worker's session. */
+  id?: string;
+};
+
+// Umami's bot filter answers `beep` to any agent containing "Server" (tested 19 Oct 2026).
+const DEFAULT_USER_AGENT = "Mozilla/5.0 Marketing/1.0";
+const TIMEOUT_MS = 3000;
+
+let _config: ServerConfig | null = null;
+
+/** Initialize the server-side Umami client. Call once at startup. */
+export function initServer(config: ServerConfig): void {
+  _config = config;
+}
+
+/**
+ * Sends one event and checks Umami recorded it. Never throws.
+ * Resolves false on a timeout, an HTTP error or a `beep` rejection.
+ */
+export async function trackServer(
+  name: string,
+  data?: EventData,
+  options?: string | ServerEventOptions,
+): Promise<boolean> {
+  const { url, id } =
+    typeof options === "string" ? { url: options, id: undefined } : (options ?? {});
+  try {
+    if (!_config) throw new Error("Call initServer() before tracking events");
+
+    const body = buildSendBody({
+      websiteId: _config.websiteId,
+      hostname: _config.hostname,
+      name,
+      url,
+      data,
+    });
+    const payload = id ? { ...body.payload, id } : body.payload;
+
+    const response = await fetch(`${_config.hostUrl.replace(/\/$/, "")}${UMAMI_ENDPOINTS.send}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": _config.userAgent ?? DEFAULT_USER_AGENT,
+      },
+      body: JSON.stringify({ ...body, payload }),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    const text = await response.text();
+    if (!response.ok || text.includes("beep")) {
+      throw new Error(`HTTP ${response.status}: ${text.slice(0, 120)}`);
+    }
+    return true;
+  } catch (err: unknown) {
+    console.error(`[analytics] Server track failed for ${name}:`, err);
+    return false;
+  }
+}
+
+/** Track a server-side revenue event. Revenue must be in dollars (not cents). */
+export function trackServerRevenue(
+  name: string,
+  revenue: number,
+  currency: string,
+  data?: EventData,
+  options?: string | ServerEventOptions,
+): Promise<boolean> {
+  return trackServer(name, { ...data, revenue, currency }, options);
+}

package/src/analytics/svelte.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect } from "vite-plus/test";
+import { umamiScriptAttrs } from "#src/analytics/svelte.js";
+
+const DEFAULT_HOST = "https://your-umami-instance.com";
+
+describe("umamiScriptAttrs", () => {
+  it("returns src and data-website-id using the default host when no options are given", () => {
+    const attrs = umamiScriptAttrs("my-website-id");
+    expect(attrs).toEqual({
+      src: `${DEFAULT_HOST}/script.js`,
+      "data-website-id": "my-website-id",
+    });
+  });
+
+  it("uses a custom hostUrl when provided", () => {
+    const attrs = umamiScriptAttrs("my-website-id", {
+      hostUrl: "https://custom.umami.io",
+    });
+    expect(attrs.src).toBe("https://custom.umami.io/script.js");
+  });
+
+  it("sets data-website-id from the first argument", () => {
+    const attrs = umamiScriptAttrs("site-abc");
+    expect(attrs["data-website-id"]).toBe("site-abc");
+  });
+
+  it("adds data-domains when domains are provided", () => {
+    const attrs = umamiScriptAttrs("site-id", {
+      domains: ["myapp.com", "www.myapp.com"],
+    });
+    expect(attrs["data-domains"]).toBe("myapp.com,www.myapp.com");
+  });
+
+  it("does not add data-domains when domains array is empty", () => {
+    const attrs = umamiScriptAttrs("site-id", { domains: [] });
+    expect(attrs).not.toHaveProperty("data-domains");
+  });
+
+  it("does not add data-domains when domains option is absent", () => {
+    const attrs = umamiScriptAttrs("site-id");
+    expect(attrs).not.toHaveProperty("data-domains");
+  });
+
+  it("adds data-before-send when beforeSend is provided", () => {
+    const attrs = umamiScriptAttrs("site-id", { beforeSend: "umamiBeforeSend" });
+    expect(attrs["data-before-send"]).toBe("umamiBeforeSend");
+  });
+
+  it("does not add data-before-send when beforeSend is absent", () => {
+    const attrs = umamiScriptAttrs("site-id");
+    expect(attrs).not.toHaveProperty("data-before-send");
+  });
+
+  it("adds data-do-not-track=true when doNotTrack is true", () => {
+    const attrs = umamiScriptAttrs("site-id", { doNotTrack: true });
+    expect(attrs["data-do-not-track"]).toBe("true");
+  });
+
+  it("does not add data-do-not-track when doNotTrack is false", () => {
+    const attrs = umamiScriptAttrs("site-id", { doNotTrack: false });
+    expect(attrs).not.toHaveProperty("data-do-not-track");
+  });
+
+  it("does not add data-do-not-track when doNotTrack is absent", () => {
+    const attrs = umamiScriptAttrs("site-id");
+    expect(attrs).not.toHaveProperty("data-do-not-track");
+  });
+
+  it("adds data-performance=true when performance is true", () => {
+    const attrs = umamiScriptAttrs("site-id", { performance: true });
+    expect(attrs["data-performance"]).toBe("true");
+  });
+
+  it("does not add data-performance when performance is false or absent", () => {
+    expect(umamiScriptAttrs("site-id")).not.toHaveProperty("data-performance");
+    expect(umamiScriptAttrs("site-id", { performance: false })).not.toHaveProperty(
+      "data-performance",
+    );
+  });
+
+  it("adds data-tag when tag is provided", () => {
+    const attrs = umamiScriptAttrs("site-id", { tag: "v2" });
+    expect(attrs["data-tag"]).toBe("v2");
+  });
+
+  it("all optional attributes can be combined", () => {
+    const attrs = umamiScriptAttrs("site-id", {
+      hostUrl: "https://u.example.com",
+      domains: ["app.com"],
+      beforeSend: "handler",
+      doNotTrack: true,
+      performance: true,
+      tag: "release-42",
+    });
+    expect(attrs).toEqual({
+      src: "https://u.example.com/script.js",
+      "data-website-id": "site-id",
+      "data-domains": "app.com",
+      "data-before-send": "handler",
+      "data-do-not-track": "true",
+      "data-performance": "true",
+      "data-tag": "release-42",
+    });
+  });
+});

package/src/analytics/svelte.ts

@@ -0,0 +1,58 @@
+/**
+ * Svelte component for loading the Umami script tag.
+ */
+
+/*
+ * Usage in +layout.svelte: import { umamiScriptAttrs } from "@heyramzi/utils/analytics/svelte";
+ */
+
+/*
+ * <svelte:head> <script defer {...umamiScriptAttrs("website-id")} /> </svelte:head>
+ */
+
+/*
+ * Or with beforeSend: define window.umamiBeforeSend yourself and pass its name below.
+ */
+
+/*
+ * <script defer {...umamiScriptAttrs("website-id", { beforeSend: "umamiBeforeSend" })} />
+ */
+
+const DEFAULT_HOST = "https://your-umami-instance.com";
+
+type ScriptOptions = {
+  hostUrl?: string;
+  domains?: string[];
+  beforeSend?: string;
+  doNotTrack?: boolean;
+  performance?: boolean;
+  tag?: string;
+};
+
+/** Generate attributes for the Umami script tag. */
+export function umamiScriptAttrs(
+  websiteId: string,
+  options?: ScriptOptions,
+): Record<string, string> {
+  const host = options?.hostUrl ?? DEFAULT_HOST;
+  const attrs: Record<string, string> = {
+    src: `${host}/script.js`,
+    "data-website-id": websiteId,
+  };
+  if (options?.domains?.length) {
+    attrs["data-domains"] = options.domains.join(",");
+  }
+  if (options?.beforeSend) {
+    attrs["data-before-send"] = options.beforeSend;
+  }
+  if (options?.doNotTrack) {
+    attrs["data-do-not-track"] = "true";
+  }
+  if (options?.performance) {
+    attrs["data-performance"] = "true";
+  }
+  if (options?.tag) {
+    attrs["data-tag"] = options.tag;
+  }
+  return attrs;
+}

package/src/analytics/types.ts

@@ -0,0 +1,26 @@
+export type EventData = Record<string, string | number | boolean>;
+
+export type RevenueData = {
+  revenue: number;
+  currency: string;
+} & EventData;
+
+export type UmamiConfig = {
+  websiteId: string;
+  hostUrl?: string;
+  domains?: string[];
+};
+
+declare global {
+  interface Window {
+    umami?: {
+      track: {
+        (): void;
+        (event: string): void;
+        (event: string, data: Record<string, unknown>): void;
+        (fn: (props: Record<string, unknown>) => Record<string, unknown>): void;
+      };
+      identify?: (data: Record<string, unknown>) => void;
+    };
+  }
+}

package/src/analytics/umami/protocol.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vite-plus/test";
+import { buildSendBody } from "#src/analytics/umami/protocol.js";
+
+describe("buildSendBody", () => {
+  // Apps Script appends its own tag to any header, so payload.userAgent is the only way past the bot filter.
+  it("carries userAgent into the payload", () => {
+    const body = buildSendBody({
+      websiteId: "site-1",
+      name: "sync_run",
+      userAgent: "Mozilla/5.0 airtable-to-sheets/1.0",
+    });
+    expect(body.payload.userAgent).toBe("Mozilla/5.0 airtable-to-sheets/1.0");
+  });
+
+  it("leaves userAgent out when none is given", () => {
+    expect(buildSendBody({ websiteId: "site-1" }).payload).not.toHaveProperty("userAgent");
+  });
+});

package/src/analytics/umami/protocol.ts

@@ -0,0 +1,104 @@
+/**
+ * Pure Umami wire-protocol helpers: no I/O, no global dependencies.
+ */
+
+/*
+ * Consumers in any runtime (browser, Node, Convex actions, Apps Script, service workers, edge functions, Chrome extensions) can use these to build a request body for Umami's `/api/send` endpoint,
+ */
+
+/*
+ * then plug in their own transport (fetch, UrlFetchApp.fetch, etc.) without re-implementing the protocol details.
+ */
+
+/*
+ * Umami's `/api/send` accepts one event per request. Authentication is via the website ID embedded in the payload, so there's no API key.
+ */
+
+/*
+ * The User-Agent header is required; without it the request is dropped.
+ */
+
+import type { EventData } from "#src/analytics/types.js";
+
+export const UMAMI_ENDPOINTS = {
+  send: "/api/send",
+} as const;
+
+export type SendBodyInput = {
+  /** Umami website ID (UUID). */
+  websiteId: string;
+  /** Event name. Required for custom events; omit to record a raw pageview. */
+  name?: string;
+  /** Pathname (or full URL) the event is associated with. Defaults to "/". */
+  url?: string;
+  /** Hostname the event came from. Optional but useful for multi-domain dashboards. */
+  hostname?: string;
+  /** Page title. Optional. */
+  title?: string;
+  /** Referrer URL. Optional. */
+  referrer?: string;
+  /** Browser language tag (e.g. "en-US"). Optional. */
+  language?: string;
+  /** Screen size (e.g. "1920x1080"). Optional. */
+  screen?: string;
+  /** Custom event data. Coerced via `coerceData`. */
+  data?: EventData | Record<string, unknown>;
+  /**
+   * Overrides the User-Agent header. Umami answers a bot agent with `beep` and stores nothing, and Apps Script can't set a clean header, so send `Mozilla/5.0 <name>/<version>` here.
+   */
+  userAgent?: string;
+};
+
+export type SendBody = {
+  type: "event";
+  payload: {
+    website: string;
+    url: string;
+    name?: string;
+    hostname?: string;
+    title?: string;
+    referrer?: string;
+    language?: string;
+    screen?: string;
+    data?: Record<string, string | number | boolean>;
+    userAgent?: string;
+  };
+};
+
+/**
+ * Coerce arbitrary event data to Umami-safe primitives. Umami accepts
+ * string/number/boolean values in `data`. Nulls and undefineds are dropped.
+ */
+export function coerceData(
+  data?: EventData | Record<string, unknown>,
+): Record<string, string | number | boolean> | undefined {
+  if (!data) return undefined;
+  const out: Record<string, string | number | boolean> = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (value === undefined || value === null) continue;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      out[key] = value;
+    } else {
+      out[key] = String(value);
+    }
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/** Build the JSON body for a POST to Umami's `/api/send`. */
+export function buildSendBody(input: SendBodyInput): SendBody {
+  const data = coerceData(input.data);
+  const payload: SendBody["payload"] = {
+    website: input.websiteId,
+    url: input.url ?? "/",
+  };
+  if (input.name) payload.name = input.name;
+  if (input.hostname) payload.hostname = input.hostname;
+  if (input.title) payload.title = input.title;
+  if (input.referrer) payload.referrer = input.referrer;
+  if (input.language) payload.language = input.language;
+  if (input.screen) payload.screen = input.screen;
+  if (data) payload.data = data;
+  if (input.userAgent) payload.userAgent = input.userAgent;
+  return { type: "event", payload };
+}