@carlonicora/nextjs-jsonapi 3.24.2 → 3.25.0

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

@@ -0,0 +1,175 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { useTheme } from "next-themes";
+import { useMemo } from "react";
+import { Bar, BarChart, CartesianGrid, XAxis, YAxis } from "recharts";
+import {
+  ChartConfig,
+  ChartContainer,
+  ChartLegend,
+  ChartLegendContent,
+  ChartTooltip,
+  ChartTooltipContent,
+} from "../../../shadcnui";
+import { useUsageFormatters } from "../../tokenusage/lib/formatters";
+import { ChartMode, seriesColor } from "../../tokenusage/lib/palette";
+import { AnalyticsTimelineInterface } from "../data/analytics-timeline.interface";
+
+/** The two fixed series, in palette order: slot 0 visitors, slot 1 page views. */
+const SERIES = ["visitors", "pageViews"] as const;
+
+type AnalyticsTimelineChartProps = {
+  rows: AnalyticsTimelineInterface[];
+  className?: string;
+};
+
+type TimelineBucket = { bucket: string; visitors: number; pageViews: number };
+
+/**
+ * The bucket key, derived with UTC getters.
+ *
+ * The backend field is `type: "date"` — a calendar day with no time — and the
+ * model parses the `YYYY-MM-DD` wire value with `new Date(...)`, which lands on
+ * UTC midnight. Reading it back with local getters would shift the bucket a day
+ * early west of UTC, so the key (and every label built from it) stays in UTC.
+ */
+const bucketKey = (date: Date): string => {
+  const y = date.getUTCFullYear();
+  const m = `${date.getUTCMonth() + 1}`.padStart(2, "0");
+  const d = `${date.getUTCDate()}`.padStart(2, "0");
+  return `${y}-${m}-${d}`;
+};
+
+/**
+ * The granularity the data was bucketed at, inferred from the spacing between
+ * consecutive buckets. The backend chooses the granularity and the rows carry
+ * the consequence, so the axis reads it off the data rather than taking a prop
+ * that could disagree with what was actually fetched.
+ */
+const inferGranularity = (buckets: string[]): "day" | "week" | "month" => {
+  if (buckets.length < 2) return "day";
+
+  const dayMs = 24 * 60 * 60 * 1000;
+  let smallestGap = Number.POSITIVE_INFINITY;
+  for (let i = 1; i < buckets.length; i += 1) {
+    const gap = (Date.parse(buckets[i]) - Date.parse(buckets[i - 1])) / dayMs;
+    if (gap > 0 && gap < smallestGap) smallestGap = gap;
+  }
+
+  if (smallestGap >= 28) return "month";
+  if (smallestGap >= 7) return "week";
+  return "day";
+};
+
+/**
+ * Traffic over time as a grouped bar chart: visitors and page views per bucket.
+ *
+ * The backend returns one row per bucket per section; the chart sums the
+ * sections into one entry per bucket. The two series measure different things,
+ * so they sit side by side rather than stacked.
+ *
+ * Colour does an IDENTITY job here — each bar is a series, not a magnitude — so
+ * it draws the fixed categorical order from the token-usage palette (slots 0 and
+ * 1). The palette's light-mode validator run carries a sub-3:1 contrast WARN,
+ * which obliges a relief channel: the legend and the value-carrying tooltip
+ * below are what make the fills readable.
+ */
+export function AnalyticsTimelineChart({ rows, className }: AnalyticsTimelineChartProps) {
+  const t = useTranslations();
+  const { compact, bucketDate, decimal } = useUsageFormatters();
+  const { resolvedTheme } = useTheme();
+  const mode: ChartMode = resolvedTheme === "dark" ? "dark" : "light";
+
+  const chartData = useMemo(() => {
+    const byBucket = new Map<string, TimelineBucket>();
+    for (const row of rows) {
+      const key = bucketKey(row.bucket);
+      let entry = byBucket.get(key);
+      if (!entry) {
+        entry = { bucket: key, visitors: 0, pageViews: 0 };
+        byBucket.set(key, entry);
+      }
+      entry.visitors += row.visitors;
+      entry.pageViews += row.pageViews;
+    }
+    return [...byBucket.values()].sort((a, b) => a.bucket.localeCompare(b.bucket));
+  }, [rows]);
+
+  const chartConfig = useMemo(
+    () =>
+      ({
+        visitors: { label: t("analytics.admin.series.visitors") },
+        pageViews: { label: t("analytics.admin.series.page_views") },
+      }) as ChartConfig,
+    [t],
+  );
+
+  if (chartData.length === 0) {
+    return (
+      <p className={className ? `text-muted-foreground text-sm ${className}` : "text-muted-foreground text-sm"}>
+        {t("analytics.admin.no_data")}
+      </p>
+    );
+  }
+
+  const granularity = inferGranularity(chartData.map((entry) => entry.bucket));
+
+  return (
+    // The chart is a coordinate system, not prose: recharts lays the axes and the
+    // bars out left-to-right, so the whole chart stays an LTR island even under
+    // dir="rtl". Only the labels inside it are translated.
+    // rtl-ok: deliberate LTR island (chart)
+    <div className={className} dir="ltr">
+      {/* The pivot, exposed for assertions and for screen readers that would
+          otherwise get nothing from the SVG. */}
+      <span className="sr-only" data-testid="analytics-timeline-data">
+        {JSON.stringify(chartData)}
+      </span>
+
+      <ChartContainer config={chartConfig} className="aspect-auto h-72 w-full">
+        <BarChart accessibilityLayer data={chartData} margin={{ top: 8, right: 8, bottom: 0, left: 0 }}>
+          <CartesianGrid vertical={false} />
+          <XAxis
+            dataKey="bucket"
+            tickLine={false}
+            axisLine={false}
+            tickMargin={8}
+            minTickGap={16}
+            tickFormatter={(value: string) => bucketDate(value, granularity)}
+          />
+          <YAxis
+            tickLine={false}
+            axisLine={false}
+            tickMargin={8}
+            width={48}
+            tickFormatter={(value: number) => compact(value)}
+          />
+          <ChartTooltip
+            content={
+              <ChartTooltipContent
+                labelFormatter={(value) => bucketDate(String(value), granularity)}
+                valueFormatter={(value) => decimal(Number(value), 0)}
+              />
+            }
+          />
+          <ChartLegend content={<ChartLegendContent />} />
+          {SERIES.map((series, index) => (
+            <Bar
+              key={series}
+              dataKey={series}
+              maxBarSize={28}
+              fill={seriesColor(index, mode)}
+              // A 2px stroke in the surface colour is the gap between
+              // neighbouring bars — the palette's own secondary-encoding
+              // channel, not a border.
+              stroke="var(--background)"
+              strokeWidth={2}
+              radius={[4, 4, 0, 0]}
+            />
+          ))}
+        </BarChart>
+      </ChartContainer>
+    </div>
+  );
+}

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

