@carlonicora/nextjs-jsonapi 3.24.2 → 3.25.0

package/src/features/analytics/components/__tests__/AnalyticsSessionsTable.spec.tsx

@@ -0,0 +1,121 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { beforeAll, describe, expect, it, vi } from "vitest";
+import { configureI18n } from "../../../../i18n";
+import { AnalyticsSessionsTable } from "../AnalyticsSessionsTable";
+
+beforeAll(() => {
+  // The package Link resolves its inner component at runtime and throws if i18n
+  // was never configured (src/i18n/config.ts).
+  configureI18n({
+    useRouter: () => ({
+      push: vi.fn(),
+      replace: vi.fn(),
+      back: vi.fn(),
+      forward: vi.fn(),
+      refresh: vi.fn(),
+      prefetch: vi.fn(),
+    }),
+    useTranslations: () => (key: string) => key,
+    usePathname: () => "/",
+    Link: ({
+      href,
+      children,
+      prefetch: _prefetch,
+      ...rest
+    }: {
+      href: string;
+      children: React.ReactNode;
+      [key: string]: any;
+    }) => (
+      <a href={href} {...rest}>
+        {children}
+      </a>
+    ),
+  });
+});
+
+const session = (id: string, extra: Record<string, unknown> = {}) =>
+  ({
+    id,
+    visitorId: `visitor-0000-${id}-abc123`,
+    consented: false,
+    startedAt: new Date("2026-10-01T10:00:00.000Z"),
+    lastSeenAt: new Date("2026-10-01T10:05:00.000Z"),
+    pageViews: 3,
+    section: "public",
+    landingRoute: "/pricing",
+    utmSource: "linkedin",
+    utmMedium: "social",
+    deviceType: "desktop",
+    ...extra,
+  }) as any;
+
+const SESSION_PAGE_URL = "/administration/analytics/sessions";
+
+describe("AnalyticsSessionsTable", () => {
+  it("renders the linked user's name and email", () => {
+    render(
+      <AnalyticsSessionsTable
+        rows={[session("s1", { user: { id: "u1", name: "Ada Lovelace", email: "ada@example.com" } })]}
+        sessionPageUrl={SESSION_PAGE_URL}
+        onLoadMore={vi.fn()}
+        hasMore={false}
+      />,
+    );
+
+    expect(screen.getByText("Ada Lovelace")).toBeInTheDocument();
+    expect(screen.getByText("ada@example.com")).toBeInTheDocument();
+    expect(screen.queryByText("analytics.admin.anonymous")).not.toBeInTheDocument();
+  });
+
+  it("renders an anonymous visitor with the last six characters of the visitor id", () => {
+    render(
+      <AnalyticsSessionsTable
+        rows={[session("s2")]}
+        sessionPageUrl={SESSION_PAGE_URL}
+        onLoadMore={vi.fn()}
+        hasMore={false}
+      />,
+    );
+
+    expect(screen.getByText("analytics.admin.anonymous")).toBeInTheDocument();
+    expect(screen.getByText("abc123")).toBeInTheDocument();
+  });
+
+  it("links each row to its journey page", () => {
+    render(
+      <AnalyticsSessionsTable
+        rows={[session("s3")]}
+        sessionPageUrl={SESSION_PAGE_URL}
+        onLoadMore={vi.fn()}
+        hasMore={false}
+      />,
+    );
+
+    expect(screen.getByTestId("analytics-session-link-s3")).toHaveAttribute("href", `${SESSION_PAGE_URL}/s3`);
+  });
+
+  it("shows the load-more button only when more sessions exist", () => {
+    const onLoadMore = vi.fn();
+    const { rerender } = render(
+      <AnalyticsSessionsTable
+        rows={[session("s4")]}
+        sessionPageUrl={SESSION_PAGE_URL}
+        onLoadMore={onLoadMore}
+        hasMore={false}
+      />,
+    );
+    expect(screen.queryByText("analytics.admin.load_more")).not.toBeInTheDocument();
+
+    rerender(
+      <AnalyticsSessionsTable
+        rows={[session("s4")]}
+        sessionPageUrl={SESSION_PAGE_URL}
+        onLoadMore={onLoadMore}
+        hasMore
+      />,
+    );
+    fireEvent.click(screen.getByText("analytics.admin.load_more"));
+    expect(onLoadMore).toHaveBeenCalledTimes(1);
+  });
+});

