@modular-rest/server 1.11.13 → 1.12.0

package/dist/events.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerEventCallback = registerEventCallback;
+exports.getEventCallbacks = getEventCallbacks;
+exports.triggerEvent = triggerEvent;
+/**
+ * Array to store all registered event callbacks
+ */
+const eventCallbacks = [];
+/**
+ * Supported event types:
+ * - onBeforeInit: (koaApp: Koa) => void; // A callback called before initializing the Koa server.
+ * - onAfterInit: (koaApp: Koa) => void; // A callback called after server initialization.
+ * - onNewUser: (user: any) => void; // A callback called when a new user is created.
+ *
+ * @param event - The event name to register
+ * @param callback - The callback function to be called when the event is triggered
+ * @throws Error if event is not a string or callback is not a function
+ */
+function registerEventCallback(event, callback) {
+    if (typeof event !== "string")
+        throw new Error("Event must be a string");
+    if (typeof callback !== "function")
+        throw new Error("Callback must be a function");
+    eventCallbacks.push({ event, callback });
+}
+/**
+ * Get all registered callbacks for a specific event
+ * @param event - The event name to get callbacks for
+ * @returns Array of callbacks registered for the event
+ */
+function getEventCallbacks(event) {
+    return eventCallbacks
+        .filter((cb) => cb.event === event)
+        .map((cb) => cb.callback);
+}
+/**
+ * Trigger an event with arguments
+ * @param event - The event name to trigger
+ * @param args - Arguments to pass to the callback functions
+ */
+function triggerEvent(event, ...args) {
+    const callbacks = getEventCallbacks(event);
+    for (const callback of callbacks) {
+        callback(...args);
+    }
+}

package/dist/helper/data_insertion.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Admin user credentials interface
+ * @interface AdminCredentials
+ * @property {string} email - Admin user email address
+ * @property {string} password - Admin user password
+ */
+interface AdminCredentials {
+    email: string;
+    password: string;
+}
+/**
+ * Creates default system users if they don't exist
+ * @function createAdminUser
+ * @param {AdminCredentials} credentials - Admin user credentials
+ * @returns {Promise<void>} A promise that resolves when the operation is complete
+ * @throws {Error} If admin credentials are invalid or if the operation fails
+ * @description
+ * This function performs the following operations:
+ * 1. Checks if an anonymous user exists, creates one if it doesn't
+ * 2. Checks if an administrator user exists, creates one if it doesn't
+ * 3. Uses the provided credentials for the administrator user
+ *
+ * @example
+ * ```typescript
+ * // Create default system users
+ * await createAdminUser({
+ *   email: 'admin@example.com',
+ *   password: 'secure-password'
+ * });
+ *
+ * // The function will:
+ * // 1. Create an anonymous user if it doesn't exist
+ * // 2. Create an admin user with the provided credentials if it doesn't exist
+ * // 3. Do nothing if both users already exist
+ * ```
+ */
+export declare function createAdminUser({ email, password }: AdminCredentials): Promise<void>;
+export {};

package/dist/helper/data_insertion.js

@@ -0,0 +1,110 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAdminUser = createAdminUser;
+const DataProvider = __importStar(require("../services/data_provider/service"));
+const permissionManager_1 = require("../services/user_manager/permissionManager");
+const userManager = __importStar(require("../services/user_manager/service"));
+/**
+ * Creates default system users if they don't exist
+ * @function createAdminUser
+ * @param {AdminCredentials} credentials - Admin user credentials
+ * @returns {Promise<void>} A promise that resolves when the operation is complete
+ * @throws {Error} If admin credentials are invalid or if the operation fails
+ * @description
+ * This function performs the following operations:
+ * 1. Checks if an anonymous user exists, creates one if it doesn't
+ * 2. Checks if an administrator user exists, creates one if it doesn't
+ * 3. Uses the provided credentials for the administrator user
+ *
+ * @example
+ * ```typescript
+ * // Create default system users
+ * await createAdminUser({
+ *   email: 'admin@example.com',
+ *   password: 'secure-password'
+ * });
+ *
+ * // The function will:
+ * // 1. Create an anonymous user if it doesn't exist
+ * // 2. Create an admin user with the provided credentials if it doesn't exist
+ * // 3. Do nothing if both users already exist
+ * ```
+ */
+async function createAdminUser({ email, password }) {
+    const authModel = DataProvider.getCollection('cms', 'auth');
+    try {
+        const isAnonymousExisted = await authModel.countDocuments({ type: 'anonymous' }).exec();
+        const isAdministratorExisted = await authModel
+            .countDocuments({ type: 'user', email: email })
+            .exec();
+        if (isAnonymousExisted === 0) {
+            await userManager.main.registerUser({
+                permissionGroup: (0, permissionManager_1.getDefaultAnonymousPermissionGroup)().title,
+                email: '',
+                phone: '',
+                password: '',
+                type: 'anonymous',
+            });
+            // await new authModel({
+            //   permission: getDefaultAnonymousPermissionGroup().title,
+            //   email: "",
+            //   phone: "",
+            //   password: "",
+            //   type: "anonymous",
+            // }).save();
+        }
+        if (isAdministratorExisted === 0) {
+            if (!email || !password) {
+                return Promise.reject('Invalid email or password for admin user.');
+            }
+            await userManager.main.registerUser({
+                permissionGroup: (0, permissionManager_1.getDefaultAdministratorPermissionGroup)().title,
+                email: email,
+                password: password,
+                type: 'user',
+            });
+            // await new authModel({
+            //   permission: getDefaultAdministratorPermissionGroup().title,
+            //   email: email,
+            //   password: password,
+            //   type: "user",
+            // }).save();
+        }
+    }
+    catch (e) {
+        return Promise.reject(e);
+    }
+}

