@carlonicora/nextjs-jsonapi 1.142.0 → 1.143.0

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

@@ -0,0 +1,54 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
+import { TokenUsageAdminBreakdownInterface } from "./tokenusage-admin-breakdown.interface";
+import { TokenUsageAdminSummaryInterface } from "./tokenusage-admin-summary.interface";
+import { TokenUsageAdminTimelineInterface } from "./tokenusage-admin-timeline.interface";
+import { Dimension, Granularity, Scope, StackBy, TokenUsageAdminFilters } from "./tokenusage-admin.types";
+
+function withFilters(endpoint: EndpointCreator, filters: TokenUsageAdminFilters): EndpointCreator {
+  endpoint.addAdditionalParam("from", filters.from);
+  endpoint.addAdditionalParam("to", filters.to);
+  if (filters.companyId) endpoint.addAdditionalParam("companyId", filters.companyId);
+  return endpoint;
+}
+
+export class TokenUsageAdminService extends AbstractService {
+  /** Six rows: {customer, platform, total} × {current, previous}. */
+  static async getSummary(filters: TokenUsageAdminFilters): Promise<TokenUsageAdminSummaryInterface[]> {
+    const endpoint = withFilters(new EndpointCreator({ endpoint: Modules.TokenUsageAdminSummary }), filters);
+
+    return this.callApi<TokenUsageAdminSummaryInterface[]>({
+      type: Modules.TokenUsageAdminSummary,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+
+  static async getTimeline(
+    params: TokenUsageAdminFilters & { granularity: Granularity; stackBy: StackBy },
+  ): Promise<TokenUsageAdminTimelineInterface[]> {
+    const endpoint = withFilters(new EndpointCreator({ endpoint: Modules.TokenUsageAdminTimeline }), params);
+    endpoint.addAdditionalParam("granularity", params.granularity);
+    endpoint.addAdditionalParam("stackBy", params.stackBy);
+
+    return this.callApi<TokenUsageAdminTimelineInterface[]>({
+      type: Modules.TokenUsageAdminTimeline,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+
+  static async getBreakdown(
+    params: TokenUsageAdminFilters & { dimension: Dimension; scope: Scope; limit?: number },
+  ): Promise<TokenUsageAdminBreakdownInterface[]> {
+    const endpoint = withFilters(new EndpointCreator({ endpoint: Modules.TokenUsageAdminBreakdown }), params);
+    endpoint.addAdditionalParam("dimension", params.dimension);
+    endpoint.addAdditionalParam("scope", params.scope);
+    if (params.limit !== undefined) endpoint.addAdditionalParam("limit", String(params.limit));
+
+    return this.callApi<TokenUsageAdminBreakdownInterface[]>({
+      type: Modules.TokenUsageAdminBreakdown,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+}

package/src/features/tokenusage/data/__tests__/tokenusage-admin-models.spec.ts

@@ -0,0 +1,147 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { ModuleFactory, ModuleWithPermissions } from "../../../../permissions/types";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import {
+  TokenUsageAdminBreakdownModule,
+  TokenUsageAdminSummaryModule,
+  TokenUsageAdminTimelineModule,
+} from "../../tokenusage-admin.module";
+import { TokenUsageAdminBreakdown } from "../tokenusage-admin-breakdown";
+import { TokenUsageAdminSummary } from "../tokenusage-admin-summary";
+import { TokenUsageAdminTimeline } from "../tokenusage-admin-timeline";
+
+// createJsonApi reads Modules.X.name (resolved lazily via ModuleRegistry), so
+// the modules must be registered before a model serialises — mirrors the
+// HowTo.spec / AssistantMessage.spec setup convention in this package.
+const moduleFactory: ModuleFactory = (params) =>
+  ({
+    pageUrl: params.pageUrl,
+    name: params.name,
+    model: params.model,
+  }) as ModuleWithPermissions;
+
+beforeAll(() => {
+  ModuleRegistry.register("TokenUsageAdminSummary", TokenUsageAdminSummaryModule(moduleFactory));
+  ModuleRegistry.register("TokenUsageAdminTimeline", TokenUsageAdminTimelineModule(moduleFactory));
+  ModuleRegistry.register("TokenUsageAdminBreakdown", TokenUsageAdminBreakdownModule(moduleFactory));
+});
+
+const hydrate = (attributes: Record<string, unknown>) =>
+  ({ jsonApi: { id: "x", type: "t", attributes }, included: [] }) as any;
+
+describe("token usage admin models", () => {
+  it("rehydrates every summary attribute", () => {
+    const m = new TokenUsageAdminSummary().rehydrate(
+      hydrate({
+        scope: "customer",
+        window: "current",
+        cost: 9.46,
+        credits: 3394,
+        tokensIn: 49244143,
+        tokensOut: 12,
+        cached: 75752,
+        calls: 2956,
+      }),
+    );
+    expect(m.scope).toBe("customer");
+    expect(m.window).toBe("current");
+    expect(m.cost).toBe(9.46);
+    expect(m.credits).toBe(3394);
+    expect(m.tokensIn).toBe(49244143);
+    expect(m.tokensOut).toBe(12);
+    expect(m.cached).toBe(75752);
+    expect(m.calls).toBe(2956);
+  });
+
+  it("parses the timeline bucket into a Date, not the wire string", () => {
+    const m = new TokenUsageAdminTimeline().rehydrate(
+      hydrate({
+        bucket: "2026-08-01",
+        series: "customer",
+        cost: 1,
+        credits: 1,
+        tokensIn: 1,
+        tokensOut: 1,
+        cached: 0,
+        calls: 1,
+      }),
+    );
+    expect(m.bucket).toBeInstanceOf(Date);
+    expect(m.bucket.toISOString().slice(0, 10)).toBe("2026-08-01");
+    expect(m.series).toBe("customer");
+  });
+
+  it("leaves company-only breakdown fields undefined on other dimensions", () => {
+    const m = new TokenUsageAdminBreakdown().rehydrate(
+      hydrate({
+        label: "m.rossi",
+        sublabel: "Studio Rossi",
+        cost: 3.74,
+        credits: 900,
+        tokensIn: 1,
+        tokensOut: 1,
+        cached: 0,
+        calls: 4,
+      }),
+    );
+    expect(m.label).toBe("m.rossi");
+    expect(m.sublabel).toBe("Studio Rossi");
+    expect(m.activeUsers).toBeUndefined();
+    expect(m.monthlyCredits).toBeUndefined();
+    expect(m.availableMonthlyCredits).toBeUndefined();
+  });
+
+  it("serialises a summary back to a JSON:API resource object", () => {
+    const doc = new TokenUsageAdminSummary().createJsonApi({
+      id: "customer|current",
+      scope: "customer",
+      window: "current",
+      cost: 9.46,
+      credits: 3394,
+      tokensIn: 1,
+      tokensOut: 2,
+      cached: 3,
+      calls: 4,
+    });
+
+    expect(doc.data.type).toBe("tokenusages/administration/summary");
+    expect(doc.data.id).toBe("customer|current");
+    expect(doc.data.attributes).toMatchObject({ scope: "customer", window: "current", cost: 9.46, calls: 4 });
+  });
+
+  it("emits the timeline bucket as YYYY-MM-DD via formatLocalDate, never a raw Date", () => {
+    const doc = new TokenUsageAdminTimeline().createJsonApi({
+      id: "2026-08-01|customer",
+      bucket: new Date(2026, 7, 1),
+      series: "customer",
+      cost: 1,
+      credits: 1,
+      tokensIn: 1,
+      tokensOut: 1,
+      cached: 0,
+      calls: 1,
+    });
+
+    expect(doc.data.attributes.bucket).toBe("2026-08-01");
+    expect(typeof doc.data.attributes.bucket).toBe("string");
+    // A raw Date would survive JSON.stringify as an ISO instant and UTC-shift.
+    expect(JSON.parse(JSON.stringify(doc)).data.attributes.bucket).toBe("2026-08-01");
+  });
+
+  it("omits absent optional breakdown attributes rather than emitting undefined", () => {
+    const doc = new TokenUsageAdminBreakdown().createJsonApi({
+      id: "u1",
+      label: "m.rossi",
+      cost: 1,
+      credits: 1,
+      tokensIn: 1,
+      tokensOut: 1,
+      cached: 0,
+      calls: 1,
+    });
+
+    expect(doc.data.attributes.label).toBe("m.rossi");
+    expect("sublabel" in doc.data.attributes).toBe(false);
+    expect("activeUsers" in doc.data.attributes).toBe(false);
+  });
+});

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

@@ -0,0 +1,8 @@
+export * from "./tokenusage-admin.types";
+export { TokenUsageAdminSummary } from "./tokenusage-admin-summary";
+export type { TokenUsageAdminSummaryInterface } from "./tokenusage-admin-summary.interface";
+export { TokenUsageAdminTimeline } from "./tokenusage-admin-timeline";
+export type { TokenUsageAdminTimelineInterface } from "./tokenusage-admin-timeline.interface";
+export { TokenUsageAdminBreakdown } from "./tokenusage-admin-breakdown";
+export type { TokenUsageAdminBreakdownInterface } from "./tokenusage-admin-breakdown.interface";
+export { TokenUsageAdminService } from "./TokenUsageAdminService";

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

@@ -0,0 +1,18 @@
+import { ApiDataInterface } from "../../../core";
+
+export interface TokenUsageAdminBreakdownInterface 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;
+  /** Company dimension only. */
+  get activeUsers(): number | undefined;
+  /** Company dimension only. */
+  get monthlyCredits(): number | undefined;
+  /** Company dimension only. */
+  get availableMonthlyCredits(): number | undefined;
+}

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

@@ -0,0 +1,115 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { TokenUsageAdminBreakdownInterface } from "./tokenusage-admin-breakdown.interface";
+import { TokenUsageAdminBreakdownInput } from "./tokenusage-admin.types";
+
+/**
+ * One ranked row of a breakdown. The same shape serves all three dimensions —
+ * company, user and operation — which is why the three "by-X" views collapse
+ * into a single `breakdown?dimension=` call.
+ *
+ * `activeUsers` / `monthlyCredits` / `availableMonthlyCredits` are populated only
+ * for `dimension=company`; they are absent on user and operation rows.
+ */
+export class TokenUsageAdminBreakdown extends AbstractApiData implements TokenUsageAdminBreakdownInterface {
+  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;
+  private _activeUsers?: number;
+  private _monthlyCredits?: number;
+  private _availableMonthlyCredits?: number;
+
+  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;
+  }
+
+  get activeUsers(): number | undefined {
+    return this._activeUsers;
+  }
+
+  get monthlyCredits(): number | undefined {
+    return this._monthlyCredits;
+  }
+
+  get availableMonthlyCredits(): number | undefined {
+    return this._availableMonthlyCredits;
+  }
+
+  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;
+    this._activeUsers = attrs.activeUsers ?? undefined;
+    this._monthlyCredits = attrs.monthlyCredits ?? undefined;
+    this._availableMonthlyCredits = attrs.availableMonthlyCredits ?? undefined;
+
+    return this;
+  }
+
+  createJsonApi(data: TokenUsageAdminBreakdownInput) {
+    const response: any = {
+      data: {
+        type: Modules.TokenUsageAdminBreakdown.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;
+    if (data.activeUsers !== undefined) response.data.attributes.activeUsers = data.activeUsers;
+    if (data.monthlyCredits !== undefined) response.data.attributes.monthlyCredits = data.monthlyCredits;
+    if (data.availableMonthlyCredits !== undefined)
+      response.data.attributes.availableMonthlyCredits = data.availableMonthlyCredits;
+
+    return response;
+  }
+}

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

@@ -0,0 +1,14 @@
+import { ApiDataInterface } from "../../../core";
+
+export interface TokenUsageAdminSummaryInterface extends ApiDataInterface {
+  /** "customer" | "platform" | "total" */
+  get scope(): string;
+  /** "current" | "previous" */
+  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-admin-summary.ts

@@ -0,0 +1,90 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { TokenUsageAdminSummaryInterface } from "./tokenusage-admin-summary.interface";
+import { TokenUsageAdminSummaryInput } from "./tokenusage-admin.types";
+
+/**
+ * One row of the administrative summary: a cost centre observed over one time
+ * window. Six rows are returned per request — scope crossed with window — so the
+ * KPI tiles can render a value and its delta without a second call.
+ */
+export class TokenUsageAdminSummary extends AbstractApiData implements TokenUsageAdminSummaryInterface {
+  private _scope: string = "";
+  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 scope(): string {
+    return this._scope;
+  }
+
+  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._scope = attrs.scope ?? "";
+    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: TokenUsageAdminSummaryInput) {
+    const response: any = {
+      data: {
+        type: Modules.TokenUsageAdminSummary.name,
+        id: data.id,
+        attributes: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    if (data.scope !== undefined) response.data.attributes.scope = data.scope;
+    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-admin-timeline.interface.ts

@@ -0,0 +1,13 @@
+import { ApiDataInterface } from "../../../core";
+
+export interface TokenUsageAdminTimelineInterface 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-admin-timeline.ts

@@ -0,0 +1,94 @@
+import { AbstractApiData, formatLocalDate, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { TokenUsageAdminTimelineInterface } from "./tokenusage-admin-timeline.interface";
+import { TokenUsageAdminTimelineInput } from "./tokenusage-admin.types";
+
+/**
+ * One (bucket, series) cell of the usage-over-time chart. Rows arrive flat; the
+ * chart pivots them into stacked columns.
+ */
+export class TokenUsageAdminTimeline extends AbstractApiData implements TokenUsageAdminTimelineInterface {
+  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: TokenUsageAdminTimelineInput) {
+    const response: any = {
+      data: {
+        type: Modules.TokenUsageAdminTimeline.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-admin.types.ts

@@ -0,0 +1,56 @@
+export type Granularity = "day" | "week" | "month";
+export type StackBy = "scope" | "type" | "company";
+export type Dimension = "company" | "user" | "operation";
+export type Scope = "customer" | "platform";
+export type Metric = "cost" | "credits" | "tokens";
+
+export type TokenUsageAdminFilters = {
+  /** ISO 8601 instant. */
+  from: string;
+  /** ISO 8601 instant. */
+  to: string;
+  companyId?: string;
+};
+
+// Input types for createJsonApi(). `id` is always required — JSON:API resource
+// objects are identified.
+
+export type TokenUsageAdminSummaryInput = {
+  id: string;
+  scope: string;
+  window: string;
+  cost: number;
+  credits: number;
+  tokensIn: number;
+  tokensOut: number;
+  cached: number;
+  calls: number;
+};
+
+export type TokenUsageAdminTimelineInput = {
+  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 TokenUsageAdminBreakdownInput = {
+  id: string;
+  label: string;
+  sublabel?: string;
+  cost: number;
+  credits: number;
+  tokensIn: number;
+  tokensOut: number;
+  cached: number;
+  calls: number;
+  activeUsers?: number;
+  monthlyCredits?: number;
+  availableMonthlyCredits?: number;
+};

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

@@ -0,0 +1,65 @@
+/**
+ * The fixed namespace of i18n keys the administrative token-usage feature reads
+ * via useTranslations/getTranslations. Consuming apps must define each entry in
+ * their messages/<locale>.json — this list is the contract between the package
+ * and the app.
+ *
+ * One key is NOT listed because it is resolved from data rather than from a
+ * fixed string: the timeline chart labels each series through
+ * `token_usage.types.<camelCase>` and falls back to the raw series key when the
+ * app has no entry, so that namespace stays the app's own vocabulary.
+ */
+export const TOKEN_USAGE_ADMIN_I18N_KEYS = [
+  // Page + KPI tiles
+  "token_usage.admin.title",
+  "token_usage.admin.customer_spend",
+  "token_usage.admin.platform_spend",
+  "token_usage.admin.total_cost",
+  "token_usage.admin.avg_per_call",
+  "token_usage.admin.cache_hit",
+  "token_usage.admin.vs_previous",
+
+  // Panel titles
+  "token_usage.admin.usage_over_time",
+  "token_usage.admin.by_company",
+  "token_usage.admin.by_user",
+  "token_usage.admin.customer_by_operation",
+  "token_usage.admin.platform_by_operation",
+  "token_usage.admin.detail",
+
+  // Shared states
+  "token_usage.admin.other",
+  "token_usage.admin.no_data",
+
+  // Filter bar
+  "token_usage.admin.all_companies",
+  "token_usage.admin.granularity.label",
+  "token_usage.admin.granularity.day",
+  "token_usage.admin.granularity.week",
+  "token_usage.admin.granularity.month",
+  "token_usage.admin.metric.label",
+  "token_usage.admin.metric.cost",
+  "token_usage.admin.metric.credits",
+  "token_usage.admin.metric.tokens",
+
+  // Timeline stacking control
+  "token_usage.admin.stack_by",
+  "token_usage.admin.stack.scope",
+  "token_usage.admin.stack.type",
+  "token_usage.admin.stack.company",
+
+  // Breakdown table columns
+  "token_usage.admin.columns.label",
+  "token_usage.admin.columns.sublabel",
+  "token_usage.admin.columns.calls",
+  "token_usage.admin.columns.tokens_in",
+  "token_usage.admin.columns.tokens_out",
+  "token_usage.admin.columns.cost",
+  "token_usage.admin.columns.credits",
+  "token_usage.admin.columns.share",
+  "token_usage.admin.columns.active_users",
+
+  // Timeline chart
+  "token_usage.series.other",
+  "token_usage.timeline.empty",
+] as const;