@carlonicora/nextjs-jsonapi 3.24.2 → 3.26.0

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

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

@@ -0,0 +1,56 @@
+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 { AnalyticsEventInput } from "../analytics.types";
+import { AnalyticsService } from "../AnalyticsService";
+
+const moduleFactory: ModuleFactory = (params) =>
+  ({ pageUrl: params.pageUrl, name: params.name, model: params.model }) as ModuleWithPermissions;
+
+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;
+  input?: unknown;
+  suppressGlobalError?: boolean;
+};
+
+const input: AnalyticsEventInput = { id: "e1", path: "/pricing", section: "public", utmSource: "linkedin" };
+
+describe("AnalyticsService.track", () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it("posts the input to Modules.AnalyticsEvent with the global error handler suppressed", async () => {
+    const spy = vi.spyOn(AbstractService as any, "callApi").mockResolvedValue({});
+
+    await AnalyticsService.track(input);
+
+    const call = spy.mock.calls[0][0] as CallApiParams;
+    expect(call.type).toBe(ModuleRegistry.get("AnalyticsEvent" as any));
+    expect(call.method).toBe("POST");
+    expect(call.endpoint).toBe("analytics/events");
+    expect(call.input).toBe(input);
+    expect(call.suppressGlobalError).toBe(true);
+  });
+
+  it("resolves even when callApi rejects — a lost page view never breaks the page", async () => {
+    vi.spyOn(AbstractService as any, "callApi").mockRejectedValue(new Error("network down"));
+
+    await expect(AnalyticsService.track(input)).resolves.toBeUndefined();
+  });
+});