package/src/features/analytics/components/__tests__/AnalyticsTimelineChart.spec.tsx

@@ -0,0 +1,35 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { AnalyticsTimelineChart } from "../AnalyticsTimelineChart";
+
+const row = (bucket: string, section: string, visitors: number, pageViews: number) =>
+  ({
+    id: `${bucket}|${section}`,
+    bucket: new Date(bucket),
+    section,
+    visitors,
+    sessions: visitors,
+    pageViews,
+  }) as any;
+
+describe("AnalyticsTimelineChart", () => {
+  it("pivots flat rows into one entry per bucket with visitors and pageViews", () => {
+    render(
+      <AnalyticsTimelineChart
+        rows={[row("2026-10-01", "public", 3, 10), row("2026-10-01", "app", 2, 5), row("2026-10-02", "public", 4, 8)]}
+      />,
+    );
+
+    const data = JSON.parse(screen.getByTestId("analytics-timeline-data").textContent!);
+    expect(data).toHaveLength(2);
+    expect(data[0]).toMatchObject({ bucket: "2026-10-01", visitors: 5, pageViews: 15 });
+    expect(data[1]).toMatchObject({ bucket: "2026-10-02", visitors: 4, pageViews: 8 });
+  });
+
+  it("renders the empty state without a data node when there are no rows", () => {
+    render(<AnalyticsTimelineChart rows={[]} />);
+
+    expect(screen.queryByTestId("analytics-timeline-data")).not.toBeInTheDocument();
+    expect(screen.getByText("analytics.admin.no_data")).toBeInTheDocument();
+  });
+});

package/src/features/analytics/components/__tests__/AnalyticsTracker.spec.tsx

