@modular-rest/server 1.11.14 → 1.11.15

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/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>;

package/dist/middlewares.js

@@ -0,0 +1,106 @@
+"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.auth = auth;
+const validator_1 = require("./class/validator");
+const userManager = __importStar(require("./services/user_manager/service"));
+/**
+ * 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;
+ * ```
+ */
+async function auth(ctx, next) {
+    const headers = ctx.header;
+    const headersValidated = (0, validator_1.validator)(headers, 'authorization');
+    if (!headersValidated.isValid)
+        ctx.throw(401, 'authentication is required');
+    const token = headers.authorization;
+    await userManager.main
+        .getUserByToken(token)
+        .then(async (user) => {
+        ctx.state.user = user;
+        await next();
+    })
+        .catch(err => {
+        console.log(err);
+        ctx.throw(err.status || 412, err.message);
+    });
+}

package/dist/play-test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/play-test.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const application_1 = require("./application");
+const app = (0, application_1.createRest)({
+    adminUser: {
+        email: 'admin@example.com',
+        password: 'password',
+    },
+});

package/dist/services/data_provider/router.d.ts

@@ -0,0 +1,4 @@
+import Router from 'koa-router';
+declare const name = "data-provider";
+declare const dataProvider: Router<any, {}>;
+export { name, dataProvider as main };