package/dist/helper/presetup_services.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Setup options interface for initializing required services
+ * @interface SetupOptions
+ * @property {Object} [keypair] - JWT keypair configuration
+ * @property {string} keypair.private - Private key for JWT signing
+ * @property {string} keypair.public - Public key for JWT verification
+ * @property {Object} adminUser - Admin user configuration
+ * @property {string} adminUser.email - Admin user email address
+ * @property {string} adminUser.password - Admin user password
+ * @property {string} [uploadDirectory] - Directory for file uploads
+ */
+interface SetupOptions {
+    keypair?: {
+        private: string;
+        public: string;
+    };
+    adminUser: {
+        email: string;
+        password: string;
+    };
+    uploadDirectory?: string;
+}
+/**
+ * Sets up required services for the application to run
+ * @function setup
+ * @param {SetupOptions} options - Setup configuration options
+ * @returns {Promise<void>} A promise that resolves when setup is complete
+ * @throws {Error} If admin user configuration is missing or if setup fails
+ * @description
+ * This function performs the following setup operations:
+ * 1. Configures JWT with provided or generated keypair
+ * 2. Creates default system users (admin and anonymous)
+ * 3. Configures file upload directory if specified
+ *
+ * @example
+ * ```typescript
+ * // Setup with custom keypair
+ * await setup({
+ *   keypair: {
+ *     private: 'your-private-key',
+ *     public: 'your-public-key'
+ *   },
+ *   adminUser: {
+ *     email: 'admin@example.com',
+ *     password: 'secure-password'
+ *   },
+ *   uploadDirectory: './uploads'
+ * });
+ *
+ * // Setup with auto-generated keypair
+ * await setup({
+ *   adminUser: {
+ *     email: 'admin@example.com',
+ *     password: 'secure-password'
+ *   }
+ * });
+ * ```
+ */
+export declare function setup({ keypair, adminUser, uploadDirectory }: SetupOptions): Promise<void>;
+export {};

package/dist/helper/presetup_services.js

