adminizer 5.0.0-build.2 → 5.0.0-build.21

package/controllers/docs/index.js

@@ -0,0 +1,126 @@
+import { resolveModelResource } from '../../helpers/modelResourceHelper.js';
+import { getUiTranslations } from '../../lib/ui-i18n/getUiTranslations.js';
+import { DOCS_UI_TRANSLATION_KEYS } from '../../lib/ui-i18n/uiTranslationKeys.js';
+import { DataAccessor } from '../../lib/DataAccessor.js';
+/**
+ * Thin JSON proxy of the documentation subsystem: policies have checked the
+ * auth and the base token, `DocumentationHandler` applies per-document rights,
+ * the implementation does the actual work. No logic lives here.
+ */
+function requestedLocale(req) {
+    const locale = typeof req.query.locale === 'string' ? req.query.locale.trim() : '';
+    return locale || req.adminizer.documentationHandler.localeFor(req.user);
+}
+function describeMeta(meta) {
+    return {
+        id: meta.id,
+        title: meta.title,
+        section: meta.section,
+        keywords: meta.keywords,
+        models: meta.models,
+        urls: meta.urls,
+        locales: meta.locales,
+    };
+}
+export async function docsList(req, res) {
+    const documents = await req.adminizer.documentationHandler.list(req.user, requestedLocale(req));
+    return res.json({ documents: documents.map(describeMeta) });
+}
+export async function docsKeywords(req, res) {
+    const keywords = await req.adminizer.documentationHandler.keywords(req.user, requestedLocale(req));
+    return res.json({ keywords: Object.fromEntries(keywords) });
+}
+export async function docsSearch(req, res) {
+    const keywords = typeof req.query.keywords === 'string'
+        ? req.query.keywords.split(',').map((keyword) => keyword.trim()).filter(Boolean)
+        : undefined;
+    const results = await req.adminizer.documentationHandler.search(req.user, {
+        query: typeof req.query.q === 'string' ? req.query.q : undefined,
+        keywords,
+        url: typeof req.query.url === 'string' ? req.query.url : undefined,
+        model: typeof req.query.model === 'string' ? req.query.model : undefined,
+    }, requestedLocale(req));
+    return res.json({
+        results: results.map((result) => ({ ...describeMeta(result.meta), snippets: result.snippets })),
+    });
+}
+export async function docsContext(req, res) {
+    const documents = await req.adminizer.documentationHandler.forContext(req.user, {
+        url: typeof req.query.url === 'string' ? req.query.url : undefined,
+        model: typeof req.query.model === 'string' ? req.query.model : undefined,
+    }, requestedLocale(req));
+    return res.json({ documents: documents.map(describeMeta) });
+}
+export async function docsDoc(req, res) {
+    const content = await req.adminizer.documentationHandler.get(req.user, String(req.params.id ?? ''), requestedLocale(req));
+    // A document the user may not read does not exist for them.
+    if (!content) {
+        return res.status(404).json({ error: req.i18n?.__('Not found') || 'Not found' });
+    }
+    return res.json({ meta: describeMeta(content.meta), markdown: content.markdown, locale: content.locale });
+}
+/**
+ * Resolves references written inside a document to document ids. How a
+ * reference is spelled is the implementation's business; the viewer only
+ * learns which of them point at a document this user may open — the rest stay
+ * unresolved and are rendered as plain text.
+ */
+export async function docsResolve(req, res) {
+    const from = typeof req.query.from === 'string' ? req.query.from : '';
+    // `refs` is the comma-separated form the viewer uses; repeated `ref`
+    // parameters are accepted as well for hand-written calls.
+    const raw = req.query.ref;
+    const refs = [
+        ...(typeof req.query.refs === 'string' ? req.query.refs.split(',') : []),
+        ...(Array.isArray(raw) ? raw : [raw]),
+    ]
+        .filter((ref) => typeof ref === 'string' && ref.trim() !== '')
+        .map((ref) => ref.trim());
+    const resolved = {};
+    for (const ref of refs) {
+        const id = await req.adminizer.documentationHandler.resolveLink(req.user, from, ref);
+        if (id)
+            resolved[ref] = id;
+    }
+    return res.json({ resolved });
+}
+/**
+ * The viewer page. The document itself is fetched by the page through the API,
+ * so a deep link only has to name the document it opens with.
+ */
+export async function docsPage(req) {
+    return req.Inertia.render({
+        component: 'docs',
+        props: {
+            title: req.i18n.__('Documentation'),
+            docId: typeof req.params.id === 'string' ? req.params.id : null,
+            i18nPage: getUiTranslations(req, DOCS_UI_TRANSLATION_KEYS),
+        },
+    });
+}
+/**
+ * Structure of a model resource as this user is allowed to see it — the same
+ * fields DataAccessor would hand to the list page, nothing more.
+ */
+export async function docsSchema(req, res) {
+    const name = typeof req.query.model === 'string' ? req.query.model.trim() : '';
+    const resource = name ? resolveModelResource(req.adminizer, name) : undefined;
+    if (!resource) {
+        return res.status(404).json({ error: req.i18n.__('Model not found') });
+    }
+    if (!await req.adminizer.accessRightsHelper.hasPermission(`read-${resource.name}-model`, req.user)) {
+        return res.status(403).json({ error: req.i18n.__('Access denied') });
+    }
+    const fields = new DataAccessor(req.adminizer, req.user, resource, 'list').getFieldsConfig() ?? {};
+    return res.json({
+        model: resource.name,
+        title: req.i18n.__(resource.config?.title ?? resource.name),
+        url: resource.uri,
+        fields: Object.entries(fields).map(([key, field]) => ({
+            name: key,
+            title: field.config?.title ? req.i18n.__(field.config.title) : key,
+            type: String(field.config?.type ?? field.model?.type ?? 'string'),
+            required: Boolean(field.config?.required ?? field.model?.required),
+        })),
+    });
+}

