@heyramzi/marketing 3.0.0 → 3.1.0

package/README.md

@@ -26,8 +26,13 @@ The analytics module provides wrappers for Umami tracking across different envir
 ```typescript
 import { initServer, trackServer } from '@heyramzi/marketing/analytics/server';
 
-initServer({ websiteId: process.env.UMAMI_WEBSITE_ID });
-await trackServer('signup', { plan: 'pro' });
+initServer({
+  hostUrl: 'https://umami.example.com',
+  websiteId: process.env.UMAMI_WEBSITE_ID,
+  hostname: 'example.com',
+});
+// Resolves true once Umami recorded it. On a Worker, await it or pass it to waitUntil.
+await trackServer('signup', { plan: 'pro' }, { url: '/signup', id: user.id });
 ```
 
 #### Script tag and browser tracking

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyramzi/marketing",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Umami analytics for client, server, and Svelte, plus a satori-based HTML-to-image pipeline.",
   "license": "MIT",
   "repository": {

package/src/analytics/server.test.ts

@@ -1,282 +1,165 @@
-import { describe, it, expect, vi, beforeEach } from "vite-plus/test";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vite-plus/test";
 
-// The server module holds module-level singletons (client, _config).
-// Each test resets them by calling vi.resetModules() + re-importing.
+// 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");
 }
 
-beforeEach(() => {
-  vi.resetModules();
-});
-
-// ---- initServer ----
-
-describe("initServer", () => {
-  it("stores config so that subsequent trackServer calls succeed", async () => {
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        track = mockTrack;
-      },
-    }));
-
-    const { initServer, trackServer } = await freshImport();
-    initServer({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServer("test_event");
-    await new Promise((r) => setTimeout(r, 0));
+const fetchMock = vi.fn();
 
-    expect(mockTrack).toHaveBeenCalledWith({ name: "test_event" });
-  });
+function answer(body: string, status = 200) {
+  fetchMock.mockResolvedValue(new Response(body, { status }));
+}
 
-  it("throws when trackServer is called without prior initServer", async () => {
-    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-    vi.doMock("@umami/node", () => ({ Umami: class {} }));
+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> },
+  };
+}
 
-    const { trackServer } = await freshImport();
-    trackServer("orphan_event");
-    await new Promise((r) => setTimeout(r, 0));
+beforeEach(() => {
+  fetchMock.mockReset();
+  answer('{"cache":"x"}');
+  vi.stubGlobal("fetch", fetchMock);
+  vi.spyOn(console, "error").mockImplementation(() => {});
+});
 
-    expect(consoleSpy).toHaveBeenCalledWith(
-      "[analytics] Server track failed:",
-      expect.objectContaining({ message: "Call initServer() before tracking events" }),
-    );
-  });
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
 });
 
-// ---- trackServer ----
+const config = {
+  hostUrl: "https://umami.example.com",
+  websiteId: "abc-123",
+  hostname: "example.com",
+};
 
 describe("trackServer", () => {
-  it("builds a payload with only name when no data or url is given", async () => {
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        track = mockTrack;
-      },
-    }));
-
+  it("awaits the POST to /api/send and resolves true", async () => {
     const { initServer, trackServer } = await freshImport();
-    initServer({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServer("signup");
-    await new Promise((r) => setTimeout(r, 0));
-
-    expect(mockTrack).toHaveBeenCalledWith({ name: "signup" });
-  });
-
-  it("includes data in the payload when provided", async () => {
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        track = mockTrack;
-      },
-    }));
+    initServer(config);
 
