@carlonicora/nextjs-jsonapi 1.142.0 → 1.143.0

package/src/features/tokenusage/components/TokenUsageTimelineChart.tsx

@@ -0,0 +1,225 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { useTheme } from "next-themes";
+import { useMemo } from "react";
+import { Bar, BarChart, CartesianGrid, XAxis, YAxis } from "recharts";
+import {
+  ChartConfig,
+  ChartContainer,
+  ChartLegend,
+  ChartLegendContent,
+  ChartTooltip,
+  ChartTooltipContent,
+} from "../../../shadcnui";
+import { TokenUsageAdminTimelineInterface } from "../data/tokenusage-admin-timeline.interface";
+import { Metric, StackBy } from "../data/tokenusage-admin.types";
+import { operationLabel } from "../lib/operation-label";
+import { CATEGORICAL_CEILING, ChartMode, OTHER_COLOR, seriesColor } from "../lib/palette";
+
+/** The rollup series every series past the colour ceiling folds into. */
+const OTHER_SERIES = "other";
+
+type TokenUsageTimelineChartProps = {
+  rows: TokenUsageAdminTimelineInterface[];
+  metric: Metric;
+  stackBy: StackBy;
+  className?: string;
+};
+
+type TimelineBucket = { bucket: string } & Record<string, number | string>;
+
+/**
+ * The bucket key, derived with UTC getters.
+ *
+ * The backend field is `type: "date"` — a calendar day with no time — and the
+ * model parses the `YYYY-MM-DD` wire value with `new Date(...)`, which lands on
+ * UTC midnight. Reading it back with local getters would shift the bucket a day
+ * early west of UTC, so the key (and every label built from it) stays in UTC.
+ */
+const bucketKey = (date: Date): string => {
+  const y = date.getUTCFullYear();
+  const m = `${date.getUTCMonth() + 1}`.padStart(2, "0");
+  const d = `${date.getUTCDate()}`.padStart(2, "0");
+  return `${y}-${m}-${d}`;
+};
+
+const metricValue = (row: TokenUsageAdminTimelineInterface, metric: Metric): number => {
+  if (metric === "cost") return row.cost;
+  if (metric === "credits") return row.credits;
+  return row.tokensIn + row.tokensOut;
+};
+
+/**
+ * The granularity the data was bucketed at, inferred from the spacing between
+ * consecutive buckets. The backend chooses the granularity and the rows carry
+ * the consequence, so the axis reads it off the data rather than taking a prop
+ * that could disagree with what was actually fetched.
+ */
+const inferGranularity = (buckets: string[]): "day" | "week" | "month" => {
+  if (buckets.length < 2) return "day";
+
+  const dayMs = 24 * 60 * 60 * 1000;
+  let smallestGap = Number.POSITIVE_INFINITY;
+  for (let i = 1; i < buckets.length; i += 1) {
+    const gap = (Date.parse(buckets[i]) - Date.parse(buckets[i - 1])) / dayMs;
+    if (gap > 0 && gap < smallestGap) smallestGap = gap;
+  }
+
+  if (smallestGap >= 28) return "month";
+  if (smallestGap >= 7) return "week";
+  return "day";
+};
+
+const bucketFormatter = (granularity: "day" | "week" | "month"): Intl.DateTimeFormat =>
+  granularity === "month"
+    ? new Intl.DateTimeFormat("it-IT", { month: "short", year: "numeric", timeZone: "UTC" })
+    : new Intl.DateTimeFormat("it-IT", { day: "numeric", month: "short", timeZone: "UTC" });
+
+const compactNumber = new Intl.NumberFormat("it-IT", { notation: "compact", maximumFractionDigits: 1 });
+
+/**
+ * Usage over time as a stacked bar chart.
+ *
+ * Colour does an IDENTITY job here — each stacked segment is a series, not a
+ * magnitude — so it draws the fixed categorical order from `../lib/palette` and
+ * never generates or cycles a hue: series past the ceiling are summed into a
+ * single "other" segment painted in the palette's neutral.
+ *
+ * The palette's light-mode validator run carries a sub-3:1 contrast WARN on
+ * three slots, which obliges a relief channel. That is why the legend and the
+ * value-carrying tooltip below are not optional decoration: they are what makes
+ * the low-contrast fills readable.
+ */
+export function TokenUsageTimelineChart({ rows, metric, stackBy, className }: TokenUsageTimelineChartProps) {
+  const t = useTranslations();
+  const { resolvedTheme } = useTheme();
+  const mode: ChartMode = resolvedTheme === "dark" ? "dark" : "light";
+
+  const { chartData, seriesKeys } = useMemo(() => {
+    if (rows.length === 0) return { chartData: [] as TimelineBucket[], seriesKeys: [] as string[] };
+
+    // Totals per raw series decide who keeps an identity colour: the biggest
+    // seven do, everything else is summed into "other". Ranking by total (not by
+    // first appearance) keeps the assignment stable while a filter changes which
+    // series are present.
+    const totals = new Map<string, number>();
+    for (const row of rows) totals.set(row.series, (totals.get(row.series) ?? 0) + metricValue(row, metric));
+
+    const ranked = [...totals.entries()].sort((a, b) => b[1] - a[1]).map(([series]) => series);
+    const named = ranked.slice(0, CATEGORICAL_CEILING);
+    const folded = new Set(ranked.slice(CATEGORICAL_CEILING));
+
+    const keys = folded.size > 0 ? [...named, OTHER_SERIES] : named;
+
+    const byBucket = new Map<string, TimelineBucket>();
+    for (const row of rows) {
+      const key = bucketKey(row.bucket);
+      let entry = byBucket.get(key);
+      if (!entry) {
+        entry = { bucket: key };
+        for (const series of keys) entry[series] = 0;
+        byBucket.set(key, entry);
+      }
+      const series = folded.has(row.series) ? OTHER_SERIES : row.series;
+      entry[series] = (entry[series] as number) + metricValue(row, metric);
+    }
+
+    return {
+      chartData: [...byBucket.values()].sort((a, b) => a.bucket.localeCompare(b.bucket)),
+      seriesKeys: keys,
+    };
+  }, [rows, metric]);
+
+  const seriesLabel = (series: string): string => {
+    if (series === OTHER_SERIES) {
+      const key = "token_usage.series.other";
+      return t.has(key) ? t(key) : "Altro";
+    }
+    // Stacking by company makes the series a company NAME, which is data, not
+    // vocabulary — it is never looked up. Scope and type keys are vocabulary the
+    // consuming app supplies, with the raw key as the fallback.
+    if (stackBy === "company") return series;
+    return operationLabel(
+      series,
+      (key) => t(key),
+      (key) => t.has(key),
+    );
+  };
+
+  const chartConfig = useMemo(
+    () => Object.fromEntries(seriesKeys.map((series) => [series, { label: seriesLabel(series) }])) as ChartConfig,
+    [seriesKeys, stackBy],
+  );
+
+  if (chartData.length === 0) {
+    const key = "token_usage.timeline.empty";
+    return (
+      <p className={className ? `text-muted-foreground text-sm ${className}` : "text-muted-foreground text-sm"}>
+        {t.has(key) ? t(key) : "Nessun dato nel periodo selezionato"}
+      </p>
+    );
+  }
+
+  const granularity = inferGranularity(chartData.map((entry) => entry.bucket));
+  const formatBucket = bucketFormatter(granularity);
+  const seriesColorFor = (series: string, index: number) =>
+    series === OTHER_SERIES ? OTHER_COLOR : seriesColor(index, mode);
+
+  return (
+    <div className={className}>
+      {/* The pivot, exposed for assertions and for screen readers that would
+          otherwise get nothing from the SVG. */}
+      <span className="sr-only" data-testid="timeline-data">
+        {JSON.stringify(chartData)}
+      </span>
+      <span className="sr-only" data-testid="timeline-series">
+        {JSON.stringify(seriesKeys)}
+      </span>
+
+      <ChartContainer config={chartConfig} className="aspect-auto h-72 w-full">
+        <BarChart accessibilityLayer data={chartData} margin={{ top: 8, right: 8, bottom: 0, left: 0 }}>
+          <CartesianGrid vertical={false} />
+          <XAxis
+            dataKey="bucket"
+            tickLine={false}
+            axisLine={false}
+            tickMargin={8}
+            minTickGap={16}
+            tickFormatter={(value: string) => formatBucket.format(new Date(`${value}T00:00:00.000Z`))}
+          />
+          <YAxis
+            tickLine={false}
+            axisLine={false}
+            tickMargin={8}
+            width={48}
+            tickFormatter={(value: number) => compactNumber.format(value)}
+          />
+          <ChartTooltip
+            content={
+              <ChartTooltipContent
+                labelFormatter={(value) => formatBucket.format(new Date(`${String(value)}T00:00:00.000Z`))}
+              />
+            }
+          />
+          {seriesKeys.length >= 2 ? <ChartLegend content={<ChartLegendContent />} /> : null}
+          {seriesKeys.map((series, index) => (
+            <Bar
+              key={series}
+              dataKey={series}
+              stackId="usage"
+              maxBarSize={28}
+              fill={seriesColorFor(series, index)}
+              // A 2px stroke in the surface colour is the gap between stacked
+              // segments and between neighbouring bars — the palette's own
+              // secondary-encoding channel, not a border.
+              stroke="var(--background)"
+              strokeWidth={2}
+              radius={index === seriesKeys.length - 1 ? [4, 4, 0, 0] : 0}
+            />
+          ))}
+        </BarChart>
+      </ChartContainer>
+    </div>
+  );
+}

