@carlonicora/nextjs-jsonapi 1.141.3 → 1.143.0

package/dist/{s3.service-BrmeMjtk.d.ts → s3.service-CpwA3sl_.d.ts}

@@ -1,129 +1,8 @@
+import { A as AbstractService, N as NextRef, P as PreviousRef } from './AbstractService-Cew0PD0L.js';
 import { F as FeatureInterface } from './feature.interface-BO25VLlx.js';
-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-LKFmZndR.js';
+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--27exGde.js';
 import { A as ApiDataInterface, J as JsonApiHydratedDataInterface } from './ApiDataInterface-BcZeXy5X.js';
-import { A as AuthInput, b as AuthInterface } from './auth.interface-yivTb46w.js';
-import { A as ApiRequestDataTypeInterface } from './ApiRequestDataTypeInterface-CYEcRUrh.js';
-
-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>;
-}
+import { A as AuthInput, b as AuthInterface } from './auth.interface-COmBjh89.js';
 
 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/{s3.service-CXKV_OT-.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-B3kNUTZs.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-r3XKYOrQ.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>;
-}
+import { A as AuthInput, b as AuthInterface } from './auth.interface-CkmZqat3.mjs';
 
 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,13 +1,14 @@
 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-CXKV_OT-.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-B3kNUTZs.mjs';