@@ -0,0 +1,108 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setup = setup;
+const DataInsertion = __importStar(require("./data_insertion"));
+const JWT = __importStar(require("../services/jwt/service"));
+const FileService = __importStar(require("../services/file/service"));
+const keypair_1 = __importDefault(require("keypair"));
+/**
+ * Sets up required services for the application to run
+ * @function setup
+ * @param {SetupOptions} options - Setup configuration options
+ * @returns {Promise<void>} A promise that resolves when setup is complete
+ * @throws {Error} If admin user configuration is missing or if setup fails
+ * @description
+ * This function performs the following setup operations:
+ * 1. Configures JWT with provided or generated keypair
+ * 2. Creates default system users (admin and anonymous)
+ * 3. Configures file upload directory if specified
+ *
+ * @example
+ * ```typescript
+ * // Setup with custom keypair
+ * await setup({
+ *   keypair: {
+ *     private: 'your-private-key',
+ *     public: 'your-public-key'
+ *   },
+ *   adminUser: {
+ *     email: 'admin@example.com',
+ *     password: 'secure-password'
+ *   },
+ *   uploadDirectory: './uploads'
+ * });
+ *
+ * // Setup with auto-generated keypair
+ * await setup({
+ *   adminUser: {
+ *     email: 'admin@example.com',
+ *     password: 'secure-password'
+ *   }
+ * });
+ * ```
+ */
+async function setup({ keypair, adminUser, uploadDirectory }) {
+    /**
+     * Json web Token
+     *
+     * Setup private and public keys for JWT module
+     */
+    let keyPairToUse = keypair;
+    if (!keyPairToUse) {
+        // generate new keypair
+        keyPairToUse = (0, keypair_1.default)();
+    }
+    JWT.main.setKies(keyPairToUse.private, keyPairToUse.public);
+    if (!adminUser) {
+        throw new Error('Admin user is not supported in TypeScript version');
+    }
+    /**
+     * Data Insertion
+     *
+     * Insert admin user
+     * for the first time
+     */
+    await DataInsertion.createAdminUser(adminUser);
+    /**
+     * File Service
+     */
+    if (uploadDirectory) {
+        FileService.main.setUploadDirectory(uploadDirectory);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+import { createRest } from './application';
+import { Schema } from 'mongoose';
+import * as paginator from './class/paginator';
+import * as reply from './class/reply';
+import { validator } from './class/validator';
+import { getCollection } from './services/data_provider/service';
+import { defineFunction } from './services/functions/service';
+import TypeCasters from './services/data_provider/typeCasters';
+import { main as userManager } from './services/user_manager/service';
+import { main as fileService } from './services/file/service';
+import { CollectionDefinition, defineCollection } from './class/collection_definition';
+import { schemas } from './class/db_schemas';
+import DatabaseTrigger from './class/database_trigger';
+import CmsTrigger from './class/cms_trigger';
+import { AccessDefinition, Permission, PermissionTypes, PermissionGroup, AccessTypes } from './class/security';
+import * as middleware from './middlewares';
+/**
+ * @description Creates a new REST API instance
+ * @example
+ * ```typescript
+ * const rest = createRest();
+ * ```
+ * @returns A new REST API instance
+ */
+export { createRest };
+export { CollectionDefinition, defineCollection };
+/**
+ * @description Provides predefined database schemas
+ * @example
+ * ```typescript
+ * const userSchema = new Schema({
+ *   name: String,
+ *   avatar: Schemas.file
+ * });
+ * ```
+ */
+export { schemas };
+/**
+ * @description Mongoose Schema class for defining data models
+ */
+export { Schema };
+/**
+ * @description Handles database triggers and events
+ * @example
+ * ```typescript
+ * const trigger = new DatabaseTrigger('insert-one', (data) => {
+ *   // Handle insert event
+ * });
+ * ```
+ */
+export { DatabaseTrigger };
+/**
+ * @description Handles CMS triggers and events
+ */
+export { CmsTrigger };
+/**
+ * @description Security and access control definitions
+ * @example
+ * ```typescript
+ * const permission = new Permission({
+ *   type: 'user_access',
+ *   read: true,
+ *   write: true
+ * });
+ * ```
+ */
+export { AccessDefinition, Permission, PermissionTypes, PermissionGroup, AccessTypes };
+/**
+ * @description Defines custom functions for the API
+ * @example
+ * ```typescript
+ * defineFunction('sendEmail', async (data) => {
+ *   // Send email logic
+ * });
+ * ```
+ */
+export { defineFunction };
+/**
+ * @description Type casting utilities for data transformation
+ */
+export { TypeCasters };
+/**
+ * @description Input validation utilities
+ */
+export { validator };
+/**
+ * @description Response handling utilities
+ */
+export { reply };
+/**
+ * @description Pagination utilities
+ */
+export { paginator };
+/**
+ * @description Database collection access utilities
+ */
+export { getCollection };
+/**
+ * @description File handling utilities
+ * @example
+ * ```typescript
+ * const file = await fileService.getFile('fileId');
+ * const link = fileService.getFileLink('fileId');
+ * ```
+ */
+export { fileService };
+/**
+ * @description Middleware utilities
+ */
+export { middleware };
+/**
+ * @description User management utilities
+ * @example
+ * ```typescript
+ * const user = await userManager.getUserById('userId');
+ * ```
+ */
+export { userManager };

package/dist/index.js

@@ -0,0 +1,79 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.userManager = exports.middleware = exports.fileService = exports.getCollection = exports.paginator = exports.reply = exports.validator = exports.TypeCasters = exports.defineFunction = exports.AccessTypes = exports.PermissionGroup = exports.PermissionTypes = exports.Permission = exports.AccessDefinition = exports.CmsTrigger = exports.DatabaseTrigger = exports.Schema = exports.schemas = exports.defineCollection = exports.CollectionDefinition = exports.createRest = void 0;
+// Application
+const application_1 = require("./application");
+Object.defineProperty(exports, "createRest", { enumerable: true, get: function () { return application_1.createRest; } });
+const mongoose_1 = require("mongoose");
+Object.defineProperty(exports, "Schema", { enumerable: true, get: function () { return mongoose_1.Schema; } });
+// Utilities
+const paginator = __importStar(require("./class/paginator"));
+exports.paginator = paginator;
+const reply = __importStar(require("./class/reply"));
+exports.reply = reply;
+const validator_1 = require("./class/validator");
+Object.defineProperty(exports, "validator", { enumerable: true, get: function () { return validator_1.validator; } });
+const service_1 = require("./services/data_provider/service");
+Object.defineProperty(exports, "getCollection", { enumerable: true, get: function () { return service_1.getCollection; } });
+const service_2 = require("./services/functions/service");
+Object.defineProperty(exports, "defineFunction", { enumerable: true, get: function () { return service_2.defineFunction; } });
+const typeCasters_1 = __importDefault(require("./services/data_provider/typeCasters"));
+exports.TypeCasters = typeCasters_1.default;
+const service_3 = require("./services/user_manager/service");
+Object.defineProperty(exports, "userManager", { enumerable: true, get: function () { return service_3.main; } });
+const service_4 = require("./services/file/service");
+Object.defineProperty(exports, "fileService", { enumerable: true, get: function () { return service_4.main; } });
+// Base class
+const collection_definition_1 = require("./class/collection_definition");
+Object.defineProperty(exports, "CollectionDefinition", { enumerable: true, get: function () { return collection_definition_1.CollectionDefinition; } });
+Object.defineProperty(exports, "defineCollection", { enumerable: true, get: function () { return collection_definition_1.defineCollection; } });
+const db_schemas_1 = require("./class/db_schemas");
+Object.defineProperty(exports, "schemas", { enumerable: true, get: function () { return db_schemas_1.schemas; } });
+const database_trigger_1 = __importDefault(require("./class/database_trigger"));
+exports.DatabaseTrigger = database_trigger_1.default;
+const cms_trigger_1 = __importDefault(require("./class/cms_trigger"));
+exports.CmsTrigger = cms_trigger_1.default;
+const security_1 = require("./class/security");
+Object.defineProperty(exports, "AccessDefinition", { enumerable: true, get: function () { return security_1.AccessDefinition; } });
+Object.defineProperty(exports, "Permission", { enumerable: true, get: function () { return security_1.Permission; } });
+Object.defineProperty(exports, "PermissionTypes", { enumerable: true, get: function () { return security_1.PermissionTypes; } });
+Object.defineProperty(exports, "PermissionGroup", { enumerable: true, get: function () { return security_1.PermissionGroup; } });
+Object.defineProperty(exports, "AccessTypes", { enumerable: true, get: function () { return security_1.AccessTypes; } });
+const middleware = __importStar(require("./middlewares"));
+exports.middleware = middleware;

package/dist/middlewares.d.ts

@@ -0,0 +1,53 @@
+import { Context, Next } from 'koa';
+/**
+ * Authentication middleware that secures routes by validating user tokens and managing access control.
+ *
+ * This middleware performs several key functions:
+ * 1. Validates that the incoming request contains an authorization token in the header
+ * 2. Verifies the token is valid by checking against the user management service
+ * 3. Retrieves the associated user object if the token is valid
+ * 4. Attaches the authenticated {@link User} object on ctx.state.user for use in subsequent middleware/routes
+ * 5. Throws appropriate HTTP errors (401, 412) if authentication fails
+ *
+ * The middleware integrates with the permission system to enable role-based access control.
+ * The attached user object provides methods like hasPermission() to check specific permissions.
+ *
+ * Common usage patterns:
+ * - Protecting sensitive API endpoints
+ * - Implementing role-based access control
+ * - Getting the current authenticated user
+ * - Validating user permissions before allowing actions
+ *
+ * @throws {Error} 401 - If no authorization header is present
+ * @throws {Error} 412 - If token validation fails
+ * @param ctx - Koa Context object containing request/response data
+ * @param next - Function to invoke next middleware
+ *
+ * @example
+ * ```typescript
+ * // Inside the router.ts file
+ * import { auth } from '@modular-rest/server';
+ * import { Router } from 'koa-router';
+ *
+ * const name = 'flowers';
+ *
+ * const flowerRouter = new Router();
+ *
+ * flowerRouter.get('/list', auth, (ctx) => {
+ *  // Get the authenticated user
+ *  const user = ctx.state.user;
+ *
+ *  // Then you can check the user's role and permission
+ *  if(user.hasPermission('get_flower')) {
+ *    ctx.body = 'This is a list of flowers: Rose, Lily, Tulip';
+ *  } else {
+ *    ctx.status = 403;
+ *    ctx.body = 'You are not authorized to access this resource';
+ *  }
+ * });
+ *
+ * module.exports.name = name;
+ * module.exports.main = flowerRouter;
+ * ```
+ */
+export declare function auth(ctx: Context, next: Next): Promise<void>;