@carlonicora/nextjs-jsonapi 2.4.0 → 2.5.0

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

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

@@ -0,0 +1,94 @@
+import { AbstractApiData, formatLocalDate, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { TokenUsageReportTimelineInterface } from "./tokenusage-report-timeline.interface";
+import { TokenUsageReportTimelineInput } from "./tokenusage-report.types";
+
+/**
+ * One (bucket, series) cell of the self-service usage-over-time chart. Rows
+ * arrive flat; the chart pivots them into stacked columns.
+ */
+export class TokenUsageReportTimeline extends AbstractApiData implements TokenUsageReportTimelineInterface {
+  private _bucket: Date = new Date(0);
+  private _series: 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 bucket(): Date {
+    return this._bucket;
+  }
+
+  get series(): string {
+    return this._series;
+  }
+
+  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;
+    // Wire format is "YYYY-MM-DD"; the interface promises a Date.
+    this._bucket = attrs.bucket ? new Date(attrs.bucket) : new Date(0);
+    this._series = attrs.series ?? "";
+    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: TokenUsageReportTimelineInput) {
+    const response: any = {
+      data: {
+        type: Modules.TokenUsageReportTimeline.name,
+        id: data.id,
+        attributes: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    // `bucket` is type: "date" on the backend descriptor. formatLocalDate is
+    // mandatory — passing the raw Date lets JSON.stringify call .toISOString(),
+    // which UTC-shifts and can move the bucket a day. Imported from the package
+    // core, never reimplemented inline.
+    if (data.bucket !== undefined) response.data.attributes.bucket = formatLocalDate(data.bucket);
+    if (data.series !== undefined) response.data.attributes.series = data.series;
+    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.types.ts

@@ -0,0 +1,51 @@
+/** Metrics the self-service surface may request. `cost` is deliberately absent. */
+export type ReportMetric = "credits" | "tokens";
+
+/** Dimensions the self-service breakdown can group by. */
+export type ReportDimension = "operation" | "target";
+
+export type TokenUsageReportFilters = {
+  /** ISO 8601 instant. */
+  from: string;
+  /** ISO 8601 instant. */
+  to: string;
+};
+
+// Input types for createJsonApi(). `id` is always required — JSON:API resource
+// objects are identified.
+
+export type TokenUsageReportSummaryInput = {
+  id: string;
+  window: string;
+  cost: number;
+  credits: number;
+  tokensIn: number;
+  tokensOut: number;
+  cached: number;
+  calls: number;
+};
+
+export type TokenUsageReportTimelineInput = {
+  id: string;
+  /** Backend field type is "date" — emitted via formatLocalDate, never raw. */
+  bucket: Date;
+  series: string;
+  cost: number;
+  credits: number;
+  tokensIn: number;
+  tokensOut: number;
+  cached: number;
+  calls: number;
+};
+
+export type TokenUsageReportBreakdownInput = {
+  id: string;
+  label: string;
+  sublabel?: string;
+  cost: number;
+  credits: number;
+  tokensIn: number;
+  tokensOut: number;
+  cached: number;
+  calls: number;
+};

package/src/features/tokenusage/i18n-keys.ts

@@ -63,3 +63,31 @@ export const TOKEN_USAGE_ADMIN_I18N_KEYS = [
   "token_usage.series.other",
   "token_usage.timeline.empty",
 ] as const;
+
+/**
+ * The fixed namespace of i18n keys the self-service token-usage feature reads.
+ * Consuming apps must define each entry in their messages/<locale>.json — this
+ * list is the contract between the package and the app.
+ *
+ * The target panel's title is NOT listed: its key is supplied per app through
+ * the provider's `targetPanelTitleKey`, because what usage is attributed to is
+ * application-specific. Operation labels resolve through
+ * `token_usage.types.<camelCase>` with the raw key as fallback, so that
+ * namespace stays the app's own vocabulary.
+ */
+export const TOKEN_USAGE_REPORT_I18N_KEYS = [
+  // Page + KPI tiles
+  "token_usage.report.title",
+  "token_usage.report.used_in_period",
+  "token_usage.report.vs_previous",
+  "token_usage.report.monthly_left",
+  "token_usage.report.extra_credits",
+  "token_usage.report.calls",
+
+  // Panel titles
+  "token_usage.report.usage_over_time",
+  "token_usage.report.by_operation",
+
+  // Shared states
+  "token_usage.report.no_data",
+] as const;

package/src/features/tokenusage/index.ts

@@ -28,3 +28,21 @@ export {
 } from "./tokenusage-admin.module";
 
 export { TOKEN_USAGE_ADMIN_I18N_KEYS } from "./i18n-keys";
+
+// Self-service ("report") token-usage dashboard — the company-scoped mirror of
+// the administrative trio above, reusing its chart components verbatim.
+
+export { TokenUsageReportProvider, useTokenUsageReport } from "./contexts/TokenUsageReportContext";
+export type { TokenUsageReportContextType, TokenUsageReportFilterState } from "./contexts/TokenUsageReportContext";
+
+export { TokenUsageReportContainer } from "./components/TokenUsageReportContainer";
+export { TokenUsageReportFilterBar } from "./components/TokenUsageReportFilterBar";
+export { TokenUsageReportTiles } from "./components/TokenUsageReportTiles";
+export type { TokenUsageBalances } from "./components/TokenUsageReportTiles";
+
+export { tokenUsageModules } from "./tokenusage.modules";
+export { configureTokenUsage, getTokenUsageCurrency } from "./lib/config";
+export { createUsageFormatters, useUsageFormatters } from "./lib/formatters";
+export type { UsageFormatters } from "./lib/formatters";
+
+export { TOKEN_USAGE_REPORT_I18N_KEYS } from "./i18n-keys";

package/src/features/tokenusage/lib/config.ts

@@ -0,0 +1,22 @@
+/**
+ * The currency the token-usage surfaces render monetary values in.
+ *
+ * The package cannot infer this: the figures come from whatever per-million-token
+ * rates the consuming app configured, and those are denominated in whatever
+ * currency that app buys inference in — EUR for one consumer, USD for another
+ * whose rates are OpenRouter list prices. So the app declares it once at
+ * bootstrap, next to configureJsonApi().
+ *
+ * EUR is the default purely for backward compatibility: the previous
+ * implementation hard-coded a euro sign, so an app that never calls this keeps
+ * rendering exactly what it rendered before.
+ */
+let currency = "EUR";
+
+export function configureTokenUsage(config: { currency: string }): void {
+  currency = config.currency;
+}
+
+export function getTokenUsageCurrency(): string {
+  return currency;
+}

package/src/features/tokenusage/lib/formatters.ts

@@ -0,0 +1,100 @@
+"use client";
+
+import { useLocale } from "next-intl";
+import { useMemo } from "react";
+import type { Metric } from "../data/tokenusage-admin.types";
+import { getTokenUsageCurrency } from "./config";
+
+export type UsageFormatters = {
+  /** Locale-aware fixed-decimal number, e.g. 9.46 → "9,46" in it-IT. */
+  decimal(value: number, decimals: number): string;
+  /** Currency for cost, 2 decimals for credits, whole numbers for tokens. */
+  metricValue(value: number, metric: Metric): string;
+  /** Currency with an explicit decimal count — the per-call tile needs 4. */
+  currency(value: number, decimals: number): string;
+  /** Percentage with one decimal by default, e.g. 60 → "60,0 %" in it-IT. */
+  percent(value: number, decimals?: number): string;
+  /** Compact notation for axis ticks, e.g. 1500000 → "1,5 Mln" in it-IT. */
+  compact(value: number): string;
+  /** A "YYYY-MM-DD" bucket key rendered as an axis or tooltip label, in UTC. */
+  bucketDate(iso: string, granularity: "day" | "week" | "month"): string;
+  /** Locale collation for client-side table sorting. */
+  compare(a: string, b: string): number;
+};
+
+/**
+ * Builds every formatter the token-usage surfaces need, for one locale and one
+ * currency.
+ *
+ * A pure factory on purpose: it takes no React context, so the arithmetic and
+ * the formatting are unit-testable without rendering, and a server component or
+ * a test can construct a set for an arbitrary locale.
+ *
+ * The currency symbol is placed with a space rather than through
+ * `style: "currency"`, which is what the previous hard-coded implementation
+ * rendered ("€ 9,46"). Keeping that shape means a consuming app on EUR sees
+ * byte-identical output after this refactor.
+ *
+ * `bucketDate` formats in UTC, always. The wire value is a `type: "date"` — a
+ * calendar day — parsed to UTC midnight; reading it back with local getters
+ * would shift the label a day early west of UTC.
+ */
+export function createUsageFormatters(locale: string, currency: string): UsageFormatters {
+  const symbol =
+    new Intl.NumberFormat(locale, { style: "currency", currency, currencyDisplay: "narrowSymbol" })
+      .formatToParts(0)
+      .find((part) => part.type === "currency")?.value ?? currency;
+
+  const decimal = (value: number, decimals: number): string =>
+    value.toLocaleString(locale, { minimumFractionDigits: decimals, maximumFractionDigits: decimals });
+
+  const dayFormat = new Intl.DateTimeFormat(locale, { day: "numeric", month: "short", timeZone: "UTC" });
+  const monthFormat = new Intl.DateTimeFormat(locale, { month: "short", year: "numeric", timeZone: "UTC" });
+  const compactFormat = new Intl.NumberFormat(locale, { notation: "compact", maximumFractionDigits: 1 });
+  const collator = new Intl.Collator(locale);
+
+  return {
+    decimal,
+
+    metricValue(value, metric) {
+      if (metric === "cost") return `${symbol} ${decimal(value, 2)}`;
+      // Credits are stored to 4 decimals (round4(cost / creditCost)), but that
+      // precision is noise to a reader comparing rows: one decimal is enough to
+      // separate two values and keeps the columns narrow enough to scan.
+      if (metric === "credits") return decimal(value, 1);
+      return decimal(value, 0);
+    },
+
+    currency(value, decimals) {
+      return `${symbol} ${decimal(value, decimals)}`;
+    },
+
+    percent(value, decimals = 1) {
+      return `${decimal(value, decimals)} %`;
+    },
+
+    compact(value) {
+      return compactFormat.format(value);
+    },
+
+    bucketDate(iso, granularity) {
+      const date = new Date(`${iso}T00:00:00.000Z`);
+      return granularity === "month" ? monthFormat.format(date) : dayFormat.format(date);
+    },
+
+    compare(a, b) {
+      return collator.compare(a, b);
+    },
+  };
+}
+
+/**
+ * The formatter set for the current request's locale and the app's configured
+ * currency. Memoised on both, so the Intl objects are built once per locale
+ * rather than on every render.
+ */
+export function useUsageFormatters(): UsageFormatters {
+  const locale = useLocale();
+  const currency = getTokenUsageCurrency();
+  return useMemo(() => createUsageFormatters(locale, currency), [locale, currency]);
+}

package/src/features/tokenusage/lib/metrics.ts

@@ -1,5 +1,13 @@
 import type { Metric } from "../data/tokenusage-admin.types";
 
+/**
+ * Locale-free arithmetic for the token-usage surfaces.
+ *
+ * Everything that turns a number into a STRING lives in `./formatters` instead,
+ * because it depends on the request's locale and the app's configured currency.
+ * This file stays pure arithmetic so it needs neither.
+ */
+
 /**
  * The metric field set every admin token-usage resource carries. Declared
  * structurally so it accepts the summary, timeline and breakdown interfaces
@@ -14,9 +22,6 @@ export type TokenUsageMetrics = {
   calls: number;
 };
 
-/** UI copy is Italian, so every figure is formatted with the Italian locale. */
-const LOCALE = "it-IT";
-
 /** Reads the single number a row contributes for the currently selected metric. */
 export function metricValue(row: TokenUsageMetrics, metric: Metric): number {
   if (metric === "cost") return row.cost;
@@ -24,29 +29,6 @@ export function metricValue(row: TokenUsageMetrics, metric: Metric): number {
   return row.tokensIn + row.tokensOut;
 }
 
-/** Locale-aware fixed-decimal number, e.g. 9.46 → "9,46". */
-export function formatDecimal(value: number, decimals: number): string {
-  return value.toLocaleString(LOCALE, {
-    minimumFractionDigits: decimals,
-    maximumFractionDigits: decimals,
-  });
-}
-
-/**
- * Formats a metric value for display: euros carry a "€ " prefix and 2 decimals,
- * credits 2 decimals, token counts are whole numbers.
- */
-export function formatMetricValue(value: number, metric: Metric): string {
-  if (metric === "cost") return `€ ${formatDecimal(value, 2)}`;
-  if (metric === "credits") return formatDecimal(value, 2);
-  return formatDecimal(value, 0);
-}
-
-/** Percentage with one decimal, e.g. 60 → "60,0 %". */
-export function formatPercent(value: number, decimals = 1): string {
-  return `${formatDecimal(value, decimals)} %`;
-}
-
 /**
  * Share of cached input tokens. Returns 0 rather than NaN when the window holds
  * no input tokens at all, so the tile renders "0,0 %" instead of "NaN %".