@carlonicora/nextjs-jsonapi 3.24.2 → 3.25.0

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

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

@@ -0,0 +1,140 @@
+import { act, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { AnalyticsAdminService } from "../../data/AnalyticsAdminService";
+import { AnalyticsAdminProvider, useAnalyticsAdmin } from "../AnalyticsAdminContext";
+
+vi.mock("../../data/AnalyticsAdminService", () => ({
+  AnalyticsAdminService: {
+    getSummary: vi.fn(async () => []),
+    getTimeline: vi.fn(async () => []),
+    getBreakdown: vi.fn(async () => []),
+    getSessions: vi.fn(async () => []),
+    next: vi.fn(async () => []),
+  },
+}));
+
+// The registry throws for modules nobody registered; the provider only needs
+// the sessions module as the `type` of the load-more request.
+vi.mock("../../../../core", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../../../core")>();
+  return {
+    ...actual,
+    Modules: { AnalyticsSession: { name: "analytics/administration/sessions" } },
+  };
+});
+
+function Probe() {
+  const ctx = useAnalyticsAdmin();
+  return (
+    <div>
+      <span data-testid="sessions">{ctx.sessions.map((s) => s.id).join(",")}</span>
+      <span data-testid="has-more">{String(ctx.hasMoreSessions)}</span>
+      <span data-testid="section">{ctx.filters.section}</span>
+      <button type="button" onClick={() => ctx.setFilters({ section: "app" })}>
+        app
+      </button>
+      <button type="button" onClick={() => void ctx.loadMoreSessions()}>
+        more
+      </button>
+    </div>
+  );
+}
+
+describe("AnalyticsAdminContext", () => {
+  // The mocked service is module-level, so its call counts survive across tests.
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("throws when used outside its provider", () => {
+    expect(() => render(<Probe />)).toThrow();
+  });
+
+  it("requests every panel on mount: summary, timeline, one breakdown per dimension and the sessions", async () => {
+    render(
+      <AnalyticsAdminProvider>
+        <Probe />
+      </AnalyticsAdminProvider>,
+    );
+
+    await waitFor(() => expect(AnalyticsAdminService.getSessions).toHaveBeenCalledTimes(1));
+
+    expect(AnalyticsAdminService.getSummary).toHaveBeenCalledTimes(1);
+    expect(AnalyticsAdminService.getTimeline).toHaveBeenCalledWith(
+      expect.objectContaining({ section: "all", granularity: "day" }),
+    );
+
+    const breakdowns = vi
+      .mocked(AnalyticsAdminService.getBreakdown)
+      .mock.calls.map(([args]) => [args.dimension, args.limit]);
+    expect(breakdowns).toEqual(
+      expect.arrayContaining([
+        ["source", 20],
+        ["medium", 20],
+        ["campaign", 20],
+        ["referrer", 20],
+        ["route", 20],
+        ["landing", 20],
+      ]),
+    );
+    expect(breakdowns).toHaveLength(6);
+  });
+
+  it("defaults to the last 30 days", async () => {
+    render(
+      <AnalyticsAdminProvider>
+        <Probe />
+      </AnalyticsAdminProvider>,
+    );
+
+    await waitFor(() => expect(AnalyticsAdminService.getSummary).toHaveBeenCalled());
+
+    const { from, to } = vi.mocked(AnalyticsAdminService.getSummary).mock.calls[0][0];
+    const days = (Date.parse(to) - Date.parse(from)) / (24 * 60 * 60 * 1000);
+    expect(Math.round(days)).toBe(30);
+  });
+
+  it("refetches when a filter changes", async () => {
+    render(
+      <AnalyticsAdminProvider>
+        <Probe />
+      </AnalyticsAdminProvider>,
+    );
+    await waitFor(() => expect(AnalyticsAdminService.getSummary).toHaveBeenCalledTimes(1));
+
+    fireEvent.click(screen.getByText("app"));
+
+    await waitFor(() => expect(AnalyticsAdminService.getSummary).toHaveBeenCalledTimes(2));
+    expect(AnalyticsAdminService.getSummary).toHaveBeenLastCalledWith(expect.objectContaining({ section: "app" }));
+    expect(screen.getByTestId("section")).toHaveTextContent("app");
+  });
+
+  it("appends the next page of sessions on loadMoreSessions", async () => {
+    vi.mocked(AnalyticsAdminService.getSessions).mockImplementationOnce(async (params: any) => {
+      params.next.next = "https://api.example.com/analytics/administration/sessions?page[cursor]=2";
+      return [{ id: "s1" }] as any;
+    });
+    vi.mocked(AnalyticsAdminService.next).mockResolvedValueOnce([{ id: "s2" }] as any);
+
+    render(
+      <AnalyticsAdminProvider>
+        <Probe />
+      </AnalyticsAdminProvider>,
+    );
+
+    await waitFor(() => expect(screen.getByTestId("sessions")).toHaveTextContent("s1"));
+    expect(screen.getByTestId("has-more")).toHaveTextContent("true");
+
+    await act(async () => {
+      fireEvent.click(screen.getByText("more"));
+    });
+
+    await waitFor(() => expect(screen.getByTestId("sessions")).toHaveTextContent("s1,s2"));
+    expect(AnalyticsAdminService.next).toHaveBeenCalledWith(
+      expect.objectContaining({
+        endpoint: "https://api.example.com/analytics/administration/sessions?page[cursor]=2",
+      }),
+    );
+    expect(screen.getByTestId("has-more")).toHaveTextContent("false");
+  });
+});

