cyberia 3.2.5 → 3.2.12

package/src/api/cyberia-instance-conf/cyberia-instance-conf.router.js

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

package/src/api/cyberia-instance-conf/cyberia-instance-conf.service.js

@@ -1,18 +1,20 @@
-import { DataBaseProvider } from '../../db/DataBaseProvider.js';
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
 import { loggerFactory } from '../../server/logger.js';
 import { DataQuery } from '../../server/data-query.js';
 
 const logger = loggerFactory(import.meta);
 
-const CyberiaInstanceConfService = {
-  post: async (req, res, options) => {
+class CyberiaInstanceConfService {
+  static post = async (req, res, options) => {
     /** @type {import('./cyberia-instance-conf.model.js').CyberiaInstanceConfModel} */
-    const CyberiaInstanceConf = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaInstanceConf;
+    const CyberiaInstanceConf =
+      DataBaseProviderService.getModel("CyberiaInstanceConf", options);
     return await new CyberiaInstanceConf(req.body).save();
-  },
-  get: async (req, res, options) => {
+  };
+  static get = async (req, res, options) => {
     /** @type {import('./cyberia-instance-conf.model.js').CyberiaInstanceConfModel} */
-    const CyberiaInstanceConf = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaInstanceConf;
+    const CyberiaInstanceConf =
+      DataBaseProviderService.getModel("CyberiaInstanceConf", options);
     if (req.params.id) return await CyberiaInstanceConf.findById(req.params.id);
 
     // Parse query parameters using DataQuery helper
@@ -25,18 +27,20 @@ const CyberiaInstanceConfService = {
 
     const totalPages = Math.ceil(total / limit);
     return { data, total, page, totalPages };
-  },
-  put: async (req, res, options) => {
+  };
+  static put = async (req, res, options) => {
     /** @type {import('./cyberia-instance-conf.model.js').CyberiaInstanceConfModel} */
-    const CyberiaInstanceConf = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaInstanceConf;
+    const CyberiaInstanceConf =
+      DataBaseProviderService.getModel("CyberiaInstanceConf", options);
     return await CyberiaInstanceConf.findByIdAndUpdate(req.params.id, req.body);
-  },
-  delete: async (req, res, options) => {
+  };
+  static delete = async (req, res, options) => {
     /** @type {import('./cyberia-instance-conf.model.js').CyberiaInstanceConfModel} */
-    const CyberiaInstanceConf = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaInstanceConf;
+    const CyberiaInstanceConf =
+      DataBaseProviderService.getModel("CyberiaInstanceConf", options);
     if (req.params.id) return await CyberiaInstanceConf.findByIdAndDelete(req.params.id);
     else return await CyberiaInstanceConf.deleteMany();
-  },
-};
+  };
+}
 
 export { CyberiaInstanceConfService };

package/src/api/cyberia-map/cyberia-map.controller.js

@@ -3,8 +3,8 @@ import { CyberiaMapService } from './cyberia-map.service.js';
 
 const logger = loggerFactory(import.meta);
 
-const CyberiaMapController = {
-  post: async (req, res, options) => {
+class CyberiaMapController {
+  static post = async (req, res, options) => {
     try {
       const result = await CyberiaMapService.post(req, res, options);
       return res.status(200).json({
@@ -18,8 +18,8 @@ const CyberiaMapController = {
         message: error.message,
       });
     }
-  },
-  get: async (req, res, options) => {
+  };
+  static get = async (req, res, options) => {
     try {
       const { page, limit } = req.query;
       const result = await CyberiaMapService.get(
@@ -43,8 +43,8 @@ const CyberiaMapController = {
         message: error.message,
       });
     }
-  },
-  put: async (req, res, options) => {
+  };
+  static put = async (req, res, options) => {
     try {
       const result = await CyberiaMapService.put(req, res, options);
       return res.status(200).json({
@@ -58,8 +58,8 @@ const CyberiaMapController = {
         message: error.message,
       });
     }
-  },
-  delete: async (req, res, options) => {
+  };
+  static delete = async (req, res, options) => {
     try {
       const result = await CyberiaMapService.delete(req, res, options);
       return res.status(200).json({
@@ -73,7 +73,7 @@ const CyberiaMapController = {
         message: error.message,
       });
     }
-  },
-};
+  };
+}
 
 export { CyberiaMapController };

package/src/api/cyberia-map/cyberia-map.router.js

@@ -5,36 +5,41 @@ import express from 'express';
 
 const logger = loggerFactory(import.meta);
 
-const CyberiaMapRouter = (options) => {
-  const router = express.Router();
-  const authMiddleware = options.authMiddleware;
-  router.post(
-    `/:id`,
-    authMiddleware,
-    userGuard,
-    async (req, res) => await CyberiaMapController.post(req, res, options),
-  );
-  router.post(`/`, authMiddleware, userGuard, async (req, res) => await CyberiaMapController.post(req, res, options));
-  router.get(`/search-codes`, async (req, res) => await CyberiaMapController.get(req, res, options));
-  router.get(`/:id`, async (req, res) => await CyberiaMapController.get(req, res, options));
-  router.get(`/`, async (req, res) => await CyberiaMapController.get(req, res, options));
-  router.put(`/:id`, authMiddleware, userGuard, async (req, res) => await CyberiaMapController.put(req, res, options));
-  router.put(`/`, authMiddleware, userGuard, async (req, res) => await CyberiaMapController.put(req, res, options));
-  router.delete(
-    `/:id`,
-    authMiddleware,
-    userGuard,
-    async (req, res) => await CyberiaMapController.delete(req, res, options),
-  );
-  router.delete(
-    `/`,
-    authMiddleware,
-    adminGuard,
-    async (req, res) => await CyberiaMapController.delete(req, res, options),
-  );
-  return router;
-};
+class CyberiaMapRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const router = express.Router();
+    router.post(
+      `/:id`,
+      options.authMiddleware,
+      userGuard,
+      async (req, res) => await CyberiaMapController.post(req, res, options),
+    );
+    router.post(`/`, options.authMiddleware, userGuard, async (req, res) => await CyberiaMapController.post(req, res, options));
+    router.get(`/search-codes`, async (req, res) => await CyberiaMapController.get(req, res, options));
+    router.get(`/:id`, async (req, res) => await CyberiaMapController.get(req, res, options));
+    router.get(`/`, async (req, res) => await CyberiaMapController.get(req, res, options));
+    router.put(`/:id`, options.authMiddleware, userGuard, async (req, res) => await CyberiaMapController.put(req, res, options));
+    router.put(`/`, options.authMiddleware, userGuard, async (req, res) => await CyberiaMapController.put(req, res, options));
+    router.delete(
+      `/:id`,
+      options.authMiddleware,
+      userGuard,
+      async (req, res) => await CyberiaMapController.delete(req, res, options),
+    );
+    router.delete(
+      `/`,
+      options.authMiddleware,
+      adminGuard,
+      async (req, res) => await CyberiaMapController.delete(req, res, options),
+    );
+    return router;
+  }
+}
 
-const ApiRouter = CyberiaMapRouter;
+const ApiRouter = (options) => CyberiaMapRouter.router(options);
 
 export { ApiRouter, CyberiaMapRouter };

package/src/api/cyberia-map/cyberia-map.service.js

@@ -1,19 +1,19 @@
-import { DataBaseProvider } from '../../db/DataBaseProvider.js';
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
 import { loggerFactory } from '../../server/logger.js';
 import { DataQuery } from '../../server/data-query.js';
 
 const logger = loggerFactory(import.meta);
 
-const CyberiaMapService = {
-  post: async (req, res, options) => {
+class CyberiaMapService {
+  static post = async (req, res, options) => {
     /** @type {import('./cyberia-map.model.js').CyberiaMapModel} */
-    const CyberiaMap = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaMap;
+    const CyberiaMap = DataBaseProviderService.getModel("CyberiaMap", options);
     if (req.auth && req.auth.user) req.body.creator = req.auth.user._id;
     return await new CyberiaMap(req.body).save();
-  },
-  get: async (req, res, options) => {
+  };
+  static get = async (req, res, options) => {
     /** @type {import('./cyberia-map.model.js').CyberiaMapModel} */
-    const CyberiaMap = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaMap;
+    const CyberiaMap = DataBaseProviderService.getModel("CyberiaMap", options);
     const populateCreator = { path: 'creator', model: 'User', select: '_id username' };
 
     // GET /search-codes?q=<partial> - Fast partial match search on code
@@ -40,35 +40,35 @@ const CyberiaMapService = {
 
     const totalPages = Math.ceil(total / limit);
     return { data, total, page, totalPages };
-  },
-  put: async (req, res, options) => {
+  };
+  static put = async (req, res, options) => {
     /** @type {import('./cyberia-map.model.js').CyberiaMapModel} */
-    const CyberiaMap = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaMap;
+    const CyberiaMap = DataBaseProviderService.getModel("CyberiaMap", options);
     const map = await CyberiaMap.findById(req.params.id);
     if (!map) throw new Error('map not found');
     if (req.auth.user.role !== 'admin' && String(map.creator) !== String(req.auth.user._id))
       throw new Error('insufficient permission');
     if (req.body.thumbnail && map.thumbnail && String(req.body.thumbnail) !== String(map.thumbnail)) {
-      const File = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.File;
+      const File = DataBaseProviderService.getModel("File", options);
       await File.findByIdAndDelete(map.thumbnail);
     }
     return await CyberiaMap.findByIdAndUpdate(req.params.id, req.body, { returnDocument: 'after' });
-  },
-  delete: async (req, res, options) => {
+  };
+  static delete = async (req, res, options) => {
     /** @type {import('./cyberia-map.model.js').CyberiaMapModel} */
-    const CyberiaMap = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaMap;
+    const CyberiaMap = DataBaseProviderService.getModel("CyberiaMap", options);
     if (req.params.id) {
       const map = await CyberiaMap.findById(req.params.id);
       if (!map) throw new Error('map not found');
       if (req.auth.user.role !== 'admin' && String(map.creator) !== String(req.auth.user._id))
         throw new Error('insufficient permission');
       if (map.thumbnail) {
-        const File = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.File;
+        const File = DataBaseProviderService.getModel("File", options);
         await File.findByIdAndDelete(map.thumbnail);
       }
       return await CyberiaMap.findByIdAndDelete(req.params.id);
     } else return await CyberiaMap.deleteMany();
-  },
-};
+  };
+}
 
 export { CyberiaMapService };

package/src/api/cyberia-quest/cyberia-quest.controller.js

@@ -0,0 +1,74 @@
+import { loggerFactory } from '../../server/logger.js';
+import { CyberiaQuestService } from './cyberia-quest.service.js';
+
+const logger = loggerFactory(import.meta);
+
+class CyberiaQuestController {
+  static post = async (req, res, options) => {
+    try {
+      const result = await CyberiaQuestService.post(req, res, options);
+      return res.status(200).json({
+        status: 'success',
+        data: result,
+      });
+    } catch (error) {
+      logger.error(error, error.stack);
+      return res.status(400).json({
+        status: 'error',
+        message: error.message,
+      });
+    }
+  };
+  static get = async (req, res, options) => {
+    try {
+      const { page, limit } = req.query;
+      const result = await CyberiaQuestService.get(
+        { ...req, query: { ...req.query, page: parseInt(page), limit: parseInt(limit) } },
+        res,
+        options,
+      );
+      return res.status(200).json({
+        status: 'success',
+        data: result,
+      });
+    } catch (error) {
+      logger.error(error, error.stack);
+      return res.status(400).json({
+        status: 'error',
+        message: error.message,
+      });
+    }
+  };
+  static put = async (req, res, options) => {
+    try {
+      const result = await CyberiaQuestService.put(req, res, options);
+      return res.status(200).json({
+        status: 'success',
+        data: result,
+      });
+    } catch (error) {
+      logger.error(error, error.stack);
+      return res.status(400).json({
+        status: 'error',
+        message: error.message,
+      });
+    }
+  };
+  static delete = async (req, res, options) => {
+    try {
+      const result = await CyberiaQuestService.delete(req, res, options);
+      return res.status(200).json({
+        status: 'success',
+        data: result,
+      });
+    } catch (error) {
+      logger.error(error, error.stack);
+      return res.status(400).json({
+        status: 'error',
+        message: error.message,
+      });
+    }
+  };
+}
+
+export { CyberiaQuestController };

package/src/api/cyberia-quest/cyberia-quest.model.js

@@ -0,0 +1,67 @@
+import { Schema, model } from 'mongoose';
+import { QUEST_STEPS_TYPES } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
+
+// https://mongoosejs.com/docs/2.7.x/docs/schematypes.html
+
+const CyberiaQuestSchema = new Schema(
+  {
+    // Spatial origin: the NPC/entity cell that grants this quest.
+    // Matched against map entity initCellX/initCellY during instance init
+    // and assignable from ObjectLayerEngineModal.
+    sourceMapCode: { type: String, trim: true },
+    sourceCellX: { type: Number },
+    sourceCellY: { type: Number },
+
+    // Stable slug, e.g. "fallback-intro-quest"
+    code: { type: String, required: true, trim: true },
+    title: { type: String, required: true, trim: true },
+    description: { type: String, default: '' },
+
+    // ── Chain / tree unlock structure ─────────────────────────────────────
+    // All listed quest codes must be completed before this quest becomes
+    // available (AND logic). Empty array = no prerequisites.
+    prerequisiteCodes: { type: [String], default: [] },
+
+    // Quest codes unlocked when this quest is completed.
+    // Supports both chain (one successor) and tree (multiple successors).
+    // The server re-checks prerequisiteCodes on each target before activating it.
+    unlocksQuestCodes: { type: [String], default: [] },
+
+    // ── Steps ─────────────────────────────────────────────────────────────
+    // Ordered linear sequence. The active step is always the first incomplete one.
+    steps: [
+      {
+        id: { type: String, required: true },
+        description: { type: String, default: '' },
+        objectives: [
+          {
+            // collect — itemId = item that must appear in the player's inventory
+            // talk    — itemId = provideItemId of the CyberiaAction to interact with
+            // kill    — itemId = skin item ID of the target entity
+            type: { type: String, required: true, enum: QUEST_STEPS_TYPES },
+            itemId: { type: String, required: true, trim: true },
+            quantity: { type: Number, default: 1, min: 1 },
+          },
+        ],
+      },
+    ],
+
+    // ── Rewards ───────────────────────────────────────────────────────────
+    rewards: [
+      {
+        itemId: { type: String, required: true, trim: true },
+        quantity: { type: Number, default: 1, min: 1 },
+      },
+    ],
+  },
+  { timestamps: true },
+);
+
+CyberiaQuestSchema.index({ code: 1 }, { unique: true });
+CyberiaQuestSchema.index({ sourceMapCode: 1, sourceCellX: 1, sourceCellY: 1 });
+
+const CyberiaQuestModel = model('CyberiaQuest', CyberiaQuestSchema);
+
+const ProviderSchema = CyberiaQuestSchema;
+
+export { CyberiaQuestSchema, CyberiaQuestModel, ProviderSchema };

package/src/api/cyberia-quest/cyberia-quest.router.js

@@ -0,0 +1,31 @@
+import { loggerFactory } from '../../server/logger.js';
+import { CyberiaQuestController } from './cyberia-quest.controller.js';
+import express from 'express';
+
+const logger = loggerFactory(import.meta);
+
+class CyberiaQuestRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const router = express.Router();
+    router.post(`/:id`, async (req, res) => await CyberiaQuestController.post(req, res, options));
+    router.post(`/`, async (req, res) => await CyberiaQuestController.post(req, res, options));
+    router.get(`/:id`,
+      // options.authMiddleware,
+      async (req, res) => await CyberiaQuestController.get(req, res, options),
+    );
+    router.get(`/`, async (req, res) => await CyberiaQuestController.get(req, res, options));
+    router.put(`/:id`, async (req, res) => await CyberiaQuestController.put(req, res, options));
+    router.put(`/`, async (req, res) => await CyberiaQuestController.put(req, res, options));
+    router.delete(`/:id`, async (req, res) => await CyberiaQuestController.delete(req, res, options));
+    router.delete(`/`, async (req, res) => await CyberiaQuestController.delete(req, res, options));
+    return router;
+  }
+}
+
+const ApiRouter = (options) => CyberiaQuestRouter.router(options);
+
+export { ApiRouter, CyberiaQuestRouter };

package/src/api/cyberia-quest/cyberia-quest.service.js

@@ -0,0 +1,42 @@
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
+import { loggerFactory } from '../../server/logger.js';
+import { DataQuery } from '../../server/data-query.js';
+
+const logger = loggerFactory(import.meta);
+
+class CyberiaQuestService {
+  static post = async (req, res, options) => {
+    /** @type {import('./cyberia-quest.model.js').CyberiaQuestModel} */
+    const CyberiaQuest = DataBaseProviderService.getModel("CyberiaQuest", options);
+    return await new CyberiaQuest(req.body).save();
+  };
+  static get = async (req, res, options) => {
+    /** @type {import('./cyberia-quest.model.js').CyberiaQuestModel} */
+    const CyberiaQuest = DataBaseProviderService.getModel("CyberiaQuest", options);
+    if (req.params.id) return await CyberiaQuest.findById(req.params.id);
+
+    // Parse query parameters using DataQuery helper
+    const { query, sort, skip, limit, page } = DataQuery.parse(req.query);
+
+    const [data, total] = await Promise.all([
+      CyberiaQuest.find(query).sort(sort).limit(limit).skip(skip),
+      CyberiaQuest.countDocuments(query),
+    ]);
+
+    const totalPages = Math.ceil(total / limit);
+    return { data, total, page, totalPages };
+  };
+  static put = async (req, res, options) => {
+    /** @type {import('./cyberia-quest.model.js').CyberiaQuestModel} */
+    const CyberiaQuest = DataBaseProviderService.getModel("CyberiaQuest", options);
+    return await CyberiaQuest.findByIdAndUpdate(req.params.id, req.body);
+  };
+  static delete = async (req, res, options) => {
+    /** @type {import('./cyberia-quest.model.js').CyberiaQuestModel} */
+    const CyberiaQuest = DataBaseProviderService.getModel("CyberiaQuest", options);
+    if (req.params.id) return await CyberiaQuest.findByIdAndDelete(req.params.id);
+    else return await CyberiaQuest.deleteMany();
+  };
+}
+
+export { CyberiaQuestService };

package/src/api/cyberia-quest-progress/cyberia-quest-progress.controller.js

@@ -0,0 +1,74 @@
+import { loggerFactory } from '../../server/logger.js';
+import { CyberiaQuestProgressService } from './cyberia-quest-progress.service.js';
+
+const logger = loggerFactory(import.meta);
+
+class CyberiaQuestProgressController {
+  static post = async (req, res, options) => {
+    try {
+      const result = await CyberiaQuestProgressService.post(req, res, options);
+      return res.status(200).json({
+        status: 'success',
+        data: result,
+      });
+    } catch (error) {
+      logger.error(error, error.stack);
+      return res.status(400).json({
+        status: 'error',
+        message: error.message,
+      });
+    }
+  };
+  static get = async (req, res, options) => {
+    try {
+      const { page, limit } = req.query;
+      const result = await CyberiaQuestProgressService.get(
+        { ...req, query: { ...req.query, page: parseInt(page), limit: parseInt(limit) } },
+        res,
+        options,
+      );
+      return res.status(200).json({
+        status: 'success',
+        data: result,
+      });
+    } catch (error) {
+      logger.error(error, error.stack);
+      return res.status(400).json({
+        status: 'error',
+        message: error.message,
+      });
+    }
+  };
+  static put = async (req, res, options) => {
+    try {
+      const result = await CyberiaQuestProgressService.put(req, res, options);
+      return res.status(200).json({
+        status: 'success',
+        data: result,
+      });
+    } catch (error) {
+      logger.error(error, error.stack);
+      return res.status(400).json({
+        status: 'error',
+        message: error.message,
+      });
+    }
+  };
+  static delete = async (req, res, options) => {
+    try {
+      const result = await CyberiaQuestProgressService.delete(req, res, options);
+      return res.status(200).json({
+        status: 'success',
+        data: result,
+      });
+    } catch (error) {
+      logger.error(error, error.stack);
+      return res.status(400).json({
+        status: 'error',
+        message: error.message,
+      });
+    }
+  };
+}
+
+export { CyberiaQuestProgressController };

package/src/api/cyberia-quest-progress/cyberia-quest-progress.model.js

@@ -0,0 +1,49 @@
+import { Schema, model } from 'mongoose';
+
+// https://mongoosejs.com/docs/2.7.x/docs/schematypes.html
+
+const CyberiaQuestProgressSchema = new Schema(
+  {
+    // Matches the Go relay server's player UUID
+    playerId: { type: String, required: true, trim: true },
+    // References CyberiaQuest.code
+    questCode: { type: String, required: true, trim: true },
+    // active | completed
+    // Quests do not fail — they stay active until completed or abandoned by the player.
+    status: {
+      type: String,
+      required: true,
+      enum: ['active', 'completed'],
+      default: 'active',
+    },
+    // One entry per step in the corresponding CyberiaQuest.steps[].
+    // A step is complete when all its objectiveProgress entries satisfy current >= required.
+    // The active step is the first step where not all objectives are done.
+    // done flags are intentionally omitted — completeness is always computed, never stored.
+    stepProgress: [
+      {
+        stepId: { type: String, required: true },
+        // One entry per objective in CyberiaQuest.steps[i].objectives[].
+        // `required` is denormalized from the quest definition for efficient server checks.
+        objectiveProgress: [
+          {
+            current: { type: Number, default: 0, min: 0 },
+            required: { type: Number, default: 1, min: 1 },
+          },
+        ],
+      },
+    ],
+    startedAt: { type: Date, default: Date.now },
+    completedAt: { type: Date, default: null },
+  },
+  { timestamps: true },
+);
+
+CyberiaQuestProgressSchema.index({ playerId: 1, questCode: 1 }, { unique: true });
+CyberiaQuestProgressSchema.index({ playerId: 1, status: 1 });
+
+const CyberiaQuestProgressModel = model('CyberiaQuestProgress', CyberiaQuestProgressSchema);
+
+const ProviderSchema = CyberiaQuestProgressSchema;
+
+export { CyberiaQuestProgressSchema, CyberiaQuestProgressModel, ProviderSchema };