@carlonicora/nextjs-jsonapi 6.18.0 → 6.20.0

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

@@ -0,0 +1,224 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { useTheme } from "next-themes";
+import { useMemo } from "react";
+import { CartesianGrid, Line, LineChart, XAxis, YAxis } from "recharts";
+import { ChartConfig, ChartContainer, ChartTooltip, ChartTooltipContent } from "../../../shadcnui";
+import { useUsageFormatters } from "../../tokenusage/lib/formatters";
+import { ChartMode, seriesColor } from "../../tokenusage/lib/palette";
+import type { AnalyticsDailyUniqueTimelineInterface } from "../data/analytics-daily-unique-timeline.interface";
+
+type DailyUniquesMetric = "visitors" | "users";
+
+type AnalyticsDailyUniquesChartProps = {
+  rows: AnalyticsDailyUniqueTimelineInterface[];
+  metric: DailyUniquesMetric;
+  className?: string;
+};
+
+/** One chart entry per row. */
+export type DailyUniquesEntry = {
+  day: string;
+  /** The row's value: null = unknown for that day. */
+  value: number | null;
+  /** The solid line. Null where the line has a gap or the dotted segment takes over. */
+  line: number | null;
+  /** The dotted yesterday-to-today segment; null everywhere else. */
+  todayLine: number | null;
+  isToday: boolean;
+};
+
+/**
+ * The palette slot of each metric: visitors keep the "Visitors" colour of the
+ * "Over time" chart (slot 0); users skip slot 1, which is page views there.
+ */
+const METRIC_SLOT: Record<DailyUniquesMetric, number> = { visitors: 0, users: 2 };
+
+/** Dot radius, solid and hollow alike. */
+const DOT_RADIUS = 4;
+
+/**
+ * The day key, derived with UTC getters — the same helper as
+ * `AnalyticsTimelineChart`. The backend field is `type: "date"`, which the model
+ * parses to UTC midnight, so local getters would shift it a day west of 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}`;
+};
+
+/**
+ * Splits the rows into the solid line and the dotted "today" segment.
+ *
+ * Today (UTC) is still counting, so when the last row is today and both today
+ * and yesterday have values, the last segment moves to `todayLine` (drawn
+ * dotted) and the solid line stops at yesterday. A null value stays null in
+ * both series, which recharts draws as a gap (`connectNulls={false}`).
+ */
+export function buildDailyUniquesSeries(
+  rows: AnalyticsDailyUniqueTimelineInterface[],
+  metric: DailyUniquesMetric,
+  todayKey: string,
+): DailyUniquesEntry[] {
+  const entries: DailyUniquesEntry[] = rows.map((row) => {
+    const day = bucketKey(row.day);
+    const value = row[metric] ?? null;
+    return { day, value, line: value, todayLine: null, isToday: day === todayKey };
+  });
+
+  const last = entries.length - 1;
+  if (last >= 1 && entries[last].isToday && entries[last].value !== null && entries[last - 1].value !== null) {
+    entries[last - 1].todayLine = entries[last - 1].value;
+    entries[last].todayLine = entries[last].value;
+    entries[last].line = null;
+  }
+
+  return entries;
+}
+
+type DotProps = { cx?: number | null; cy?: number | null; index?: number; payload?: DailyUniquesEntry };
+
+/**
+ * Unique visitors or unique users per day, as a line.
+ *
+ * Always daily and never filtered by section: one row per day of the picked
+ * range, as the backend returns it. One series, so no legend — the card title
+ * names it. Colour does an identity job (the same metric keeps the same colour
+ * as in the "Over time" chart); the tooltip carries the value as text.
+ */
+export function AnalyticsDailyUniquesChart({ rows, metric, className }: AnalyticsDailyUniquesChartProps) {
+  const t = useTranslations();
+  const { compact, bucketDate, decimal } = useUsageFormatters();
+  const { resolvedTheme } = useTheme();
+  const mode: ChartMode = resolvedTheme === "dark" ? "dark" : "light";
+  const color = seriesColor(METRIC_SLOT[metric], mode);
+
+  const chartData = useMemo(() => buildDailyUniquesSeries(rows, metric, bucketKey(new Date())), [rows, metric]);
+
+  const points = useMemo(() => chartData.map(({ day, value }) => ({ day, value })), [chartData]);
+
+  const seriesLabel = t(`analytics.admin.daily_uniques.${metric}`);
+
+  const chartConfig = useMemo(() => ({ line: { label: seriesLabel, color } }) as ChartConfig, [seriesLabel, color]);
+
+  if (chartData.length === 0) {
+    return (
+      <p className={className ? `text-muted-foreground text-xs ${className}` : "text-muted-foreground text-xs"}>
+        {t("analytics.admin.no_data")}
+      </p>
+    );
+  }
+
+  /** Small solid dots; today's point is hollow (still counting). */
+  const renderDot = ({ cx, cy, index, payload }: DotProps) => {
+    if (cx == null || cy == null || payload?.value == null) return <g key={`dot-${index}`} />;
+    return (
+      <circle
+        key={`dot-${index}`}
+        cx={cx}
+        cy={cy}
+        r={DOT_RADIUS}
+        fill={payload.isToday ? "var(--card)" : color}
+        stroke={payload.isToday ? color : "var(--card)"}
+        strokeWidth={2}
+      />
+    );
+  };
+
+  /** The dotted segment draws only today's hollow dot; yesterday's is on the solid line. */
+  const renderTodayDot = (props: DotProps) =>
+    props.payload?.isToday ? renderDot(props) : <g key={`today-dot-${props.index}`} />;
+
+  return (
+    // The chart is a coordinate system, not prose: it stays an LTR island.
+    // rtl-ok: deliberate LTR island (chart)
+    <div className={className} dir="ltr">
+      {/* The points, exposed for assertions and for screen readers that would
+          otherwise get nothing from the SVG. */}
+      <span className="sr-only" data-testid={`analytics-daily-${metric}-data`}>
+        {JSON.stringify(points)}
+      </span>
+
+      <ChartContainer config={chartConfig} className="aspect-auto h-72 w-full">
+        <LineChart accessibilityLayer data={chartData} margin={{ top: 8, right: 16, bottom: 0, left: 0 }}>
+          <CartesianGrid vertical={false} />
+          <XAxis
+            dataKey="day"
+            tickLine={false}
+            axisLine={false}
+            tickMargin={8}
+            minTickGap={16}
+            tickFormatter={(value: string) => bucketDate(value, "day")}
+          />
+          <YAxis
+            domain={[0, "auto"]}
+            allowDecimals={false}
+            tickLine={false}
+            axisLine={false}
+            tickMargin={8}
+            width={48}
+            tickFormatter={(value: number) => compact(value)}
+          />
+          <ChartTooltip
+            // Keep a null day in the payload so the tooltip can say "no data".
+            filterNull={false}
+            content={
+              <ChartTooltipContent
+                labelFormatter={(value, payload) => {
+                  const entry = payload?.[0]?.payload as DailyUniquesEntry | undefined;
+                  return (
+                    <>
+                      {bucketDate(String(value), "day")}
+                      {entry?.isToday && (
+                        <div className="text-muted-foreground text-xs">{t("analytics.admin.daily_uniques.today")}</div>
+                      )}
+                    </>
+                  );
+                }}
+                // The row's own value, not the hovered series': on today's
+                // point the solid line is null while the dotted one holds it.
+                formatter={(_value, _name, item) => {
+                  const entry = item.payload as DailyUniquesEntry;
+                  return (
+                    <div className="flex flex-1 justify-between gap-4 leading-none">
+                      <span className="text-muted-foreground">{seriesLabel}</span>
+                      <span className="text-xs tabular-nums text-end">
+                        {entry.value === null ? t("analytics.admin.daily_uniques.no_data") : decimal(entry.value, 0)}
+                      </span>
+                    </div>
+                  );
+                }}
+              />
+            }
+          />
+          <Line
+            dataKey="line"
+            type="linear"
+            stroke={color}
+            strokeWidth={2}
+            connectNulls={false}
+            dot={renderDot}
+            activeDot={{ r: DOT_RADIUS, strokeWidth: 2, stroke: "var(--card)" }}
+            isAnimationActive={false}
+          />
+          <Line
+            dataKey="todayLine"
+            type="linear"
+            stroke={color}
+            strokeWidth={2}
+            strokeDasharray="2 5"
+            connectNulls={false}
+            dot={renderTodayDot}
+            activeDot={false}
+            tooltipType="none"
+            legendType="none"
+            isAnimationActive={false}
+          />
+        </LineChart>
+      </ChartContainer>
+    </div>
+  );
+}

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