-    const { initServer, trackServer } = await freshImport();
-    initServer({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServer("feature_used", { feature: "export", count: 5 });
-    await new Promise((r) => setTimeout(r, 0));
+    await expect(trackServer("signup")).resolves.toBe(true);
 
-    expect(mockTrack).toHaveBeenCalledWith({
-      name: "feature_used",
-      data: { feature: "export", count: 5 },
+    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("includes url in the payload when provided", async () => {
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        track = mockTrack;
-      },
-    }));
-
+  it("sends data, url and id", async () => {
     const { initServer, trackServer } = await freshImport();
-    initServer({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServer("page_view", undefined, "/pricing");
-    await new Promise((r) => setTimeout(r, 0));
-
-    expect(mockTrack).toHaveBeenCalledWith({ name: "page_view", url: "/pricing" });
-  });
+    initServer(config);
 
-  it("includes both data and url when both are provided", async () => {
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        track = mockTrack;
-      },
-    }));
+    await trackServer("click", { label: "CTA" }, { url: "/home", id: "cs_123" });
 
-    const { initServer, trackServer } = await freshImport();
-    initServer({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServer("click", { label: "CTA" }, "/home");
-    await new Promise((r) => setTimeout(r, 0));
-
-    expect(mockTrack).toHaveBeenCalledWith({
+    expect(sent().body.payload).toEqual({
+      website: "abc-123",
+      hostname: "example.com",
+      url: "/home",
       name: "click",
       data: { label: "CTA" },
-      url: "/home",
+      id: "cs_123",
     });
   });
 
-  it("logs an error and does not throw when track rejects", async () => {
-    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-    const mockTrack = vi.fn().mockRejectedValue(new Error("network failure"));
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        track = mockTrack;
-      },
-    }));
-
+  it("still takes the url as a plain string", async () => {
     const { initServer, trackServer } = await freshImport();
-    initServer({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServer("risky_event");
-    await new Promise((r) => setTimeout(r, 0));
+    initServer(config);
 
-    expect(consoleSpy).toHaveBeenCalledWith("[analytics] Server track failed:", expect.any(Error));
-  });
+    await trackServer("page_view", undefined, "/pricing");
 
-  it("reuses the same Umami instance across multiple calls", async () => {
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    let constructorCallCount = 0;
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        constructor() {
-          constructorCallCount++;
-        }
-        track = mockTrack;
-      },
-    }));
+    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({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServer("first");
-    // Wait for the first getClient() promise to resolve and set the cached client
-    await new Promise((r) => setTimeout(r, 10));
-    trackServer("second");
-    await new Promise((r) => setTimeout(r, 10));
-
-    expect(constructorCallCount).toBe(1);
-    expect(mockTrack).toHaveBeenCalledTimes(2);
-  });
-});
+    initServer({
+      ...config,
+      hostUrl: "https://umami.example.com/",
+      userAgent: "Mozilla/5.0 Seam/1.0",
+    });
 
-// ---- trackServerRevenue ----
+    await trackServer("ua_test");
 
-describe("trackServerRevenue", () => {
-  it("tracks a revenue event with revenue and currency merged into data", async () => {
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        track = mockTrack;
-      },
-    }));
+    expect(sent().url).toBe("https://umami.example.com/api/send");
+    expect(sent().headers["User-Agent"]).toBe("Mozilla/5.0 Seam/1.0");
+  });
 
-    const { initServer, trackServerRevenue } = await freshImport();
-    initServer({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServerRevenue("purchase", 49.99, "USD");
-    await new Promise((r) => setTimeout(r, 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);
 
-    expect(mockTrack).toHaveBeenCalledWith({
-      name: "purchase",
-      data: { revenue: 49.99, currency: "USD" },
-    });
+    await expect(trackServer("dropped")).resolves.toBe(false);
+    expect(console.error).toHaveBeenCalled();
   });
 
-  it("merges extra EventData alongside revenue and currency", async () => {
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        track = mockTrack;
-      },
-    }));
+  it("resolves false on an HTTP error", async () => {
+    answer("nope", 500);
+    const { initServer, trackServer } = await freshImport();
+    initServer(config);
 
-    const { initServer, trackServerRevenue } = await freshImport();
-    initServer({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServerRevenue("subscription", 9.99, "EUR", { plan: "pro" });
-    await new Promise((r) => setTimeout(r, 0));
+    await expect(trackServer("server_error")).resolves.toBe(false);
+  });
 
-    expect(mockTrack).toHaveBeenCalledWith({
-      name: "subscription",
-      data: { plan: "pro", revenue: 9.99, currency: "EUR" },
-    });
+  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("passes url to the underlying trackServer call", async () => {
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        track = mockTrack;
-      },
-    }));
+  it("resolves false without initServer and sends nothing", async () => {
+    const { trackServer } = await freshImport();
 
-    const { initServer, trackServerRevenue } = await freshImport();
-    initServer({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServerRevenue("checkout", 19.99, "USD", undefined, "/checkout");
-    await new Promise((r) => setTimeout(r, 0));
-
-    expect(mockTrack).toHaveBeenCalledWith({
-      name: "checkout",
-      data: { revenue: 19.99, currency: "USD" },
-      url: "/checkout",
-    });
+    await expect(trackServer("orphan_event")).resolves.toBe(false);
+    expect(fetchMock).not.toHaveBeenCalled();
   });
 });
 