@@ -0,0 +1,112 @@
+"use client";
+
+import { usePathname } from "next/navigation";
+import { useEffect, useRef } from "react";
+import { v4 } from "uuid";
+import { AnalyticsService } from "../data/AnalyticsService";
+import type { AnalyticsEventInput } from "../data/analytics.types";
+import { readUtm } from "../lib/utm";
+import { clearVisitorCookie, ensureVisitorCookie } from "../lib/visitorCookie";
+
+// The dashboard itself is never tracked, so administrators reading it do not inflate it.
+const EXCLUDED_PREFIX = "/administration/analytics";
+
+// The API rejects longer referrers.
+const MAX_REFERRER_LENGTH = 2048;
+
+type Attribution = Pick<
+  AnalyticsEventInput,
+  "referrer" | "utmSource" | "utmMedium" | "utmCampaign" | "utmTerm" | "utmContent"
+>;
+
+type AnalyticsTrackerProps = {
+  hasConsent: boolean;
+  resolveSection: (pathname: string) => "public" | "app";
+  sensitivePrefixes?: string[];
+};
+
+/**
+ * Returns the referrer only when it comes from another host, so internal
+ * navigation is never stored as a traffic source.
+ */
+function readExternalReferrer(): string | undefined {
+  if (!document.referrer) return undefined;
+  try {
+    if (new URL(document.referrer).host === window.location.host) return undefined;
+  } catch {
+    return undefined;
+  }
+  return document.referrer.slice(0, MAX_REFERRER_LENGTH);
+}
+
+/**
+ * Replaces every segment after a sensitive prefix with ":code", so single-use
+ * account codes in the URL never leave the browser.
+ */
+function maskSensitivePath(path: string, sensitivePrefixes: string[] | undefined): string {
+  if (!sensitivePrefixes) return path;
+
+  for (const prefix of sensitivePrefixes) {
+    if (path === prefix) return path;
+    if (path.startsWith(`${prefix}/`)) {
+      const segments = path
+        .slice(prefix.length + 1)
+        .split("/")
+        .filter((segment) => segment.length > 0);
+      return [prefix, ...segments.map(() => ":code")].join("/");
+    }
+  }
+
+  return path;
+}
+
+export function AnalyticsTracker({ hasConsent, resolveSection, sensitivePrefixes }: AnalyticsTrackerProps): null {
+  const pathname = usePathname();
+  const lastPath = useRef<string | null>(null);
+  const lastConsent = useRef<boolean>(false);
+  const attribution = useRef<Attribution | null>(null);
+
+  useEffect(() => {
+    if (!hasConsent) clearVisitorCookie();
+
+    if (!pathname) return;
+    if (typeof navigator !== "undefined" && navigator.webdriver) return;
+
+    const path = pathname.split(/[?#]/)[0] || "/";
+    if (path.startsWith(EXCLUDED_PREFIX)) return;
+
+    // One event per distinct path. The same path is sent again only when consent
+    // was just granted, so the processor starts a new visitor on the cookie id.
+    const isNewPath = lastPath.current !== path;
+    const consentJustGranted = hasConsent && !lastConsent.current;
+    lastConsent.current = hasConsent;
+    if (!isNewPath && !consentJustGranted) return;
+    lastPath.current = path;
+
+    const sentPath = maskSensitivePath(path, sensitivePrefixes);
+
+    const input: AnalyticsEventInput = {
+      id: v4(),
+      path: sentPath,
+      section: resolveSection(sentPath),
+      screenWidth: window.innerWidth,
+    };
+
+    if (hasConsent) input.visitorId = ensureVisitorCookie();
+
+    // The first event of the page load carries the attribution. The event sent
+    // because consent was just granted carries it again, so the session opened
+    // on the cookie id keeps the source the visitor arrived from.
+    const isFirstEvent = attribution.current === null;
+    if (isFirstEvent) {
+      const referrer = readExternalReferrer();
+      attribution.current = { ...(referrer ? { referrer } : {}), ...readUtm(window.location.search) };
+    }
+    if (isFirstEvent || consentJustGranted) Object.assign(input, attribution.current);
+
+    // AnalyticsService.track never rejects: it logs and swallows its own failures.
+    void AnalyticsService.track(input);
+  }, [pathname, hasConsent, resolveSection, sensitivePrefixes]);
+
+  return null;
+}

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

@@ -0,0 +1,39 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { AnalyticsAdminTiles } from "../AnalyticsAdminTiles";
+
+const row = (section: string, window: string, values: Partial<Record<string, number>>) =>
+  ({
+    id: `${section}|${window}`,
+    section,
+    window,
+    visitors: 0,
+    sessions: 0,
+    pageViews: 0,
+    pagesPerSession: 0,
+    consentShare: 0,
+    ...values,
+  }) as any;
+
+const summary = [
+  row("total", "current", { visitors: 120, sessions: 150, pageViews: 600, pagesPerSession: 4, consentShare: 0.25 }),
+  row("total", "previous", { visitors: 100 }),
+];
+
+describe("AnalyticsAdminTiles", () => {
+  it("shows the current totals with the delta against the previous window", () => {
+    render(<AnalyticsAdminTiles summary={summary} />);
+
+    expect(screen.getByTestId("analytics-tile-visitors")).toHaveTextContent("120");
+    expect(screen.getByTestId("analytics-tile-visitors-delta")).toHaveTextContent("+20%");
+    expect(screen.getByTestId("analytics-tile-consent-share")).toHaveTextContent("25%");
+    expect(screen.getByTestId("analytics-tile-pages-per-session")).toHaveTextContent("4.0");
+  });
+
+  it("suppresses the delta rather than showing Infinity when the previous window is zero", () => {
+    render(<AnalyticsAdminTiles summary={summary} />);
+
+    // sessions previous is 0
+    expect(screen.getByTestId("analytics-tile-sessions-delta")).toHaveTextContent("—");
+  });
+});

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

@@ -0,0 +1,39 @@
+import { fireEvent, render, screen, within } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { AnalyticsBreakdownTable } from "../AnalyticsBreakdownTable";
+
+const row = (dimension: string, key: string, visitors: number) =>
+  ({ id: `${dimension}|${key}`, dimension, key, visitors, sessions: visitors, pageViews: visitors * 2 }) as any;
+
+const breakdowns = {
+  source: [row("source", "(none)", 5), row("source", "linkedin", 30), row("source", "google", 12)],
+  medium: [],
+  campaign: [],
+  referrer: [],
+  route: [row("route", "/rolls/:id", 9)],
+  landing: [],
+} as any;
+
+describe("AnalyticsBreakdownTable", () => {
+  it("renders one tab per dimension", () => {
+    render(<AnalyticsBreakdownTable breakdowns={breakdowns} />);
+
+    expect(screen.getAllByRole("tab")).toHaveLength(6);
+  });
+
+  it("sorts rows by visitors descending and renders the (none) key as-is", () => {
+    render(<AnalyticsBreakdownTable breakdowns={breakdowns} />);
+
+    const rows = screen.getAllByTestId(/^analytics-breakdown-row-/);
+    expect(rows.map((r) => within(r).getAllByRole("cell")[0].textContent)).toEqual(["linkedin", "google", "(none)"]);
+  });
+
+  it("shows the selected dimension's rows when its tab is clicked", () => {
+    render(<AnalyticsBreakdownTable breakdowns={breakdowns} />);
+
+    fireEvent.click(screen.getByRole("tab", { name: "analytics.admin.dimensions.route" }));
+
+    expect(screen.getByText("/rolls/:id")).toBeInTheDocument();
+    expect(screen.queryByText("linkedin")).not.toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,124 @@
+import { render, screen, waitFor, within } from "@testing-library/react";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { configureI18n } from "../../../../i18n";
+import { AnalyticsAdminService } from "../../data/AnalyticsAdminService";
+import { AnalyticsJourneyContainer } from "../AnalyticsJourneyContainer";
+
+vi.mock("../../data/AnalyticsAdminService", () => ({
+  AnalyticsAdminService: {
+    getSession: vi.fn(),
+    getSessionPageViews: vi.fn(),
+    getSessions: vi.fn(),
+  },
+}));
+
+// The real page chrome needs the whole app shell (header, sidebar, navigation
+// contexts); the journey's own content is what is under test here.
+vi.mock("../../../../components", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../../../components")>();
+  return {
+    ...actual,
+    RoundPageContainer: ({ children }: { children?: React.ReactNode }) => <div>{children}</div>,
+  };
+});
+
+beforeAll(() => {
+  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, startedAt: string) =>
+  ({
+    id,
+    visitorId: "visitor-0000-0000-abc123",
+    consented: true,
+    startedAt: new Date(startedAt),
+    lastSeenAt: new Date(startedAt),
+    pageViews: 3,
+    section: "public",
+    landingRoute: "/pricing",
+    referrerHost: "linkedin.com",
+    utmSource: "linkedin",
+    utmMedium: "social",
+    utmCampaign: "launch",
+    deviceType: "desktop",
+  }) as any;
+
+const pageView = (id: string, createdAt: string, path: string) =>
+  ({ id, createdAt: new Date(createdAt), path, route: path, section: "public" }) as any;
+
+describe("AnalyticsJourneyContainer", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(AnalyticsAdminService.getSession).mockResolvedValue(session("s1", "2026-10-01T10:00:00.000Z"));
+    vi.mocked(AnalyticsAdminService.getSessionPageViews).mockResolvedValue([
+      pageView("p1", "2026-10-01T10:00:00.000Z", "/pricing"),
+      pageView("p2", "2026-10-01T10:02:00.000Z", "/features"),
+      pageView("p3", "2026-10-01T10:02:30.000Z", "/register"),
+    ]);
+    vi.mocked(AnalyticsAdminService.getSessions).mockResolvedValue([
+      session("s1", "2026-10-01T10:00:00.000Z"),
+      session("s9", "2026-09-20T08:00:00.000Z"),
+    ]);
+  });
+
+  it("renders the page views in order with the gap to the previous one", async () => {
+    render(<AnalyticsJourneyContainer sessionId="s1" />);
+
+    const rows = await screen.findAllByTestId(/^analytics-pageview-row-/);
+    expect(rows.map((row) => within(row).getAllByRole("cell")[2].textContent)).toEqual([
+      "/pricing",
+      "/features",
+      "/register",
+    ]);
+    expect(within(rows[1]).getByText("2 min")).toBeInTheDocument();
+    expect(AnalyticsAdminService.getSessionPageViews).toHaveBeenCalledWith({ sessionId: "s1" });
+  });
+
+  it("renders the attribution header", async () => {
+    render(<AnalyticsJourneyContainer sessionId="s1" />);
+
+    const header = await screen.findByTestId("analytics-journey-attribution");
+    expect(header).toHaveTextContent("linkedin");
+    expect(header).toHaveTextContent("analytics.admin.consented");
+  });
+
+  it("lists the visitor's other sessions, excluding the current one", async () => {
+    render(<AnalyticsJourneyContainer sessionId="s1" />);
+
+    await waitFor(() =>
+      expect(AnalyticsAdminService.getSessions).toHaveBeenCalledWith(
+        expect.objectContaining({ visitorId: "visitor-0000-0000-abc123", section: "all" }),
+      ),
+    );
+    expect(await screen.findByTestId("analytics-session-link-s9")).toHaveAttribute(
+      "href",
+      "/administration/analytics/sessions/s9",
+    );
+    expect(screen.queryByTestId("analytics-session-link-s1")).not.toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,117 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { configureI18n } from "../../../../i18n";
+import { AnalyticsAdminService } from "../../data/AnalyticsAdminService";
+import { AnalyticsAdminPageContainer } from "../AnalyticsAdminPageContainer";
+import { AnalyticsJourneyPageContainer } from "../AnalyticsJourneyPageContainer";
+
+vi.mock("../../data/AnalyticsAdminService", () => ({
+  AnalyticsAdminService: {
+    getSummary: vi.fn(),
+    getTimeline: vi.fn(),
+    getBreakdown: vi.fn(),
+    getSessions: vi.fn(),
+    getSession: vi.fn(),
+    getSessionPageViews: vi.fn(),
+    next: vi.fn(),
+  },
+}));
+
+// The real page chrome needs the whole app shell (header, sidebar, navigation
+// contexts); the page content is what is under test here.
+vi.mock("../../../../components", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../../../components")>();
+  return {
+    ...actual,
+    RoundPageContainer: ({ children }: { children?: React.ReactNode }) => <div>{children}</div>,
+  };
+});
+
+beforeAll(() => {
+  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, startedAt: string) =>
+  ({
+    id,
+    visitorId: "visitor-0000-0000-abc123",
+    consented: true,
+    startedAt: new Date(startedAt),
+    lastSeenAt: new Date(startedAt),
+    pageViews: 3,
+    section: "public",
+    landingRoute: "/pricing",
+    referrerHost: "linkedin.com",
+    utmSource: "linkedin",
+    deviceType: "desktop",
+  }) as any;
+
+describe("AnalyticsAdminPageContainer", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(AnalyticsAdminService.getSummary).mockResolvedValue([]);
+    vi.mocked(AnalyticsAdminService.getTimeline).mockResolvedValue([]);
+    vi.mocked(AnalyticsAdminService.getBreakdown).mockResolvedValue([]);
+    vi.mocked(AnalyticsAdminService.getSessions).mockResolvedValue([session("s1", "2026-10-01T10:00:00.000Z")]);
+  });
+
+  it("loads the dashboard and links each session under the given sessionPageUrl", async () => {
+    render(<AnalyticsAdminPageContainer pageUrl="/admin/stats" sessionPageUrl="/admin/stats/sessions" />);
+
+    expect(await screen.findByTestId("analytics-session-link-s1")).toHaveAttribute("href", "/admin/stats/sessions/s1");
+    expect(AnalyticsAdminService.getSummary).toHaveBeenCalledTimes(1);
+  });
+
+  it("falls back to the provider's default routes", async () => {
+    render(<AnalyticsAdminPageContainer />);
+
+    expect(await screen.findByTestId("analytics-session-link-s1")).toHaveAttribute(
+      "href",
+      "/administration/analytics/sessions/s1",
+    );
+  });
+});
+
+describe("AnalyticsJourneyPageContainer", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(AnalyticsAdminService.getSession).mockResolvedValue(session("s1", "2026-10-01T10:00:00.000Z"));
+    vi.mocked(AnalyticsAdminService.getSessionPageViews).mockResolvedValue([]);
+    vi.mocked(AnalyticsAdminService.getSessions).mockResolvedValue([
+      session("s1", "2026-10-01T10:00:00.000Z"),
+      session("s9", "2026-09-20T08:00:00.000Z"),
+    ]);
+  });
+
+  it("loads the given session and links the other sessions under pageUrl", async () => {
+    render(<AnalyticsJourneyPageContainer sessionId="s1" pageUrl="/admin/stats" />);
+
+    await waitFor(() => expect(AnalyticsAdminService.getSession).toHaveBeenCalledWith({ id: "s1" }));
+    expect(await screen.findByTestId("analytics-session-link-s9")).toHaveAttribute("href", "/admin/stats/sessions/s9");
+  });
+});