@@ -0,0 +1,248 @@
+import { render } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { AnalyticsTracker } from "../AnalyticsTracker";
+
+const mocks = vi.hoisted(() => ({
+  pathname: "/",
+  track: vi.fn(),
+}));
+
+vi.mock("next/navigation", () => ({
+  usePathname: () => mocks.pathname,
+}));
+
+vi.mock("../../data/AnalyticsService", () => ({
+  AnalyticsService: { track: mocks.track },
+}));
+
+// The cookie helpers come from Task 7. These stand-ins keep the same contract
+// against jsdom's document.cookie so the assertions below read the real cookie jar.
+vi.mock("../../lib/visitorCookie", () => {
+  const NAME = "analytics_visitor";
+  const readVisitorCookie = vi.fn(() => {
+    const entry = document.cookie.split("; ").find((part) => part.startsWith(`${NAME}=`));
+    return entry ? entry.slice(NAME.length + 1) : undefined;
+  });
+  return {
+    ANALYTICS_VISITOR_COOKIE: NAME,
+    readVisitorCookie,
+    ensureVisitorCookie: vi.fn(() => {
+      const existing = readVisitorCookie();
+      if (existing) return existing;
+      const id = crypto.randomUUID();
+      document.cookie = `${NAME}=${id}; path=/; SameSite=Lax`;
+      return id;
+    }),
+    clearVisitorCookie: vi.fn(() => {
+      document.cookie = `${NAME}=; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT`;
+    }),
+  };
+});
+
+vi.mock("../../lib/utm", () => ({
+  readUtm: vi.fn((search: string) => {
+    const params = new URLSearchParams(search);
+    const source = params.get("utm_source");
+    return source ? { utmSource: source } : {};
+  }),
+}));
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const publicSection = () => "public" as const;
+
+const setReferrer = (value: string) => {
+  Object.defineProperty(document, "referrer", { value, configurable: true });
+};
+
+const setWebdriver = (value: boolean) => {
+  Object.defineProperty(window.navigator, "webdriver", { value, configurable: true });
+};
+
+const clearCookie = () => {
+  document.cookie = "analytics_visitor=; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT";
+};
+
+const eventAt = (index: number) => mocks.track.mock.calls[index][0];
+
+describe("AnalyticsTracker", () => {
+  beforeEach(() => {
+    mocks.pathname = "/";
+    mocks.track.mockReset();
+    mocks.track.mockResolvedValue(undefined);
+    setReferrer("");
+    setWebdriver(false);
+    clearCookie();
+    window.history.replaceState(null, "", "/");
+  });
+
+  afterEach(() => {
+    clearCookie();
+  });
+
+  it("sends one event per pathname and none on re-render with the same pathname", () => {
+    mocks.pathname = "/pricing";
+    const { rerender } = render(<AnalyticsTracker hasConsent={false} resolveSection={publicSection} />);
+    rerender(<AnalyticsTracker hasConsent={false} resolveSection={publicSection} />);
+    rerender(<AnalyticsTracker hasConsent={false} resolveSection={publicSection} />);
+    expect(mocks.track).toHaveBeenCalledTimes(1);
+
+    mocks.pathname = "/about";
+    rerender(<AnalyticsTracker hasConsent={false} resolveSection={publicSection} />);
+    expect(mocks.track).toHaveBeenCalledTimes(2);
+    expect(eventAt(1)).toEqual(expect.objectContaining({ path: "/about", section: "public" }));
+  });
+
+  it("first event carries referrer and UTM, later events do not", () => {
+    setReferrer("https://www.linkedin.com/");
+    window.history.replaceState(null, "", "/?utm_source=linkedin");
+    mocks.pathname = "/";
+    const { rerender } = render(<AnalyticsTracker hasConsent={false} resolveSection={publicSection} />);
+
+    mocks.pathname = "/pricing";
+    rerender(<AnalyticsTracker hasConsent={false} resolveSection={publicSection} />);
+
+    expect(mocks.track).toHaveBeenCalledTimes(2);
+    expect(eventAt(0)).toEqual(expect.objectContaining({ referrer: expect.any(String), utmSource: "linkedin" }));
+    expect(eventAt(1).utmSource).toBeUndefined();
+    expect(eventAt(1).referrer).toBeUndefined();
+  });
+
+  it("re-sends the first event's attribution when consent is granted", () => {
+    setReferrer("https://www.linkedin.com/");
+    window.history.replaceState(null, "", "/?utm_source=linkedin");
+    mocks.pathname = "/";
+    const { rerender } = render(<AnalyticsTracker hasConsent={false} resolveSection={publicSection} />);
+
+    rerender(<AnalyticsTracker hasConsent={true} resolveSection={publicSection} />);
+
+    mocks.pathname = "/pricing";
+    rerender(<AnalyticsTracker hasConsent={true} resolveSection={publicSection} />);
+
+    expect(mocks.track).toHaveBeenCalledTimes(3);
+    expect(eventAt(1)).toEqual(
+      expect.objectContaining({
+        utmSource: "linkedin",
+        referrer: eventAt(0).referrer,
+        visitorId: expect.stringMatching(UUID),
+      }),
+    );
+    expect(eventAt(1).referrer).toBe("https://www.linkedin.com/");
+    expect(eventAt(2).utmSource).toBeUndefined();
+    expect(eventAt(2).referrer).toBeUndefined();
+  });
+
+  it("drops a same-host referrer", () => {
+    setReferrer(`${window.location.origin}/pricing`);
+    mocks.pathname = "/about";
+    render(<AnalyticsTracker hasConsent={false} resolveSection={publicSection} />);
+
+    expect(eventAt(0).referrer).toBeUndefined();
+  });
+
+  it("keeps an external referrer", () => {
+    setReferrer("https://news.ycombinator.com/item?id=1");
+    mocks.pathname = "/about";
+    render(<AnalyticsTracker hasConsent={false} resolveSection={publicSection} />);
+
+    expect(eventAt(0).referrer).toBe("https://news.ycombinator.com/item?id=1");
+  });
+
+  it("masks segments under sensitive prefixes", () => {
+    const prefixes = ["/reset", "/activation", "/invitation"];
+    mocks.pathname = "/reset/abc123";
+    const { rerender } = render(
+      <AnalyticsTracker hasConsent={false} resolveSection={publicSection} sensitivePrefixes={prefixes} />,
+    );
+
+    mocks.pathname = "/invitation/abc123/def456";
+    rerender(<AnalyticsTracker hasConsent={false} resolveSection={publicSection} sensitivePrefixes={prefixes} />);
+
+    mocks.pathname = "/activation";
+    rerender(<AnalyticsTracker hasConsent={false} resolveSection={publicSection} sensitivePrefixes={prefixes} />);
+
+    expect(eventAt(0).path).toBe("/reset/:code");
+    expect(eventAt(1).path).toBe("/invitation/:code/:code");
+    expect(eventAt(2).path).toBe("/activation");
+  });
+
+  it("leaves other paths untouched", () => {
+    const prefixes = ["/reset"];
+    mocks.pathname = "/resets/abc123";
+    const { rerender } = render(
+      <AnalyticsTracker hasConsent={false} resolveSection={publicSection} sensitivePrefixes={prefixes} />,
+    );
+
+    mocks.pathname = "/rolls/abc123";
+    rerender(<AnalyticsTracker hasConsent={false} resolveSection={publicSection} sensitivePrefixes={prefixes} />);
+
+    expect(eventAt(0).path).toBe("/resets/abc123");
+    expect(eventAt(1).path).toBe("/rolls/abc123");
+  });
+
+  it("strips query and hash from path", () => {
+    window.history.replaceState(null, "", "/pricing?x=1#plans");
+    mocks.pathname = "/pricing";
+    render(<AnalyticsTracker hasConsent={false} resolveSection={publicSection} />);
+
+    expect(eventAt(0).path).toBe("/pricing");
+  });
+
+  it("sends the cookie id only with consent, and creates it", () => {
+    mocks.pathname = "/pricing";
+    render(<AnalyticsTracker hasConsent={true} resolveSection={publicSection} />);
+
+    expect(eventAt(0).visitorId).toMatch(UUID);
+    expect(document.cookie).toContain(`analytics_visitor=${eventAt(0).visitorId}`);
+  });
+
+  it("sends no id and clears the cookie without consent", () => {
+    document.cookie = "analytics_visitor=6f1c2d3e-0000-4000-8000-000000000001; path=/";
+    mocks.pathname = "/pricing";
+    render(<AnalyticsTracker hasConsent={false} resolveSection={publicSection} />);
+
+    expect(eventAt(0).visitorId).toBeUndefined();
+    expect(document.cookie).not.toContain("analytics_visitor");
+  });
+
+  it("switches to cookie id after consent", () => {
+    mocks.pathname = "/pricing";
+    const { rerender } = render(<AnalyticsTracker hasConsent={false} resolveSection={publicSection} />);
+    expect(eventAt(0).visitorId).toBeUndefined();
+
+    rerender(<AnalyticsTracker hasConsent={true} resolveSection={publicSection} />);
+
+    expect(mocks.track).toHaveBeenCalledTimes(2);
+    expect(eventAt(1)).toEqual(expect.objectContaining({ path: "/pricing", visitorId: expect.stringMatching(UUID) }));
+  });
+
+  it("skips automated browsers and the analytics admin pages", () => {
+    setWebdriver(true);
+    mocks.pathname = "/pricing";
+    const { unmount } = render(<AnalyticsTracker hasConsent={true} resolveSection={publicSection} />);
+    expect(mocks.track).not.toHaveBeenCalled();
+    unmount();
+
+    setWebdriver(false);
+    mocks.pathname = "/administration/analytics";
+    render(<AnalyticsTracker hasConsent={true} resolveSection={publicSection} />);
+    expect(mocks.track).not.toHaveBeenCalled();
+  });
+
+  it("passes the app's section", () => {
+    const resolveSection = vi.fn(() => "app" as const);
+    mocks.pathname = "/rolls";
+    render(<AnalyticsTracker hasConsent={false} resolveSection={resolveSection} />);
+
+    expect(resolveSection).toHaveBeenCalledWith("/rolls");
+    expect(eventAt(0).section).toBe("app");
+  });
+
+  it("never throws when track rejects", async () => {
+    mocks.track.mockRejectedValue(new Error("network down"));
+    mocks.pathname = "/pricing";
+
+    expect(() => render(<AnalyticsTracker hasConsent={false} resolveSection={publicSection} />)).not.toThrow();
+    await Promise.resolve();
+    expect(mocks.track).toHaveBeenCalledTimes(1);
+  });
+});