-import '../auth.interface-r3XKYOrQ.mjs';
+import '../notification.interface-CG1vqoxg.mjs';
+import '../auth.interface-CkmZqat3.mjs';
 
 type CacheProfile = "seconds" | "minutes" | "hours" | "days" | "weeks" | "max" | "default";
 /**

package/dist/server/index.d.ts

@@ -1,13 +1,14 @@
 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-BrmeMjtk.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-LKFmZndR.js';
-import '../auth.interface-yivTb46w.js';
+import '../notification.interface--27exGde.js';
+import '../auth.interface-COmBjh89.js';
 
 type CacheProfile = "seconds" | "minutes" | "hours" | "days" | "weeks" | "max" | "default";
 /**

package/dist/server/index.js

@@ -15,7 +15,7 @@ var _chunkIOLU4ASDjs = require('../chunk-IOLU4ASD.js');
 
 
 
-var _chunkAGKZCRG2js = require('../chunk-AGKZCRG2.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 _chunkAGKZCRG2js.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 = _chunkAGKZCRG2js.AuthService; exports.ServerCompanyService = _chunkAGKZCRG2js.CompanyService; exports.ServerContentService = _chunkAGKZCRG2js.ContentService; exports.ServerFeatureService = _chunkAGKZCRG2js.FeatureService; exports.ServerJsonApiDelete = ServerJsonApiDelete; exports.ServerJsonApiGet = ServerJsonApiGet; exports.ServerJsonApiPatch = ServerJsonApiPatch; exports.ServerJsonApiPost = ServerJsonApiPost; exports.ServerJsonApiPut = ServerJsonApiPut; exports.ServerNotificationService = _chunkAGKZCRG2js.NotificationService; exports.ServerPushService = _chunkAGKZCRG2js.PushService; exports.ServerRoleService = _chunkAGKZCRG2js.RoleService; exports.ServerS3Service = _chunkAGKZCRG2js.S3Service; exports.ServerSession = ServerSession; exports.ServerUserService = _chunkAGKZCRG2js.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-5GVY2M5X.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/dist/{useSocket-BsbaGPqE.d.ts → useSocket-DgGAQW6h.d.ts}

@@ -1,4 +1,4 @@
-import { N as NotificationInterface } from './notification.interface-LKFmZndR.js';
+import { N as NotificationInterface } from './notification.interface--27exGde.js';
 
 interface UseSocketOptions {
     token: string;

package/dist/{useSocket-BSjn1Rlb.d.mts → useSocket-M3YY0aTS.d.mts}

@@ -1,4 +1,4 @@
-import { N as NotificationInterface } from './notification.interface-B3kNUTZs.mjs';
+import { N as NotificationInterface } from './notification.interface-CG1vqoxg.mjs';
 
 interface UseSocketOptions {
     token: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "1.141.3",
+  "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/company/components/details/TokenStatusIndicator.tsx

@@ -31,12 +31,12 @@ export function TokenStatusIndicator({ className, size = "md", showExtraPages =
   // Don't render if no company data
   if (!company) return null;
 
-  const monthlyTokens = company.monthlyTokens;
-  const availableMonthlyTokens = company.availableMonthlyTokens;
-  const availableExtraTokens = company.availableExtraTokens;
+  const monthlyCredits = company.monthlyCredits;
+  const availableMonthlyCredits = company.availableMonthlyCredits;
+  const availableExtraCredits = company.availableExtraCredits;
 
   // Calculate percentage of available monthly pages
-  const percentage = monthlyTokens > 0 ? (availableMonthlyTokens / monthlyTokens) * 100 : 0;
+  const percentage = monthlyCredits > 0 ? (availableMonthlyCredits / monthlyCredits) * 100 : 0;
 
   const sizeClasses = {
     sm: "h-4 w-4",
@@ -91,7 +91,7 @@ export function TokenStatusIndicator({ className, size = "md", showExtraPages =
             {t("billing.tokens.monthly", { defaultValue: "Monthly Pages" })}:
           </span>
           <span className={cn("font-medium", getStatusColor())}>
-            {availableMonthlyTokens} / {monthlyTokens}
+            {availableMonthlyCredits} / {monthlyCredits}
           </span>
         </div>
         <div className="flex items-center justify-between gap-4">
@@ -108,7 +108,7 @@ export function TokenStatusIndicator({ className, size = "md", showExtraPages =
           <span className="text-muted-foreground">
             {t("billing.tokens.available_extra", { defaultValue: "Extra Pages" })}:
           </span>
-          <span className="font-medium text-blue-500">{availableExtraTokens}</span>
+          <span className="font-medium text-blue-500">{availableExtraCredits}</span>
         </div>
         <Link href="/settings/billing?action=subscribe" className="w-full flex justify-end my-4">
           <Button variant="outline" size="sm">
@@ -127,11 +127,11 @@ export function TokenStatusIndicator({ className, size = "md", showExtraPages =
           aria-label={t("billing.tokens.status", { defaultValue: "Page Status" })}
         >
           {getBatteryIcon()}
-          <span className={cn(textSize, "text-muted-foreground font-medium")}>{availableMonthlyTokens}</span>
-          {showExtraPages && availableExtraTokens > 0 && (
+          <span className={cn(textSize, "text-muted-foreground font-medium")}>{availableMonthlyCredits}</span>
+          {showExtraPages && availableExtraCredits > 0 && (
             <div className="inline-flex items-center gap-0.5">
               <PlusCircle className={cn(smallIconSize, "text-blue-500")} />
-              <span className={cn(textSize, "text-blue-500 font-medium")}>{availableExtraTokens}</span>
+              <span className={cn(textSize, "text-blue-500 font-medium")}>{availableExtraCredits}</span>
             </div>
           )}
         </div>

package/src/features/company/data/company.interface.ts

@@ -8,9 +8,9 @@ export type CompanyInput = {
   logo?: string;
   configurations?: any;
 
-  monthlyTokens?: number;
-  availableMonthlyTokens?: number;
-  availableExtraTokens?: number;
+  monthlyCredits?: number;
+  availableMonthlyCredits?: number;
+  availableExtraCredits?: number;
 
   featureIds?: string[];
   moduleIds?: string[];
@@ -34,9 +34,9 @@ export interface CompanyInterface extends ApiDataInterface {
 
   get isActiveSubscription(): boolean;
 
-  get monthlyTokens(): number;
-  get availableMonthlyTokens(): number;
-  get availableExtraTokens(): number;
+  get monthlyCredits(): number;
+  get availableMonthlyCredits(): number;
+  get availableExtraCredits(): number;
 
   get features(): FeatureInterface[];
   get modules(): ModuleInterface[];