@ti-engine/web-framework 1.19.0 → 1.20.0

package/package.json

@@ -1,67 +1,139 @@
-{
-  "name": "@ti-engine/web-framework",
-  "version": "1.19.0",
-  "description": "A web-framework based on the ti-engine. It provides a customizable ready-to-use web-server microservice and a set of tools for creating web applications. NOTICE: This is still a work in progress and the full architecture, design, and functionality are not available!",
-  "author": "Boris Kostadinov <kostadinov.boris@gmail.com>",
-  "license": "GPL-3.0-or-later",
-  "exports": {
-    "./config-management": "./components/config-service.js",
-    "./web-application": "./bin/web-app-manager.js",
-    "./web-server": "./bin/web-server.js"
-  },
-  "imports": {
-    "#admin-config-handlers": "./components/admin-config-handlers.js",
-    "#auth-manager": "./components/auth-manager.js",
-    "#authorization": "./components/authorization.js",
-    "#config-change-notifier": "./components/config-change-notifier.js",
-    "#config-registry": "./components/config-registry.js",
-    "#config-service": "./components/config-service.js",
-    "#config-store": "./components/config-store.js",
-    "#session-store": "./components/session-store.js",
-    "#user": "./components/user.js",
-    "#web-app-manager": "./bin/web-app-manager.js",
-    "#web-config-env": "./components/web-config-env.js",
-    "#web-handlers": "./components/web-handlers.js",
-    "#web-server": "./bin/web-server.js",
-    "#web-server-config": "./bin/web-server.json"
-  },
-  "dependencies": {
-    "@ti-engine/core": "*",
-    "@alpinejs/csp": "^3.15.12",
-    "htmx.org": "^2.0.10",
-    "ajv": "^8.20.0",
-    "cookie-parser": "^1.4.7",
-    "express": "^5.2.1",
-    "express-session": "^1.19.0",
-    "helmet": "^8.3.0",
-    "lodash": "^4.18.1",
-    "openid-client": "^6.8.4"
-  },
-  "devDependencies": {
-  },
-  "files": [
-    "bin/",
-    "!bin/tls/**/*",
-    "components/",
-    ".env",
-    "package.json",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Belleal/ti-engine.git",
-    "directory": "packages/web-framework"
-  },
-  "bugs": {
-    "url": "https://github.com/Belleal/ti-engine/issues"
-  },
-  "homepage": "https://github.com/Belleal/ti-engine/tree/master/packages/web-framework#readme",
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "scripts": {
-    "postinstall": "node ./bin/build/post-install.js",
-    "test": "node --test test/*.test.js"
-  }
-}
+{
+  "name": "@ti-engine/web-framework",
+  "version": "1.20.0",
+  "description": "A web-framework based on the ti-engine. It provides a customizable ready-to-use web-server microservice and a set of tools for creating web applications. NOTICE: This is still a work in progress and the full architecture, design, and functionality are not available!",
+  "keywords": [
+    "ti-engine",
+    "web-framework",
+    "express",
+    "microservices",
+    "htmx",
+    "alpinejs",
+    "openid-connect",
+    "csp"
+  ],
+  "author": "Boris Kostadinov <kostadinov.boris@gmail.com>",
+  "license": "GPL-3.0-or-later",
+  "exports": {
+    "./config-management": {
+      "types": "./types/components/config-service.d.ts",
+      "default": "./components/config-service.js"
+    },
+    "./web-application": {
+      "types": "./types/bin/web-app-manager.d.ts",
+      "default": "./bin/web-app-manager.js"
+    },
+    "./web-server": {
+      "types": "./types/bin/web-server.d.ts",
+      "default": "./bin/web-server.js"
+    },
+    "./definitions": {
+      "types": "./types/components/definitions.types.d.ts",
+      "default": "./components/definitions.types.js"
+    }
+  },
+  "imports": {
+    "#admin-config-handlers": {
+      "types": "./types/components/admin-config-handlers.d.ts",
+      "default": "./components/admin-config-handlers.js"
+    },
+    "#auth-manager": {
+      "types": "./types/components/auth-manager.d.ts",
+      "default": "./components/auth-manager.js"
+    },
+    "#authorization": {
+      "types": "./types/components/authorization.d.ts",
+      "default": "./components/authorization.js"
+    },
+    "#config-change-notifier": {
+      "types": "./types/components/config-change-notifier.d.ts",
+      "default": "./components/config-change-notifier.js"
+    },
+    "#config-registry": {
+      "types": "./types/components/config-registry.d.ts",
+      "default": "./components/config-registry.js"
+    },
+    "#config-service": {
+      "types": "./types/components/config-service.d.ts",
+      "default": "./components/config-service.js"
+    },
+    "#config-store": {
+      "types": "./types/components/config-store.d.ts",
+      "default": "./components/config-store.js"
+    },
+    "#definitions": {
+      "types": "./types/components/definitions.types.d.ts",
+      "default": "./components/definitions.types.js"
+    },
+    "#session-store": {
+      "types": "./types/components/session-store.d.ts",
+      "default": "./components/session-store.js"
+    },
+    "#user": {
+      "types": "./types/components/user.d.ts",
+      "default": "./components/user.js"
+    },
+    "#web-app-manager": {
+      "types": "./types/bin/web-app-manager.d.ts",
+      "default": "./bin/web-app-manager.js"
+    },
+    "#web-config-env": {
+      "types": "./types/components/web-config-env.d.ts",
+      "default": "./components/web-config-env.js"
+    },
+    "#web-handlers": {
+      "types": "./types/components/web-handlers.d.ts",
+      "default": "./components/web-handlers.js"
+    },
+    "#web-server": {
+      "types": "./types/bin/web-server.d.ts",
+      "default": "./bin/web-server.js"
+    },
+    "#web-server-config": "./bin/web-server.json"
+  },
+  "dependencies": {
+    "@alpinejs/csp": "^3.15.12",
+    "@ti-engine/core": "*",
+    "@types/express": "^5.0.6",
+    "@types/express-session": "^1.18.2",
+    "@types/node": "^24.10.1",
+    "ajv": "^8.20.0",
+    "cookie-parser": "^1.4.7",
+    "express": "^5.2.1",
+    "express-session": "^1.19.0",
+    "helmet": "^8.3.0",
+    "htmx.org": "^2.0.10",
+    "lodash": "^4.18.1",
+    "openid-client": "^6.8.4"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2"
+  },
+  "files": [
+    "bin/",
+    "!bin/tls/**/*",
+    "components/",
+    "types/",
+    ".env",
+    "package.json",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Belleal/ti-engine.git",
+    "directory": "packages/web-framework"
+  },
+  "bugs": {
+    "url": "https://github.com/Belleal/ti-engine/issues"
+  },
+  "homepage": "https://github.com/Belleal/ti-engine/tree/master/packages/web-framework#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "postinstall": "node ./bin/build/post-install.js",
+    "test": "node --test test/*.test.js",
+    "build:types": "tsc -p tsconfig.types.json"
+  }
+}

