adminizer 4.7.0-build.224 → 5.0.0-build.1

package/lib/app-manager/AdminizerApp.js

@@ -0,0 +1,17 @@
+/**
+ * Base contract for an Adminizer app.
+ *
+ * An app is created from its own configuration and optional app-level
+ * dependencies, then enabled with `adminizer.appManager.enable(app)`.
+ * The Adminizer instance belongs to the host application and must not be
+ * passed into or stored by the app.
+ *
+ * Use `setup(ctx)` for resource registration. At runtime, use:
+ * - `req.runtime` in app controllers;
+ * - the `runtime` factory argument in catalogs;
+ * - the `runtime` handler argument in event listeners.
+ */
+export class AbstractAdminizerApp {
+    config;
+    constructor() { }
+}

package/lib/app-manager/AppManager.d.ts

@@ -0,0 +1,18 @@
+import { Adminizer } from "../Adminizer";
+import { AbstractAdminizerApp, AppRuntime, AppRuntimeAppState } from "./AdminizerApp";
+export type AppState = AppRuntimeAppState;
+export declare class AppManager {
+    private adminizer;
+    private installedApps;
+    constructor(adminizer: Adminizer);
+    register(app: AbstractAdminizerApp): void;
+    enable(appOrName: AbstractAdminizerApp | string): Promise<void>;
+    disable(appName: string): Promise<void>;
+    unregister(appName: string): Promise<void>;
+    getInstalledApps(): string[];
+    getApp(name: string): AbstractAdminizerApp | undefined;
+    getState(name: string): AppState | undefined;
+    createRuntime(appName: string): AppRuntime;
+    private getRuntimeApp;
+    private disposeResources;
+}

package/lib/app-manager/AppManager.js