package/src/features/tokenusage/components/__tests__/TokenUsageAdminTiles.spec.tsx

@@ -0,0 +1,42 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { TokenUsageAdminTiles } from "../TokenUsageAdminTiles";
+
+const row = (scope: string, window: string, cost: number, calls = 1) =>
+  ({ id: `${scope}|${window}`, scope, window, cost, credits: 0, tokensIn: 0, tokensOut: 0, cached: 0, calls }) as any;
+
+const summary = [
+  row("customer", "current", 9.46, 2956),
+  row("platform", "current", 9.47, 7681),
+  row("total", "current", 18.93, 10637),
+  row("customer", "previous", 8.0, 2000),
+  row("platform", "previous", 10.0, 8000),
+  row("total", "previous", 18.0, 10000),
+];
+
+describe("TokenUsageAdminTiles", () => {
+  it("shows both cost centres with their deltas against the previous window", () => {
+    render(<TokenUsageAdminTiles summary={summary} metric="cost" singleCustomerMode={false} />);
+
+    expect(screen.getByTestId("tile-customer")).toHaveTextContent("9,46");
+    expect(screen.getByTestId("tile-platform")).toHaveTextContent("9,47");
+    // customer 9.46 vs 8.00 => +18%
+    expect(screen.getByTestId("tile-customer-delta")).toHaveTextContent("18");
+    // platform 9.47 vs 10.00 => -5%
+    expect(screen.getByTestId("tile-platform-delta")).toHaveTextContent("5");
+  });
+
+  it("hides the platform tile in single-customer mode", () => {
+    render(<TokenUsageAdminTiles summary={summary} metric="cost" singleCustomerMode />);
+
+    expect(screen.getByTestId("tile-customer")).toBeInTheDocument();
+    expect(screen.queryByTestId("tile-platform")).not.toBeInTheDocument();
+  });
+
+  it("suppresses the delta rather than showing Infinity when the previous window is zero", () => {
+    const zeroPrev = summary.map((r) => (r.window === "previous" ? { ...r, cost: 0 } : r));
+    render(<TokenUsageAdminTiles summary={zeroPrev as any} metric="cost" singleCustomerMode={false} />);
+
+    expect(screen.getByTestId("tile-customer-delta")).toHaveTextContent("—");
+  });
+});