@@ -0,0 +1,88 @@
+import { render, screen } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { AnalyticsDailyUniquesChart, buildDailyUniquesSeries } from "../AnalyticsDailyUniquesChart";
+
+const row = (day: string, visitors: number | null, users: number | null) =>
+  ({
+    id: day,
+    day: new Date(day),
+    visitors,
+    users,
+  }) as any;
+
+const ROWS = [row("2026-11-01", 5, 2), row("2026-11-02", 3, null), row("2026-11-03", 0, 0), row("2026-11-04", 4, 1)];
+
+describe("AnalyticsDailyUniquesChart", () => {
+  beforeEach(() => {
+    vi.useFakeTimers({ toFake: ["Date"] });
+    vi.setSystemTime(new Date("2026-11-04T10:00:00Z"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("exposes one visitors point per row, in order", () => {
+    render(<AnalyticsDailyUniquesChart rows={ROWS} metric="visitors" />);
+
+    const data = JSON.parse(screen.getByTestId("analytics-daily-visitors-data").textContent!);
+    expect(data).toEqual([
+      { day: "2026-11-01", value: 5 },
+      { day: "2026-11-02", value: 3 },
+      { day: "2026-11-03", value: 0 },
+      { day: "2026-11-04", value: 4 },
+    ]);
+  });
+
+  it("exposes one users point per row, keeping null as null and 0 as 0", () => {
+    render(<AnalyticsDailyUniquesChart rows={ROWS} metric="users" />);
+
+    const data = JSON.parse(screen.getByTestId("analytics-daily-users-data").textContent!);
+    expect(data).toEqual([
+      { day: "2026-11-01", value: 2 },
+      { day: "2026-11-02", value: null },
+      { day: "2026-11-03", value: 0 },
+      { day: "2026-11-04", value: 1 },
+    ]);
+  });
+
+  it("renders the empty state without a data node when there are no rows", () => {
+    render(<AnalyticsDailyUniquesChart rows={[]} metric="visitors" />);
+
+    expect(screen.queryByTestId("analytics-daily-visitors-data")).not.toBeInTheDocument();
+    expect(screen.getByText("analytics.admin.no_data")).toBeInTheDocument();
+  });
+
+  it("draws the chart, not the empty state, when every day is zero", () => {
+    render(<AnalyticsDailyUniquesChart rows={[row("2026-11-03", 0, 0), row("2026-11-04", 0, 0)]} metric="users" />);
+
+    expect(screen.getByTestId("analytics-daily-users-data")).toBeInTheDocument();
+    expect(screen.queryByText("analytics.admin.no_data")).not.toBeInTheDocument();
+  });
+});
+
+describe("buildDailyUniquesSeries", () => {
+  it("moves the yesterday-to-today segment onto the dotted series when both days have values", () => {
+    const series = buildDailyUniquesSeries(ROWS, "visitors", "2026-11-04");
+
+    expect(series.map((entry) => entry.line)).toEqual([5, 3, 0, null]);
+    expect(series.map((entry) => entry.todayLine)).toEqual([null, null, 0, 4]);
+    expect(series.map((entry) => entry.isToday)).toEqual([false, false, false, true]);
+  });
+
+  it("draws no dotted segment when yesterday is unknown, and leaves null days as gaps", () => {
+    const rows = [row("2026-11-03", 2, null), row("2026-11-04", 4, 1)];
+    const series = buildDailyUniquesSeries(rows, "users", "2026-11-04");
+
+    expect(series.map((entry) => entry.line)).toEqual([null, 1]);
+    expect(series.map((entry) => entry.todayLine)).toEqual([null, null]);
+    expect(series[1].isToday).toBe(true);
+  });
+
+  it("draws no dotted segment when the range ends before today", () => {
+    const series = buildDailyUniquesSeries(ROWS.slice(0, 3), "visitors", "2026-11-04");
+
+    expect(series.map((entry) => entry.line)).toEqual([5, 3, 0]);
+    expect(series.every((entry) => entry.todayLine === null && !entry.isToday)).toBe(true);
+  });
+});

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

@@ -11,6 +11,7 @@ vi.mock("../../data/AnalyticsAdminService", () => ({
     getTimeline: vi.fn(),
     getBreakdown: vi.fn(),
     getSessions: vi.fn(),
+    getDailyUniques: vi.fn(),
     getSession: vi.fn(),
     getSessionPageViews: vi.fn(),
     next: vi.fn(),
@@ -89,6 +90,27 @@ describe("AnalyticsAdminPageContainer", () => {
     vi.mocked(AnalyticsAdminService.getTimeline).mockResolvedValue([]);
     vi.mocked(AnalyticsAdminService.getBreakdown).mockResolvedValue([]);
     vi.mocked(AnalyticsAdminService.getSessions).mockResolvedValue([session("s1", "2026-10-01T10:00:00.000Z")]);
+    vi.mocked(AnalyticsAdminService.getDailyUniques).mockResolvedValue([]);
+  });
+
+  it("renders the daily visitors and users cards between Over time and Breakdown", async () => {
+    render(<AnalyticsAdminPageContainer />);
+
+    const visitorsCard = await screen.findByTestId("analytics-daily-visitors-card");
+    const usersCard = screen.getByTestId("analytics-daily-users-card");
+    expect(visitorsCard).toHaveTextContent("analytics.admin.panels.daily_visitors");
+    expect(usersCard).toHaveTextContent("analytics.admin.panels.daily_users");
+
+    const overTime = screen.getByText("analytics.admin.panels.over_time");
+    const breakdown = screen.getByText("analytics.admin.panels.breakdown");
+    const follows = (a: Node, b: Node) => Boolean(a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING);
+
+    expect(follows(overTime, visitorsCard)).toBe(true);
+    expect(follows(visitorsCard, usersCard)).toBe(true);
+    expect(follows(usersCard, breakdown)).toBe(true);
+    expect(overTime.closest('[data-slot="card"]')?.nextElementSibling).toBe(visitorsCard);
+    expect(visitorsCard.nextElementSibling).toBe(usersCard);
+    expect(usersCard.nextElementSibling).toBe(breakdown.closest('[data-slot="card"]'));
   });
 
   it("loads the dashboard and links each session under the given sessionPageUrl", async () => {

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

@@ -2,11 +2,12 @@
 
 import { useTranslations } from "next-intl";
 import { createContext, ReactNode, useCallback, useContext, useEffect, useMemo, useState } from "react";
-import { Modules, NextRef } from "../../../core";
+import { formatLocalDate, Modules, NextRef } from "../../../core";
 import { SharedProvider } from "../../../contexts";
 import { BreadcrumbItemData } from "../../../interfaces";
 import { AnalyticsAdminFilterBar } from "../components/AnalyticsAdminFilterBar";
 import type { AnalyticsBreakdownInterface } from "../data/analytics-breakdown.interface";
+import type { AnalyticsDailyUniqueTimelineInterface } from "../data/analytics-daily-unique-timeline.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";
@@ -51,6 +52,8 @@ export interface AnalyticsAdminContextType {
   timeline: AnalyticsTimelineInterface[];
   breakdowns: Record<AnalyticsDimension, AnalyticsBreakdownInterface[]>;
   sessions: AnalyticsSessionInterface[];
+  /** One row per day of the range: unique visitors and users, never filtered by section. */
+  dailyUniques: AnalyticsDailyUniqueTimelineInterface[];
   filters: AnalyticsAdminFilterState;
   /** Merges a partial patch into the current filters; every key is optional. */
   setFilters: (next: Partial<AnalyticsAdminFilterState>) => void;
@@ -120,6 +123,7 @@ export const AnalyticsAdminProvider = ({
   const [breakdowns, setBreakdowns] =
     useState<Record<AnalyticsDimension, AnalyticsBreakdownInterface[]>>(EMPTY_BREAKDOWNS);
   const [sessions, setSessions] = useState<AnalyticsSessionInterface[]>([]);
+  const [dailyUniques, setDailyUniques] = useState<AnalyticsDailyUniqueTimelineInterface[]>([]);
   /** 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);
@@ -149,8 +153,14 @@ export const AnalyticsAdminProvider = ({
         ),
       ),
       AnalyticsAdminService.getSessions({ ...base, next: sessionsNext }),
+      // The local calendar days the admin picked: the picker emits local-midnight
+      // instants, so slicing the UTC instant would shift the range a day east of UTC.
+      AnalyticsAdminService.getDailyUniques({
+        fromDate: formatLocalDate(new Date(from)),
+        toDate: formatLocalDate(new Date(to)),
+      }),
     ])
-      .then(([nextSummary, nextTimeline, nextBreakdowns, nextSessions]) => {
+      .then(([nextSummary, nextTimeline, nextBreakdowns, nextSessions, nextDailyUniques]) => {
         if (cancelled) return;
         setSummary(nextSummary ?? []);
         setTimeline(nextTimeline ?? []);
@@ -161,6 +171,7 @@ export const AnalyticsAdminProvider = ({
         );
         setSessions(nextSessions ?? []);
         setSessionsNextPage(sessionsNext.next);
+        setDailyUniques(nextDailyUniques ?? []);
       })
       .catch((err) => {
         if (cancelled) return;
@@ -225,6 +236,7 @@ export const AnalyticsAdminProvider = ({
       timeline,
       breakdowns,
       sessions,
+      dailyUniques,
       filters,
       setFilters,
       loadMoreSessions,
@@ -238,6 +250,7 @@ export const AnalyticsAdminProvider = ({
       timeline,
       breakdowns,
       sessions,
+      dailyUniques,
       filters,
       setFilters,
       loadMoreSessions,

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

@@ -1,6 +1,7 @@
 import { act, fireEvent, render, screen, waitFor } from "@testing-library/react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { useSharedContext } from "../../../../contexts/SharedContext";
+import { formatLocalDate } from "../../../../core";
 import { AnalyticsAdminService } from "../../data/AnalyticsAdminService";
 import { AnalyticsAdminProvider, useAnalyticsAdmin } from "../AnalyticsAdminContext";
 
@@ -10,6 +11,7 @@ vi.mock("../../data/AnalyticsAdminService", () => ({
     getTimeline: vi.fn(async () => []),
     getBreakdown: vi.fn(async () => []),
     getSessions: vi.fn(async () => []),
+    getDailyUniques: vi.fn(async () => []),
     next: vi.fn(async () => []),
   },
 }));
@@ -31,6 +33,8 @@ function Probe() {
       <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>
+      <span data-testid="daily-uniques">{ctx.dailyUniques.map((d) => d.id).join(",")}</span>
+      <span data-testid="error">{ctx.error ?? ""}</span>
       <button type="button" onClick={() => ctx.setFilters({ section: "app" })}>
         app
       </button>
@@ -86,6 +90,40 @@ describe("AnalyticsAdminContext", () => {
     expect(breakdowns).toHaveLength(6);
   });
 
+  it("requests the daily uniques once with the local calendar dates of the range and exposes them", async () => {
+    vi.mocked(AnalyticsAdminService.getDailyUniques).mockResolvedValueOnce([
+      { id: "2026-11-03" },
+      { id: "2026-11-04" },
+    ] as any);
+
+    render(
+      <AnalyticsAdminProvider>
+        <Probe />
+      </AnalyticsAdminProvider>,
+    );
+
+    await waitFor(() => expect(screen.getByTestId("daily-uniques")).toHaveTextContent("2026-11-03,2026-11-04"));
+
+    expect(AnalyticsAdminService.getDailyUniques).toHaveBeenCalledTimes(1);
+    const { from, to } = vi.mocked(AnalyticsAdminService.getSummary).mock.calls[0][0];
+    expect(AnalyticsAdminService.getDailyUniques).toHaveBeenCalledWith({
+      fromDate: formatLocalDate(new Date(from)),
+      toDate: formatLocalDate(new Date(to)),
+    });
+  });
+
+  it("sets the page error when the daily uniques request fails", async () => {
+    vi.mocked(AnalyticsAdminService.getDailyUniques).mockRejectedValueOnce(new Error("daily uniques failed"));
+
+    render(
+      <AnalyticsAdminProvider>
+        <Probe />
+      </AnalyticsAdminProvider>,
+    );
+
+    await waitFor(() => expect(screen.getByTestId("error")).toHaveTextContent("daily uniques failed"));
+  });
+
   it("defaults to the last 30 days", async () => {
     render(
       <AnalyticsAdminProvider>

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

@@ -1,5 +1,6 @@
 import { AbstractService, EndpointCreator, HttpMethod, Modules, NextRef } from "../../../core";
 import { AnalyticsBreakdownInterface } from "./analytics-breakdown.interface";
+import { AnalyticsDailyUniqueTimelineInterface } from "./analytics-daily-unique-timeline.interface";
 import { AnalyticsPageViewInterface } from "./analytics-page-view.interface";
 import { AnalyticsSessionInterface } from "./analytics-session.interface";
 import { AnalyticsSummaryInterface } from "./analytics-summary.interface";
@@ -38,6 +39,25 @@ export class AnalyticsAdminService extends AbstractService {
     });
   }
 
+  /**
+   * One row per calendar day from fromDate to toDate (YYYY-MM-DD, local dates).
+   * Always daily and never filtered by section, so it skips withFilters.
+   */
+  static async getDailyUniques(params: {
+    fromDate: string;
+    toDate: string;
+  }): Promise<AnalyticsDailyUniqueTimelineInterface[]> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.AnalyticsDailyUniqueTimeline });
+    endpoint.addAdditionalParam("fromDate", params.fromDate);
+    endpoint.addAdditionalParam("toDate", params.toDate);
+
+    return this.callApi<AnalyticsDailyUniqueTimelineInterface[]>({
+      type: Modules.AnalyticsDailyUniqueTimeline,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+
   static async getBreakdown(
     params: AnalyticsFilters & { dimension: AnalyticsDimension; limit?: number },
   ): Promise<AnalyticsBreakdownInterface[]> {

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

@@ -114,4 +114,19 @@ describe("AnalyticsAdminService", () => {
     expect(call.method).toBe("GET");
     expect(call.endpoint).toBe("analytics/administration/sessions/s1/pageviews");
   });
+  it("getDailyUniques sends only fromDate and toDate to the daily-uniques endpoint, never the section filters", async () => {
+    const spy = callApi();
+
+    await AnalyticsAdminService.getDailyUniques({ fromDate: "2026-10-05", toDate: "2026-11-04" });
+
+    const call = firstCall(spy);
+    expect(call.type).toBe(ModuleRegistry.get("AnalyticsDailyUniqueTimeline" as any));
+    expect(call.method).toBe("GET");
+    expect(call.endpoint).toContain("analytics/administration/daily-uniques");
+    expect(call.endpoint).toContain("fromDate=2026-10-05");
+    expect(call.endpoint).toContain("toDate=2026-11-04");
+    expect(call.endpoint).not.toContain("section");
+    expect(call.endpoint).not.toMatch(/[?&]from=/);
+    expect(call.endpoint).not.toMatch(/[?&]to=/);
+  });
 });

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

@@ -7,6 +7,7 @@ import { AbstractApiData } from "../../../../core/abstracts/AbstractApiData";
 import { JsonApiHydratedDataInterface } from "../../../../core/interfaces/JsonApiHydratedDataInterface";
 import { analyticsModules } from "../../analytics.modules";
 import { AnalyticsBreakdown } from "../analytics-breakdown";
+import { AnalyticsDailyUniqueTimeline } from "../analytics-daily-unique-timeline";
 import { AnalyticsEvent } from "../analytics-event";
 import { AnalyticsPageView } from "../analytics-page-view";
 import { AnalyticsSession } from "../analytics-session";
@@ -89,6 +90,26 @@ describe("analytics models — rehydrate", () => {
     expect(m.pageViews).toBe(3);
   });
 
+  it("rehydrates a daily-unique row: the day into a UTC-midnight Date and both counts", () => {
+    const m = new AnalyticsDailyUniqueTimeline().rehydrate(hydrate({ day: "2026-11-03", visitors: 3, users: 1 }));
+    expect(m.day).toBeInstanceOf(Date);
+    expect(m.day.getTime()).toBe(new Date("2026-11-03").getTime());
+    expect(m.visitors).toBe(3);
+    expect(m.users).toBe(1);
+  });
+
+  it("rehydrates an unknown daily-unique count to null, whether sent as null or missing", () => {
+    const m = new AnalyticsDailyUniqueTimeline().rehydrate(hydrate({ day: "2026-11-03", visitors: null }));
+    expect(m.visitors).toBeNull();
+    expect(m.users).toBeNull();
+  });
+
+  it("keeps a zero daily-unique count as 0, not null", () => {
+    const m = new AnalyticsDailyUniqueTimeline().rehydrate(hydrate({ day: "2026-11-03", visitors: 0, users: 0 }));
+    expect(m.visitors).toBe(0);
+    expect(m.users).toBe(0);
+  });
+
   it("rehydrates every breakdown attribute", () => {
     const m = new AnalyticsBreakdown().rehydrate(
       hydrate({ dimension: "source", key: "linkedin", visitors: 4, sessions: 5, pageViews: 6 }),
@@ -254,6 +275,14 @@ describe("analytics models — createJsonApi", () => {
     expect(JSON.parse(JSON.stringify(doc)).data.attributes.bucket).toBe("2026-09-01");
   });
 
+  it("emits the daily-unique day as YYYY-MM-DD via formatLocalDate, never a raw Date", () => {
+    const doc = new AnalyticsDailyUniqueTimeline().createJsonApi({ id: "2026-11-03", day: new Date(2026, 10, 3) });
+    expect(doc.data.type).toBe("analytics/administration/daily-uniques");
+    expect(doc.data.id).toBe("2026-11-03");
+    expect(doc.data.attributes.day).toBe("2026-11-03");
+    expect(JSON.parse(JSON.stringify(doc)).data.attributes.day).toBe("2026-11-03");
+  });
+
   it("serialises a breakdown row", () => {
     const doc = new AnalyticsBreakdown().createJsonApi({
       id: "source|linkedin",

package/src/features/analytics/data/analytics-daily-unique-timeline.interface.ts

@@ -0,0 +1,11 @@
+import { ApiDataInterface } from "../../../core";
+
+/** One calendar day of the unique visitors / unique users charts. */
+export interface AnalyticsDailyUniqueTimelineInterface extends ApiDataInterface {
+  /** Backend declares this `type: "date"`, so it is a Date in memory. */
+  get day(): Date;
+  /** null = unknown for that day (drawn as a gap). */
+  get visitors(): number | null;
+  /** null = unknown for that day (drawn as a gap). */
+  get users(): number | null;
+}

package/src/features/analytics/data/analytics-daily-unique-timeline.ts

@@ -0,0 +1,53 @@
+import { AbstractApiData, formatLocalDate, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { AnalyticsDailyUniqueTimelineInterface } from "./analytics-daily-unique-timeline.interface";
+import { AnalyticsDailyUniqueTimelineInput } from "./analytics.types";
+
+/** One day of the daily unique visitors / users charts. A null count is an unknown day, never 0. */
+export class AnalyticsDailyUniqueTimeline extends AbstractApiData implements AnalyticsDailyUniqueTimelineInterface {
+  private _day: Date = new Date(0);
+  private _visitors: number | null = null;
+  private _users: number | null = null;
+
+  get day(): Date {
+    return this._day;
+  }
+
+  get visitors(): number | null {
+    return this._visitors;
+  }
+
+  get users(): number | null {
+    return this._users;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attrs = data.jsonApi.attributes;
+    // Wire format is "YYYY-MM-DD" (always present); the interface promises a Date.
+    this._day = new Date(attrs.day);
+    this._visitors = attrs.visitors ?? null;
+    this._users = attrs.users ?? null;
+
+    return this;
+  }
+
+  createJsonApi(data: AnalyticsDailyUniqueTimelineInput) {
+    const response: any = {
+      data: {
+        type: Modules.AnalyticsDailyUniqueTimeline.name,
+        id: data.id,
+        attributes: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    // `day` is type: "date" on the backend descriptor: formatLocalDate, never the raw Date.
+    if (data.day !== undefined) response.data.attributes.day = formatLocalDate(data.day);
+    if (data.visitors !== undefined) response.data.attributes.visitors = data.visitors;
+    if (data.users !== undefined) response.data.attributes.users = data.users;
+
+    return response;
+  }
+}

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

@@ -59,6 +59,16 @@ export type AnalyticsTimelineInput = {
   pageViews: number;
 };
 
+export type AnalyticsDailyUniqueTimelineInput = {
+  id: string;
+  /** Backend field type is "date" — emitted via formatLocalDate, never raw. */
+  day?: Date;
+  /** null = unknown for that day. */
+  visitors?: number | null;
+  /** null = unknown for that day. */
+  users?: number | null;
+};
+
 export type AnalyticsBreakdownInput = {
   id: string;
   dimension: string;