@webtypen/webframez-core 0.3.38 → 0.3.40

package/README.md

@@ -4,6 +4,7 @@ TypeScript-first backend framework core for Node.js.
 
 This README reflects the current API in this repository and focuses on:
 - Routing
+- ApiScopes and ApiFunctions
 - Datatables
 - DataBuilder
 - Console Commands
@@ -103,6 +104,7 @@ app.boot({
 - `modules`
 - `config`
 - `datatables`
+- `apiScopes` on the kernel or module providers
 - `jobs`
 - `mode`
 - `onBoot`
@@ -116,6 +118,7 @@ Route.get("/", "HomeController@index");
 Route.post("/login", "AuthController@login");
 Route.put("/users/:id", "UserController@update");
 Route.delete("/users/:id", "UserController@delete");
+Route.patch("/users/:id", "UserController@patch");
 ```
 
 You can also register inline handlers:
@@ -233,6 +236,156 @@ Also available:
 - `stream(req, filepath, filename, mimeType)`
 - `registerEvent("after", fn)`
 
+## ApiScopes and ApiFunctions
+
+ApiScopes group callable ApiFunctions and can automatically expose them as normal HTTP routes. MCP exposure is intentionally not implemented in core; install `@webtypen/webframez-ai` and use `APIFunctionsMCPServer` when ApiFunctions should be exposed as MCP tools.
+
+### Define ApiFunctions
+
+```ts
+import { ApiFunction, ApiFunctionRequest, ApiFunctionResponse } from "@webtypen/webframez-core";
+
+class CurrentUserFunction extends ApiFunction {
+  key = "current-user";
+  description = "Returns the current user.";
+  requestMethod = "GET";
+  params = {
+    includePermissions: { type: "boolean", default: false }
+  };
+
+  async handle(apiRequest: ApiFunctionRequest) {
+    return new ApiFunctionResponse({
+      user: apiRequest.context.user,
+      includePermissions: apiRequest.params.includePermissions
+    });
+  }
+}
+```
+
+`requestMethod` may be `"GET"`, `"POST"`, `"PUT"`, `"PATCH"`, `"DELETE"` or `null`.
+Functions with `requestMethod = null` are not registered as normal HTTP routes, but they can still be used by higher-level integrations such as `APIFunctionsMCPServer` in `@webtypen/webframez-ai`.
+
+### Define ApiScopes
+
+```ts
+import { ApiScope, Request, Response } from "@webtypen/webframez-core";
+
+class BackofficeApiScope extends ApiScope {
+  key = "backoffice";
+  apiBasePath = "/api/backoffice";
+  functions = [CurrentUserFunction];
+
+  async middleware(req: Request, _res: Response, abort: (message?: any, status?: number) => never) {
+    if (!req.headers.authorization) {
+      return abort("Unauthorized", 401);
+    }
+
+    return {
+      user: { id: "..." }
+    };
+  }
+}
+```
+
+For every function with a non-null request method, core registers:
+
+```text
+apiBasePath + "/" + function.key
+```
+
+Example: `GET /api/backoffice/current-user`.
+
+The scope middleware runs before the function. Its return value is passed to the function as `apiRequest.context`. Calling `abort(message, status)` stops execution and returns an error response with that status.
+
+### Group ApiScopes
+
+Use `ApiScopesGroup` to share middleware across multiple scopes:
+
+```ts
+import { ApiScope, ApiScopesGroup, Request, Response } from "@webtypen/webframez-core";
+
+class BackofficeApiScope extends ApiScope {
+  key = "backoffice";
+  apiBasePath = "/api/backoffice";
+  functions = [CurrentUserFunction];
+
+  async middleware(_req: Request, _res: Response, _abort: (message?: any, status?: number) => never) {
+    return {
+      scope: "backoffice"
+    };
+  }
+
+  async groupMiddleware(_req: Request, _res: Response, _abort: (message?: any, status?: number) => never) {
+    return {
+      reachedThroughGroup: true
+    };
+  }
+}
+
+class BackofficeApiScopesGroup extends ApiScopesGroup {
+  key = "backoffice-group";
+  apiScopes = [BackofficeApiScope];
+
+  async middleware(req: Request, _res: Response, abort: (message?: any, status?: number) => never) {
+    if (!req.headers.authorization) {
+      return abort("Unauthorized", 401);
+    }
+
+    return {
+      user: { id: "..." }
+    };
+  }
+}
+```
+
+When a scope is reached through a group, middleware runs in this order:
+
+```text
+ApiScopesGroup.middleware()
+ApiScope.middleware()
+ApiScope.groupMiddleware()
+```
+
+The context objects are merged in that order, so later scope-specific values can override group values. `groupMiddleware()` only runs when the scope was registered through an `ApiScopesGroup`.
+
+### Register ApiScopes
+
+Register scopes on the web kernel:
+
+```ts
+import { BaseKernelWeb } from "@webtypen/webframez-core";
+
+class Kernel extends BaseKernelWeb {
+  static apiScopes = [BackofficeApiScope, BackofficeApiScopesGroup];
+}
+```
+
+Modules can register scopes as instance properties:
+
+```ts
+import { ModuleProvider } from "@webtypen/webframez-core";
+
+class BackofficeModuleProvider extends ModuleProvider {
+  apiScopes = [BackofficeApiScope, BackofficeApiScopesGroup];
+}
+```
+
+### Params and Validation
+
+GET functions validate params from `req.query`; all other request methods validate params from `req.body`.
+
+Supported descriptor types include:
+- `string`
+- `number` / `float`
+- `integer` / `int`
+- `boolean` / `bool`
+- `ObjectId`
+- `option`
+- `array`
+- `object`
+
+Defaults are applied before required checks. Unknown types are passed through unchanged but still respect `required` and `default`.
+
 ## Datatables
 
 Use `Datatable` + `DatatableRegistry` + `DatatableController`.

package/dist/Api/ApiFunction.d.ts

@@ -0,0 +1,27 @@
+import { ApiFunctionParamsDefinition, ApiFunctionRequest, ApiFunctionRequestMethod, ApiFunctionResponseType } from "./ApiTypes";
+export declare class ApiFunctionResponse {
+    data: {
+        [key: string]: any;
+    };
+    status: number;
+    responseType: ApiFunctionResponseType;
+    getData(): {
+        [key: string]: any;
+    };
+    constructor(data: {
+        [key: string]: any;
+    }, options?: {
+        status?: number;
+        responseType?: ApiFunctionResponseType;
+    });
+}
+export declare class ApiFunction {
+    key: string;
+    description: string;
+    requestMethod: ApiFunctionRequestMethod;
+    mcpDisabled: boolean;
+    params: ApiFunctionParamsDefinition;
+    handle(apiRequest: ApiFunctionRequest): Promise<ApiFunctionResponse | {
+        [key: string]: any;
+    }>;
+}

package/dist/Api/ApiFunction.js

@@ -0,0 +1,45 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiFunction = exports.ApiFunctionResponse = void 0;
+class ApiFunctionResponse {
+    getData() {
+        return this.data;
+    }
+    constructor(data, options) {
+        var _a, _b;
+        this.data = {};
+        this.status = 200;
+        this.responseType = "response";
+        this.data = data;
+        this.status = (_a = options === null || options === void 0 ? void 0 : options.status) !== null && _a !== void 0 ? _a : 200;
+        this.responseType = (_b = options === null || options === void 0 ? void 0 : options.responseType) !== null && _b !== void 0 ? _b : "response";
+    }
+}
+exports.ApiFunctionResponse = ApiFunctionResponse;
+class ApiFunction {
+    constructor() {
+        this.key = "unnamed-function";
+        this.description = "A unnamed example function";
+        this.requestMethod = "POST";
+        this.mcpDisabled = false;
+        this.params = {
+            elementId: { type: "ObjectId", required: true },
+            mode: { type: "option", options: [{ value: "all" }, { value: "pending" }], default: "all" },
+        };
+    }
+    handle(apiRequest) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return new ApiFunctionResponse({ status: "Api is running ..." });
+        });
+    }
+}
+exports.ApiFunction = ApiFunction;

package/dist/Api/ApiFunctionUtils.d.ts

@@ -0,0 +1,79 @@
+/// <reference types="node" />
+import { IncomingMessage } from "http";
+import { Request } from "../Router/Request";
+import { Response } from "../Router/Response";
+import { ApiFunction } from "./ApiFunction";
+import { ApiScope } from "./ApiScope";
+import { ApiScopesGroup } from "./ApiScopesGroup";
+import { ApiFunctionClass, ApiFunctionParamDefinition, ApiFunctionParamsDefinition, ApiScopeClass, ApiScopeRegistrationClass, ApiScopesGroupClass } from "./ApiTypes";
+export type ApiScopeRegistrationEntry = {
+    scopeClass: ApiScopeClass;
+    groupClass?: ApiScopesGroupClass;
+};
+export declare class ApiFunctionRuntimeError extends Error {
+    statusCode: number;
+    constructor(message: string, statusCode?: number);
+}
+export declare function normalizeApiPath(value: string): string;
+export declare function joinApiPath(...parts: Array<string | null | undefined>): string;
+export declare function getApiErrorMessage(error: any): any;
+export declare function isPlainApiObject(value: any): boolean;
+export declare function normalizeApiFunctionProvider(provider: any): ApiFunctionClass[];
+export declare function getApiFunctionClasses(scope: ApiScope): ApiFunctionClass[];
+export declare function normalizeApiScopesGroupProvider(provider: any): ApiScopeClass[];
+export declare function isApiScopesGroupInstance(value: any): value is ApiScopesGroup;
+export declare function instantiateApiScopesGroup(GroupClass: ApiScopesGroupClass): ApiScopesGroup;
+export declare function collectApiScopeRegistrations(registrations: ApiScopeRegistrationClass[]): ApiScopeRegistrationEntry[];
+export declare function runApiScopeMiddleware(scope: ApiScope, req: Request, res: Response): Promise<{
+    [key: string]: any;
+}>;
+export declare function runApiScopesGroupMiddleware(group: ApiScopesGroup, req: Request, res: Response): Promise<{
+    [key: string]: any;
+}>;
+export declare function runApiScopeGroupMiddleware(scope: ApiScope, req: Request, res: Response): Promise<{
+    [key: string]: any;
+}>;
+export declare function runApiScopeRegistrationMiddleware(registration: ApiScopeRegistrationEntry, req: Request, res: Response): Promise<{
+    [x: string]: any;
+}>;
+export declare function validateApiFunctionParams(definitions: ApiFunctionParamsDefinition, source: {
+    [key: string]: any;
+}): {
+    [key: string]: any;
+};
+export declare function coerceApiFunctionParam(key: string, value: any, definition: ApiFunctionParamDefinition): any;
+export declare function apiFunctionParamsToJsonSchema(definitions: ApiFunctionParamsDefinition): {
+    type: string;
+    properties: {
+        [key: string]: any;
+    };
+    required: string[];
+    additionalProperties: boolean;
+};
+export declare function apiFunctionParamToJsonSchema(definition: ApiFunctionParamDefinition): {
+    type: string;
+    pattern?: undefined;
+    items?: undefined;
+    enum?: undefined;
+} | {
+    type: string;
+    pattern: string;
+    items?: undefined;
+    enum?: undefined;
+} | {
+    type: string;
+    items: {};
+    pattern?: undefined;
+    enum?: undefined;
+} | {
+    enum: any[];
+    type?: undefined;
+    pattern?: undefined;
+    items?: undefined;
+};
+export declare function toApiFunctionHttpResult(res: Response, result: any): Response;
+export declare function toApiFunctionPayload(result: any): any;
+export declare function createApiFrameworkRequest(req: IncomingMessage): Request;
+export declare function assertUniqueApiFunctionKeys(scope: ApiScope, functions: ApiFunctionClass[]): void;
+export declare function instantiateApiScope(ScopeClass: ApiScopeClass): ApiScope;
+export declare function instantiateApiFunction(FunctionClass: ApiFunctionClass): ApiFunction;

package/dist/Api/ApiFunctionUtils.js

@@ -0,0 +1,351 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.instantiateApiFunction = exports.instantiateApiScope = exports.assertUniqueApiFunctionKeys = exports.createApiFrameworkRequest = exports.toApiFunctionPayload = exports.toApiFunctionHttpResult = exports.apiFunctionParamToJsonSchema = exports.apiFunctionParamsToJsonSchema = exports.coerceApiFunctionParam = exports.validateApiFunctionParams = exports.runApiScopeRegistrationMiddleware = exports.runApiScopeGroupMiddleware = exports.runApiScopesGroupMiddleware = exports.runApiScopeMiddleware = exports.collectApiScopeRegistrations = exports.instantiateApiScopesGroup = exports.isApiScopesGroupInstance = exports.normalizeApiScopesGroupProvider = exports.getApiFunctionClasses = exports.normalizeApiFunctionProvider = exports.isPlainApiObject = exports.getApiErrorMessage = exports.joinApiPath = exports.normalizeApiPath = exports.ApiFunctionRuntimeError = void 0;
+const Request_1 = require("../Router/Request");
+const ApiFunction_1 = require("./ApiFunction");
+const ApiScopesGroup_1 = require("./ApiScopesGroup");
+class ApiFunctionRuntimeError extends Error {
+    constructor(message, statusCode = 500) {
+        super(message);
+        this.statusCode = statusCode;
+    }
+}
+exports.ApiFunctionRuntimeError = ApiFunctionRuntimeError;
+function normalizeApiPath(value) {
+    const trimmed = value && value.trim() !== "" ? value.trim() : "/";
+    const withSlash = trimmed.startsWith("/") ? trimmed : "/" + trimmed;
+    const collapsed = withSlash.replace(/\/+/g, "/");
+    return collapsed.length > 1 ? collapsed.replace(/\/+$/, "") : collapsed;
+}
+exports.normalizeApiPath = normalizeApiPath;
+function joinApiPath(...parts) {
+    const cleaned = parts
+        .filter((part) => typeof part === "string" && part.trim() !== "")
+        .map((part) => part.trim().replace(/^\/+|\/+$/g, ""))
+        .filter((part) => part !== "");
+    return normalizeApiPath("/" + cleaned.join("/"));
+}
+exports.joinApiPath = joinApiPath;
+function getApiErrorMessage(error) {
+    if (error && typeof error === "string" && error.trim() !== "") {
+        return error.trim();
+    }
+    if (error && error.message && typeof error.message === "string" && error.message.trim() !== "") {
+        return error.message.trim();
+    }
+    if (error && error.toString && error.toString().trim() !== "") {
+        return error.toString().trim();
+    }
+    return "Internal Server Error";
+}
+exports.getApiErrorMessage = getApiErrorMessage;
+function isPlainApiObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value) && !(value instanceof Buffer);
+}
+exports.isPlainApiObject = isPlainApiObject;
+function normalizeApiFunctionProvider(provider) {
+    if (typeof provider === "function") {
+        const resolved = provider();
+        if (resolved && typeof resolved.then === "function") {
+            throw new Error("Async ApiScope.functions providers are not supported during web boot");
+        }
+        return Array.isArray(resolved) ? resolved : [];
+    }
+    return Array.isArray(provider) ? provider : [];
+}
+exports.normalizeApiFunctionProvider = normalizeApiFunctionProvider;
+function getApiFunctionClasses(scope) {
+    const functions = normalizeApiFunctionProvider(scope.functions);
+    assertUniqueApiFunctionKeys(scope, functions);
+    return functions;
+}
+exports.getApiFunctionClasses = getApiFunctionClasses;
+function createApiScopeMiddlewareAbort() {
+    const abort = (message, status = 403) => {
+        throw new ApiFunctionRuntimeError(getApiErrorMessage(message || "Request aborted"), status);
+    };
+    return abort;
+}
+function normalizeApiScopesGroupProvider(provider) {
+    if (typeof provider === "function") {
+        const resolved = provider();
+        if (resolved && typeof resolved.then === "function") {
+            throw new Error("Async ApiScopesGroup.apiScopes providers are not supported during web boot");
+        }
+        return Array.isArray(resolved) ? resolved : [];
+    }
+    return Array.isArray(provider) ? provider : [];
+}
+exports.normalizeApiScopesGroupProvider = normalizeApiScopesGroupProvider;
+function isApiScopesGroupInstance(value) {
+    return value instanceof ApiScopesGroup_1.ApiScopesGroup;
+}
+exports.isApiScopesGroupInstance = isApiScopesGroupInstance;
+function instantiateApiScopesGroup(GroupClass) {
+    return new GroupClass();
+}
+exports.instantiateApiScopesGroup = instantiateApiScopesGroup;
+function collectApiScopeRegistrations(registrations) {
+    const entries = [];
+    for (const RegistrationClass of registrations || []) {
+        if (typeof RegistrationClass !== "function") {
+            continue;
+        }
+        const registration = new RegistrationClass();
+        if (isApiScopesGroupInstance(registration)) {
+            for (const ScopeClass of normalizeApiScopesGroupProvider(registration.apiScopes)) {
+                if (typeof ScopeClass === "function") {
+                    entries.push({
+                        scopeClass: ScopeClass,
+                        groupClass: RegistrationClass,
+                    });
+                }
+            }
+            continue;
+        }
+        entries.push({
+            scopeClass: RegistrationClass,
+        });
+    }
+    return entries;
+}
+exports.collectApiScopeRegistrations = collectApiScopeRegistrations;
+function runApiScopeMiddleware(scope, req, res) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const abort = createApiScopeMiddlewareAbort();
+        const result = yield scope.middleware(req, res, abort);
+        return isPlainApiObject(result) ? result : {};
+    });
+}
+exports.runApiScopeMiddleware = runApiScopeMiddleware;
+function runApiScopesGroupMiddleware(group, req, res) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const abort = createApiScopeMiddlewareAbort();
+        const result = yield group.middleware(req, res, abort);
+        return isPlainApiObject(result) ? result : {};
+    });
+}
+exports.runApiScopesGroupMiddleware = runApiScopesGroupMiddleware;
+function runApiScopeGroupMiddleware(scope, req, res) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const abort = createApiScopeMiddlewareAbort();
+        const result = yield scope.groupMiddleware(req, res, abort);
+        return isPlainApiObject(result) ? result : {};
+    });
+}
+exports.runApiScopeGroupMiddleware = runApiScopeGroupMiddleware;
+function runApiScopeRegistrationMiddleware(registration, req, res) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const groupContext = registration.groupClass
+            ? yield runApiScopesGroupMiddleware(instantiateApiScopesGroup(registration.groupClass), req, res)
+            : {};
+        const scope = instantiateApiScope(registration.scopeClass);
+        const scopeContext = yield runApiScopeMiddleware(scope, req, res);
+        const groupScopeContext = registration.groupClass ? yield runApiScopeGroupMiddleware(scope, req, res) : {};
+        return Object.assign(Object.assign(Object.assign({}, groupContext), scopeContext), groupScopeContext);
+    });
+}
+exports.runApiScopeRegistrationMiddleware = runApiScopeRegistrationMiddleware;
+function validateApiFunctionParams(definitions, source) {
+    const params = {};
+    const input = isPlainApiObject(source) ? source : {};
+    for (const key of Object.keys(definitions || {})) {
+        const definition = definitions[key] || {};
+        const hasValue = input[key] !== undefined && input[key] !== null && input[key] !== "";
+        const value = hasValue ? input[key] : definition.default;
+        if ((value === undefined || value === null || value === "") && definition.required) {
+            throw new ApiFunctionRuntimeError(`Missing required parameter "${key}"`, 400);
+        }
+        if (value === undefined || value === null || value === "") {
+            params[key] = value;
+            continue;
+        }
+        params[key] = coerceApiFunctionParam(key, value, definition);
+    }
+    return params;
+}
+exports.validateApiFunctionParams = validateApiFunctionParams;
+function coerceApiFunctionParam(key, value, definition) {
+    const type = (definition.type || "string").toLowerCase();
+    if (type === "string") {
+        return typeof value === "string" ? value : value.toString();
+    }
+    if (type === "number" || type === "float") {
+        const parsed = typeof value === "number" ? value : parseFloat(value);
+        if (isNaN(parsed)) {
+            throw new ApiFunctionRuntimeError(`Parameter "${key}" must be a number`, 400);
+        }
+        return parsed;
+    }
+    if (type === "integer" || type === "int") {
+        const parsed = typeof value === "number" ? value : parseInt(value, 10);
+        if (isNaN(parsed)) {
+            throw new ApiFunctionRuntimeError(`Parameter "${key}" must be an integer`, 400);
+        }
+        return parsed;
+    }
+    if (type === "boolean" || type === "bool") {
+        if (typeof value === "boolean") {
+            return value;
+        }
+        const normalized = value.toString().toLowerCase();
+        if (["true", "1", "yes", "on"].includes(normalized)) {
+            return true;
+        }
+        if (["false", "0", "no", "off"].includes(normalized)) {
+            return false;
+        }
+        throw new ApiFunctionRuntimeError(`Parameter "${key}" must be a boolean`, 400);
+    }
+    if (type === "objectid") {
+        const stringValue = value.toString();
+        if (!/^[a-fA-F0-9]{24}$/.test(stringValue)) {
+            throw new ApiFunctionRuntimeError(`Parameter "${key}" must be a valid ObjectId`, 400);
+        }
+        return stringValue;
+    }
+    if (type === "option") {
+        const allowedValues = Array.isArray(definition.options) ? definition.options.map((option) => option.value) : [];
+        if (allowedValues.length > 0 && !allowedValues.includes(value)) {
+            throw new ApiFunctionRuntimeError(`Parameter "${key}" must be one of: ${allowedValues.join(", ")}`, 400);
+        }
+        return value;
+    }
+    if (type === "array") {
+        if (Array.isArray(value)) {
+            return value;
+        }
+        if (typeof value === "string") {
+            try {
+                const parsed = JSON.parse(value);
+                if (Array.isArray(parsed)) {
+                    return parsed;
+                }
+            }
+            catch (_error) { }
+        }
+        throw new ApiFunctionRuntimeError(`Parameter "${key}" must be an array`, 400);
+    }
+    if (type === "object") {
+        if (isPlainApiObject(value)) {
+            return value;
+        }
+        if (typeof value === "string") {
+            try {
+                const parsed = JSON.parse(value);
+                if (isPlainApiObject(parsed)) {
+                    return parsed;
+                }
+            }
+            catch (_error) { }
+        }
+        throw new ApiFunctionRuntimeError(`Parameter "${key}" must be an object`, 400);
+    }
+    return value;
+}
+exports.coerceApiFunctionParam = coerceApiFunctionParam;
+function apiFunctionParamsToJsonSchema(definitions) {
+    const properties = {};
+    const required = [];
+    for (const key of Object.keys(definitions || {})) {
+        const definition = definitions[key] || {};
+        const schema = apiFunctionParamToJsonSchema(definition);
+        if (definition.description) {
+            schema.description = definition.description;
+        }
+        if (definition.default !== undefined) {
+            schema.default = definition.default;
+        }
+        if (definition.required && definition.default === undefined) {
+            required.push(key);
+        }
+        properties[key] = schema;
+    }
+    return {
+        type: "object",
+        properties,
+        required,
+        additionalProperties: false,
+    };
+}
+exports.apiFunctionParamsToJsonSchema = apiFunctionParamsToJsonSchema;
+function apiFunctionParamToJsonSchema(definition) {
+    const type = (definition.type || "string").toLowerCase();
+    if (type === "number" || type === "float")
+        return { type: "number" };
+    if (type === "integer" || type === "int")
+        return { type: "integer" };
+    if (type === "boolean" || type === "bool")
+        return { type: "boolean" };
+    if (type === "objectid")
+        return { type: "string", pattern: "^[a-fA-F0-9]{24}$" };
+    if (type === "array")
+        return { type: "array", items: {} };
+    if (type === "object")
+        return { type: "object" };
+    if (type === "option" && Array.isArray(definition.options) && definition.options.length > 0) {
+        return { enum: definition.options.map((option) => option.value) };
+    }
+    return { type: "string" };
+}
+exports.apiFunctionParamToJsonSchema = apiFunctionParamToJsonSchema;
+function toApiFunctionHttpResult(res, result) {
+    if (result instanceof ApiFunction_1.ApiFunctionResponse) {
+        res.status(result.status);
+        return res.send(result.getData());
+    }
+    return res.send(result);
+}
+exports.toApiFunctionHttpResult = toApiFunctionHttpResult;
+function toApiFunctionPayload(result) {
+    return result instanceof ApiFunction_1.ApiFunctionResponse ? result.getData() : result;
+}
+exports.toApiFunctionPayload = toApiFunctionPayload;
+function createApiFrameworkRequest(req) {
+    const parsedUrl = new URL(req.url || "/", "http://webframez.local");
+    const request = new Request_1.Request();
+    request.message = req;
+    request.headers = req.headers;
+    request.rawHeaders = req.rawHeaders;
+    request.url = req.url || "";
+    request.method = req.method || "";
+    request.socket = req.socket;
+    request.query = Object.fromEntries(parsedUrl.searchParams.entries());
+    request.queryRaw = parsedUrl.search ? parsedUrl.search.substring(1) : "";
+    request.pathname = parsedUrl.pathname;
+    request.body = {};
+    request.bodyPlain = "";
+    return request;
+}
+exports.createApiFrameworkRequest = createApiFrameworkRequest;
+function assertUniqueApiFunctionKeys(scope, functions) {
+    const seen = {};
+    for (const FunctionClass of functions) {
+        const func = new FunctionClass();
+        if (!func.key || func.key.trim() === "") {
+            throw new Error(`ApiFunction in scope "${scope.key}" is missing a key`);
+        }
+        if (seen[func.key]) {
+            throw new Error(`Duplicate ApiFunction key "${func.key}" in scope "${scope.key}"`);
+        }
+        seen[func.key] = true;
+    }
+}
+exports.assertUniqueApiFunctionKeys = assertUniqueApiFunctionKeys;
+function instantiateApiScope(ScopeClass) {
+    return new ScopeClass();
+}
+exports.instantiateApiScope = instantiateApiScope;
+function instantiateApiFunction(FunctionClass) {
+    return new FunctionClass();
+}
+exports.instantiateApiFunction = instantiateApiFunction;

package/dist/Api/ApiScope.d.ts

@@ -0,0 +1,15 @@
+import { Request } from "../Router/Request";
+import { Response } from "../Router/Response";
+import { ApiFunctionClass, ApiScopeMiddlewareAbort } from "./ApiTypes";
+export declare class ApiScope {
+    key: string;
+    apiBasePath: string | null;
+    mcpEndpoint: string | null;
+    functions: Array<ApiFunctionClass> | (() => Array<ApiFunctionClass>);
+    middleware(_req: Request, _res: Response, _abort: ApiScopeMiddlewareAbort): Promise<{
+        [key: string]: any;
+    }>;
+    groupMiddleware(_req: Request, _res: Response, _abort: ApiScopeMiddlewareAbort): Promise<{
+        [key: string]: any;
+    }>;
+}

package/dist/Api/ApiScope.js

@@ -0,0 +1,31 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiScope = void 0;
+class ApiScope {
+    constructor() {
+        this.key = "unique_scope_key";
+        this.apiBasePath = "/api";
+        this.mcpEndpoint = null;
+        this.functions = [];
+    }
+    middleware(_req, _res, _abort) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return {};
+        });
+    }
+    groupMiddleware(_req, _res, _abort) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return {};
+        });
+    }
+}
+exports.ApiScope = ApiScope;

package/dist/Api/ApiScopeRegistry.d.ts

@@ -0,0 +1,17 @@
+import { ApiScopeRegistrationEntry } from "./ApiFunctionUtils";
+type ApiScopeRuntimeContext = {
+    kernel?: any;
+    modulesLoader?: any;
+};
+declare class ApiScopeRegistryFacade {
+    private context;
+    configure(context?: ApiScopeRuntimeContext): this;
+    collect(context?: ApiScopeRuntimeContext): ApiScopeRegistrationEntry[];
+    register(context?: ApiScopeRuntimeContext): this;
+    private registerHttpRoutes;
+    private registerRouteMethod;
+    private handleHttpFunction;
+    private assertUniqueApiPaths;
+}
+export declare const ApiScopeRegistry: ApiScopeRegistryFacade;
+export {};

package/dist/Api/ApiScopeRegistry.js

@@ -0,0 +1,130 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiScopeRegistry = void 0;
+const Route_1 = require("../Router/Route");
+const ApiFunctionUtils_1 = require("./ApiFunctionUtils");
+function getModuleInstances(modulesLoader) {
+    if (!modulesLoader) {
+        return [];
+    }
+    if (typeof modulesLoader.getLoadedModuleInstances === "function") {
+        return modulesLoader.getLoadedModuleInstances();
+    }
+    if (typeof modulesLoader.getLoadedModules === "function") {
+        const modules = modulesLoader.getLoadedModules();
+        return Object.keys(modules || {}).map((key) => modules[key]);
+    }
+    return [];
+}
+class ApiScopeRegistryFacade {
+    constructor() {
+        this.context = {};
+    }
+    configure(context) {
+        this.context = Object.assign(Object.assign({}, (this.context || {})), (context || {}));
+        return this;
+    }
+    collect(context) {
+        const runtimeContext = Object.assign(Object.assign({}, (this.context || {})), (context || {}));
+        const scopes = [];
+        const kernelScopes = runtimeContext.kernel && Array.isArray(runtimeContext.kernel.apiScopes) ? runtimeContext.kernel.apiScopes : [];
+        scopes.push(...kernelScopes);
+        for (const mod of getModuleInstances(runtimeContext.modulesLoader)) {
+            const moduleScopes = Array.isArray(mod && mod.apiScopes)
+                ? mod.apiScopes
+                : Array.isArray(mod && mod.constructor && mod.constructor.apiScopes)
+                    ? mod.constructor.apiScopes
+                    : [];
+            scopes.push(...moduleScopes);
+        }
+        return (0, ApiFunctionUtils_1.collectApiScopeRegistrations)(scopes);
+    }
+    register(context) {
+        this.configure(context);
+        const scopes = this.collect(context);
+        this.assertUniqueApiPaths(scopes);
+        for (const registration of scopes) {
+            this.registerHttpRoutes(registration);
+        }
+        return this;
+    }
+    registerHttpRoutes(registration) {
+        const scope = (0, ApiFunctionUtils_1.instantiateApiScope)(registration.scopeClass);
+        if (!scope.apiBasePath) {
+            return;
+        }
+        for (const FunctionClass of (0, ApiFunctionUtils_1.getApiFunctionClasses)(scope)) {
+            const func = (0, ApiFunctionUtils_1.instantiateApiFunction)(FunctionClass);
+            if (func.requestMethod === null) {
+                continue;
+            }
+            const path = (0, ApiFunctionUtils_1.joinApiPath)(scope.apiBasePath, func.key);
+            const handler = (req, res) => __awaiter(this, void 0, void 0, function* () {
+                return yield this.handleHttpFunction(registration, FunctionClass, req, res);
+            });
+            this.registerRouteMethod(func.requestMethod, path, handler);
+        }
+    }
+    registerRouteMethod(method, path, handler) {
+        if (!method) {
+            return;
+        }
+        const methodName = method.toLowerCase();
+        const routeMethod = Route_1.Route[methodName];
+        if (!routeMethod || typeof routeMethod !== "function") {
+            throw new Error(`ApiFunction request method "${method}" is not supported by Route`);
+        }
+        routeMethod.bind(Route_1.Route)(path, handler);
+    }
+    handleHttpFunction(registration, FunctionClass, req, res) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const func = (0, ApiFunctionUtils_1.instantiateApiFunction)(FunctionClass);
+            try {
+                const context = yield (0, ApiFunctionUtils_1.runApiScopeRegistrationMiddleware)(registration, req, res);
+                const paramsSource = (func.requestMethod || req.method).toUpperCase() === "GET" ? req.query : req.body;
+                const params = (0, ApiFunctionUtils_1.validateApiFunctionParams)(func.params || {}, paramsSource || {});
+                const result = yield func.handle({ context, params, request: req, response: res });
+                return (0, ApiFunctionUtils_1.toApiFunctionHttpResult)(res, result);
+            }
+            catch (error) {
+                const statusCode = error && error.statusCode && !isNaN(parseInt(error.statusCode)) ? parseInt(error.statusCode) : 500;
+                return res.status(statusCode).send({
+                    status: "error",
+                    message: (0, ApiFunctionUtils_1.getApiErrorMessage)(error),
+                });
+            }
+        });
+    }
+    assertUniqueApiPaths(scopes) {
+        const seen = {};
+        for (const registration of scopes) {
+            const scope = (0, ApiFunctionUtils_1.instantiateApiScope)(registration.scopeClass);
+            if (!scope.apiBasePath) {
+                continue;
+            }
+            for (const FunctionClass of (0, ApiFunctionUtils_1.getApiFunctionClasses)(scope)) {
+                const func = (0, ApiFunctionUtils_1.instantiateApiFunction)(FunctionClass);
+                if (func.requestMethod === null) {
+                    continue;
+                }
+                const method = func.requestMethod || "GET";
+                const path = (0, ApiFunctionUtils_1.joinApiPath)(scope.apiBasePath, func.key);
+                const lookupKey = `${method}:${path}`;
+                if (seen[lookupKey]) {
+                    throw new Error(`Duplicate ApiFunction route "${lookupKey}"`);
+                }
+                seen[lookupKey] = true;
+            }
+        }
+    }
+}
+exports.ApiScopeRegistry = new ApiScopeRegistryFacade();

package/dist/Api/ApiScopesGroup.d.ts

@@ -0,0 +1,10 @@
+import { Request } from "../Router/Request";
+import { Response } from "../Router/Response";
+import { ApiScopeClass, ApiScopeMiddlewareAbort } from "./ApiTypes";
+export declare class ApiScopesGroup {
+    key: string;
+    apiScopes: Array<ApiScopeClass> | (() => Array<ApiScopeClass>);
+    middleware(_req: Request, _res: Response, _abort: ApiScopeMiddlewareAbort): Promise<{
+        [key: string]: any;
+    }>;
+}

package/dist/Api/ApiScopesGroup.js

@@ -0,0 +1,24 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiScopesGroup = void 0;
+class ApiScopesGroup {
+    constructor() {
+        this.key = "unique_api_scopes_group_key";
+        this.apiScopes = [];
+    }
+    middleware(_req, _res, _abort) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return {};
+        });
+    }
+}
+exports.ApiScopesGroup = ApiScopesGroup;

package/dist/Api/ApiTypes.d.ts

@@ -0,0 +1,35 @@
+import { Request } from "../Router/Request";
+import { Response } from "../Router/Response";
+export type ApiFunctionRequestMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | null;
+export type ApiFunctionResponseType = "response" | "confirm" | "ask";
+export type ApiScopeFunctionContext = {
+    [key: string]: any;
+};
+export type ApiFunctionParamOption = {
+    value: any;
+    label?: string;
+};
+export type ApiFunctionParamDefinition = {
+    type?: string;
+    required?: boolean;
+    default?: any;
+    options?: ApiFunctionParamOption[];
+    description?: string;
+    label?: string;
+};
+export type ApiFunctionParamsDefinition = {
+    [key: string]: ApiFunctionParamDefinition;
+};
+export type ApiFunctionClass = new (...args: any[]) => any;
+export type ApiScopeClass = new (...args: any[]) => any;
+export type ApiScopesGroupClass = new (...args: any[]) => any;
+export type ApiScopeRegistrationClass = ApiScopeClass | ApiScopesGroupClass;
+export type ApiScopeMiddlewareAbort = (message?: any, status?: number) => never;
+export type ApiFunctionRequest = {
+    context: ApiScopeFunctionContext;
+    params: {
+        [key: string]: any;
+    };
+    request?: Request;
+    response?: Response;
+};

package/dist/Api/ApiTypes.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/BaseKernelWeb.d.ts

@@ -1,6 +1,7 @@
 import { Controller } from "./Controller/Controller";
 import { KernelAiRegistrations } from "./Ai/AiTypes";
 import { KernelMcpRegistrations } from "./Mcp/McpTypes";
+import { ApiScopeRegistrationClass } from "./Api/ApiTypes";
 export declare class BaseKernelWeb {
     static controller: {
         [key: string]: Controller;
@@ -8,6 +9,7 @@ export declare class BaseKernelWeb {
     static middleware: {
         [key: string]: any;
     };
+    static apiScopes: ApiScopeRegistrationClass[];
     static mcp?: KernelMcpRegistrations;
     static ai?: KernelAiRegistrations;
 }

package/dist/BaseKernelWeb.js

@@ -6,3 +6,4 @@ class BaseKernelWeb {
 exports.BaseKernelWeb = BaseKernelWeb;
 BaseKernelWeb.controller = {};
 BaseKernelWeb.middleware = {};
+BaseKernelWeb.apiScopes = [];

package/dist/Facades/Storage.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+/// <reference types="node" />
 import { BaseStorageDriver, StorageDeleteOptions, StorageMkdirOptions, StorageReadDirOptions } from "./StorageDrivers/BaseStorageDriver";
 declare class StorageDriverRegistyFacade {
     drivers: {

package/dist/Facades/StorageDrivers/BaseStorageDriver.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+/// <reference types="node" />
 export type StorageDeleteOptions = {
     recursive?: boolean;
     force?: boolean;

package/dist/Facades/StorageDrivers/LocalStorageDriver.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+/// <reference types="node" />
 import { BaseStorageDriver, StorageDeleteOptions, StorageMkdirOptions, StorageReadDirOptions } from "./BaseStorageDriver";
 import { Request } from "../../Router/Request";
 export declare class LocalStorageDriver implements BaseStorageDriver {

package/dist/Mcp/McpTypes.d.ts

@@ -1,5 +1,5 @@
 export type KernelMcpWebServerRegistration = {
-    path: string;
+    path?: string;
     server: any;
     middleware?: string[];
     allowedOrigins?: string[];

package/dist/Modules/ModuleProvider.d.ts

@@ -1,4 +1,5 @@
 import { KernelAiRegistrations } from "../Ai/AiTypes";
+import { ApiScopeRegistrationClass } from "../Api/ApiTypes";
 import { KernelMcpRegistrations } from "../Mcp/McpTypes";
 export declare class ModuleProvider {
     static key: string;
@@ -8,6 +9,7 @@ export declare class ModuleProvider {
     middleware: {
         [key: string]: any;
     };
+    apiScopes: ApiScopeRegistrationClass[];
     commands: any[];
     mcp?: KernelMcpRegistrations;
     ai?: KernelAiRegistrations;

package/dist/Modules/ModuleProvider.js

@@ -5,6 +5,7 @@ class ModuleProvider {
     constructor() {
         this.controller = {};
         this.middleware = {};
+        this.apiScopes = [];
         this.commands = [];
     }
     boot(_context) { }

package/dist/Router/Route.d.ts

@@ -37,6 +37,14 @@ export declare class RouteFacade {
      * @param options
      */
     put(path: string, component: any, options?: RouteRegistrationOptions): void;
+    /**
+     * Register a PATCH-Method
+     *
+     * @param path
+     * @param component
+     * @param options
+     */
+    patch(path: string, component: any, options?: RouteRegistrationOptions): void;
     /**
      * Register a DELETE-Method
      *

package/dist/Router/Route.js

@@ -79,6 +79,16 @@ class RouteFacade {
     put(path, component, options) {
         this.registerWithGroupContext("PUT", path, component, options);
     }
+    /**
+     * Register a PATCH-Method
+     *
+     * @param path
+     * @param component
+     * @param options
+     */
+    patch(path, component, options) {
+        this.registerWithGroupContext("PATCH", path, component, options);
+    }
     /**
      * Register a DELETE-Method
      *

package/dist/Router/Router.d.ts

@@ -53,6 +53,12 @@ declare class RouterFacade {
     routesPUT: {
         [key: string]: RouteObject[];
     };
+    /**
+     * PATCH Route Store
+     */
+    routesPATCH: {
+        [key: string]: RouteObject[];
+    };
     /**
      * DELETE Route Store
      */

package/dist/Router/Router.js

@@ -47,6 +47,10 @@ class RouterFacade {
          * PUT Route Store
          */
         this.routesPUT = {};
+        /**
+         * PATCH Route Store
+         */
+        this.routesPATCH = {};
         /**
          * DELETE Route Store
          */
@@ -66,6 +70,7 @@ class RouterFacade {
         this.routesGET = {};
         this.routesPOST = {};
         this.routesPUT = {};
+        this.routesPATCH = {};
         this.routesDELETE = {};
         // Load routes
         if (options.routesFunction) {
@@ -136,6 +141,12 @@ class RouterFacade {
             }
             this.routesPUT[path].push(routeConf);
         }
+        else if (type === "PATCH") {
+            if (!this.routesPATCH[path]) {
+                this.routesPATCH[path] = [];
+            }
+            this.routesPATCH[path].push(routeConf);
+        }
         else if (type === "DELETE") {
             if (!this.routesDELETE[path]) {
                 this.routesDELETE[path] = [];
@@ -167,6 +178,9 @@ class RouterFacade {
         else if (req.method === "PUT") {
             return this.dissolveRoute(this.routesPUT, cleanUrl, req);
         }
+        else if (req.method === "PATCH") {
+            return this.dissolveRoute(this.routesPATCH, cleanUrl, req);
+        }
         else if (req.method === "DELETE") {
             return this.dissolveRoute(this.routesDELETE, cleanUrl, req);
         }
@@ -180,6 +194,9 @@ class RouterFacade {
             else if (req.headers["access-control-request-method"] === "PUT") {
                 return this.dissolveRoute(this.routesPUT, cleanUrl, req);
             }
+            else if (req.headers["access-control-request-method"] === "PATCH") {
+                return this.dissolveRoute(this.routesPATCH, cleanUrl, req);
+            }
             else if (req.headers["access-control-request-method"] === "DELETE") {
                 return this.dissolveRoute(this.routesDELETE, cleanUrl, req);
             }

package/dist/WebApplication.js

@@ -23,6 +23,7 @@ const ModulesLoader_1 = require("./Modules/ModulesLoader");
 const ErrorHandler_1 = require("./ErrorHandling/ErrorHandler");
 const WebframezHooks_1 = require("./Hooks/WebframezHooks");
 const HttpKernelHandlerRegistry_1 = require("./Http/HttpKernelHandlerRegistry");
+const ApiScopeRegistry_1 = require("./Api/ApiScopeRegistry");
 // import { SigNozTelemetry } from "./Telemetry/SigNozTelemetry";
 class WebApplication {
     constructor() {
@@ -72,6 +73,10 @@ class WebApplication {
             tempDir: options && options.tempDir ? options.tempDir : null,
         });
         this.modulesLoader.initRoutes();
+        ApiScopeRegistry_1.ApiScopeRegistry.register({
+            kernel: options && options.kernel ? options.kernel : null,
+            modulesLoader: this.modulesLoader,
+        });
         if (options && options.datatables) {
             DatatableRegistry_1.DatatableRegistry.registerMany(options.datatables);
         }

package/dist/index.d.ts

@@ -40,6 +40,12 @@ export * from "./Commands/ConsoleOutputHelper";
 export * from "./Modules/ModuleProvider";
 export * from "./ErrorHandling/ErrorHandler";
 export * from "./Hooks/WebframezHooks";
+export * from "./Api/ApiTypes";
+export * from "./Api/ApiFunction";
+export * from "./Api/ApiScope";
+export * from "./Api/ApiScopesGroup";
+export * from "./Api/ApiFunctionUtils";
+export * from "./Api/ApiScopeRegistry";
 export * from "./Ai/AiTypes";
 export * from "./Mcp/McpTypes";
 export * from "./Http/HttpKernelHandlerRegistry";

package/dist/index.js

@@ -56,6 +56,12 @@ __exportStar(require("./Commands/ConsoleOutputHelper"), exports);
 __exportStar(require("./Modules/ModuleProvider"), exports);
 __exportStar(require("./ErrorHandling/ErrorHandler"), exports);
 __exportStar(require("./Hooks/WebframezHooks"), exports);
+__exportStar(require("./Api/ApiTypes"), exports);
+__exportStar(require("./Api/ApiFunction"), exports);
+__exportStar(require("./Api/ApiScope"), exports);
+__exportStar(require("./Api/ApiScopesGroup"), exports);
+__exportStar(require("./Api/ApiFunctionUtils"), exports);
+__exportStar(require("./Api/ApiScopeRegistry"), exports);
 __exportStar(require("./Ai/AiTypes"), exports);
 __exportStar(require("./Mcp/McpTypes"), exports);
 __exportStar(require("./Http/HttpKernelHandlerRegistry"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@webtypen/webframez-core",
-    "version": "0.3.38",
+    "version": "0.3.40",
     "description": "The core package of the typescript based webframez (web-framework) by webtypen.de",
     "homepage": "https://webtypen.de/",
     "license": "MIT",