underpost 3.2.8 → 3.2.10

package/src/api/document/document.service.js

@@ -1,5 +1,14 @@
+/**
+ * Document service module for handling document CRUD operations.
+ * Provides REST API handlers for document management with security-aware
+ * public/private document access control, search, and file cleanup integration.
+ *
+ * @module src/api/document/document.service.js
+ * @namespace DocumentService
+ */
+
 import { loggerFactory } from '../../server/logger.js';
-import { DataBaseProvider } from '../../db/DataBaseProvider.js';
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
 import { DocumentDto } from './document.model.js';
 import { uniqueArray } from '../../client/components/core/CommonJs.js';
 import { getBearerToken, verifyJWT } from '../../server/auth.js';
@@ -8,10 +17,26 @@ import { FileCleanup } from '../file/file.service.js';
 
 const logger = loggerFactory(import.meta);
 
-const DocumentService = {
-  post: async (req, res, options) => {
+/**
+ * Document Service for handling REST API document operations.
+ * Implements a security model for public/private document access control
+ * with support for high-query typeahead search, tag filtering, and pagination.
+ * @namespace DocumentService
+ */
+class DocumentService {
+  /**
+   * POST - Create a new document.
+   * @async
+   * @function post
+   * @memberof DocumentService
+   * @param {Object} req - Express request object.
+   * @param {Object} res - Express response object.
+   * @param {Object} options - Request options containing host and path.
+   * @returns {Promise<Object>} Created document object.
+   */
+  static post = async (req, res, options) => {
     /** @type {import('./document.model.js').DocumentModel} */
-    const Document = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Document;
+    const Document = DataBaseProviderService.getModel("Document", options);
 
     switch (req.params.id) {
       default:
@@ -25,14 +50,28 @@ const DocumentService = {
 
         return await new Document(req.body).save();
     }
-  },
-  get: async (req, res, options) => {
+  };
+
+  /**
+   * GET - Retrieve documents.
+   * Supports public high-query search, public tag-filtered listing,
+   * and authenticated user document retrieval with pagination.
+   * @async
+   * @function get
+   * @memberof DocumentService
+   * @param {Object} req - Express request object.
+   * @param {Object} res - Express response object.
+   * @param {Object} options - Request options containing host and path.
+   * @returns {Promise<Object>} Document data with optional pagination metadata.
+   * @throws {Error} If search query is invalid or document not found.
+   */
+  static get = async (req, res, options) => {
     /** @type {import('./document.model.js').DocumentModel} */
-    const Document = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Document;
+    const Document = DataBaseProviderService.getModel("Document", options);
     /** @type {import('../user/user.model.js').UserModel} */
-    const User = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.User;
+    const User = DataBaseProviderService.getModel("User", options);
     /** @type {import('../file/file.model.js').FileModel} */
-    const File = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.File;
+    const File = DataBaseProviderService.getModel("File", options);
 
     // High-query endpoint for typeahead search
     //
@@ -436,12 +475,24 @@ const DocumentService = {
         };
       }
     }
-  },
-  delete: async (req, res, options) => {
+  };
+
+  /**
+   * DELETE - Remove a document and its associated files.
+   * @async
+   * @function delete
+   * @memberof DocumentService
+   * @param {Object} req - Express request object.
+   * @param {Object} res - Express response object.
+   * @param {Object} options - Request options containing host and path.
+   * @returns {Promise<Object>} Deleted document object.
+   * @throws {Error} If document not found or user not authorized.
+   */
+  static delete = async (req, res, options) => {
     /** @type {import('./document.model.js').DocumentModel} */
-    const Document = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Document;
+    const Document = DataBaseProviderService.getModel("Document", options);
     /** @type {import('../file/file.model.js').FileModel} */
-    const File = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.File;
+    const File = DataBaseProviderService.getModel("File", options);
 
     switch (req.params.id) {
       default: {
@@ -460,12 +511,25 @@ const DocumentService = {
         return await Document.findByIdAndDelete(req.params.id);
       }
     }
-  },
-  put: async (req, res, options) => {
+  };
+
+  /**
+   * PUT - Update a document.
+   * Cleans up replaced files and handles tag-based isPublic extraction.
+   * @async
+   * @function put
+   * @memberof DocumentService
+   * @param {Object} req - Express request object.
+   * @param {Object} res - Express response object.
+   * @param {Object} options - Request options containing host and path.
+   * @returns {Promise<Object>} Updated document object.
+   * @throws {Error} If document not found.
+   */
+  static put = async (req, res, options) => {
     /** @type {import('./document.model.js').DocumentModel} */
-    const Document = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Document;
+    const Document = DataBaseProviderService.getModel("Document", options);
     /** @type {import('../file/file.model.js').FileModel} */
-    const File = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.File;
+    const File = DataBaseProviderService.getModel("File", options);
 
     switch (req.params.id) {
       default: {
@@ -500,10 +564,23 @@ const DocumentService = {
         return await Document.findByIdAndUpdate(req.params.id, req.body, { returnDocument: 'after' });
       }
     }
-  },
-  patch: async (req, res, options) => {
+  };
+
+  /**
+   * PATCH - Partially update a document.
+   * Supports toggle-public and copy-share-link operations.
+   * @async
+   * @function patch
+   * @memberof DocumentService
+   * @param {Object} req - Express request object.
+   * @param {Object} res - Express response object.
+   * @param {Object} options - Request options containing host and path.
+   * @returns {Promise<Object>} Updated document or result object.
+   * @throws {Error} If document not found or invalid patch endpoint.
+   */
+  static patch = async (req, res, options) => {
     /** @type {import('./document.model.js').DocumentModel} */
-    const Document = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Document;
+    const Document = DataBaseProviderService.getModel("Document", options);
 
     if (req.path.includes('/toggle-public')) {
       const document = await Document.findById(req.params.id);
@@ -550,7 +627,7 @@ const DocumentService = {
     }
 
     throw new Error('Invalid patch endpoint');
-  },
-};
+  };
+}
 
-export { DocumentService };
+export { DocumentService };

package/src/api/file/file.router.js

@@ -2,21 +2,27 @@ import { adminGuard } from '../../server/auth.js';
 import { loggerFactory } from '../../server/logger.js';
 import { FileController } from './file.controller.js';
 import express from 'express';
+
 const logger = loggerFactory(import.meta);
 
-const FileRouter = (options) => {
-  const router = express.Router();
-  const authMiddleware = options.authMiddleware;
-  router.post(`/:id`, authMiddleware, async (req, res) => await FileController.post(req, res, options));
-  router.post(`/`, authMiddleware, async (req, res) => await FileController.post(req, res, options));
-  router.get(`/blob/:id`, async (req, res) => await FileController.get(req, res, options));
-  router.get(`/:id`, async (req, res) => await FileController.get(req, res, options));
-  router.get(`/`, async (req, res) => await FileController.get(req, res, options));
-  router.delete(`/:id`, authMiddleware, adminGuard, async (req, res) => await FileController.delete(req, res, options));
-  router.delete(`/`, authMiddleware, adminGuard, async (req, res) => await FileController.delete(req, res, options));
-  return router;
-};
+class FileRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const router = express.Router();
+    router.post(`/:id`, options.authMiddleware, async (req, res) => await FileController.post(req, res, options));
+    router.post(`/`, options.authMiddleware, async (req, res) => await FileController.post(req, res, options));
+    router.get(`/blob/:id`, async (req, res) => await FileController.get(req, res, options));
+    router.get(`/:id`, async (req, res) => await FileController.get(req, res, options));
+    router.get(`/`, async (req, res) => await FileController.get(req, res, options));
+    router.delete(`/:id`, options.authMiddleware, adminGuard, async (req, res) => await FileController.delete(req, res, options));
+    router.delete(`/`, options.authMiddleware, adminGuard, async (req, res) => await FileController.delete(req, res, options));
+    return router;
+  }
+}
 