package/controllers/edit.js

@@ -134,7 +134,7 @@ export default async function edit(req, res) {
             });
         }
     }
-    const props = inertiaAddHelper(req, modelResource, fields, record);
+    const props = await inertiaAddHelper(req, modelResource, fields, record);
     if (req.query?.without_layout) {
         return res.json({
             props: props

package/controllers/editGroup.js

@@ -44,13 +44,22 @@ export default async function editGroup(req, res) {
                     }
                 }
             }
-            if (key.startsWith("token-checkbox-") && req.body[key] === true) {
-                for (let token of allTokens) {
-                    if (token.id == key.slice(15)) {
-                        tokensOfThisGroup.push(token.id);
-                    }
-                }
+        }
+        for (const token of allTokens) {
+            if (req.body[`token-checkbox-${token.id}`] !== true)
+                continue;
+            if (!token.getOptions) {
+                tokensOfThisGroup.push(token.id);
+                continue;
             }
+            const submittedRights = req.body[`token-record-rights-${token.id}`];
+            const rights = Array.isArray(submittedRights)
+                ? Array.from(new Set(submittedRights.map(String)))
+                : [];
+            tokensOfThisGroup.push({
+                tokenId: token.id,
+                rights,
+            });
         }
         let updatedGroup;
         try {

package/controllers/feedback/feedbackController.d.ts

@@ -1,2 +1,2 @@
-import { Adminizer } from '../../lib/Adminizer';
+import { Adminizer } from '../../lib/Adminizer.js';
 export declare function bindFeedbackController(adminizer: Adminizer, middlewares: MiddlewareType[]): void;

package/controllers/filter-fields/savedFilters.js

@@ -125,7 +125,7 @@ export async function saveFilter(req, res) {
     }
     // Determine visibility and groupIds
     const isAdmin = req.user?.isAdministrator === true;
-    const canManageGroupVisibility = isAdmin || req.adminizer.accessRightsHelper.hasPermission(GROUP_FILTER_VISIBILITY_TOKEN, req.user);
+    const canManageGroupVisibility = isAdmin || await req.adminizer.accessRightsHelper.hasPermission(GROUP_FILTER_VISIBILITY_TOKEN, req.user);
     let effectiveVisibility = 'private';
     let effectiveGroupIds;
     if (visibility === 'public' && isAdmin) {

package/controllers/history-actions/HistoryController.d.ts

@@ -1,4 +1,4 @@
-import { AbstractHistoryAdapter } from "../../lib/history-actions/AbstractHistoryAdapter";
+import { AbstractHistoryAdapter } from "../../lib/history-actions/AbstractHistoryAdapter.js";
 export declare class HistoryController {
     static index(req: ReqType, res: ResType): Promise<any>;
     static getAllModelHistory(req: ReqType, res: ResType): Promise<any>;

package/controllers/history-actions/HistoryController.js

@@ -3,13 +3,13 @@ import { getUiTranslations } from "../../lib/ui-i18n/getUiTranslations.js";
 import { HISTORY_UI_TRANSLATION_KEYS } from "../../lib/ui-i18n/uiTranslationKeys.js";
 export class HistoryController {
     static async index(req, res) {
-        if (!HistoryController.checkHistoryPermission(req, res))
+        if (!await HistoryController.checkHistoryPermission(req, res))
             return;
         const adapter = HistoryController.getAdapter(req);
         if (req.method.toUpperCase() === 'GET') {
             const rawModels = adapter.getModels(req.user);
             let users = [];
-            const accessToUsersHistory = req.adminizer.accessRightsHelper.enoughPermissions([
+            const accessToUsersHistory = await req.adminizer.accessRightsHelper.enoughPermissions([
                 `users-history-${adapter.id}`
             ], req.user);
             if (accessToUsersHistory)
@@ -59,7 +59,7 @@ export class HistoryController {
         return res.status(405).end();
     }
     static async getAllModelHistory(req, res) {
-        if (!HistoryController.checkHistoryPermission(req, res))
+        if (!await HistoryController.checkHistoryPermission(req, res))
             return;
         const { modelId, modelName } = req.body;
         if (!modelId || !modelName) {
@@ -80,7 +80,7 @@ export class HistoryController {
         }
     }
     static async getModelFieldsHistory(req, res) {
-        if (!HistoryController.checkHistoryPermission(req, res))
+        if (!await HistoryController.checkHistoryPermission(req, res))
             return;
         const { historyId } = req.body;
         if (!historyId) {
@@ -103,12 +103,12 @@ export class HistoryController {
         const adapter = req.adminizer.config.history?.adapter ?? 'default';
         return req.adminizer.historyHandler.get(adapter);
     }
-    static checkHistoryPermission(req, res) {
+    static async checkHistoryPermission(req, res) {
         if (!req.adminizer?.historyHandler) {
             res.status(401).json({ error: 'History system not initialized' });
             return false;
         }
-        const hasPermission = req.adminizer.accessRightsHelper.hasPermission(`history-${req.adminizer.config.history?.adapter ?? 'default'}`, req.user);
+        const hasPermission = await req.adminizer.accessRightsHelper.hasPermission(`history-${req.adminizer.config.history?.adapter ?? 'default'}`, req.user);
         if (!hasPermission) {
             res.sendStatus(403);
             return false;

package/controllers/list.js

@@ -14,7 +14,7 @@ export default async function list(req, res) {
     }
     let dataAccessor = new DataAccessor(req.adminizer, req.user, modelResource, "list");
     let fields = dataAccessor.getFieldsConfig();
-    const header = inertiaListHelper(modelResource, req, fields);
+    const header = await inertiaListHelper(modelResource, req, fields);
     const i18nPage = getUiTranslations(req, FILTER_UI_TRANSLATION_KEYS);
     // Parse pagination
     const defaultPageSize = req.adminizer.config.list?.defaultPageSize ?? 50;

package/controllers/login.js

@@ -61,7 +61,7 @@ export default async function login(req, res) {
                         //Here we use the captchaSolution key to output messages unrelated to the form fields.
                         return inertiaAdminMessage(req, "Profile expired, contact the administrator", 'captchaSolution');
                     }
-                    if (!req.adminizer.accessRightsHelper.hasPermission('access-to-adminpanel', user)) {
+                    if (!await req.adminizer.accessRightsHelper.hasPermission('access-to-adminpanel', user)) {
                         return inertiaAdminMessage(req, "The user is not allowed to enter, please contact the administrator", 'captchaSolution');
                     }
                     const token = signUser({

package/controllers/media-manager/mediaManagerAdapter.d.ts

@@ -1,4 +1,4 @@
-import { AbstractMediaManager } from "../../lib/media-manager/AbstractMediaManager";
+import { AbstractMediaManager } from "../../lib/media-manager/AbstractMediaManager.js";
 export declare class MediaManagerAdapter {
     private manager;
     constructor(manager: AbstractMediaManager);

package/controllers/notifications/NotificationController.js

@@ -7,7 +7,7 @@ export class NotificationController {
             return;
         if (req.method.toUpperCase() === 'POST') {
             const { s, notificationClass } = req.body;
-            const hasPermission = req.adminizer.accessRightsHelper.hasPermission(`notification-${notificationClass}`, req.user);
+            const hasPermission = await req.adminizer.accessRightsHelper.hasPermission(`notification-${notificationClass}`, req.user);
             if (!hasPermission) {
                 res.status(403).json({ error: 'Forbidden' });
                 return;
@@ -42,7 +42,7 @@ export class NotificationController {
         const services = req.adminizer.notificationHandler.getAllServices();
         let activeServices = [];
         for (const service of services) {
-            const hasPermission = req.adminizer.accessRightsHelper.hasPermission(`notification-${service.notificationClass}`, req.user);
+            const hasPermission = await req.adminizer.accessRightsHelper.hasPermission(`notification-${service.notificationClass}`, req.user);
             if (hasPermission) {
                 activeServices.push({
                     displayName: req.i18n.__(service.displayName),
@@ -68,12 +68,12 @@ export class NotificationController {
         res.write(': stream-open\n\n');
         const clientId = `user-${req.user?.id}-${Date.now()}`;
         // Function for sending events to the client
-        const sendEvent = (event) => {
+        const sendEvent = async (event) => {
             // Filtering notifications by user rights
             if (event.type === 'notification') {
                 const notificationClass = event.notificationClass;
                 // UNIFIED rights check via AccessRightsHelper
-                const hasPermission = req.adminizer.accessRightsHelper.hasPermission(`notification-${notificationClass}`, req.user);
+                const hasPermission = await req.adminizer.accessRightsHelper.hasPermission(`notification-${notificationClass}`, req.user);
                 if (!hasPermission) {
                     return; // The user does not have rights to this notification class
                 }
@@ -88,7 +88,10 @@ export class NotificationController {
         };
         // We connect the client to all services
         const services = req.adminizer.notificationHandler.getAllServices();
-        const allowedServices = services.filter(service => req.adminizer.accessRightsHelper.hasPermission(`notification-${service.notificationClass}`, req.user));
+        const allowedServices = (await Promise.all(services.map(async (service) => ({
+            service,
+            allowed: await req.adminizer.accessRightsHelper.hasPermission(`notification-${service.notificationClass}`, req.user),
+        })))).filter(({ allowed }) => allowed).map(({ service }) => service);
         allowedServices.forEach(service => {
             service.addClient(clientId, sendEvent, req.user);
             // For a system service, add a client to CRUD channels
@@ -100,7 +103,7 @@ export class NotificationController {
             //     });
             // }
         });
-        sendEvent({
+        await sendEvent({
             type: 'connected',
             data: {
                 message: 'Connected to unified notification stream',
@@ -144,7 +147,7 @@ export class NotificationController {
             const { notificationClass } = req.params;
             const { limit = 20, skip = 0, unreadOnly = false } = req.query;
             // Checking access rights
-            const hasPermission = req.adminizer.accessRightsHelper.hasPermission(`notification-${notificationClass}`, req.user);
+            const hasPermission = await req.adminizer.accessRightsHelper.hasPermission(`notification-${notificationClass}`, req.user);
             if (!hasPermission) {
                 res.status(403).json({ error: 'Forbidden' });
                 return;
@@ -170,7 +173,10 @@ export class NotificationController {
         try {
             // Filtering services by access rights
             const services = req.adminizer.notificationHandler.getAllServices();
-            const allowedServices = services.filter(service => req.adminizer.accessRightsHelper.hasPermission(`notification-${service.notificationClass}`, req.user));
+            const allowedServices = (await Promise.all(services.map(async (service) => ({
+                service,
+                allowed: await req.adminizer.accessRightsHelper.hasPermission(`notification-${service.notificationClass}`, req.user),
+            })))).filter(({ allowed }) => allowed).map(({ service }) => service);
             const allNotifications = [];
             for (const service of allowedServices) {
                 const notifications = await service.getNotifications(req.user.id, Number(limit), Number(skip), unreadOnly === 'true');

package/controllers/view.js

@@ -29,7 +29,7 @@ export default async function view(req, res) {
         Adminizer.log.error(e);
         return res.status(500).send({ error: 'Internal Server Error' });
     }
-    switch (modelResource.config.model) {
+    switch (modelResource.name) {
         case 'User':
             let groups;
             try {
@@ -83,7 +83,7 @@ export default async function view(req, res) {
                     });
                 }
             }
-            const props = inertiaAddHelper(req, modelResource, fields, record, true);
+            const props = await inertiaAddHelper(req, modelResource, fields, record, true);
             return req.Inertia.render({
                 component: 'add',
                 props: props

package/controllers/widgets/filterInfo.js

@@ -28,7 +28,7 @@ export async function widgetFilterInfoController(req, res) {
     if (!filter || !filterService.canViewFilter(filter, user)) {
         return res.status(404).send({ error: req.i18n.__("Not found") });
     }
-    if (!req.adminizer.accessRightsHelper.hasPermission(`read-${filter.modelName}-model`, user)) {
+    if (!await req.adminizer.accessRightsHelper.hasPermission(`read-${filter.modelName}-model`, user)) {
         return res.sendStatus(403);
     }
     if (req.method.toUpperCase() === "GET") {

package/helpers/accessRightsHelper.d.ts

@@ -1,6 +1,7 @@
-import { User } from "../models/User";
-import { AccessRightsToken } from "../interfaces/types";
-import { Adminizer } from "../lib/Adminizer";
+import { User } from "../models/User.js";
+import { AccessRightsToken, GroupPermissionGrant, PermissionContext } from "../interfaces/types.js";
+import { Adminizer } from "../lib/Adminizer.js";
+export declare function parseGroupPermissionGrant(value: unknown): GroupPermissionGrant | null;
 export declare class AccessRightsHelper {
     private _tokens;
     adminizer: Adminizer;
@@ -8,13 +9,19 @@ export declare class AccessRightsHelper {
     registerToken(accessRightsToken: AccessRightsToken): void;
     unregisterToken(tokenId: string): boolean;
     hasToken(tokenId: string): boolean;
+    getToken(tokenId: string): AccessRightsToken | undefined;
     registerTokens(accessRightsTokens: AccessRightsToken[]): void;
     registerModelTokens(modelName: string, department?: string): void;
     getTokens(): AccessRightsToken[];
     getTokensByDepartment(department: string): AccessRightsToken[];
     getAllDepartments(): string[];
     enoughPermissions(tokens: string[], user: User): boolean;
-    hasPermission(tokenId: string | undefined, user: User, context?: string): boolean;
+    hasPermission(tokenId: string | undefined, user: User, context?: PermissionContext): boolean | Promise<boolean>;
+    /** Returns trusted option IDs granted by all groups for a contextual token. */
+    getPermissionRights(tokenId: string | undefined, user: User): string[] | null;
+    private getRegisteredToken;
+    private hasAssignedPermission;
+    private runTokenCheck;
 }
 export declare class GroupsAccessRightsHelper {
     static hasAccess(user: User, groupsAccessRights?: string[]): boolean;

package/helpers/accessRightsHelper.js

@@ -1,4 +1,18 @@
 import { Adminizer } from "../lib/Adminizer.js";
+export function parseGroupPermissionGrant(value) {
+    if (!value ||
+        typeof value !== "object" ||
+        typeof value.tokenId !== "string" ||
+        !Array.isArray(value.rights) ||
+        !value.rights.every((right) => typeof right === "string" || typeof right === "number")) {
+        return null;
+    }
+    const parsed = value;
+    return {
+        tokenId: parsed.tokenId.toLowerCase(),
+        rights: Array.from(new Set(parsed.rights.map(String))),
+    };
+}
 export class AccessRightsHelper {
     _tokens = [];
     adminizer;
@@ -10,6 +24,12 @@ export class AccessRightsHelper {
         if (!accessRightsToken.id || !accessRightsToken.name || !accessRightsToken.description || !accessRightsToken.department) {
             throw new Error("Adminpanel > Can not register token: Missed one or more required parameters");
         }
+        if (accessRightsToken.getOptions && typeof accessRightsToken.getOptions !== "function") {
+            throw new Error("Adminpanel > Can not register token: getOptions must be a function");
+        }
+        if (accessRightsToken.check && typeof accessRightsToken.check !== "function") {
+            throw new Error("Adminpanel > Can not register token: check must be a function");
+        }
         for (let i = 0; i < this._tokens.length; i++) {
             if (this._tokens[i].id === accessRightsToken.id) {
                 this._tokens.splice(i, 1);
@@ -31,6 +51,10 @@ export class AccessRightsHelper {
         const normalizedTokenId = tokenId.toLowerCase();
         return this._tokens.some((token) => token.id === normalizedTokenId);
     }
+    getToken(tokenId) {
+        const normalizedTokenId = tokenId.toLowerCase();
+        return this._tokens.find((token) => token.id === normalizedTokenId);
+    }
     registerTokens(accessRightsTokens) {
         for (let token of accessRightsTokens) {
             this.registerToken(token);
@@ -62,30 +86,76 @@ export class AccessRightsHelper {
         if (!tokens.length) {
             return true;
         }
-        return tokens.some((token) => this.hasPermission(token, user));
+        return tokens.some((token) => Boolean(this.hasPermission(token, user)));
     }
     hasPermission(tokenId, user, context) {
-        if (!this.adminizer.config.auth.enable) {
-            return true;
-        }
-        if (user.isAdministrator) {
+        if (!this.adminizer.config.auth.enable || user.isAdministrator) {
             return true;
         }
-        if (!tokenId) {
-            Adminizer.log.warn(`AccessRightsHelper > hasPermission: missing accessRightsToken${context ? ` [${context}]` : ''}`);
+        const token = this.getRegisteredToken(tokenId);
+        if (!token) {
             return false;
         }
-        tokenId = tokenId.toLowerCase();
-        const tokenIsValid = this._tokens.some((token) => token.id === tokenId);
-        if (!tokenIsValid) {
-            Adminizer.log.error("Adminpanel > Token is not valid", tokenId, user.login);
+        if (!this.hasAssignedPermission(token.id, user)) {
             return false;
         }
+        if (!token.check) {
+            return true;
+        }
+        return this.runTokenCheck(token, user, context ?? {});
+    }
+    /** Returns trusted option IDs granted by all groups for a contextual token. */
+    getPermissionRights(tokenId, user) {
+        if (!this.adminizer.config.auth.enable) {
+            return null;
+        }
+        if (user.isAdministrator) {
+            return null;
+        }
+        const token = this.getRegisteredToken(tokenId);
+        if (!token) {
+            return [];
+        }
         if (!user.groups) {
             Adminizer.log.error('User has no groups');
+            return [];
+        }
+        const rights = user.groups.flatMap((group) => group.tokens ?? [])
+            .map(parseGroupPermissionGrant)
+            .filter((grant) => grant?.tokenId === token.id)
+            .flatMap((grant) => grant.rights);
+        return Array.from(new Set(rights));
+    }
+    getRegisteredToken(tokenId) {
+        if (!tokenId) {
+            Adminizer.log.warn("AccessRightsHelper > hasPermission: missing accessRightsToken");
+            return undefined;
+        }
+        const token = this.getToken(tokenId);
+        if (!token) {
+            Adminizer.log.error("Adminpanel > Token is not valid", tokenId);
+        }
+        return token;
+    }
+    hasAssignedPermission(tokenId, user) {
+        if (!this.adminizer.config.auth.enable || user.isAdministrator) {
+            return true;
+        }
+        if (!user.groups) {
+            Adminizer.log.error("User has no groups");
+            return false;
+        }
+        return user.groups.some((group) => group.tokens?.some((groupToken) => groupToken === tokenId || parseGroupPermissionGrant(groupToken)?.tokenId === tokenId));
+    }
+    async runTokenCheck(token, user, context) {
+        try {
+            const rights = this.getPermissionRights(token.id, user) ?? [];
+            return await token.check(user, { ...context, rights });
+        }
+        catch (error) {
+            Adminizer.log.error("AccessRightsHelper > token check failed", token.id, error);
             return false;
         }
-        return user.groups.some((group) => group.tokens?.includes(tokenId));
     }
 }
 export class GroupsAccessRightsHelper {

package/helpers/assetVersionHelper.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Adminizer package version. Some built entries keep stable file names because
+ * they are imported by a hard-coded path and so cannot be looked up in the
+ * manifest (agent.es.js, controls/*.es.js and controls/*.css); for those this
+ * version is appended as a query string to invalidate browser caches on release.
+ *
+ * Only ever put this on a *self-contained* bundle. An entry whose split chunks
+ * import it back by name (app.js) must be content-hashed instead — a query
+ * string there makes the browser instantiate the module twice.
+ */
+export declare function getAssetVersion(): string;
+/** Appends ?v=<version> to a production asset URL; dev URLs pass through untouched. */
+export declare function withAssetVersion(url: string): string;
+export declare function withAssetVersion(url: string | undefined): string | undefined;

package/helpers/assetVersionHelper.js

@@ -0,0 +1,42 @@
+import fs from "fs";
+import path from "node:path";
+let cachedVersion = null;
+/**
+ * Adminizer package version. Some built entries keep stable file names because
+ * they are imported by a hard-coded path and so cannot be looked up in the
+ * manifest (agent.es.js, controls/*.es.js and controls/*.css); for those this
+ * version is appended as a query string to invalidate browser caches on release.
+ *
+ * Only ever put this on a *self-contained* bundle. An entry whose split chunks
+ * import it back by name (app.js) must be content-hashed instead — a query
+ * string there makes the browser instantiate the module twice.
+ */
+export function getAssetVersion() {
+    if (cachedVersion !== null) {
+        return cachedVersion;
+    }
+    let version = "";
+    // Compiled sources sit one level below the package root in the published
+    // package (helpers/) and two below it in the repo (dist/helpers/).
+    for (const candidate of ["../package.json", "../../package.json"]) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.resolve(import.meta.dirname, candidate), "utf-8"));
+            if (pkg?.name === "adminizer" && typeof pkg.version === "string") {
+                version = pkg.version;
+                break;
+            }
+        }
+        catch {
+            // Missing or unreadable package.json: try the next candidate.
+        }
+    }
+    cachedVersion = version;
+    return version;
+}
+export function withAssetVersion(url) {
+    const version = getAssetVersion();
+    if (!url || !version || process.env.ADMINIZER_ENV === "dev") {
+        return url;
+    }
+    return `${url}${url.includes("?") ? "&" : "?"}v=${version}`;
+}

package/helpers/configHelper.d.ts

@@ -1,6 +1,6 @@
-import { AdminpanelConfig, BaseFieldConfig } from "../interfaces/adminpanelConfig";
-import { Attribute } from "../lib/model/AbstractModel";
-import { Adminizer } from "../lib/Adminizer";
+import { AdminpanelConfig, BaseFieldConfig } from "../interfaces/adminpanelConfig.js";
+import { Attribute } from "../lib/model/AbstractModel.js";
+import { Adminizer } from "../lib/Adminizer.js";
 export declare class ConfigHelper {
     adminizer: Adminizer;
     constructor(adminizer: Adminizer);