package/src/features/analytics/components/server/AnalyticsAdminPage.tsx

@@ -0,0 +1,28 @@
+import { redirect } from "next/navigation";
+// The container is imported through the package's own client subpath, never by
+// relative path. tsup keeps this specifier external, so the built server entry
+// reaches the container through `features/analytics/index`, which carries the
+// "use client" banner. A relative import would inline the container's hooks and
+// contexts into this server bundle, outside any client boundary.
+import { AnalyticsAdminPageContainer } from "@carlonicora/nextjs-jsonapi/analytics";
+import { ServerSession } from "../../../../server";
+
+type Props = {
+  /** Role id the viewer must hold. The package has no role constants, so the host app passes its own. */
+  adminRoleId: string;
+  /** Route the breadcrumb links back to. */
+  pageUrl?: string;
+  /** Base route of the journey page each session row links to. */
+  sessionPageUrl?: string;
+  /** Where a viewer without the role is sent. */
+  deniedRedirect?: string;
+};
+
+/** Server page for the administrative analytics dashboard: role gate, then the client container. */
+export async function AnalyticsAdminPage({ adminRoleId, pageUrl, sessionPageUrl, deniedRedirect = "/" }: Props) {
+  if (!(await ServerSession.hasRole(adminRoleId))) {
+    redirect(deniedRedirect);
+  }
+
+  return <AnalyticsAdminPageContainer pageUrl={pageUrl} sessionPageUrl={sessionPageUrl} />;
+}

