@carlonicora/nextjs-jsonapi 1.142.0 → 1.143.0

package/dist/{s3.service-DYflLXCt.d.mts → s3.service-Dt6MfuHr.d.mts}

@@ -1,129 +1,8 @@
+import { A as AbstractService, N as NextRef, P as PreviousRef } from './AbstractService-B0T7h8fX.mjs';
 import { F as FeatureInterface } from './feature.interface-CXb1-vNq.mjs';
 import { e as RoleInterface, U as UserInterface, f as UserInput, c as CompanyInterface, b as CompanyInput, C as ContentInterface, N as NotificationInterface } from './notification.interface-CG1vqoxg.mjs';
 import { A as ApiDataInterface, J as JsonApiHydratedDataInterface } from './ApiDataInterface-BcZeXy5X.mjs';
 import { A as AuthInput, b as AuthInterface } from './auth.interface-CkmZqat3.mjs';
-import { A as ApiRequestDataTypeInterface } from './ApiRequestDataTypeInterface-CYEcRUrh.mjs';
-
-declare enum HttpMethod {
-    GET = "GET",
-    POST = "POST",
-    PUT = "PUT",
-    PATCH = "PATCH",
-    DELETE = "DELETE"
-}
-interface NextRef {
-    next?: string;
-}
-interface PreviousRef {
-    previous?: string;
-}
-interface SelfRef {
-    self?: string;
-}
-interface TotalRef {
-    total?: number;
-}
-declare function getLastApiTotal(): number | undefined;
-declare function clearLastApiTotal(): void;
-declare function getLastApiMeta(): Record<string, any> | undefined;
-declare function clearLastApiMeta(): void;
-/**
- * Set a global error handler for API errors (client-side only).
- * This handler will be called instead of throwing errors.
- */
-declare function setGlobalErrorHandler(handler: (status: number, message: string) => void): void;
-/**
- * Get the current global error handler.
- */
-declare function getGlobalErrorHandler(): ((status: number, message: string) => void) | null;
-/**
- * Abstract base class for services that interact with the JSON:API.
- * Extend this class to create feature-specific services.
- */
-declare abstract class AbstractService {
-    /**
-     * Extract locale from client-side URL pathname
-     * URL structure: /{locale}/route-path (e.g., /it/accounts)
-     * Fallback chain: URL locale → navigator.language → "en"
-     */
-    private static getClientLocale;
-    static next<T>(params: {
-        type: ApiRequestDataTypeInterface;
-        endpoint: string;
-        next?: NextRef;
-        previous?: PreviousRef;
-        self?: SelfRef;
-        total?: TotalRef;
-    }): Promise<T>;
-    /**
-     * Fetch the previous page of results.
-     */
-    static previous<T>(params: {
-        type: ApiRequestDataTypeInterface;
-        endpoint: string;
-        next?: NextRef;
-        previous?: PreviousRef;
-        self?: SelfRef;
-        total?: TotalRef;
-    }): Promise<T>;
-    /**
-     * Make an API call with automatic environment detection and error handling.
-     */
-    protected static callApi<T>(params: {
-        type: ApiRequestDataTypeInterface;
-        method: HttpMethod;
-        endpoint: string;
-        companyId?: string;
-        input?: any;
-        overridesJsonApiCreation?: boolean;
-        next?: NextRef;
-        previous?: PreviousRef;
-        self?: SelfRef;
-        total?: TotalRef;
-        responseType?: ApiRequestDataTypeInterface;
-        files?: {
-            [key: string]: File | Blob;
-        } | File | Blob;
-        token?: string;
-        suppressGlobalError?: boolean;
-        /**
-         * Per-call override of the API base URL. When omitted, the existing global
-         * `NEXT_PUBLIC_API_URL` (or `configureJsonApi({ apiUrl })`) resolution is used —
-         * fully backward compatible. Ignored when `endpoint` starts with "http" (passthrough).
-         */
-        baseUrl?: string;
-    }): Promise<T>;
-    /**
-     * Make an API call and return both data and meta from the response.
-     */
-    protected static callApiWithMeta<T>(params: {
-        type: ApiRequestDataTypeInterface;
-        method: HttpMethod;
-        endpoint: string;
-        companyId?: string;
-        input?: any;
-        overridesJsonApiCreation?: boolean;
-        responseType?: ApiRequestDataTypeInterface;
-        files?: {
-            [key: string]: File | Blob;
-        } | File | Blob;
-        suppressGlobalError?: boolean;
-    }): Promise<{
-        data: T;
-        meta?: Record<string, any>;
-    }>;
-    /**
-     * Get raw JSON:API response data without deserialization.
-     */
-    protected static getRawData(params: {
-        type: ApiRequestDataTypeInterface;
-        method: HttpMethod;
-        endpoint: string;
-        companyId?: string;
-        baseUrl?: string;
-        suppressGlobalError?: boolean;
-    }): Promise<any>;
-}
 
 declare class FeatureService extends AbstractService {
     static findMany(params: {
@@ -388,4 +267,4 @@ declare class S3Service extends AbstractService {
     }): Promise<void>;
 }
 
-export { AuthService as A, CompanyService as C, FeatureService as F, HttpMethod as H, NotificationService as N, PushService as P, RoleService as R, S3Service as S, type TotalRef as T, UserService as U, ContentService as a, AbstractService as b, type NextRef as c, type PreviousRef as d, type SelfRef as e, clearLastApiTotal as f, getLastApiTotal as g, getLastApiMeta as h, clearLastApiMeta as i, getGlobalErrorHandler as j, type TwoFactorChallengeInterface as k, type S3Input as l, type S3Interface as m, setGlobalErrorHandler as s };
+export { AuthService as A, CompanyService as C, FeatureService as F, NotificationService as N, PushService as P, RoleService as R, S3Service as S, type TwoFactorChallengeInterface as T, UserService as U, ContentService as a, type S3Input as b, type S3Interface as c };

package/dist/server/index.d.mts

@@ -1,10 +1,11 @@
 import { A as ApiData } from '../ApiData-DPKNfY-9.mjs';
-import { M as ModuleWithPermissions, A as Action } from '../types-CQSjy7et.mjs';
+import { M as ModuleWithPermissions, A as Action } from '../types-Bq_UA8Lg.mjs';
 import { A as ApiRequestDataTypeInterface } from '../ApiRequestDataTypeInterface-CYEcRUrh.mjs';
 import { A as ApiResponseInterface } from '../ApiResponseInterface-rsXRL_Hn.mjs';
-export { A as ServerAuthService, C as ServerCompanyService, a as ServerContentService, F as ServerFeatureService, N as ServerNotificationService, P as ServerPushService, R as ServerRoleService, S as ServerS3Service, U as ServerUserService } from '../s3.service-DYflLXCt.mjs';
+export { A as ServerAuthService, C as ServerCompanyService, a as ServerContentService, F as ServerFeatureService, N as ServerNotificationService, P as ServerPushService, R as ServerRoleService, S as ServerS3Service, U as ServerUserService } from '../s3.service-Dt6MfuHr.mjs';
 import 'lucide-react';
 import '../ApiDataInterface-BcZeXy5X.mjs';
+import '../AbstractService-B0T7h8fX.mjs';
 import '../feature.interface-CXb1-vNq.mjs';
 import '../notification.interface-CG1vqoxg.mjs';
 import '../auth.interface-CkmZqat3.mjs';

package/dist/server/index.d.ts

@@ -1,10 +1,11 @@
 import { A as ApiData } from '../ApiData-DPKNfY-9.js';
-import { M as ModuleWithPermissions, A as Action } from '../types-DHOxe8rc.js';
+import { M as ModuleWithPermissions, A as Action } from '../types-bsm8Fp55.js';
 import { A as ApiRequestDataTypeInterface } from '../ApiRequestDataTypeInterface-CYEcRUrh.js';
 import { A as ApiResponseInterface } from '../ApiResponseInterface-CWLvSCvS.js';
-export { A as ServerAuthService, C as ServerCompanyService, a as ServerContentService, F as ServerFeatureService, N as ServerNotificationService, P as ServerPushService, R as ServerRoleService, S as ServerS3Service, U as ServerUserService } from '../s3.service-Dmfxpn-k.js';
+export { A as ServerAuthService, C as ServerCompanyService, a as ServerContentService, F as ServerFeatureService, N as ServerNotificationService, P as ServerPushService, R as ServerRoleService, S as ServerS3Service, U as ServerUserService } from '../s3.service-CpwA3sl_.js';
 import 'lucide-react';
 import '../ApiDataInterface-BcZeXy5X.js';
+import '../AbstractService-Cew0PD0L.js';
 import '../feature.interface-BO25VLlx.js';
 import '../notification.interface--27exGde.js';
 import '../auth.interface-COmBjh89.js';

package/dist/server/index.js

@@ -15,7 +15,7 @@ var _chunkIOLU4ASDjs = require('../chunk-IOLU4ASD.js');
 
 
 
-var _chunk5SFFHIEEjs = require('../chunk-5SFFHIEE.js');
+var _chunkDS4IBFWAjs = require('../chunk-DS4IBFWA.js');
 require('../chunk-LXKSUWAV.js');
 require('../chunk-IBS6NI7D.js');
 
@@ -86,7 +86,7 @@ var ServerSession = class {
     if (!rawModules) return false;
     const modules = JSON.parse(_pako.ungzip.call(void 0, Buffer.from(rawModules, "base64"), { toText: true }));
     const selectedModule = modules.find((module) => module.id === params.module.moduleId);
-    return _chunk5SFFHIEEjs.checkPermissionsFromServer.call(void 0, {
+    return _chunkDS4IBFWAjs.checkPermissionsFromServer.call(void 0, {
       module: params.module,
       action: params.action,
       data: params.data,
@@ -296,5 +296,5 @@ _chunk7QVYU63Ejs.__name.call(void 0, ServerJsonApiDelete, "ServerJsonApiDelete")
 
 
 
-exports.ServerAuthService = _chunk5SFFHIEEjs.AuthService; exports.ServerCompanyService = _chunk5SFFHIEEjs.CompanyService; exports.ServerContentService = _chunk5SFFHIEEjs.ContentService; exports.ServerFeatureService = _chunk5SFFHIEEjs.FeatureService; exports.ServerJsonApiDelete = ServerJsonApiDelete; exports.ServerJsonApiGet = ServerJsonApiGet; exports.ServerJsonApiPatch = ServerJsonApiPatch; exports.ServerJsonApiPost = ServerJsonApiPost; exports.ServerJsonApiPut = ServerJsonApiPut; exports.ServerNotificationService = _chunk5SFFHIEEjs.NotificationService; exports.ServerPushService = _chunk5SFFHIEEjs.PushService; exports.ServerRoleService = _chunk5SFFHIEEjs.RoleService; exports.ServerS3Service = _chunk5SFFHIEEjs.S3Service; exports.ServerSession = ServerSession; exports.ServerUserService = _chunk5SFFHIEEjs.UserService; exports.configureServerJsonApi = configureServerJsonApi; exports.getServerApiUrl = getServerApiUrl; exports.getServerAppUrl = getServerAppUrl; exports.getServerToken = _chunkYUO55Q5Ajs.getServerToken; exports.getServerTrackablePages = getServerTrackablePages; exports.invalidateCacheTag = invalidateCacheTag; exports.invalidateCacheTags = invalidateCacheTags; exports.serverRequest = _chunkIOLU4ASDjs.serverRequest;
+exports.ServerAuthService = _chunkDS4IBFWAjs.AuthService; exports.ServerCompanyService = _chunkDS4IBFWAjs.CompanyService; exports.ServerContentService = _chunkDS4IBFWAjs.ContentService; exports.ServerFeatureService = _chunkDS4IBFWAjs.FeatureService; exports.ServerJsonApiDelete = ServerJsonApiDelete; exports.ServerJsonApiGet = ServerJsonApiGet; exports.ServerJsonApiPatch = ServerJsonApiPatch; exports.ServerJsonApiPost = ServerJsonApiPost; exports.ServerJsonApiPut = ServerJsonApiPut; exports.ServerNotificationService = _chunkDS4IBFWAjs.NotificationService; exports.ServerPushService = _chunkDS4IBFWAjs.PushService; exports.ServerRoleService = _chunkDS4IBFWAjs.RoleService; exports.ServerS3Service = _chunkDS4IBFWAjs.S3Service; exports.ServerSession = ServerSession; exports.ServerUserService = _chunkDS4IBFWAjs.UserService; exports.configureServerJsonApi = configureServerJsonApi; exports.getServerApiUrl = getServerApiUrl; exports.getServerAppUrl = getServerAppUrl; exports.getServerToken = _chunkYUO55Q5Ajs.getServerToken; exports.getServerTrackablePages = getServerTrackablePages; exports.invalidateCacheTag = invalidateCacheTag; exports.invalidateCacheTags = invalidateCacheTags; exports.serverRequest = _chunkIOLU4ASDjs.serverRequest;
 //# sourceMappingURL=index.js.map

package/dist/server/index.mjs

@@ -15,7 +15,7 @@ import {
   S3Service,
   UserService,
   checkPermissionsFromServer
-} from "../chunk-KZHHKPQZ.mjs";
+} from "../chunk-BIL2WQEV.mjs";
 import "../chunk-AUXK7QSA.mjs";
 import "../chunk-C7C7VY4F.mjs";
 import {

package/dist/tokenusage-admin.module-5wJ_tZTj.d.ts

@@ -0,0 +1,61 @@
+import { A as ApiDataInterface, J as JsonApiHydratedDataInterface } from './ApiDataInterface-BcZeXy5X.js';
+import { A as ApiRequestDataTypeInterface } from './ApiRequestDataTypeInterface-CYEcRUrh.js';
+import { a as ModuleFactory, M as ModuleWithPermissions } from './types-bsm8Fp55.js';
+
+declare abstract class AbstractApiData implements ApiDataInterface {
+    static identifierFields: string[];
+    get identifier(): string;
+    protected _jsonApi?: any;
+    protected _included?: any[];
+    protected _id?: string;
+    protected _type?: string;
+    protected _createdAt?: Date;
+    protected _updatedAt?: Date;
+    protected _self?: string;
+    get type(): string;
+    get id(): string;
+    get self(): string | undefined;
+    get createdAt(): Date;
+    get updatedAt(): Date;
+    get included(): any[];
+    get jsonApi(): any;
+    ingestJsonApi(_data: JsonApiHydratedDataInterface): void;
+    generateApiUrl(_params?: any): string;
+    createJsonApi(_data?: any): any;
+    protected _readIncluded<T extends ApiDataInterface>(data: JsonApiHydratedDataInterface, type: string, dataType: ApiRequestDataTypeInterface): T | T[] | undefined;
+    /**
+     * Read included relationships with polymorphic type resolution.
+     * Determines the correct model class based on the JSON:API type in included data.
+     */
+    protected _readIncludedPolymorphic<T extends ApiDataInterface>(data: JsonApiHydratedDataInterface, relationshipKey: string, candidateModules: ApiRequestDataTypeInterface[]): T | T[] | undefined;
+    /**
+     * Read included relationship data and augment with relationship meta properties.
+     * Handles both single relationships (one-to-one) and array relationships (one-to-many).
+     *
+     * For single relationships: meta is read from `relationships[type].meta`
+     * For array relationships: per-item meta is read from `relationships[type].data[].meta`
+     *
+     * @param data - Hydrated JSON:API data
+     * @param type - Relationship type key (e.g., "guide", "persons")
+     * @param dataType - Module reference for rehydration
+     * @returns Related object(s) augmented with meta properties, or undefined
+     */
+    protected _readIncludedWithMeta<T extends ApiDataInterface, M extends Record<string, any>>(data: JsonApiHydratedDataInterface, type: string, dataType: ApiRequestDataTypeInterface): (T & M) | (T & M)[] | undefined;
+    dehydrate(): JsonApiHydratedDataInterface;
+    rehydrate(data: JsonApiHydratedDataInterface): this;
+}
+
+/**
+ * Read-only reporting resources behind the administrative token-usage page.
+ * `name` is the endpoint path EndpointCreator builds URLs from; there is no
+ * pageUrl because these are not navigable resources.
+ *
+ * Distinct from the consuming app's own TokenUsage module (name "tokenusages",
+ * pageUrl "/tokenusage") — that one is an AppModuleDefinitions entry the package
+ * cannot reference, which is why these three exist.
+ */
+declare const TokenUsageAdminSummaryModule: (factory: ModuleFactory) => ModuleWithPermissions;
+declare const TokenUsageAdminTimelineModule: (factory: ModuleFactory) => ModuleWithPermissions;
+declare const TokenUsageAdminBreakdownModule: (factory: ModuleFactory) => ModuleWithPermissions;
+
+export { AbstractApiData as A, TokenUsageAdminSummaryModule as T, TokenUsageAdminTimelineModule as a, TokenUsageAdminBreakdownModule as b };

package/dist/tokenusage-admin.module-DQVT4O4j.d.mts

@@ -0,0 +1,61 @@
+import { A as ApiDataInterface, J as JsonApiHydratedDataInterface } from './ApiDataInterface-BcZeXy5X.mjs';
+import { A as ApiRequestDataTypeInterface } from './ApiRequestDataTypeInterface-CYEcRUrh.mjs';
+import { a as ModuleFactory, M as ModuleWithPermissions } from './types-Bq_UA8Lg.mjs';
+
+declare abstract class AbstractApiData implements ApiDataInterface {
+    static identifierFields: string[];
+    get identifier(): string;
+    protected _jsonApi?: any;
+    protected _included?: any[];
+    protected _id?: string;
+    protected _type?: string;
+    protected _createdAt?: Date;
+    protected _updatedAt?: Date;
+    protected _self?: string;
+    get type(): string;
+    get id(): string;
+    get self(): string | undefined;
+    get createdAt(): Date;
+    get updatedAt(): Date;
+    get included(): any[];
+    get jsonApi(): any;
+    ingestJsonApi(_data: JsonApiHydratedDataInterface): void;
+    generateApiUrl(_params?: any): string;
+    createJsonApi(_data?: any): any;
+    protected _readIncluded<T extends ApiDataInterface>(data: JsonApiHydratedDataInterface, type: string, dataType: ApiRequestDataTypeInterface): T | T[] | undefined;
+    /**
+     * Read included relationships with polymorphic type resolution.
+     * Determines the correct model class based on the JSON:API type in included data.
+     */
+    protected _readIncludedPolymorphic<T extends ApiDataInterface>(data: JsonApiHydratedDataInterface, relationshipKey: string, candidateModules: ApiRequestDataTypeInterface[]): T | T[] | undefined;
+    /**
+     * Read included relationship data and augment with relationship meta properties.
+     * Handles both single relationships (one-to-one) and array relationships (one-to-many).
+     *
+     * For single relationships: meta is read from `relationships[type].meta`
+     * For array relationships: per-item meta is read from `relationships[type].data[].meta`
+     *
+     * @param data - Hydrated JSON:API data
+     * @param type - Relationship type key (e.g., "guide", "persons")
+     * @param dataType - Module reference for rehydration
+     * @returns Related object(s) augmented with meta properties, or undefined
+     */
+    protected _readIncludedWithMeta<T extends ApiDataInterface, M extends Record<string, any>>(data: JsonApiHydratedDataInterface, type: string, dataType: ApiRequestDataTypeInterface): (T & M) | (T & M)[] | undefined;
+    dehydrate(): JsonApiHydratedDataInterface;
+    rehydrate(data: JsonApiHydratedDataInterface): this;
+}
+
+/**
+ * Read-only reporting resources behind the administrative token-usage page.
+ * `name` is the endpoint path EndpointCreator builds URLs from; there is no
+ * pageUrl because these are not navigable resources.
+ *
+ * Distinct from the consuming app's own TokenUsage module (name "tokenusages",
+ * pageUrl "/tokenusage") — that one is an AppModuleDefinitions entry the package
+ * cannot reference, which is why these three exist.
+ */
+declare const TokenUsageAdminSummaryModule: (factory: ModuleFactory) => ModuleWithPermissions;
+declare const TokenUsageAdminTimelineModule: (factory: ModuleFactory) => ModuleWithPermissions;
+declare const TokenUsageAdminBreakdownModule: (factory: ModuleFactory) => ModuleWithPermissions;
+
+export { AbstractApiData as A, TokenUsageAdminSummaryModule as T, TokenUsageAdminTimelineModule as a, TokenUsageAdminBreakdownModule as b };

package/dist/{types-CQSjy7et.d.mts → types-Bq_UA8Lg.d.mts}

@@ -98,4 +98,4 @@ type ModuleFactory = (params: {
     }>;
 }) => ModuleWithPermissions;
 
-export { Action as A, type ModuleWithPermissions as M, type PageUrl as P, type PermissionCheck as a, type ModulePermissionDefinition as b, type ModuleDefinition as c, type PermissionConfig as d, type PermissionModule as e, type PermissionUser as f, type ModuleFactory as g };
+export { Action as A, type ModuleWithPermissions as M, type PageUrl as P, type ModuleFactory as a, type PermissionCheck as b, type ModulePermissionDefinition as c, type ModuleDefinition as d, type PermissionConfig as e, type PermissionModule as f, type PermissionUser as g };

package/dist/{types-DHOxe8rc.d.ts → types-bsm8Fp55.d.ts}

@@ -98,4 +98,4 @@ type ModuleFactory = (params: {
     }>;
 }) => ModuleWithPermissions;
 
-export { Action as A, type ModuleWithPermissions as M, type PageUrl as P, type PermissionCheck as a, type ModulePermissionDefinition as b, type ModuleDefinition as c, type PermissionConfig as d, type PermissionModule as e, type PermissionUser as f, type ModuleFactory as g };
+export { Action as A, type ModuleWithPermissions as M, type PageUrl as P, type ModuleFactory as a, type PermissionCheck as b, type ModulePermissionDefinition as c, type ModuleDefinition as d, type PermissionConfig as e, type PermissionModule as f, type PermissionUser as g };

package/dist/{usePageUrlGenerator-tjq2mlDV.d.ts → usePageUrlGenerator-J_ECv-oQ.d.ts}

@@ -1,4 +1,4 @@
-import { P as PageUrl } from './types-DHOxe8rc.js';
+import { P as PageUrl } from './types-bsm8Fp55.js';
 
 declare function usePageUrlGenerator(): (params: {
     page?: PageUrl | string;

package/dist/{usePageUrlGenerator-uOnyJ6j2.d.mts → usePageUrlGenerator-uKBjAKqC.d.mts}

@@ -1,4 +1,4 @@
-import { P as PageUrl } from './types-CQSjy7et.mjs';
+import { P as PageUrl } from './types-Bq_UA8Lg.mjs';
 
 declare function usePageUrlGenerator(): (params: {
     page?: PageUrl | string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "1.142.0",
+  "version": "1.143.0",
   "description": "Next.js JSON:API client with server/client support and caching",
   "author": "Carlo Nicora",
   "license": "GPL-3.0-or-later",
@@ -62,6 +62,11 @@
       "types": "./dist/features/help/server.d.ts",
       "import": "./dist/features/help/server.mjs",
       "require": "./dist/features/help/server.js"
+    },
+    "./tokenusage": {
+      "types": "./dist/features/tokenusage/index.d.ts",
+      "import": "./dist/features/tokenusage/index.mjs",
+      "require": "./dist/features/tokenusage/index.js"
     }
   },
   "scripts": {

package/src/core/index.ts

@@ -91,4 +91,9 @@ export * from "../features/rbac/rbac.module";
 export * from "../features/referral/data";
 export * from "../features/referral/referral.module";
 export * from "../features/referral/referral-stats.module";
+// Administrative token-usage reporting modules. Exported from core (not only
+// from the client-marked ./tokenusage barrel) so a consuming app can register
+// them in its bootstrapper without pulling the feature's client bundle —
+// same placement as waitlist-stats and referral-stats above.
+export * from "../features/tokenusage/tokenusage-admin.module";
 export * from "../features/audit-log";

package/src/core/registry/ModuleRegistry.ts

@@ -58,6 +58,10 @@ export interface FoundationModuleDefinitions {
   RbacMatrix: ModuleWithPermissions;
   // Audit modules
   AuditLog: ModuleWithPermissions;
+  // Administrative token-usage reporting modules
+  TokenUsageAdminSummary: ModuleWithPermissions;
+  TokenUsageAdminTimeline: ModuleWithPermissions;
+  TokenUsageAdminBreakdown: ModuleWithPermissions;
 }
 
 // App-specific modules - apps will augment this interface ONLY

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

@@ -0,0 +1,189 @@
+"use client";
+
+import { cn } from "../../../lib/utils";
+import { useTranslations } from "next-intl";
+import { useMemo } from "react";
+import { RoundPageContainer } from "../../../components";
+import {
+  Card,
+  CardAction,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "../../../shadcnui";
+import { useTokenUsageAdmin } from "../contexts/TokenUsageAdminContext";
+import type { StackBy } from "../data/tokenusage-admin.types";
+import { TokenUsageAdminTiles } from "./TokenUsageAdminTiles";
+import { TokenUsageBreakdownTable } from "./TokenUsageBreakdownTable";
+import { TokenUsageRankedBar } from "./TokenUsageRankedBar";
+import { TokenUsageTimelineChart } from "./TokenUsageTimelineChart";
+
+const STACK_BY_VALUES: StackBy[] = ["scope", "type", "company"];
+
+/**
+ * Page body for the administrative token-usage dashboard.
+ *
+ * Stateless by design — every value it renders comes from
+ * `useTokenUsageAdmin()`. The filter bar is deliberately NOT here: it belongs to
+ * the page title bar, which `RoundPageContainer` fills from `SharedContext`, so
+ * the provider publishes it (see TokenUsageAdminContext).
+ */
+export function TokenUsageAdminContainer() {
+  const t = useTranslations();
+  const {
+    summary,
+    timeline,
+    byCompany,
+    byUser,
+    byOperation,
+    byCustomerOperation,
+    filters,
+    setFilters,
+    singleCustomerMode,
+    isLoading,
+    error,
+  } = useTokenUsageAdmin();
+
+  const stackByItems = useMemo(
+    () => ({
+      scope: t("token_usage.admin.stack.scope"),
+      type: t("token_usage.admin.stack.type"),
+      company: t("token_usage.admin.stack.company"),
+    }),
+    [t],
+  );
+
+  if (error) {
+    return (
+      <RoundPageContainer fullWidth forceHeader>
+        <div className="p-4">
+          <Card>
+            <CardContent>
+              <p className="text-destructive text-xs/relaxed">{error}</p>
+            </CardContent>
+          </Card>
+        </div>
+      </RoundPageContainer>
+    );
+  }
+
+  // Loading renders nothing in the body: the title bar (with the filter bar) is
+  // already mounted, so a spinner would only make the controls jump on arrival.
+  if (isLoading) return <RoundPageContainer fullWidth forceHeader />;
+
+  const emptyLabel = t("token_usage.admin.no_data");
+
+  return (
+    <RoundPageContainer fullWidth forceHeader>
+      <div className="flex w-full flex-col gap-4 p-4">
+        <TokenUsageAdminTiles summary={summary} metric={filters.metric} singleCustomerMode={singleCustomerMode} />
+
+        <Card>
+          <CardHeader>
+            <CardTitle>{t("token_usage.admin.usage_over_time")}</CardTitle>
+            <CardAction>
+              <div className="flex items-center gap-2">
+                <span className="text-muted-foreground text-xs">{t("token_usage.admin.stack_by")}</span>
+                <Select
+                  items={stackByItems}
+                  value={filters.stackBy}
+                  onValueChange={(value) => {
+                    if (value) setFilters({ stackBy: value as StackBy });
+                  }}
+                >
+                  <SelectTrigger size="sm" className="w-36">
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {STACK_BY_VALUES.map((value) => (
+                      <SelectItem key={value} value={value}>
+                        {stackByItems[value]}
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              </div>
+            </CardAction>
+          </CardHeader>
+          <CardContent>
+            <TokenUsageTimelineChart rows={timeline} metric={filters.metric} stackBy={filters.stackBy} />
+          </CardContent>
+        </Card>
+
+        <div className="grid gap-4 md:grid-cols-2">
+          <Card>
+            <CardHeader>
+              <CardTitle>{t("token_usage.admin.by_company")}</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <TokenUsageRankedBar rows={byCompany} metric={filters.metric} emptyLabel={emptyLabel} />
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>{t("token_usage.admin.by_user")}</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <TokenUsageRankedBar rows={byUser} metric={filters.metric} emptyLabel={emptyLabel} />
+            </CardContent>
+          </Card>
+        </div>
+
+        {/* The two cost centres, broken down the same way so they can be read
+            against each other. Operation types are vocabulary, not data — unlike
+            the company and user panels above, these labels get translated.
+
+            Platform spend has no owning company, so a company filter makes that
+            half meaningless: the provider skips the request and the card is
+            hidden rather than rendered empty, leaving the customer half full
+            width. */}
+        <div className={cn("grid gap-4", !singleCustomerMode && "md:grid-cols-2")}>
+          <Card>
+            <CardHeader>
+              <CardTitle>{t("token_usage.admin.customer_by_operation")}</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <TokenUsageRankedBar
+                rows={byCustomerOperation}
+                metric={filters.metric}
+                emptyLabel={emptyLabel}
+                labelsAreOperationTypes
+              />
+            </CardContent>
+          </Card>
+
+          {!singleCustomerMode && (
+            <Card>
+              <CardHeader>
+                <CardTitle>{t("token_usage.admin.platform_by_operation")}</CardTitle>
+              </CardHeader>
+              <CardContent>
+                <TokenUsageRankedBar
+                  rows={byOperation}
+                  metric={filters.metric}
+                  emptyLabel={emptyLabel}
+                  labelsAreOperationTypes
+                />
+              </CardContent>
+            </Card>
+          )}
+        </div>
+
+        <Card>
+          <CardHeader>
+            <CardTitle>{t("token_usage.admin.detail")}</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <TokenUsageBreakdownTable rows={byCompany} metric={filters.metric} />
+          </CardContent>
+        </Card>
+      </div>
+    </RoundPageContainer>
+  );
+}