package/src/features/tokenusage/components/__tests__/TokenUsageRankedBar.spec.tsx

@@ -0,0 +1,41 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { TokenUsageRankedBar } from "../TokenUsageRankedBar";
+
+const row = (id: string, label: string, cost: number) =>
+  ({ id, label, cost, credits: 0, tokensIn: 0, tokensOut: 0, cached: 0, calls: 1 }) as any;
+
+describe("TokenUsageRankedBar", () => {
+  it("direct-labels each row with its value and its share of the total", () => {
+    render(
+      <TokenUsageRankedBar
+        rows={[row("a", "Studio Rossi", 6), row("b", "Studio Bianchi", 4)]}
+        metric="cost"
+        emptyLabel="nessun dato"
+      />,
+    );
+
+    expect(screen.getByTestId("ranked-value-a")).toHaveTextContent("6,00");
+    expect(screen.getByTestId("ranked-share-a")).toHaveTextContent("60");
+    expect(screen.getByTestId("ranked-share-b")).toHaveTextContent("40");
+  });
+
+  it("renders the empty label when there are no rows", () => {
+    render(<TokenUsageRankedBar rows={[]} metric="cost" emptyLabel="nessun dato" />);
+    expect(screen.getByText("nessun dato")).toBeInTheDocument();
+  });
+
+  it("assigns colour by rank position from one ramp, so no two rows share an identity hue by accident", () => {
+    render(
+      <TokenUsageRankedBar
+        rows={[row("a", "A", 3), row("b", "B", 2), row("c", "C", 1)]}
+        metric="cost"
+        emptyLabel="nessun dato"
+      />,
+    );
+
+    const colours = ["a", "b", "c"].map((id) => screen.getByTestId(`ranked-fill-${id}`).getAttribute("data-ramp-step"));
+    expect(new Set(colours).size).toBe(3);
+    expect(colours).toEqual(["0", "1", "2"]);
+  });
+});