package/src/features/analytics/data/AnalyticsAdminService.ts

@@ -0,0 +1,91 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules, NextRef } from "../../../core";
+import { AnalyticsBreakdownInterface } from "./analytics-breakdown.interface";
+import { AnalyticsPageViewInterface } from "./analytics-page-view.interface";
+import { AnalyticsSessionInterface } from "./analytics-session.interface";
+import { AnalyticsSummaryInterface } from "./analytics-summary.interface";
+import { AnalyticsTimelineInterface } from "./analytics-timeline.interface";
+import { AnalyticsDimension, AnalyticsFilters, AnalyticsGranularity } from "./analytics.types";
+
+function withFilters(endpoint: EndpointCreator, filters: AnalyticsFilters): EndpointCreator {
+  endpoint.addAdditionalParam("from", filters.from);
+  endpoint.addAdditionalParam("to", filters.to);
+  endpoint.addAdditionalParam("section", filters.section);
+  return endpoint;
+}
+
+export class AnalyticsAdminService extends AbstractService {
+  /** Headline tiles: one row per window (current, previous). */
+  static async getSummary(filters: AnalyticsFilters): Promise<AnalyticsSummaryInterface[]> {
+    const endpoint = withFilters(new EndpointCreator({ endpoint: Modules.AnalyticsSummary }), filters);
+
+    return this.callApi<AnalyticsSummaryInterface[]>({
+      type: Modules.AnalyticsSummary,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+
+  static async getTimeline(
+    params: AnalyticsFilters & { granularity: AnalyticsGranularity },
+  ): Promise<AnalyticsTimelineInterface[]> {
+    const endpoint = withFilters(new EndpointCreator({ endpoint: Modules.AnalyticsTimeline }), params);
+    endpoint.addAdditionalParam("granularity", params.granularity);
+
+    return this.callApi<AnalyticsTimelineInterface[]>({
+      type: Modules.AnalyticsTimeline,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+
+  static async getBreakdown(
+    params: AnalyticsFilters & { dimension: AnalyticsDimension; limit?: number },
+  ): Promise<AnalyticsBreakdownInterface[]> {
+    const endpoint = withFilters(new EndpointCreator({ endpoint: Modules.AnalyticsBreakdown }), params);
+    endpoint.addAdditionalParam("dimension", params.dimension);
+    if (params.limit !== undefined) endpoint.addAdditionalParam("limit", String(params.limit));
+
+    return this.callApi<AnalyticsBreakdownInterface[]>({
+      type: Modules.AnalyticsBreakdown,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+
+  /** Newest sessions first, cursor-paginated through `next`. */
+  static async getSessions(
+    params: AnalyticsFilters & { visitorId?: string; userId?: string; next?: NextRef },
+  ): Promise<AnalyticsSessionInterface[]> {
+    const endpoint = withFilters(new EndpointCreator({ endpoint: Modules.AnalyticsSession }), params);
+    if (params.visitorId) endpoint.addAdditionalParam("visitorId", params.visitorId);
+    if (params.userId) endpoint.addAdditionalParam("userId", params.userId);
+
+    return this.callApi<AnalyticsSessionInterface[]>({
+      type: Modules.AnalyticsSession,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+      next: params.next,
+    });
+  }
+
+  static async getSession(params: { id: string }): Promise<AnalyticsSessionInterface> {
+    return this.callApi<AnalyticsSessionInterface>({
+      type: Modules.AnalyticsSession,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({ endpoint: Modules.AnalyticsSession, id: params.id }).generate(),
+    });
+  }
+
+  /** The journey: every page view of one session, oldest first. */
+  static async getSessionPageViews(params: { sessionId: string }): Promise<AnalyticsPageViewInterface[]> {
+    return this.callApi<AnalyticsPageViewInterface[]>({
+      type: Modules.AnalyticsPageView,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.AnalyticsSession,
+        id: params.sessionId,
+        childEndpoint: Modules.AnalyticsPageView,
+      }).generate(),
+    });
+  }
+}

package/src/features/analytics/data/AnalyticsService.ts

@@ -0,0 +1,23 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
+import { AnalyticsEventInput } from "./analytics.types";
+
+export class AnalyticsService extends AbstractService {
+  /**
+   * Posts one page view. Fire-and-forget: a lost page view must never surface
+   * an error to the visitor, so the global handler is suppressed and any
+   * rejection is logged at debug level and swallowed here.
+   */
+  static async track(input: AnalyticsEventInput): Promise<void> {
+    try {
+      await this.callApi({
+        type: Modules.AnalyticsEvent,
+        method: HttpMethod.POST,
+        endpoint: new EndpointCreator({ endpoint: Modules.AnalyticsEvent }).generate(),
+        input,
+        suppressGlobalError: true,
+      });
+    } catch (error) {
+      console.debug("Analytics event not sent", error);
+    }
+  }
+}

package/src/features/analytics/data/__tests__/AnalyticsAdminService.spec.ts

@@ -0,0 +1,117 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { AbstractService } from "../../../../core/abstracts/AbstractService";
+import { ApiRequestDataTypeInterface } from "../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { ModuleFactory, ModuleWithPermissions } from "../../../../permissions/types";
+import { analyticsModules } from "../../analytics.modules";
+import { AnalyticsAdminService } from "../AnalyticsAdminService";
+
+const moduleFactory: ModuleFactory = (params) =>
+  ({ pageUrl: params.pageUrl, name: params.name, model: params.model }) as ModuleWithPermissions;
+
+// ModuleRegistry is shared across test files in a worker, hence the
+// register-if-absent guard (same idiom as HandbookThreadService.spec.ts).
+const registerIfAbsent = (key: string, module: ApiRequestDataTypeInterface) => {
+  try {
+    ModuleRegistry.get(key as any);
+  } catch {
+    ModuleRegistry.register(key, module);
+  }
+};
+
+beforeAll(() => {
+  for (const [key, module] of Object.entries(analyticsModules(moduleFactory))) registerIfAbsent(key, module);
+});
+
+type CallApiParams = { type: ApiRequestDataTypeInterface; method: string; endpoint: string; next?: unknown };
+
+// `callApi` is a protected static on AbstractService; spying on the base class
+// intercepts every call without touching the HTTP layer.
+const callApi = () => vi.spyOn(AbstractService as any, "callApi").mockResolvedValue([]);
+const firstCall = (spy: ReturnType<typeof callApi>): CallApiParams => spy.mock.calls[0][0] as CallApiParams;
+
+const filters = { from: "2026-09-01T00:00:00.000Z", to: "2026-10-01T00:00:00.000Z", section: "public" as const };
+
+describe("AnalyticsAdminService", () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it("getSummary sends from, to and section to the summary endpoint", async () => {
+    const spy = callApi();
+
+    await AnalyticsAdminService.getSummary(filters);
+
+    const call = firstCall(spy);
+    expect(call.type).toBe(ModuleRegistry.get("AnalyticsSummary" as any));
+    expect(call.method).toBe("GET");
+    expect(call.endpoint).toBe(
+      "analytics/administration/summary?from=2026-09-01T00:00:00.000Z&to=2026-10-01T00:00:00.000Z&section=public",
+    );
+  });
+
+  it("getTimeline builds the endpoint from Modules.AnalyticsTimeline with from, to, section and granularity", async () => {
+    const spy = callApi();
+
+    await AnalyticsAdminService.getTimeline({ ...filters, granularity: "week" });
+
+    const call = firstCall(spy);
+    expect(call.type).toBe(ModuleRegistry.get("AnalyticsTimeline" as any));
+    expect(call.endpoint).toBe(
+      "analytics/administration/timeline?from=2026-09-01T00:00:00.000Z&to=2026-10-01T00:00:00.000Z&section=public&granularity=week",
+    );
+  });
+
+  it("getBreakdown adds dimension and limit", async () => {
+    const spy = callApi();
+
+    await AnalyticsAdminService.getBreakdown({ ...filters, dimension: "source", limit: 50 });
+
+    const call = firstCall(spy);
+    expect(call.type).toBe(ModuleRegistry.get("AnalyticsBreakdown" as any));
+    expect(call.endpoint).toBe(
+      "analytics/administration/breakdown?from=2026-09-01T00:00:00.000Z&to=2026-10-01T00:00:00.000Z&section=public&dimension=source&limit=50",
+    );
+  });
+
+  it("getBreakdown leaves limit out when it is not given", async () => {
+    const spy = callApi();
+
+    await AnalyticsAdminService.getBreakdown({ ...filters, dimension: "route" });
+
+    expect(firstCall(spy).endpoint).not.toContain("limit=");
+  });
+
+  it("getSessions forwards next and the visitor and user filters", async () => {
+    const spy = callApi();
+    const next = { next: "analytics/administration/sessions?page[cursor]=25" };
+
+    await AnalyticsAdminService.getSessions({ ...filters, visitorId: "v1", userId: "u1", next });
+
+    const call = firstCall(spy);
+    expect(call.type).toBe(ModuleRegistry.get("AnalyticsSession" as any));
+    expect(call.next).toBe(next);
+    expect(call.endpoint).toBe(
+      "analytics/administration/sessions?from=2026-09-01T00:00:00.000Z&to=2026-10-01T00:00:00.000Z&section=public&visitorId=v1&userId=u1",
+    );
+  });
+
+  it("getSession reads one session by id", async () => {
+    const spy = vi.spyOn(AbstractService as any, "callApi").mockResolvedValue({});
+
+    await AnalyticsAdminService.getSession({ id: "s1" });
+
+    const call = firstCall(spy);
+    expect(call.type).toBe(ModuleRegistry.get("AnalyticsSession" as any));
+    expect(call.endpoint).toBe("analytics/administration/sessions/s1");
+  });
+
+  it("getSessionPageViews uses the session endpoint with the pageviews child segment", async () => {
+    const spy = callApi();
+
+    await AnalyticsAdminService.getSessionPageViews({ sessionId: "s1" });
+
+    const call = firstCall(spy);
+    expect(call.type).toBe(ModuleRegistry.get("AnalyticsPageView" as any));
+    expect(call.method).toBe("GET");
+    expect(call.endpoint).toBe("analytics/administration/sessions/s1/pageviews");
+  });
+});