package/src/features/analytics/components/server/AnalyticsJourneyPage.tsx

@@ -0,0 +1,25 @@
+import { redirect } from "next/navigation";
+// Imported through the package's own client subpath for the same reason as in
+// AnalyticsAdminPage: the built server entry must reach the container through
+// the "use client" bundle, not inline it.
+import { AnalyticsJourneyPageContainer } from "@carlonicora/nextjs-jsonapi/analytics";
+import { ServerSession } from "../../../../server";
+
+type Props = {
+  /** Role id the viewer must hold. The package has no role constants, so the host app passes its own. */
+  adminRoleId: string;
+  sessionId: string;
+  /** Route of the dashboard; the journey pages live under `${pageUrl}/sessions`. */
+  pageUrl?: string;
+  /** Where a viewer without the role is sent. */
+  deniedRedirect?: string;
+};
+
+/** Server page for one session's journey: role gate, then the client container. */
+export async function AnalyticsJourneyPage({ adminRoleId, sessionId, pageUrl, deniedRedirect = "/" }: Props) {
+  if (!(await ServerSession.hasRole(adminRoleId))) {
+    redirect(deniedRedirect);
+  }
+
+  return <AnalyticsJourneyPageContainer sessionId={sessionId} pageUrl={pageUrl} />;
+}