@carlonicora/nextjs-jsonapi 3.24.2 → 3.26.0

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} />;
+}

package/src/features/analytics/contexts/AnalyticsAdminContext.tsx

@@ -0,0 +1,273 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { createContext, ReactNode, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { Modules, NextRef } from "../../../core";
+import { SharedProvider } from "../../../contexts";
+import { usePageUrlGenerator } from "../../../hooks";
+import { BreadcrumbItemData } from "../../../interfaces";
+import { AnalyticsAdminFilterBar } from "../components/AnalyticsAdminFilterBar";
+import type { AnalyticsBreakdownInterface } from "../data/analytics-breakdown.interface";
+import type { AnalyticsSessionInterface } from "../data/analytics-session.interface";
+import type { AnalyticsSummaryInterface } from "../data/analytics-summary.interface";
+import type { AnalyticsTimelineInterface } from "../data/analytics-timeline.interface";
+import {
+  ANALYTICS_DIMENSIONS,
+  type AnalyticsDimension,
+  type AnalyticsGranularity,
+  type AnalyticsSection,
+} from "../data/analytics.types";
+import { AnalyticsAdminService } from "../data/AnalyticsAdminService";
+
+/**
+ * Default route the breadcrumb links back to. A host app that mounts the page
+ * elsewhere overrides it with the `pageUrl` prop — the constant stays here
+ * because the breadcrumb is built by this provider, not by the app.
+ */
+const ANALYTICS_ADMIN_PAGE_URL = "/administration/analytics";
+
+/** Default base route of the journey page each session row links to. */
+const ANALYTICS_SESSION_PAGE_URL = "/administration/analytics/sessions";
+
+/** Rows kept per breakdown tab before the repository folds the tail into "other". */
+const BREAKDOWN_LIMIT = 20;
+
+/** The window the page opens on, in days. */
+const DEFAULT_RANGE_DAYS = 30;
+
+const EMPTY_BREAKDOWNS: Record<AnalyticsDimension, AnalyticsBreakdownInterface[]> = {
+  source: [],
+  medium: [],
+  campaign: [],
+  referrer: [],
+  route: [],
+  landing: [],
+};
+
+export type AnalyticsAdminFilterState = {
+  /** ISO 8601 instant. */
+  from: string;
+  /** ISO 8601 instant. */
+  to: string;
+  section: AnalyticsSection;
+  granularity: AnalyticsGranularity;
+};
+
+export interface AnalyticsAdminContextType {
+  /** The six summary rows: {public, app, total} × {current, previous}. */
+  summary: AnalyticsSummaryInterface[];
+  timeline: AnalyticsTimelineInterface[];
+  breakdowns: Record<AnalyticsDimension, AnalyticsBreakdownInterface[]>;
+  sessions: AnalyticsSessionInterface[];
+  filters: AnalyticsAdminFilterState;
+  /** Merges a partial patch into the current filters; every key is optional. */
+  setFilters: (next: Partial<AnalyticsAdminFilterState>) => void;
+  /** Appends the next page of sessions; a no-op when there is none. */
+  loadMoreSessions: () => Promise<void>;
+  hasMoreSessions: boolean;
+  /** Base route of the journey page, as passed to the provider. */
+  sessionPageUrl: string;
+  isLoading: boolean;
+  error: string | null;
+}
+
+const AnalyticsAdminContext = createContext<AnalyticsAdminContextType | undefined>(undefined);
+
+/** The last 30 days up to now, which is the window the page opens on. */
+function defaultRange(): { from: string; to: string } {
+  const now = new Date();
+  const start = new Date(now.getTime() - DEFAULT_RANGE_DAYS * 24 * 60 * 60 * 1000);
+  return { from: start.toISOString(), to: now.toISOString() };
+}
+
+type AnalyticsAdminProviderProps = {
+  children: ReactNode;
+  /** ISO 8601 instant. Defaults to 30 days ago. */
+  initialFrom?: string;
+  /** ISO 8601 instant. Defaults to now. */
+  initialTo?: string;
+  /** Route the breadcrumb links back to. */
+  pageUrl?: string;
+  /** Base route of the journey page each session row links to. */
+  sessionPageUrl?: string;
+};
+
+/**
+ * Owns every filter the administrative analytics page reads, fetches the panels
+ * behind it, and publishes the filter bar into the page title bar.
+ *
+ * The filter bar is rendered into `title.functions` here — NOT in the container —
+ * because `RoundPageContainer`'s title bar reads `title.functions` from
+ * `SharedContext`, and a descendant cannot inject nodes into an ancestor's
+ * provider value. That is why the filter state lives at this level.
+ */
+export const AnalyticsAdminProvider = ({
+  children,
+  initialFrom,
+  initialTo,
+  pageUrl = ANALYTICS_ADMIN_PAGE_URL,
+  sessionPageUrl = ANALYTICS_SESSION_PAGE_URL,
+}: AnalyticsAdminProviderProps) => {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+
+  const [filters, setFilterState] = useState<AnalyticsAdminFilterState>(() => {
+    const range = defaultRange();
+    return {
+      from: initialFrom ?? range.from,
+      to: initialTo ?? range.to,
+      section: "all",
+      granularity: "day",
+    };
+  });
+
+  const [summary, setSummary] = useState<AnalyticsSummaryInterface[]>([]);
+  const [timeline, setTimeline] = useState<AnalyticsTimelineInterface[]>([]);
+  const [breakdowns, setBreakdowns] =
+    useState<Record<AnalyticsDimension, AnalyticsBreakdownInterface[]>>(EMPTY_BREAKDOWNS);
+  const [sessions, setSessions] = useState<AnalyticsSessionInterface[]>([]);
+  /** The cursor URL of the next sessions page, as the API returned it. */
+  const [sessionsNextPage, setSessionsNextPage] = useState<string | undefined>(undefined);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const { from, to, section, granularity } = filters;
+
+  useEffect(() => {
+    // `cancelled` is the out-of-order guard: a filter change fires a new request
+    // while the previous one is still in flight, and without this flag the slower
+    // (older) response would land last and overwrite the fresher state.
+    let cancelled = false;
+
+    setIsLoading(true);
+    setError(null);
+
+    const base = { from, to, section };
+    // callApi writes the response's next-page link into this ref.
+    const sessionsNext: NextRef = {};
+
+    Promise.all([
+      AnalyticsAdminService.getSummary(base),
+      AnalyticsAdminService.getTimeline({ ...base, granularity }),
+      Promise.all(
+        ANALYTICS_DIMENSIONS.map((dimension) =>
+          AnalyticsAdminService.getBreakdown({ ...base, dimension, limit: BREAKDOWN_LIMIT }),
+        ),
+      ),
+      AnalyticsAdminService.getSessions({ ...base, next: sessionsNext }),
+    ])
+      .then(([nextSummary, nextTimeline, nextBreakdowns, nextSessions]) => {
+        if (cancelled) return;
+        setSummary(nextSummary ?? []);
+        setTimeline(nextTimeline ?? []);
+        setBreakdowns(
+          Object.fromEntries(
+            ANALYTICS_DIMENSIONS.map((dimension, index) => [dimension, nextBreakdowns[index] ?? []]),
+          ) as Record<AnalyticsDimension, AnalyticsBreakdownInterface[]>,
+        );
+        setSessions(nextSessions ?? []);
+        setSessionsNextPage(sessionsNext.next);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        console.error("Failed to load analytics:", err);
+        setError(err instanceof Error ? err.message : String(err));
+      })
+      .finally(() => {
+        if (cancelled) return;
+        setIsLoading(false);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [from, to, section, granularity]);
+
+  const setFilters = useCallback((next: Partial<AnalyticsAdminFilterState>) => {
+    setFilterState((prev) => ({ ...prev, ...next }));
+  }, []);
+
+  const loadMoreSessions = useCallback(async () => {
+    if (!sessionsNextPage) return;
+
+    const sessionsNext: NextRef = {};
+    try {
+      const nextSessions = await AnalyticsAdminService.next<AnalyticsSessionInterface[]>({
+        type: Modules.AnalyticsSession,
+        endpoint: sessionsNextPage,
+        next: sessionsNext,
+      });
+      setSessions((prev) => [...prev, ...(nextSessions ?? [])]);
+      setSessionsNextPage(sessionsNext.next);
+    } catch (err) {
+      console.error("Failed to load more analytics sessions:", err);
+      setError(err instanceof Error ? err.message : String(err));
+    }
+  }, [sessionsNextPage]);
+
+  const breadcrumb = (): BreadcrumbItemData[] => [
+    {
+      name: t("analytics.admin.title"),
+      href: generateUrl({ page: pageUrl }),
+    },
+  ];
+
+  const title = () => ({
+    type: t("analytics.admin.title"),
+    functions: (
+      <AnalyticsAdminFilterBar
+        key="analyticsAdminFilterBar"
+        from={from}
+        to={to}
+        section={section}
+        granularity={granularity}
+        onChange={setFilters}
+      />
+    ),
+  });
+
+  const hasMoreSessions = Boolean(sessionsNextPage);
+
+  const contextValue = useMemo<AnalyticsAdminContextType>(
+    () => ({
+      summary,
+      timeline,
+      breakdowns,
+      sessions,
+      filters,
+      setFilters,
+      loadMoreSessions,
+      hasMoreSessions,
+      sessionPageUrl,
+      isLoading,
+      error,
+    }),
+    [
+      summary,
+      timeline,
+      breakdowns,
+      sessions,
+      filters,
+      setFilters,
+      loadMoreSessions,
+      hasMoreSessions,
+      sessionPageUrl,
+      isLoading,
+      error,
+    ],
+  );
+
+  return (
+    <SharedProvider value={{ breadcrumbs: breadcrumb(), title: title() }}>
+      <AnalyticsAdminContext.Provider value={contextValue}>{children}</AnalyticsAdminContext.Provider>
+    </SharedProvider>
+  );
+};
+
+export const useAnalyticsAdmin = (): AnalyticsAdminContextType => {
+  const ctx = useContext(AnalyticsAdminContext);
+  if (!ctx) {
+    throw new Error("useAnalyticsAdmin() called outside <AnalyticsAdminProvider>.");
+  }
+  return ctx;
+};