@@ -0,0 +1,537 @@
+import { Adminizer } from "../Adminizer.js";
+import { AiAssistantHandler } from "../ai-assistant/AiAssistantHandler.js";
+import { DataAccessor } from "../DataAccessor.js";
+class RuntimeAppSetupContext {
+    adminizer;
+    appName;
+    disposers = [];
+    pendingModelRegistrations = [];
+    pendingModelAccessRegistrations = [];
+    pendingAiAssistantRegistrations = [];
+    pendingMediaManagerRegistrations = [];
+    pendingCatalogRegistrations = [];
+    configLayerIndex = 0;
+    modelAccessIndex = 0;
+    constructor(adminizer, appName) {
+        this.adminizer = adminizer;
+        this.appName = appName;
+    }
+    asset(asset) {
+        const resourceId = `${this.appName}:${asset.id}`;
+        const url = this.adminizer.assetHandler.register(this.appName, asset);
+        this.disposers.push(() => this.adminizer.assetHandler.unregister(resourceId));
+        return url;
+    }
+    control(resource) {
+        const jsUrl = this.asset(resource.component);
+        const cssUrl = resource.stylesheet ? this.asset(resource.stylesheet) : undefined;
+        const control = {
+            name: resource.name,
+            type: resource.type,
+            getName: () => resource.name,
+            getConfig: () => resource.config,
+            getJsPath: () => jsUrl,
+            getCssPath: () => cssUrl,
+        };
+        const resourceId = `${this.appName}:${resource.id ?? `${resource.type}:${resource.name}`}`;
+        this.adminizer.controlsHandler.add(control);
+        this.adminizer.emitter.emit("app:control:registered", {
+            appName: this.appName,
+            resourceId,
+            type: resource.type,
+            name: resource.name,
+            jsUrl,
+            cssUrl,
+        });
+        this.disposers.push(() => {
+            if (this.adminizer.controlsHandler.get(resource.type, resource.name) === control) {
+                this.adminizer.controlsHandler.remove(resource.type, resource.name);
+            }
+            this.adminizer.emitter.emit("app:control:unregistered", {
+                appName: this.appName,
+                resourceId,
+                type: resource.type,
+                name: resource.name,
+            });
+        });
+    }
+    widget(resource) {
+        if (this.adminizer.widgetHandler.getById(resource.id)) {
+            throw new Error(`Widget "${resource.id}" is already registered`);
+        }
+        const accessRightsToken = resource.accessRightsToken ?? `widget-${resource.id}`;
+        if (!resource.accessRightsToken) {
+            this.accessRight({
+                id: accessRightsToken,
+                name: resource.name,
+                description: resource.description,
+                department: resource.department,
+            });
+        }
+        const widget = this.createWidget(resource, accessRightsToken);
+        this.adminizer.widgetHandler.add(widget);
+        this.adminizer.emitter.emit("app:widget:registered", {
+            appName: this.appName,
+            resourceId: `${this.appName}:${resource.id}`,
+            type: resource.type,
+            id: resource.id,
+        });
+        this.disposers.push(() => {
+            this.adminizer.widgetHandler.removeById(resource.id);
+            this.adminizer.emitter.emit("app:widget:unregistered", {
+                appName: this.appName,
+                resourceId: `${this.appName}:${resource.id}`,
+                type: resource.type,
+                id: resource.id,
+            });
+        });
+    }
+    controller(controller) {
+        const resourceId = `${this.appName}:${controller.id ?? `${controller.method}:${controller.route}`}`;
+        const url = this.adminizer.controllerHandler.register(this.appName, controller);
+        this.disposers.push(() => this.adminizer.controllerHandler.unregister(resourceId));
+        return url;
+    }
+    config(config, id = `config-${++this.configLayerIndex}`) {
+        const resourceId = this.adminizer.configLayerHandler.register(this.appName, id, config);
+        this.disposers.push(() => this.adminizer.configLayerHandler.unregister(resourceId));
+    }
+    accessRight(token) {
+        const resourceId = this.adminizer.accessRightsHandler.register(this.appName, token);
+        this.disposers.push(() => this.adminizer.accessRightsHandler.unregister(resourceId));
+    }
+    catalog(catalog) {
+        this.pendingCatalogRegistrations.push(() => this.registerCatalog(catalog));
+    }
+    model(model) {
+        this.pendingModelRegistrations.push(() => this.registerModel(model));
+    }
+    modelAccess(access) {
+        this.pendingModelAccessRegistrations.push(() => this.registerModelAccess(access));
+    }
+    mediaManager(resource) {
+        this.pendingMediaManagerRegistrations.push(() => this.registerMediaManager(resource));
+    }
+    aiAssistant(resource) {
+        this.pendingAiAssistantRegistrations.push(() => this.registerAiAssistant(resource));
+    }
+    listener(event, handler) {
+        const resourceId = `${this.appName}:${event.toString()}:${this.disposers.length + 1}`;
+        const listener = (payload) => handler(payload, this.adminizer.appManager.createRuntime(this.appName));
+        this.adminizer.emitter.on(event, listener);
+        this.adminizer.emitter.emit("app:listener:registered", {
+            appName: this.appName,
+            resourceId,
+            event,
+        });
+        this.disposers.push(() => {
+            this.adminizer.emitter.off(event, listener);
+            this.adminizer.emitter.emit("app:listener:unregistered", {
+                appName: this.appName,
+                resourceId,
+                event,
+            });
+        });
+    }
+    async waitForPendingRegistrations() {
+        await this.runRegistrationPhase(this.pendingModelRegistrations);
+        await this.runRegistrationPhase(this.pendingModelAccessRegistrations);
+        await this.runRegistrationPhase(this.pendingAiAssistantRegistrations);
+        await this.runRegistrationPhase(this.pendingMediaManagerRegistrations);
+        await this.runRegistrationPhase(this.pendingCatalogRegistrations);
+    }
+    async registerAiAssistant(resource) {
+        const previousHandler = this.adminizer.aiAssistantHandler;
+        const handler = new AiAssistantHandler(this.adminizer);
+        const context = this.createAiAssistantContext();
+        for (const modelFactory of resource.models) {
+            const model = await modelFactory(context);
+            handler.registerModel(model);
+        }
+        this.adminizer.aiAssistantHandler = handler;
+        this.adminizer.emitter.emit("app:ai-assistant:registered", {
+            appName: this.appName,
+            models: handler.getModels().map((model) => model.id),
+        });
+        this.disposers.push(() => {
+            if (this.adminizer.aiAssistantHandler === handler) {
+                this.adminizer.aiAssistantHandler = previousHandler;
+            }
+            this.adminizer.emitter.emit("app:ai-assistant:unregistered", {
+                appName: this.appName,
+            });
+        });
+    }
+    async registerMediaManager(resource) {
+        const manager = await resource.factory(this.adminizer.appManager.createRuntime(this.appName));
+        const resourceId = this.adminizer.mediaManagerHandler.register(this.appName, manager);
+        this.adminizer.emitter.emit("app:media-manager:registered", {
+            appName: this.appName,
+            resourceId,
+            managerId: manager.id,
+        });
+        this.disposers.push(() => {
+            this.adminizer.mediaManagerHandler.unregister(resourceId);
+            this.adminizer.emitter.emit("app:media-manager:unregistered", {
+                appName: this.appName,
+                resourceId,
+                managerId: manager.id,
+            });
+        });
+    }
+    async registerCatalog(catalogResource) {
+        const catalog = await catalogResource.factory(this.adminizer.appManager.createRuntime(this.appName));
+        const resourceId = this.adminizer.catalogHandler.register(this.appName, catalog);
+        this.adminizer.emitter.emit("app:catalog:registered", {
+            appName: this.appName,
+            resourceId,
+            slug: catalog.slug,
+        });
+        this.disposers.push(() => {
+            this.adminizer.catalogHandler.unregister(resourceId);
+            this.adminizer.emitter.emit("app:catalog:unregistered", {
+                appName: this.appName,
+                resourceId,
+                slug: catalog.slug,
+            });
+        });
+        for (const template of catalogResource.templates ?? []) {
+            const templateResourceId = this.adminizer.catalogTemplateComponentHandler.register(this.appName, catalog.slug, template);
+            this.adminizer.emitter.emit("app:catalog-template-component:registered", {
+                appName: this.appName,
+                resourceId: templateResourceId,
+                catalog: catalog.slug,
+                type: template.type,
+            });
+            this.disposers.push(() => {
+                this.adminizer.catalogTemplateComponentHandler.unregister(templateResourceId);
+                this.adminizer.emitter.emit("app:catalog-template-component:unregistered", {
+                    appName: this.appName,
+                    resourceId: templateResourceId,
+                    catalog: catalog.slug,
+                    type: template.type,
+                });
+            });
+        }
+    }
+    async registerModelAccess(access) {
+        const resourceId = this.adminizer.modelHandler.registerAppAccess(this.appName, access.id ?? `model-access-${++this.modelAccessIndex}`, access.models);
+        this.adminizer.emitter.emit("app:model-access:registered", {
+            appName: this.appName,
+            resourceId,
+            models: access.models,
+        });
+        this.disposers.push(() => {
+            this.adminizer.modelHandler.unregisterAppAccess(resourceId);
+            this.adminizer.emitter.emit("app:model-access:unregistered", {
+                appName: this.appName,
+                resourceId,
+                models: access.models,
+            });
+        });
+    }
+    async registerModel(model) {
+        const ormAdapter = this.resolveModelAdapter(model.adapter);
+        const registeredModel = ormAdapter.getModel(model.name);
+        if (!registeredModel) {
+            if (ormAdapter.ormType === "typeorm") {
+                throw new Error(`App "${this.appName}" requires TypeORM entity "${model.name}". ` +
+                    "TypeORM entities must be registered in DataSource before initialize(). " +
+                    "Dynamic app model installation is supported only for Sequelize.");
+            }
+            throw new Error(`App "${this.appName}" requires model "${model.name}", but it was not provided by adapter ` +
+                `"${ormAdapter.ormType}". Install the app model before enabling the app.`);
+        }
+        const modelInstance = new ormAdapter.Model(model.name, registeredModel);
+        const resourceId = this.adminizer.modelHandler.register(this.appName, model.name, modelInstance);
+        this.adminizer.emitter.emit("app:model:registered", {
+            appName: this.appName,
+            resourceId,
+            modelName: model.name,
+        });
+        this.disposers.push(() => {
+            this.adminizer.modelHandler.unregister(resourceId);
+            this.adminizer.emitter.emit("app:model:unregistered", {
+                appName: this.appName,
+                resourceId,
+                modelName: model.name,
+            });
+        });
+    }
+    async runRegistrationPhase(registrations) {
+        for (const registration of registrations) {
+            await registration();
+        }
+    }
+    createWidget(resource, accessRightsToken) {
+        const runtime = () => this.adminizer.appManager.createRuntime(this.appName);
+        const base = {
+            id: resource.id,
+            name: resource.name,
+            description: resource.description,
+            icon: resource.icon,
+            department: resource.department,
+            backgroundCSS: resource.backgroundCSS ?? null,
+            size: resource.size ?? null,
+            accessRightsToken,
+            group: resource.group,
+        };
+        if (resource.type === "info") {
+            return {
+                ...base,
+                widgetType: "info",
+                link: resource.link,
+                linkType: resource.linkType,
+                getInfo: (context) => resource.getInfo({
+                    ...context,
+                    runtime: runtime(),
+                }),
+            };
+        }
+        if (resource.type === "switcher") {
+            return {
+                ...base,
+                widgetType: "switcher",
+                getState: () => resource.getState({
+                    runtime: runtime(),
+                }),
+                switchIt: () => resource.switchIt({
+                    runtime: runtime(),
+                }),
+            };
+        }
+        if (resource.type === "action") {
+            return {
+                ...base,
+                widgetType: "action",
+                action: () => resource.action({
+                    runtime: runtime(),
+                }),
+            };
+        }
+        if (resource.type === "link") {
+            return {
+                ...base,
+                widgetType: "link",
+                links: resource.links,
+                getLinks: async () => resource.links,
+            };
+        }
+        const scriptUrl = this.asset(resource.component);
+        return {
+            ...base,
+            widgetType: "custom",
+            routePrefix: this.adminizer.config.routePrefix,
+            jsPath: {
+                dev: scriptUrl,
+                production: scriptUrl,
+            },
+            scriptUrl,
+        };
+    }
+    resolveModelAdapter(adapterName) {
+        const resolvedAdapterName = adapterName ?? this.adminizer.config.system?.defaultORM;
+        if (resolvedAdapterName) {
+            const adapter = this.adminizer.getOrmAdapter(resolvedAdapterName);
+            if (!adapter) {
+                throw new Error(`Adapter "${resolvedAdapterName}" was not found`);
+            }
+            return adapter;
+        }
+        if (this.adminizer.ormAdapters.length === 1) {
+            return this.adminizer.ormAdapters[0];
+        }
+        throw new Error(`Adapter was not provided for app model registration "${this.appName}"`);
+    }
+    createAiAssistantContext() {
+        return {
+            runtime: this.adminizer.appManager.createRuntime(this.appName),
+            routePrefix: this.adminizer.config.routePrefix,
+            getModelResources: () => this.getModelResources(),
+            resolveModelResource: (modelName) => this.resolveModelResource(modelName),
+            hasPermission: (token, user) => this.adminizer.accessRightsHelper.hasPermission(token, user),
+            createDataAccessor: (modelResource, user, action) => new DataAccessor(this.adminizer, user, modelResource, action),
+        };
+    }
+    getModelResources() {
+        const resources = [];
+        for (const [configName, configValue] of Object.entries(this.adminizer.config.models ?? {})) {
+            const normalizedConfig = this.normalizeModelConfig(configName, configValue);
+            const model = this.adminizer.modelHandler.model.get(normalizedConfig.model.toLowerCase());
+            if (!model) {
+                continue;
+            }
+            resources.push({
+                name: configName,
+                uri: `${this.adminizer.config.routePrefix}/model/${configName}`,
+                config: normalizedConfig,
+                model,
+            });
+        }
+        return resources;
+    }
+    resolveModelResource(modelName) {
+        const loweredName = modelName.toLowerCase();
+        return this.getModelResources().find((resource) => {
+            const modelId = resource.config.model?.toLowerCase();
+            return resource.name.toLowerCase() === loweredName || modelId === loweredName;
+        });
+    }
+    normalizeModelConfig(name, config) {
+        const baseConfig = {
+            model: name,
+            icon: "description",
+            title: name,
+            list: true,
+            add: true,
+            edit: true,
+            remove: true,
+            view: true,
+        };
+        if (typeof config === "boolean") {
+            return config ? baseConfig : { ...baseConfig, list: false, add: false, edit: false, remove: false, view: false };
+        }
+        return { ...baseConfig, ...config };
+    }
+}
+export class AppManager {
+    adminizer;
+    installedApps = new Map();
+    constructor(adminizer) {
+        this.adminizer = adminizer;
+    }
+    register(app) {
+        if (this.installedApps.has(app.name)) {
+            throw new Error(`App "${app.name}" is already registered`);
+        }
+        this.installedApps.set(app.name, {
+            app,
+            state: "registered",
+            disposers: [],
+        });
+        this.adminizer.emitter.emit("app:registered", {
+            appName: app.name,
+            version: app.version,
+        });
+    }
+    async enable(appOrName) {
+        const appName = typeof appOrName === "string" ? appOrName : appOrName.name;
+        if (typeof appOrName !== "string" && !this.installedApps.has(appName)) {
+            this.register(appOrName);
+        }
+        const installed = this.installedApps.get(appName);
+        if (!installed) {
+            throw new Error(`App "${appName}" is not registered`);
+        }
+        if (this.adminizer.config.system?.defaultORM === "typeorm") {
+            Adminizer.log.warn(`App "${appName}" is being enabled with experimental TypeORM support. ` +
+                "App entities must be registered before DataSource.initialize(); dynamic model installation is unavailable.");
+        }
+        if (installed.state === "enabled") {
+            return;
+        }
+        installed.disposers = [];
+        installed.state = "registered";
+        this.adminizer.emitter.emit("app:enable:start", {
+            appName,
+            version: installed.app.version,
+        });
+        const ctx = new RuntimeAppSetupContext(this.adminizer, appName);
+        try {
+            await installed.app.setup(ctx);
+            await ctx.waitForPendingRegistrations();
+            installed.disposers.push(...ctx.disposers);
+            installed.state = "enabled";
+            this.adminizer.emitter.emit("app:enabled", {
+                appName,
+                version: installed.app.version,
+                resources: installed.disposers.length,
+            });
+        }
+        catch (error) {
+            installed.state = "failed";
+            installed.disposers.push(...ctx.disposers);
+            await this.disposeResources(installed);
+            this.adminizer.emitter.emit("app:enable:failed", {
+                appName,
+                error,
+            });
+            throw error;
+        }
+    }
+    async disable(appName) {
+        const installed = this.installedApps.get(appName);
+        if (!installed || installed.state !== "enabled") {
+            return;
+        }
+        this.adminizer.emitter.emit("app:disable:start", {
+            appName,
+        });
+        await this.disposeResources(installed);
+        installed.state = "disabled";
+        this.adminizer.emitter.emit("app:disabled", {
+            appName,
+        });
+    }
+    async unregister(appName) {
+        const installed = this.installedApps.get(appName);
+        if (!installed) {
+            return;
+        }
+        await this.disable(appName);
+        this.installedApps.delete(appName);
+        installed.state = "unregistered";
+        this.adminizer.emitter.emit("app:unregistered", {
+            appName,
+        });
+    }
+    getInstalledApps() {
+        return Array.from(this.installedApps.keys());
+    }
+    getApp(name) {
+        return this.installedApps.get(name)?.app;
+    }
+    getState(name) {
+        return this.installedApps.get(name)?.state;
+    }
+    createRuntime(appName) {
+        return {
+            models: this.adminizer.modelHandler.createAppAccess(appName),
+            config: {
+                routePrefix: this.adminizer.config.routePrefix,
+                getModelConfig: (modelName) => {
+                    const models = this.adminizer.config.models ?? {};
+                    const modelKey = Object.keys(models).find((key) => key.toLowerCase() === modelName.toLowerCase());
+                    return modelKey ? models[modelKey] : undefined;
+                },
+            },
+            notifications: {
+                send: (notification) => this.adminizer.sendNotification(notification),
+            },
+            apps: {
+                list: () => this.getInstalledApps().map((name) => this.getRuntimeApp(name)),
+                get: (name) => this.getRuntimeApp(name),
+                enable: (name) => this.enable(name),
+                disable: (name) => this.disable(name),
+                unregister: (name) => this.unregister(name),
+            },
+        };
+    }
+    getRuntimeApp(name) {
+        const installed = this.installedApps.get(name);
+        if (!installed) {
+            return undefined;
+        }
+        return {
+            name,
+            version: installed.app.version,
+            state: installed.state,
+        };
+    }
+    async disposeResources(installed) {
+        for (const dispose of [...installed.disposers].reverse()) {
+            await dispose();
+        }
+        installed.disposers = [];
+    }
+}