package/types/bin/web-app-manager.d.ts

@@ -0,0 +1,194 @@
+export = TiWebAppManager;
+import type { TiSession } from "#definitions";
+/**
+ * Gates the login-page authentication markup to the effective enabled methods. The login fragment delimits blocks
+ * with HTML-comment markers: `<!--ti-auth-method:METHOD-->…<!--/ti-auth-method-->` around each method's control
+ * (the `local` credentials form and each OpenID provider button), `<!--ti-auth-divider-->…<!--/ti-auth-divider-->`
+ * around the "or continue with" separator, `<!--ti-auth-social-->…<!--/ti-auth-social-->` around the SSO button
+ * group, and `<!--ti-auth-none-->…<!--/ti-auth-none-->` around a "no method configured" fallback. It removes the
+ * block for any method that is not enabled, drops the social group when no SSO provider is enabled, shows the
+ * divider only when a local form AND at least one SSO provider are both present, and shows the fallback only when
+ * nothing is enabled. Any remaining markers are stripped so clean HTML ships. Fragments without these markers
+ * (every non-login fragment) are returned unchanged.
+ *
+ * @param {string} html
+ * @param {string[]} [enabledMethods] The effective enabled authentication methods.
+ * @returns {string}
+ */
+declare function applyAuthMethodVisibility(html: string, enabledMethods?: string[]): string;
+/**
+ * A generic web application manager that handles the rendering and behavior of web application views. It is designed to be extended by specific web application
+ * managers for each web application you want to implement with the ti-engine web framework.
+ * <br/>
+ * NOTE: You should not instantiate this class directly. Instead, extend it and override the abstract methods as needed. Additionally, you should configure your
+ * ti-engine web server 'TiWebApplicationConfig' settings by specifying the 'classPath' that corresponds to your web application manager. The path should be
+ * relative to the intended process's working directory.
+ *
+ * @class TiWebAppManager
+ * @abstract
+ * @public
+ */
+declare class TiWebAppManager {
+    #private;
+    /**
+     * @constructor
+     * @param {string} identifier The identifier for this web application. Should be unique and recognizable.
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     */
+    constructor(identifier: string);
+    /**
+     * Returns the identifier for this web application.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get webAppIdentifier(): string;
+    /**
+     * Adds a new HTML fragment to the web application.
+     * <br/>
+     * NOTE: This method should only be called during the initialization phase of your web application manager.
+     *
+     * @method
+     * @param {string} identifier
+     * @param {Object} fragment The fragment descriptor (`{ title, path, components }`). May also carry an optional
+     * `roles` array (`Array<string|number>`): when present, the default {@link TiWebAppManager#verifyAccess} serves
+     * the fragment only to sessions holding at least one of those roles; omit it (or leave empty) for a public screen.
+     * @throws {TiException.E_GEN_UNALLOWED_OVERRIDE} If a fragment with the same identifier already exists.
+     * @public
+     */
+    addFragment(identifier: string, fragment: Object): void;
+    /**
+     * Registers an editable configuration document with the framework config registry (JSON Schema + semantic
+     * validators + default value + editor metadata). Call during initialization. See {@link ConfigRegistry#register}.
+     *
+     * @method
+     * @param {string} configKey
+     * @param {Object} definition
+     * @returns {TiWebAppManager} this (chainable)
+     * @public
+     */
+    registerConfigDocument(configKey: string, definition: Object): TiWebAppManager;
+    /**
+     * Registers a JSON Schema that is referenced (via `$ref`) by config-document schemas but is not itself a document.
+     *
+     * @method
+     * @param {Object} schema
+     * @returns {TiWebAppManager} this (chainable)
+     * @public
+     */
+    registerConfigSchema(schema: Object): TiWebAppManager;
+    /**
+     * Registers a composite (entity) editor with the framework config service — a `compose(docs)`/`decompose(edited,docs)`
+     * pair over one or more documents. Call during initialization. See {@link ConfigService#registerEditor}.
+     *
+     * @method
+     * @param {string} editorKey
+     * @param {Object} definition
+     * @returns {TiWebAppManager} this (chainable)
+     * @public
+     */
+    registerConfigEditor(editorKey: string, definition: Object): TiWebAppManager;
+    /**
+     * Used to clear the static file cache. This is useful for testing purposes to ensure that the web server is always serving fresh content.
+     *
+     * @method
+     * @public
+     */
+    clearStaticFileCache(): void;
+    /**
+     * Sets the effective enabled authentication methods used to gate login-page provider buttons. The web server
+     * calls this at startup, after the auth manager has dropped any enabled-but-unconfigured OpenID providers.
+     *
+     * @method
+     * @param {string[]} methods
+     * @public
+     */
+    setEnabledAuthMethods(methods: string[]): void;
+    /**
+     * Optional HTML transformation hook.
+     * <br/>
+     * NOTE: Override in subclasses to add nonces or other dynamic data to outgoing HTML.
+     *
+     * @method
+     * @param {string} html
+     * @param {Object} [options]
+     * @param {string} [options.csrfToken] Optional CSRF token to inject into the HTML.
+     * @param {boolean} [options.isHome] Optional flag to indicate whether the requested route is the home page.
+     * @param {string} [options.nonce] Optional CSP nonce to inject into inline scripts/styles.
+     * @param {string} [options.title] Optional title to replace the placeholder in the HTML.
+     * @returns {Promise<string>}
+     * @virtual
+     * @public
+     */
+    transformHtml(html: string, options?: {
+        csrfToken?: string;
+        isHome?: boolean;
+        nonce?: string;
+        title?: string;
+    }): Promise<string>;
+    /**
+     * Used to assemble the complete HTML view for the requested route, including nested HTML fragments.
+     *
+     * @method
+     * @param {TiSession} session
+     * @param {string[]} staticContentPaths
+     * @param {string} route
+     * @param {Object} [options]
+     * @param {string} [options.csrfToken] Optional CSRF token to inject into the HTML.
+     * @param {boolean} [options.isPartial] Optional flag to indicate whether the requested route is a partial load of a fragment.
+     * @param {string} [options.view] Optional view name to load within this route.
+     * @param {string} [options.nonce] Optional CSP nonce to inject into inline scripts/styles.
+     * @returns {Promise<string>}
+     * @public
+     */
+    assembleHtmlView(session: TiSession, staticContentPaths: string[], route: string, options?: {
+        csrfToken?: string;
+        isPartial?: boolean;
+        view?: string;
+        nonce?: string;
+    }): Promise<string>;
+    /**
+     * Used to process a request for a data resource.
+     *
+     * @method
+     * @param {TiSession} session
+     * @param {string} view
+     * @param {Object} [options]
+     * @returns {Promise<Object>}
+     * @virtual
+     * @public
+     */
+    processDataRequest(session: TiSession, view: string, options?: Object): Promise<Object>;
+    /**
+     * Used to process an application service request.
+     *
+     * @method
+     * @param {TiSession} session
+     * @param {string} service
+     * @param {Object} params
+     * @returns {Promise<Object>}
+     * @virtual
+     * @public
+     */
+    processServiceRequest(session: TiSession, service: string, params: Object): Promise<Object>;
+    /**
+     * Used to verify whether the current user has access to the requested resource. The default implementation gates
+     * HTML fragments by their declared `roles`: a fragment registered via {@link TiWebAppManager#addFragment} with a
+     * `roles` array is served only to sessions holding at least one of those roles (see {@link addFragment}); a
+     * fragment with no `roles` is public to any authenticated user. This makes role-restricted screens unreachable by
+     * direct URL, not merely hidden in the UI. Override in subclasses only to implement additional/alternative checks.
+     *
+     * @method
+     * @virtual
+     * @param {TiSession} session
+     * @param {Object} resource The fragment descriptor; its optional `resource.roles` lists the roles permitted to load it.
+     * @returns {Promise}
+     * @exception {TiException.E_SEC_UNAUTHORIZED_ACCESS} (403) When the session holds none of the fragment's required roles.
+     * @public
+     */
+    verifyAccess(session: TiSession, resource: Object): Promise<any>;
+}
+declare namespace TiWebAppManager {
+    export { applyAuthMethodVisibility };
+}