@carlonicora/nextjs-jsonapi 2.4.0 → 3.0.0

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

@@ -14,6 +14,7 @@ import {
 } from "../../../shadcnui";
 import { TokenUsageAdminTimelineInterface } from "../data/tokenusage-admin-timeline.interface";
 import { Metric, StackBy } from "../data/tokenusage-admin.types";
+import { useUsageFormatters } from "../lib/formatters";
 import { operationLabel } from "../lib/operation-label";
 import { CATEGORICAL_CEILING, ChartMode, OTHER_COLOR, seriesColor } from "../lib/palette";
 
@@ -71,13 +72,6 @@ const inferGranularity = (buckets: string[]): "day" | "week" | "month" => {
   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.
  *
@@ -93,6 +87,7 @@ const compactNumber = new Intl.NumberFormat("it-IT", { notation: "compact", maxi
  */
 export function TokenUsageTimelineChart({ rows, metric, stackBy, className }: TokenUsageTimelineChartProps) {
   const t = useTranslations();
+  const { compact, bucketDate, metricValue: formatValue } = useUsageFormatters();
   const { resolvedTheme } = useTheme();
   const mode: ChartMode = resolvedTheme === "dark" ? "dark" : "light";
 
@@ -134,7 +129,7 @@ export function TokenUsageTimelineChart({ rows, metric, stackBy, className }: To
   const seriesLabel = (series: string): string => {
     if (series === OTHER_SERIES) {
       const key = "token_usage.series.other";
-      return t.has(key) ? t(key) : "Altro";
+      return t.has(key) ? t(key) : "Other";
     }
     // 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
@@ -156,13 +151,12 @@ export function TokenUsageTimelineChart({ rows, metric, stackBy, className }: To
     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"}
+        {t.has(key) ? t(key) : "No data in the selected period"}
       </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);
 
@@ -186,19 +180,27 @@ export function TokenUsageTimelineChart({ rows, metric, stackBy, className }: To
             axisLine={false}
             tickMargin={8}
             minTickGap={16}
-            tickFormatter={(value: string) => formatBucket.format(new Date(`${value}T00:00:00.000Z`))}
+            tickFormatter={(value: string) => bucketDate(value, granularity)}
           />
           <YAxis
             tickLine={false}
             axisLine={false}
             tickMargin={8}
             width={48}
-            tickFormatter={(value: number) => compactNumber.format(value)}
+            tickFormatter={(value: number) => compact(value)}
           />
           <ChartTooltip
             content={
               <ChartTooltipContent
-                labelFormatter={(value) => formatBucket.format(new Date(`${String(value)}T00:00:00.000Z`))}
+                labelFormatter={(value) => bucketDate(String(value), granularity)}
+                // Without this the tooltip falls back to toLocaleString() and
+                // prints the raw stored precision (credits carry 4 decimals),
+                // which disagrees with every other number on the page.
+                valueFormatter={(value) => formatValue(Number(value), metric)}
+                // Every series appears in every bucket's payload, so a day with
+                // one active operation would otherwise list the whole vocabulary
+                // as zeros and bury the one number that matters.
+                hideZeroValues
               />
             }
           />

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

@@ -18,8 +18,10 @@ 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");
+    // The suite mocks useLocale() as "en", and formatting now honours the
+    // locale instead of a hard-coded it-IT, so the separator is a point.
+    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%

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

@@ -15,7 +15,9 @@ describe("TokenUsageRankedBar", () => {
       />,
     );
 
-    expect(screen.getByTestId("ranked-value-a")).toHaveTextContent("6,00");
+    // The suite mocks useLocale() as "en", and formatting now honours the
+    // locale instead of a hard-coded it-IT, so the separator is a point.
+    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");
   });

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

@@ -13,8 +13,8 @@ import type { Granularity, Metric, StackBy } from "../data/tokenusage-admin.type
 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
+ * 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 TOKEN_USAGE_ADMIN_PAGE_URL = "/administration/token-usage";
@@ -72,6 +72,8 @@ type TokenUsageAdminProviderProps = {
   initialTo?: string;
   /** Rows per ranked panel. Defaults to 10. */
   topN?: number;
+  /** Route the breadcrumb links back to. */
+  pageUrl?: string;
 };
 
 /**
@@ -89,6 +91,7 @@ export const TokenUsageAdminProvider = ({
   initialFrom,
   initialTo,
   topN = DEFAULT_TOP_N,
+  pageUrl = TOKEN_USAGE_ADMIN_PAGE_URL,
 }: TokenUsageAdminProviderProps) => {
   const t = useTranslations();
   const generateUrl = usePageUrlGenerator();
@@ -185,7 +188,7 @@ export const TokenUsageAdminProvider = ({
   const breadcrumb = (): BreadcrumbItemData[] => [
     {
       name: t("token_usage.admin.title"),
-      href: generateUrl({ page: TOKEN_USAGE_ADMIN_PAGE_URL }),
+      href: generateUrl({ page: pageUrl }),
     },
   ];
 

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

@@ -0,0 +1,199 @@
+"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 { TokenUsageReportFilterBar } from "../components/TokenUsageReportFilterBar";
+import type { TokenUsageReportBreakdownInterface } from "../data/tokenusage-report-breakdown.interface";
+import type { TokenUsageReportSummaryInterface } from "../data/tokenusage-report-summary.interface";
+import type { TokenUsageReportTimelineInterface } from "../data/tokenusage-report-timeline.interface";
+import type { ReportMetric } from "../data/tokenusage-report.types";
+import { TokenUsageReportService } from "../data/TokenUsageReportService";
+
+/** Default page the breadcrumb links back to; overridable per host app. */
+const TOKEN_USAGE_REPORT_PAGE_URL = "/tokenusage";
+
+/** Rows kept per ranked panel before the backend folds the tail into "other". */
+const DEFAULT_TOP_N = 10;
+
+/**
+ * The unit this surface reports in, always. A game master is billed in credits,
+ * so credits are the only number that means anything to them: cost would leak
+ * platform margin and a raw token count is an implementation detail nobody is
+ * charged for. Pinned rather than exposed as a filter — there is no metric
+ * selector on the page.
+ */
+const REPORT_METRIC: ReportMetric = "credits";
+
+export type TokenUsageReportFilterState = {
+  /** ISO 8601 instant. */
+  from: string;
+  /** ISO 8601 instant. */
+  to: string;
+};
+
+export interface TokenUsageReportContextType {
+  summary: TokenUsageReportSummaryInterface[];
+  timeline: TokenUsageReportTimelineInterface[];
+  byOperation: TokenUsageReportBreakdownInterface[];
+  /** Empty unless the host app declared a targetLabel. */
+  byTarget: TokenUsageReportBreakdownInterface[];
+  /** i18n key for the target panel's title; undefined when the host set no targetLabel. */
+  targetPanelTitleKey?: string;
+  filters: TokenUsageReportFilterState;
+  /** Merges a partial patch into the current filters; every key is optional. */
+  setFilters: (next: Partial<TokenUsageReportFilterState>) => void;
+  isLoading: boolean;
+  error: string | null;
+}
+
+const TokenUsageReportContext = createContext<TokenUsageReportContextType | 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 TokenUsageReportProviderProps = {
+  children: ReactNode;
+  /**
+   * The Neo4j label the "by target" panel groups by, e.g. "Campaign". The set of
+   * things usage can be attributed to is application-specific, so the package
+   * cannot pick one — omit it and the panel is skipped rather than rendered
+   * empty, and no request is issued.
+   */
+  targetLabel?: string;
+  /** i18n key for the target panel's title. Required when targetLabel is set. */
+  targetPanelTitleKey?: 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;
+  /** Route the breadcrumb links back to. */
+  pageUrl?: string;
+};
+
+/**
+ * Owns the date range of the self-service token-usage page, fetches the three
+ * 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 TokenUsageReportProvider = ({
+  children,
+  targetLabel,
+  targetPanelTitleKey,
+  initialFrom,
+  initialTo,
+  topN = DEFAULT_TOP_N,
+  pageUrl = TOKEN_USAGE_REPORT_PAGE_URL,
+}: TokenUsageReportProviderProps) => {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+
+  const [filters, setFilterState] = useState<TokenUsageReportFilterState>(() => {
+    const range = defaultRange();
+    return { from: initialFrom ?? range.from, to: initialTo ?? range.to };
+  });
+
+  const [summary, setSummary] = useState<TokenUsageReportSummaryInterface[]>([]);
+  const [timeline, setTimeline] = useState<TokenUsageReportTimelineInterface[]>([]);
+  const [byOperation, setByOperation] = useState<TokenUsageReportBreakdownInterface[]>([]);
+  const [byTarget, setByTarget] = useState<TokenUsageReportBreakdownInterface[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const { from, to } = 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 };
+
+    Promise.all([
+      TokenUsageReportService.getSummary(base),
+      // granularity is pinned to "day": week/month bucketing buys nothing on the
+      // ranges a single tenant browses.
+      TokenUsageReportService.getTimeline({ ...base, granularity: "day" }),
+      TokenUsageReportService.getBreakdown({ ...base, dimension: "operation", metric: REPORT_METRIC, limit: topN }),
+      // No targetLabel means the host app never opted in, so the request is
+      // skipped entirely rather than issued and discarded.
+      targetLabel
+        ? TokenUsageReportService.getBreakdown({
+            ...base,
+            dimension: "target",
+            targetLabel,
+            metric: REPORT_METRIC,
+            limit: topN,
+          })
+        : Promise.resolve<TokenUsageReportBreakdownInterface[]>([]),
+    ])
+      .then(([nextSummary, nextTimeline, nextByOperation, nextByTarget]) => {
+        if (cancelled) return;
+        setSummary(nextSummary ?? []);
+        setTimeline(nextTimeline ?? []);
+        setByOperation(nextByOperation ?? []);
+        setByTarget(nextByTarget ?? []);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        console.error("Failed to load token usage:", err);
+        setError(err instanceof Error ? err.message : String(err));
+      })
+      .finally(() => {
+        if (cancelled) return;
+        setIsLoading(false);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [from, to, targetLabel, topN]);
+
+  const setFilters = useCallback((next: Partial<TokenUsageReportFilterState>) => {
+    setFilterState((prev) => ({ ...prev, ...next }));
+  }, []);
+
+  const breadcrumb = (): BreadcrumbItemData[] => [
+    { name: t("token_usage.report.title"), href: generateUrl({ page: pageUrl }) },
+  ];
+
+  const title = () => ({
+    type: t("token_usage.report.title"),
+    functions: <TokenUsageReportFilterBar key="tokenUsageReportFilterBar" onChange={setFilters} />,
+  });
+
+  const contextValue = useMemo<TokenUsageReportContextType>(
+    () => ({ summary, timeline, byOperation, byTarget, targetPanelTitleKey, filters, setFilters, isLoading, error }),
+    [summary, timeline, byOperation, byTarget, targetPanelTitleKey, filters, setFilters, isLoading, error],
+  );
+
+  return (
+    <SharedProvider value={{ breadcrumbs: breadcrumb(), title: title() }}>
+      <TokenUsageReportContext.Provider value={contextValue}>{children}</TokenUsageReportContext.Provider>
+    </SharedProvider>
+  );
+};
+
+export const useTokenUsageReport = (): TokenUsageReportContextType => {
+  const ctx = useContext(TokenUsageReportContext);
+  if (!ctx) {
+    throw new Error("useTokenUsageReport() called outside <TokenUsageReportProvider>.");
+  }
+  return ctx;
+};

package/src/features/tokenusage/data/TokenUsageReportService.ts

@@ -0,0 +1,65 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
+import { TokenUsageReportBreakdownInterface } from "./tokenusage-report-breakdown.interface";
+import { TokenUsageReportSummaryInterface } from "./tokenusage-report-summary.interface";
+import { TokenUsageReportTimelineInterface } from "./tokenusage-report-timeline.interface";
+import { ReportDimension, ReportMetric, TokenUsageReportFilters } from "./tokenusage-report.types";
+
+function withFilters(endpoint: EndpointCreator, filters: TokenUsageReportFilters): EndpointCreator {
+  endpoint.addAdditionalParam("from", filters.from);
+  endpoint.addAdditionalParam("to", filters.to);
+  return endpoint;
+}
+
+/**
+ * The self-service token-usage endpoints.
+ *
+ * No companyId parameter anywhere: the backend scopes every query to the
+ * caller's own company through the CLS preamble, so there is nothing for the
+ * client to name. No `metric: "cost"` either — the controller rejects it.
+ */
+export class TokenUsageReportService extends AbstractService {
+  /** Two rows: window "current" and "previous". */
+  static async getSummary(filters: TokenUsageReportFilters): Promise<TokenUsageReportSummaryInterface[]> {
+    const endpoint = withFilters(new EndpointCreator({ endpoint: Modules.TokenUsageReportSummary }), filters);
+
+    return this.callApi<TokenUsageReportSummaryInterface[]>({
+      type: Modules.TokenUsageReportSummary,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+
+  static async getTimeline(
+    params: TokenUsageReportFilters & { granularity: "day" },
+  ): Promise<TokenUsageReportTimelineInterface[]> {
+    const endpoint = withFilters(new EndpointCreator({ endpoint: Modules.TokenUsageReportTimeline }), params);
+    endpoint.addAdditionalParam("granularity", params.granularity);
+
+    return this.callApi<TokenUsageReportTimelineInterface[]>({
+      type: Modules.TokenUsageReportTimeline,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+
+  static async getBreakdown(
+    params: TokenUsageReportFilters & {
+      dimension: ReportDimension;
+      targetLabel?: string;
+      metric: ReportMetric;
+      limit?: number;
+    },
+  ): Promise<TokenUsageReportBreakdownInterface[]> {
+    const endpoint = withFilters(new EndpointCreator({ endpoint: Modules.TokenUsageReportBreakdown }), params);
+    endpoint.addAdditionalParam("dimension", params.dimension);
+    if (params.targetLabel) endpoint.addAdditionalParam("targetLabel", params.targetLabel);
+    endpoint.addAdditionalParam("metric", params.metric);
+    if (params.limit !== undefined) endpoint.addAdditionalParam("limit", String(params.limit));
+
+    return this.callApi<TokenUsageReportBreakdownInterface[]>({
+      type: Modules.TokenUsageReportBreakdown,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+}

package/src/features/tokenusage/data/index.ts

@@ -6,3 +6,12 @@ export type { TokenUsageAdminTimelineInterface } from "./tokenusage-admin-timeli
 export { TokenUsageAdminBreakdown } from "./tokenusage-admin-breakdown";
 export type { TokenUsageAdminBreakdownInterface } from "./tokenusage-admin-breakdown.interface";
 export { TokenUsageAdminService } from "./TokenUsageAdminService";
+
+export * from "./tokenusage-report.types";
+export { TokenUsageReportSummary } from "./tokenusage-report-summary";
+export type { TokenUsageReportSummaryInterface } from "./tokenusage-report-summary.interface";
+export { TokenUsageReportTimeline } from "./tokenusage-report-timeline";
+export type { TokenUsageReportTimelineInterface } from "./tokenusage-report-timeline.interface";
+export { TokenUsageReportBreakdown } from "./tokenusage-report-breakdown";
+export type { TokenUsageReportBreakdownInterface } from "./tokenusage-report-breakdown.interface";
+export { TokenUsageReportService } from "./TokenUsageReportService";

package/src/features/tokenusage/data/tokenusage-report-breakdown.interface.ts

@@ -0,0 +1,12 @@
+import { ApiDataInterface } from "../../../core";
+
+export interface TokenUsageReportBreakdownInterface extends ApiDataInterface {
+  get label(): string;
+  get sublabel(): string | undefined;
+  get cost(): number;
+  get credits(): number;
+  get tokensIn(): number;
+  get tokensOut(): number;
+  get cached(): number;
+  get calls(): number;
+}

package/src/features/tokenusage/data/tokenusage-report-breakdown.ts

@@ -0,0 +1,94 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { TokenUsageReportBreakdownInterface } from "./tokenusage-report-breakdown.interface";
+import { TokenUsageReportBreakdownInput } from "./tokenusage-report.types";
+
+/**
+ * One ranked row of a self-service breakdown. The same shape serves both
+ * dimensions — operation and target — which is why the two "by-X" panels
+ * collapse into a single `breakdown?dimension=` call.
+ *
+ * Deliberately narrower than the administrative row: no `activeUsers`,
+ * `monthlyCredits` or `availableMonthlyCredits`, which are company-fleet
+ * figures a single company has no business seeing.
+ */
+export class TokenUsageReportBreakdown extends AbstractApiData implements TokenUsageReportBreakdownInterface {
+  private _label: string = "";
+  private _sublabel?: string;
+  private _cost: number = 0;
+  private _credits: number = 0;
+  private _tokensIn: number = 0;
+  private _tokensOut: number = 0;
+  private _cached: number = 0;
+  private _calls: number = 0;
+
+  get label(): string {
+    return this._label;
+  }
+
+  get sublabel(): string | undefined {
+    return this._sublabel;
+  }
+
+  get cost(): number {
+    return this._cost;
+  }
+
+  get credits(): number {
+    return this._credits;
+  }
+
+  get tokensIn(): number {
+    return this._tokensIn;
+  }
+
+  get tokensOut(): number {
+    return this._tokensOut;
+  }
+
+  get cached(): number {
+    return this._cached;
+  }
+
+  get calls(): number {
+    return this._calls;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attrs = data.jsonApi.attributes;
+    this._label = attrs.label ?? "";
+    this._sublabel = attrs.sublabel ?? undefined;
+    this._cost = attrs.cost ?? 0;
+    this._credits = attrs.credits ?? 0;
+    this._tokensIn = attrs.tokensIn ?? 0;
+    this._tokensOut = attrs.tokensOut ?? 0;
+    this._cached = attrs.cached ?? 0;
+    this._calls = attrs.calls ?? 0;
+
+    return this;
+  }
+
+  createJsonApi(data: TokenUsageReportBreakdownInput) {
+    const response: any = {
+      data: {
+        type: Modules.TokenUsageReportBreakdown.name,
+        id: data.id,
+        attributes: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    if (data.label !== undefined) response.data.attributes.label = data.label;
+    if (data.sublabel !== undefined) response.data.attributes.sublabel = data.sublabel;
+    if (data.cost !== undefined) response.data.attributes.cost = data.cost;
+    if (data.credits !== undefined) response.data.attributes.credits = data.credits;
+    if (data.tokensIn !== undefined) response.data.attributes.tokensIn = data.tokensIn;
+    if (data.tokensOut !== undefined) response.data.attributes.tokensOut = data.tokensOut;
+    if (data.cached !== undefined) response.data.attributes.cached = data.cached;
+    if (data.calls !== undefined) response.data.attributes.calls = data.calls;
+
+    return response;
+  }
+}

package/src/features/tokenusage/data/tokenusage-report-summary.interface.ts

@@ -0,0 +1,12 @@
+import { ApiDataInterface } from "../../../core";
+
+export interface TokenUsageReportSummaryInterface extends ApiDataInterface {
+  /** "current" or "previous" — the equal-length preceding span. */
+  get window(): string;
+  get cost(): number;
+  get credits(): number;
+  get tokensIn(): number;
+  get tokensOut(): number;
+  get cached(): number;
+  get calls(): number;
+}

package/src/features/tokenusage/data/tokenusage-report-summary.ts

@@ -0,0 +1,87 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { TokenUsageReportSummaryInterface } from "./tokenusage-report-summary.interface";
+import { TokenUsageReportSummaryInput } from "./tokenusage-report.types";
+
+/**
+ * One row of the self-service summary: the caller's own company observed over
+ * one time window. Two rows are returned per request — "current" and the
+ * equal-length "previous" span — so the KPI tiles can render a value and its
+ * delta without a second call.
+ *
+ * There is no `scope` here: a company only ever sees itself, so the
+ * customer/platform split that the administrative summary carries is absent.
+ */
+export class TokenUsageReportSummary extends AbstractApiData implements TokenUsageReportSummaryInterface {
+  private _window: string = "";
+  private _cost: number = 0;
+  private _credits: number = 0;
+  private _tokensIn: number = 0;
+  private _tokensOut: number = 0;
+  private _cached: number = 0;
+  private _calls: number = 0;
+
+  get window(): string {
+    return this._window;
+  }
+
+  get cost(): number {
+    return this._cost;
+  }
+
+  get credits(): number {
+    return this._credits;
+  }
+
+  get tokensIn(): number {
+    return this._tokensIn;
+  }
+
+  get tokensOut(): number {
+    return this._tokensOut;
+  }
+
+  get cached(): number {
+    return this._cached;
+  }
+
+  get calls(): number {
+    return this._calls;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attrs = data.jsonApi.attributes;
+    this._window = attrs.window ?? "";
+    this._cost = attrs.cost ?? 0;
+    this._credits = attrs.credits ?? 0;
+    this._tokensIn = attrs.tokensIn ?? 0;
+    this._tokensOut = attrs.tokensOut ?? 0;
+    this._cached = attrs.cached ?? 0;
+    this._calls = attrs.calls ?? 0;
+
+    return this;
+  }
+
+  createJsonApi(data: TokenUsageReportSummaryInput) {
+    const response: any = {
+      data: {
+        type: Modules.TokenUsageReportSummary.name,
+        id: data.id,
+        attributes: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    if (data.window !== undefined) response.data.attributes.window = data.window;
+    if (data.cost !== undefined) response.data.attributes.cost = data.cost;
+    if (data.credits !== undefined) response.data.attributes.credits = data.credits;
+    if (data.tokensIn !== undefined) response.data.attributes.tokensIn = data.tokensIn;
+    if (data.tokensOut !== undefined) response.data.attributes.tokensOut = data.tokensOut;
+    if (data.cached !== undefined) response.data.attributes.cached = data.cached;
+    if (data.calls !== undefined) response.data.attributes.calls = data.calls;
+
+    return response;
+  }
+}

package/src/features/tokenusage/data/tokenusage-report-timeline.interface.ts

@@ -0,0 +1,13 @@
+import { ApiDataInterface } from "../../../core";
+
+export interface TokenUsageReportTimelineInterface extends ApiDataInterface {
+  /** Backend declares this `type: "date"`, so it is a Date in memory. */
+  get bucket(): Date;
+  get series(): string;
+  get cost(): number;
+  get credits(): number;
+  get tokensIn(): number;
+  get tokensOut(): number;
+  get cached(): number;
+  get calls(): number;
+}