-// ---- initServer config forwarding ----
-
-describe("initServer config forwarding", () => {
-  it("passes hostUrl and websiteId to the Umami constructor", async () => {
-    let capturedConfig = null;
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        constructor(cfg: unknown) {
-          capturedConfig = cfg;
-        }
-        track = mockTrack;
-      },
-    }));
-
-    const { initServer, trackServer } = await freshImport();
-    initServer({ hostUrl: "https://analytics.myapp.io", websiteId: "xyz-789" });
-    trackServer("init_test");
-    await new Promise((r) => setTimeout(r, 0));
-
-    expect(capturedConfig).toEqual({
-      hostUrl: "https://analytics.myapp.io",
-      websiteId: "xyz-789",
-      userAgent: "Server",
+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("forwards a custom userAgent to the Umami constructor", async () => {
-    let capturedConfig = null;
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        constructor(cfg: unknown) {
-          capturedConfig = cfg;
-        }
-        track = mockTrack;
-      },
-    }));
-
-    const { initServer, trackServer } = await freshImport();
-    initServer({
-      hostUrl: "https://umami.example.com",
-      websiteId: "abc-123",
-      userAgent: "MyBot/1.0",
-    });
-    trackServer("ua_test");
-    await new Promise((r) => setTimeout(r, 0));
+  it("resolves false when the send fails", async () => {
+    answer("beep");
+    const { initServer, trackServerRevenue } = await freshImport();
+    initServer(config);
 
-    expect(capturedConfig).toEqual({
-      hostUrl: "https://umami.example.com",
-      websiteId: "abc-123",
-      userAgent: "MyBot/1.0",
-    });
+    await expect(
+      trackServerRevenue("checkout", 19.99, "USD", undefined, "/checkout"),
+    ).resolves.toBe(false);
   });
 });

package/src/analytics/server.ts

@@ -1,32 +1,31 @@
 /**
- * Server-side Umami tracking via @umami/node.
- * Reliable for revenue and critical events — bypasses ad blockers.
- *
- * Requires `@umami/node` peer dependency.
+ * 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";
-
-type UmamiNodeClient = {
-  track: (payload: Record<string, unknown>) => Promise<unknown>;
-};
-
-type UmamiNodeModule = {
-  Umami: new (config: {
-    hostUrl: string;
-    websiteId: string;
-    userAgent?: string;
-  }) => UmamiNodeClient;
-};
-
-let client: UmamiNodeClient | null = null;
+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. */
@@ -34,30 +33,47 @@ export function initServer(config: ServerConfig): void {
   _config = config;
 }
 
-async function getClient(): Promise<UmamiNodeClient> {
-  if (client) return client;
-  if (!_config) throw new Error("Call initServer() before tracking events");
-
-  const { Umami } = (await import("@umami/node")) as UmamiNodeModule;
-  client = new Umami({
-    hostUrl: _config.hostUrl,
-    websiteId: _config.websiteId,
-    userAgent: _config.userAgent ?? "Server",
-  });
-  return client;
-}
+/**
+ * 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");
 
-/** Fire-and-forget server-side event tracking. Never throws. */
-export function trackServer(name: string, data?: EventData, url?: string): void {
-  const payload: { name: string; data?: EventData; url?: string } = { name };
-  if (data) payload.data = data;
-  if (url) payload.url = url;
+    const body = buildSendBody({
+      websiteId: _config.websiteId,
+      hostname: _config.hostname,
+      name,
+      url,
+      data,
+    });
+    const payload = id ? { ...body.payload, id } : body.payload;
 
-  getClient()
-    .then((c) => c.track(payload))
-    .catch((err: unknown) => {
-      console.error("[analytics] Server track failed:", err);
+    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). */
@@ -66,7 +82,7 @@ export function trackServerRevenue(
   revenue: number,
   currency: string,
   data?: EventData,
-  url?: string,
-): void {
-  trackServer(name, { ...data, revenue, currency }, url);
+  options?: string | ServerEventOptions,
+): Promise<boolean> {
+  return trackServer(name, { ...data, revenue, currency }, options);
 }