-const ApiRouter = FileRouter;
+const ApiRouter = (options) => FileRouter.router(options);
 
 export { ApiRouter, FileRouter };

package/src/api/file/file.service.js

@@ -6,7 +6,7 @@
  * @namespace FileServiceServer
  */
 
-import { DataBaseProvider } from '../../db/DataBaseProvider.js';
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
 import { getBearerToken, jwtVerify } from '../../server/auth.js';
 import { loggerFactory } from '../../server/logger.js';
 import crypto from 'crypto';
@@ -266,7 +266,9 @@ class FileCleanup {
       const newFileId = newData[field];
 
       // If field has old file and new data changes or removes it
-      if (oldFileId && newFileId !== undefined && String(oldFileId) !== String(newFileId)) {
+      // newFileId === null means client explicitly wants to remove the file
+      // newFileId === undefined means field was not included in request (no change)
+      if (oldFileId && newFileId !== undefined && (newFileId === null || String(oldFileId) !== String(newFileId))) {
         try {
           const file = await File.findOne({ _id: oldFileId });
           if (file) {
@@ -345,7 +347,7 @@ class FileService {
     }
 
     /** @type {import('./file.model.js').FileModel} */
-    const File = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.File;
+    const File = DataBaseProviderService.getModel("File", options);
 
     const uploadedFiles = await FileFactory.upload(req, File);
     return FileServiceDto.toMetadataArray(uploadedFiles);
@@ -367,11 +369,11 @@ class FileService {
    */
   static get = async (req, res, options) => {
     /** @type {import('./file.model.js').FileModel} */
-    const File = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.File;
+    const File = DataBaseProviderService.getModel("File", options);
     /** @type {import('../document/document.model.js').DocumentModel} */
-    const Document = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Document;
+    const Document = DataBaseProviderService.getModel("Document", options);
     /** @type {import('../user/user.model.js').User} */
-    const User = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.User;
+    const User = DataBaseProviderService.getModel("User", options);
 
     const isFileAuthorized = async (fileId) => {
       try {
@@ -482,7 +484,7 @@ class FileService {
    */
   static delete = async (req, res, options) => {
     /** @type {import('./file.model.js').FileModel} */
-    const File = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.File;
+    const File = DataBaseProviderService.getModel("File", options);
 
     const result = await File.findByIdAndDelete(req.params.id);
 

package/src/api/test/test.router.js

@@ -4,18 +4,23 @@ import express from 'express';
 
 const logger = loggerFactory(import.meta);
 
-const TestRouter = (options) => {
-  const router = express.Router();
-  const authMiddleware = options.authMiddleware;
-  router.post(`/:id`, async (req, res) => await TestController.post(req, res, options));
-  router.post(`/`, authMiddleware, async (req, res) => await TestController.post(req, res, options));
-  router.get(`/:id`, async (req, res) => await TestController.get(req, res, options));
-  router.get(`/`, async (req, res) => await TestController.get(req, res, options));
-  router.delete(`/:id`, async (req, res) => await TestController.delete(req, res, options));
-  router.delete(`/`, async (req, res) => await TestController.delete(req, res, options));
-  return router;
-};
+class TestRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const router = express.Router();
+    router.post(`/:id`, async (req, res) => await TestController.post(req, res, options));
+    router.post(`/`, options.authMiddleware, async (req, res) => await TestController.post(req, res, options));
+    router.get(`/:id`, async (req, res) => await TestController.get(req, res, options));
+    router.get(`/`, async (req, res) => await TestController.get(req, res, options));
+    router.delete(`/:id`, async (req, res) => await TestController.delete(req, res, options));
+    router.delete(`/`, async (req, res) => await TestController.delete(req, res, options));
+    return router;
+  }
+}
 
-const ApiRouter = TestRouter;
+const ApiRouter = (options) => TestRouter.router(options);
 
 export { ApiRouter, TestRouter };

package/src/api/types.js

@@ -0,0 +1,24 @@
+/**
+ * @module src/api/types
+ * @description Shared type definitions for the Express router layer.
+ */
+
+/**
+ * Injected dependencies and runtime configuration for every API router instance.
+ * Keyed per-host/path by the multi-tenant engine (see src/runtime/express/Express.js).
+ *
+ * @typedef {Object} RouterOptions
+ * @property {import('express').Application} app - Express application instance.
+ * @property {string} host - Per-runtime host identifier (e.g. "nexodev.org").
+ * @property {string} path - Per-runtime path prefix (e.g. "/" or "/cyberia").
+ * @property {string} apiPath - Computed base URL for the API layer.
+ * @property {string[]} origins - Allowed origins for CORS validation.
+ * @property {import('express').RequestHandler} authMiddleware - Dynamically generated JWT auth middleware (keyed by host+path).
+ * @property {Object} [db] - DataBaseProviderService configuration or instance reference.
+ * @property {Object} [mailer] - MailerProvider configuration or instance reference.
+ * @property {Object} [png] - Cached mailer image buffers (populated by UserRouter on first load).
+ * @property {Record<string, Buffer>} [png.buffer] - Map of image key to raw PNG buffer.
+ * @property {Function} [png.header] - Sets CORS/Content-Type response headers for PNG responses.
+ */
+
+export { };

package/src/api/user/guest.service.js

@@ -22,12 +22,13 @@ const _guestTtlMs = () => {
  */
 const buildGuestUser = (options) => {
   const now = new Date().toISOString();
-  const _id = new mongoose.Types.ObjectId().toString();
+  const objectId = new mongoose.Types.ObjectId().toString();
   const role = 'guest';
+  const username = `${role}${objectId.slice(-5)}`;
   return {
-    _id: `${role}${_id}`,
-    username: `${role}${_id.slice(-5)}`,
-    email: `${_id}@${options.host || 'localhost'}`,
+    _id: `${role}${objectId}`,
+    username,
+    email: `${username}@${options.host || 'localhost'}`,
     password: hashPassword(process.env.JWT_SECRET),
     role,
     emailConfirmed: false,