@webtypen/webframez-core 0.3.37 → 0.3.39

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,105 @@ 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.
+
+### Register ApiScopes
+
+Register scopes on the web kernel:
+
+```ts
+import { BaseKernelWeb } from "@webtypen/webframez-core";
+
+class Kernel extends BaseKernelWeb {
+  static apiScopes = [BackofficeApiScope];
+}
+```
+
+Modules can register scopes as instance properties:
+
+```ts
+import { ModuleProvider } from "@webtypen/webframez-core";
+
+class BackofficeModuleProvider extends ModuleProvider {
+  apiScopes = [BackofficeApiScope];
+}
+```
+
+### 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`.
@@ -453,6 +555,119 @@ export default {
 Additional built-in command:
 - `build`
 
+## Backups
+
+Backups are configured through `config.backup`, usually by importing `config/backup.ts` next to your database and queue configs. Core ships the local filesystem output driver and a generic adapter registry.
+
+```ts
+export default {
+  defaults: {
+    workDir: "storage/backups/.work",
+    outputDir: "storage/backups",
+    filename: "{key}_{date}_{time}",
+    zip: true,
+    cleanupWorkDir: true,
+    retention: {
+      keepLast: 10,
+      maxAgeDays: 30,
+      runAfterBackup: true
+    }
+  },
+  types: {
+    daily_full: {
+      is_active: true,
+      files: [
+        {
+          from: "storage",
+          to: "storage",
+          include: ["**/*"],
+          exclude: ["queue/**", "backups/**"]
+        }
+      ],
+      databases: [
+        {
+          connection: "default",
+          to: "database/default",
+          options: {}
+        }
+      ],
+      outputs: [
+        {
+          driver: "local",
+          path: "storage/backups/daily",
+          retention: {
+            keepLast: 14,
+            maxAgeDays: 60,
+            runAfterBackup: true
+          }
+        }
+      ],
+      automation: {
+        worker: "worker_1",
+        executions: [["daily", "02:00"]],
+        priority: 10
+      }
+    }
+  }
+};
+```
+
+Built-in backup commands:
+- `backup:list`
+- `backup:run <key> [--dry-run] [--channel=local]`
+- `backup:queue <key> [--worker=worker_1] [--priority=10]`
+- `backup:cleanup <key> [--channel=local] [--dry-run]`
+
+Remote outputs are optional packages and must be registered by the application before the backup config is used:
+
+```ts
+import { BackupOutputDrivers } from "@webtypen/webframez-core";
+import { GoogleDriveBackupOutputDriver } from "@webtypen/webframez-backups-googledrive";
+import { OneDriveBackupOutputDriver } from "@webtypen/webframez-backups-onedrive";
+import { SftpBackupOutputDriver } from "@webtypen/webframez-backups-sftp";
+import { FtpBackupOutputDriver } from "@webtypen/webframez-backups-ftp";
+
+BackupOutputDrivers.register("google_drive", GoogleDriveBackupOutputDriver);
+BackupOutputDrivers.register("one_drive", OneDriveBackupOutputDriver);
+BackupOutputDrivers.register("sftp", SftpBackupOutputDriver);
+BackupOutputDrivers.register("ftp", FtpBackupOutputDriver);
+
+export default {
+  types: {
+    daily_google_drive: {
+      is_active: true,
+      files: [{ from: "storage", to: "storage", exclude: ["backups/**", "queue/**"] }],
+      outputs: [
+        {
+          driver: "google_drive",
+          folderId: process.env.GOOGLE_DRIVE_BACKUP_FOLDER_ID,
+          auth: {
+            keyFile: process.env.GOOGLE_APPLICATION_CREDENTIALS
+          },
+          retention: {
+            keepLast: 30,
+            maxAgeDays: 90,
+            runAfterBackup: true
+          }
+        }
+      ],
+      automation: {
+        worker: "worker_1",
+        executions: [["daily", "03:00"], ["daily", "12:00"]]
+      }
+    }
+  }
+};
+```
+
+Available adapter packages:
+- `@webtypen/webframez-backups-googledrive`
+- `@webtypen/webframez-backups-onedrive`
+- `@webtypen/webframez-backups-sftp`
+- `@webtypen/webframez-backups-ftp`
+
+Database backups are delegated to the configured database driver via `backup(client, options)`. Implement that hook in your driver to write dump files into `options.targetDir`.
+
 ## Modules
 
 You can load module providers via `modules` in `WebApplication.boot(...)`.

package/dist/Ai/AiTypes.d.ts

@@ -0,0 +1,10 @@
+export type KernelAiAgentRegistration = any;
+export type KernelAiApiRegistrations = {
+    prefix?: string;
+    middleware?: string[];
+    [key: string]: any;
+};
+export type KernelAiRegistrations = {
+    agents?: KernelAiAgentRegistration[];
+    api?: KernelAiApiRegistrations;
+};

package/dist/Ai/AiTypes.js

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

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,61 @@
+/// <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 { ApiFunctionClass, ApiFunctionParamDefinition, ApiFunctionParamsDefinition, ApiScopeClass } from "./ApiTypes";
+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 runApiScopeMiddleware(scope: ApiScope, req: Request, res: Response): Promise<{
+    [key: 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,274 @@
+"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.runApiScopeMiddleware = 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");
+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 runApiScopeMiddleware(scope, req, res) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const abort = (message, status = 403) => {
+            throw new ApiFunctionRuntimeError(getApiErrorMessage(message || "Request aborted"), status);
+        };
+        const result = yield scope.middleware(req, res, abort);
+        return isPlainApiObject(result) ? result : {};
+    });
+}
+exports.runApiScopeMiddleware = runApiScopeMiddleware;
+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,12 @@
+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;
+    }>;
+}