package/src/features/tokenusage/components/__tests__/TokenUsageTimelineChart.spec.tsx

@@ -0,0 +1,47 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { TokenUsageTimelineChart } from "../TokenUsageTimelineChart";
+
+const row = (bucket: string, series: string, cost: number) =>
+  ({
+    id: `${bucket}|${series}`,
+    bucket: new Date(bucket),
+    series,
+    cost,
+    credits: 0,
+    tokensIn: 0,
+    tokensOut: 0,
+    cached: 0,
+    calls: 1,
+  }) as any;
+
+describe("TokenUsageTimelineChart", () => {
+  it("pivots flat rows into one entry per bucket with a key per series", () => {
+    render(
+      <TokenUsageTimelineChart
+        rows={[row("2026-08-01", "customer", 1), row("2026-08-01", "platform", 2), row("2026-08-02", "customer", 3)]}
+        metric="cost"
+        stackBy="scope"
+      />,
+    );
+
+    const data = JSON.parse(screen.getByTestId("timeline-data").textContent!);
+    expect(data).toHaveLength(2);
+    expect(data[0]).toMatchObject({ customer: 1, platform: 2 });
+    expect(data[1]).toMatchObject({ customer: 3 });
+  });
+
+  it("folds series beyond the 7-colour ceiling into a single 'other' series", () => {
+    const rows = Array.from({ length: 10 }, (_, i) => row("2026-08-01", `type${i}`, 10 - i));
+    render(<TokenUsageTimelineChart rows={rows} metric="cost" stackBy="type" />);
+
+    const series = JSON.parse(screen.getByTestId("timeline-series").textContent!);
+    expect(series).toHaveLength(8);
+    expect(series[7]).toBe("other");
+  });
+
+  it("renders the empty state without a chart when there are no rows", () => {
+    render(<TokenUsageTimelineChart rows={[]} metric="cost" stackBy="scope" />);
+    expect(screen.queryByTestId("timeline-data")).not.toBeInTheDocument();
+  });
+});

package/src/features/tokenusage/contexts/TokenUsageAdminContext.tsx