package/lib/app-manager/AssetHandler.d.ts

@@ -0,0 +1,17 @@
+import type { Adminizer } from "../Adminizer";
+import type { AppAsset } from "./AdminizerApp";
+interface AssetRecord {
+    id: string;
+    appName: string;
+    url: string;
+    controllerId?: string;
+}
+export declare class AssetHandler {
+    private adminizer;
+    private assets;
+    constructor(adminizer: Adminizer);
+    register(appName: string, asset: AppAsset): string;
+    unregister(id: string): void;
+    getByApp(appName: string): AssetRecord[];
+}
+export {};

package/lib/app-manager/AssetHandler.js

@@ -0,0 +1,67 @@
+import path from "path";
+export class AssetHandler {
+    adminizer;
+    assets = new Map();
+    constructor(adminizer) {
+        this.adminizer = adminizer;
+    }
+    register(appName, asset) {
+        const id = `${appName}:${asset.id}`;
+        if (this.assets.has(id)) {
+            throw new Error(`Asset "${id}" is already registered`);
+        }
+        if (process.env.ADMINIZER_ENV === "dev" && asset.devUrl) {
+            this.assets.set(id, {
+                id,
+                appName,
+                url: asset.devUrl,
+            });
+            this.adminizer.emitter.emit("app:asset:registered", {
+                appName,
+                resourceId: id,
+                url: asset.devUrl,
+                mode: "dev",
+            });
+            return asset.devUrl;
+        }
+        const fileName = path.basename(asset.filePath);
+        const route = asset.route ?? `/app-assets/${appName}/${asset.id}/${fileName}`;
+        const url = this.adminizer.controllerHandler.register(appName, {
+            id: `asset:${asset.id}`,
+            method: "get",
+            route,
+            middleware: (_req, res) => res.sendFile(asset.filePath),
+        });
+        this.assets.set(id, {
+            id,
+            appName,
+            url,
+            controllerId: `${appName}:asset:${asset.id}`,
+        });
+        this.adminizer.emitter.emit("app:asset:registered", {
+            appName,
+            resourceId: id,
+            url,
+            mode: "static",
+        });
+        return url;
+    }
+    unregister(id) {
+        const record = this.assets.get(id);
+        if (!record) {
+            return;
+        }
+        if (record.controllerId) {
+            this.adminizer.controllerHandler.unregister(record.controllerId);
+        }
+        this.assets.delete(id);
+        this.adminizer.emitter.emit("app:asset:unregistered", {
+            appName: record.appName,
+            resourceId: id,
+            url: record.url,
+        });
+    }
+    getByApp(appName) {
+        return Array.from(this.assets.values()).filter((record) => record.appName === appName);
+    }
+}

package/lib/app-manager/ConfigLayerHandler.d.ts

@@ -0,0 +1,18 @@
+import type { Adminizer } from "../Adminizer";
+import type { AppConfigPatch } from "./AdminizerApp";
+export interface ConfigLayerRecord {
+    id: string;
+    appName: string;
+    patch: AppConfigPatch;
+}
+export declare class ConfigLayerHandler {
+    private adminizer;
+    private baseConfig?;
+    private layers;
+    constructor(adminizer: Adminizer);
+    register(appName: string, layerId: string, patch: AppConfigPatch): string;
+    unregister(id: string): void;
+    getByApp(appName: string): ConfigLayerRecord[];
+    private rebuildConfig;
+    private getLayerId;
+}