@@ -0,0 +1,252 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { createContext, ReactNode, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { SharedProvider } from "../../../contexts";
+import { usePageUrlGenerator } from "../../../hooks";
+import { BreadcrumbItemData } from "../../../interfaces";
+import { TokenUsageAdminFilterBar } from "../components/TokenUsageAdminFilterBar";
+import type { TokenUsageAdminBreakdownInterface } from "../data/tokenusage-admin-breakdown.interface";
+import type { TokenUsageAdminSummaryInterface } from "../data/tokenusage-admin-summary.interface";
+import type { TokenUsageAdminTimelineInterface } from "../data/tokenusage-admin-timeline.interface";
+import type { Granularity, Metric, StackBy } from "../data/tokenusage-admin.types";
+import { TokenUsageAdminService } from "../data/TokenUsageAdminService";
+
+/**
+ * Route the breadcrumb links back to. The page itself lives in the consuming
+ * app (a360ai mounts it at `/administration/token-usage`); the constant is here
+ * because the breadcrumb is built by this provider, not by the app.
+ */
+const TOKEN_USAGE_ADMIN_PAGE_URL = "/administration/token-usage";
+
+/** Rows kept per ranked panel before the repository folds the tail into "other". */
+const DEFAULT_TOP_N = 10;
+
+export type TokenUsageAdminFilterState = {
+  /** ISO 8601 instant. */
+  from: string;
+  /** ISO 8601 instant. */
+  to: string;
+  granularity: Granularity;
+  stackBy: StackBy;
+  companyId?: string;
+  metric: Metric;
+};
+
+export interface TokenUsageAdminContextType {
+  summary: TokenUsageAdminSummaryInterface[];
+  timeline: TokenUsageAdminTimelineInterface[];
+  byCompany: TokenUsageAdminBreakdownInterface[];
+  byUser: TokenUsageAdminBreakdownInterface[];
+  /** Platform-side spend split by operation. Always empty in single-customer mode. */
+  /** Platform spend by operation — empty in single-customer mode. */
+  byOperation: TokenUsageAdminBreakdownInterface[];
+  /** Customer spend by operation — the customer-side mirror of byOperation. */
+  byCustomerOperation: TokenUsageAdminBreakdownInterface[];
+  companies: { id: string; label: string }[];
+  filters: TokenUsageAdminFilterState;
+  /** Merges a partial patch into the current filters; every key is optional. */
+  setFilters: (next: Partial<TokenUsageAdminFilterState>) => void;
+  /** `true` once a company filter is applied — the platform panels are meaningless then. */
+  singleCustomerMode: boolean;
+  isLoading: boolean;
+  error: string | null;
+}
+
+const TokenUsageAdminContext = createContext<TokenUsageAdminContextType | undefined>(undefined);
+
+/** Current calendar month 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.getFullYear(), now.getMonth(), 1, 0, 0, 0, 0);
+  return { from: start.toISOString(), to: now.toISOString() };
+}
+
+type TokenUsageAdminProviderProps = {
+  children: ReactNode;
+  /** Pre-select a company, which puts the page in single-customer mode from the first render. */
+  initialCompanyId?: string;
+  /** ISO 8601 instant. Defaults to the start of the current month. */
+  initialFrom?: string;
+  /** ISO 8601 instant. Defaults to now. */
+  initialTo?: string;
+  /** Rows per ranked panel. Defaults to 10. */
+  topN?: number;
+};
+
+/**
+ * Owns every filter the administrative token-usage page reads, fetches the five
+ * 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 TokenUsageAdminProvider = ({
+  children,
+  initialCompanyId,
+  initialFrom,
+  initialTo,
+  topN = DEFAULT_TOP_N,
+}: TokenUsageAdminProviderProps) => {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+
+  const [filters, setFilterState] = useState<TokenUsageAdminFilterState>(() => {
+    const range = defaultRange();
+    return {
+      from: initialFrom ?? range.from,
+      to: initialTo ?? range.to,
+      granularity: "day",
+      stackBy: "scope",
+      companyId: initialCompanyId,
+      metric: "cost",
+    };
+  });
+
+  const [summary, setSummary] = useState<TokenUsageAdminSummaryInterface[]>([]);
+  const [timeline, setTimeline] = useState<TokenUsageAdminTimelineInterface[]>([]);
+  const [byCompany, setByCompany] = useState<TokenUsageAdminBreakdownInterface[]>([]);
+  const [byUser, setByUser] = useState<TokenUsageAdminBreakdownInterface[]>([]);
+  const [byOperation, setByOperation] = useState<TokenUsageAdminBreakdownInterface[]>([]);
+  const [byCustomerOperation, setByCustomerOperation] = useState<TokenUsageAdminBreakdownInterface[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const { from, to, granularity, stackBy, companyId, metric } = filters;
+  const singleCustomerMode = Boolean(companyId);
+
+  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, companyId };
+
+    Promise.all([
+      TokenUsageAdminService.getSummary(base),
+      TokenUsageAdminService.getTimeline({ ...base, granularity, stackBy }),
+      TokenUsageAdminService.getBreakdown({ ...base, dimension: "company", scope: "customer", limit: topN }),
+      TokenUsageAdminService.getBreakdown({ ...base, dimension: "user", scope: "customer", limit: topN }),
+      // Platform spend is, by definition, the usage with no owning company, so
+      // filtering it by one is meaningless — the call is skipped entirely rather
+      // than issued and discarded.
+      companyId
+        ? Promise.resolve<TokenUsageAdminBreakdownInterface[]>([])
+        : TokenUsageAdminService.getBreakdown({ ...base, dimension: "operation", scope: "platform", limit: topN }),
+      // Customer spend by operation — unlike the platform panel this one IS
+      // meaningful under a company filter, so it is always requested.
+      TokenUsageAdminService.getBreakdown({ ...base, dimension: "operation", scope: "customer", limit: topN }),
+    ])
+      .then(([nextSummary, nextTimeline, nextByCompany, nextByUser, nextByOperation, nextByCustomerOperation]) => {
+        if (cancelled) return;
+        setSummary(nextSummary ?? []);
+        setTimeline(nextTimeline ?? []);
+        setByCompany(nextByCompany ?? []);
+        setByUser(nextByUser ?? []);
+        setByOperation(nextByOperation ?? []);
+        setByCustomerOperation(nextByCustomerOperation ?? []);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        console.error("Failed to load administrative token usage:", err);
+        setError(err instanceof Error ? err.message : String(err));
+      })
+      .finally(() => {
+        if (cancelled) return;
+        setIsLoading(false);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [from, to, granularity, stackBy, companyId, topN]);
+
+  const setFilters = useCallback((next: Partial<TokenUsageAdminFilterState>) => {
+    setFilterState((prev) => ({ ...prev, ...next }));
+  }, []);
+
+  /**
+   * Derived from the company breakdown, per the page design. Note the
+   * consequence: once a company filter is applied the breakdown returns that
+   * company alone, so the selector narrows to it — clearing the filter restores
+   * the full list.
+   */
+  const companies = useMemo(
+    () => byCompany.filter((row) => row.id !== "other").map((row) => ({ id: row.id, label: row.label })),
+    [byCompany],
+  );
+
+  const breadcrumb = (): BreadcrumbItemData[] => [
+    {
+      name: t("token_usage.admin.title"),
+      href: generateUrl({ page: TOKEN_USAGE_ADMIN_PAGE_URL }),
+    },
+  ];
+
+  const title = () => ({
+    type: t("token_usage.admin.title"),
+    functions: (
+      <TokenUsageAdminFilterBar
+        key="tokenUsageAdminFilterBar"
+        from={from}
+        to={to}
+        granularity={granularity}
+        companyId={companyId}
+        metric={metric}
+        companies={companies}
+        onChange={setFilters}
+      />
+    ),
+  });
+
+  const contextValue = useMemo<TokenUsageAdminContextType>(
+    () => ({
+      summary,
+      timeline,
+      byCompany,
+      byUser,
+      byOperation,
+      byCustomerOperation,
+      companies,
+      filters,
+      setFilters,
+      singleCustomerMode,
+      isLoading,
+      error,
+    }),
+    [
+      summary,
+      timeline,
+      byCompany,
+      byUser,
+      byOperation,
+      byCustomerOperation,
+      companies,
+      filters,
+      setFilters,
+      singleCustomerMode,
+      isLoading,
+      error,
+    ],
+  );
+
+  return (
+    <SharedProvider value={{ breadcrumbs: breadcrumb(), title: title() }}>
+      <TokenUsageAdminContext.Provider value={contextValue}>{children}</TokenUsageAdminContext.Provider>
+    </SharedProvider>
+  );
+};
+
+export const useTokenUsageAdmin = (): TokenUsageAdminContextType => {
+  const ctx = useContext(TokenUsageAdminContext);
+  if (!ctx) {
+    throw new Error("useTokenUsageAdmin() called outside <TokenUsageAdminProvider>.");
+  }
+  return ctx;
+};

package/src/features/tokenusage/contexts/__tests__/TokenUsageAdminContext.spec.tsx

@@ -0,0 +1,80 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { TokenUsageAdminService } from "../../data/TokenUsageAdminService";
+import { TokenUsageAdminProvider, useTokenUsageAdmin } from "../TokenUsageAdminContext";
+
+vi.mock("../../data/TokenUsageAdminService", () => ({
+  TokenUsageAdminService: {
+    getSummary: vi.fn(async () => []),
+    getTimeline: vi.fn(async () => []),
+    getBreakdown: vi.fn(async () => []),
+  },
+}));
+
+function Probe() {
+  const ctx = useTokenUsageAdmin();
+  return <span data-testid="mode">{String(ctx.singleCustomerMode)}</span>;
+}
+
+describe("TokenUsageAdminContext", () => {
+  // The mocked service is module-level, so its call counts survive across tests.
+  // Without this reset the per-test `toHaveBeenCalledTimes` assertions would
+  // measure the whole file rather than one render.
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("throws when used outside its provider", () => {
+    expect(() => render(<Probe />)).toThrow();
+  });
+
+  it("requests every panel on mount and reports not-single-customer by default", async () => {
+    render(
+      <TokenUsageAdminProvider>
+        <Probe />
+      </TokenUsageAdminProvider>,
+    );
+
+    await waitFor(() => expect(TokenUsageAdminService.getSummary).toHaveBeenCalled());
+
+    // Four ranked panels: company, user, customer-by-operation, platform-by-operation.
+    // Asserted by dimension+scope rather than by count alone, so a wrong pairing
+    // fails here instead of silently rendering the wrong data.
+    const calls = (TokenUsageAdminService.getBreakdown as ReturnType<typeof vi.fn>).mock.calls.map(([args]) => [
+      args.dimension,
+      args.scope,
+    ]);
+    expect(calls).toEqual(
+      expect.arrayContaining([
+        ["company", "customer"],
+        ["user", "customer"],
+        ["operation", "customer"],
+        ["operation", "platform"],
+      ]),
+    );
+    expect(calls).toHaveLength(4);
+    expect(screen.getByTestId("mode")).toHaveTextContent("false");
+  });
+
+  it("skips only the PLATFORM operation breakdown once a company filter is applied", async () => {
+    render(
+      <TokenUsageAdminProvider initialCompanyId="c1">
+        <Probe />
+      </TokenUsageAdminProvider>,
+    );
+
+    await waitFor(() => expect(TokenUsageAdminService.getSummary).toHaveBeenCalled());
+
+    const calls = (TokenUsageAdminService.getBreakdown as ReturnType<typeof vi.fn>).mock.calls.map(([args]) => [
+      args.dimension,
+      args.scope,
+    ]);
+    // Platform spend has no owning company, so filtering it is meaningless and
+    // the call is skipped. The CUSTOMER operation panel is still meaningful and
+    // must survive — that distinction is the point of this test.
+    expect(calls).toContainEqual(["operation", "customer"]);
+    expect(calls).not.toContainEqual(["operation", "platform"]);
+    expect(calls).toHaveLength(3);
+    expect(screen.getByTestId("mode")).toHaveTextContent("true");
+  });
+});