@underpostnet/cyberia 3.2.80

package/src/api/atlas-sprite-sheet/atlas-sprite-sheet.service.js

@@ -0,0 +1,382 @@
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
+import { loggerFactory } from '../../server/logger.js';
+import { DataQuery } from '../../server/data-query.js';
+import { AtlasSpriteSheetGenerator } from '../../projects/cyberia/atlas-sprite-sheet-generator.js';
+import { FileFactory } from '../file/file.service.js';
+import { AtlasSpriteSheetDto } from './atlas-sprite-sheet.model.js';
+import { IpfsClient } from '../../projects/cyberia/ipfs-client.js';
+import { createPinRecord, removePinRecordsAndUnpin } from '../ipfs/ipfs.service.js';
+
+const logger = loggerFactory(import.meta);
+const DEFAULT_ATLAS_FRAME_DURATION = 100;
+
+function parseAtlasFrameDuration(value) {
+  const frameDuration = Number(value);
+  return Number.isFinite(frameDuration) ? frameDuration : null;
+}
+
+async function resolveAtlasFrameDuration(ObjectLayer, itemKey) {
+  if (!itemKey) return DEFAULT_ATLAS_FRAME_DURATION;
+
+  const objectLayer = await ObjectLayer.findOne({ 'data.item.id': itemKey })
+    .select({ _id: 1, objectLayerRenderFramesId: 1 })
+    .populate('objectLayerRenderFramesId', { _id: 1, frame_duration: 1 })
+    .lean();
+
+  return (
+    parseAtlasFrameDuration(objectLayer?.objectLayerRenderFramesId?.frame_duration) || DEFAULT_ATLAS_FRAME_DURATION
+  );
+}
+
+async function withResolvedAtlasFrameDuration(doc, ObjectLayer) {
+  if (!doc?.metadata) return doc;
+
+  const frameDuration = parseAtlasFrameDuration(doc.metadata.frame_duration);
+  if (frameDuration !== null) {
+    return {
+      ...doc,
+      metadata: {
+        ...doc.metadata,
+        frame_duration: frameDuration,
+      },
+    };
+  }
+
+  return {
+    ...doc,
+    metadata: {
+      ...doc.metadata,
+      frame_duration: await resolveAtlasFrameDuration(ObjectLayer, doc.metadata.itemKey),
+    },
+  };
+}
+
+class AtlasSpriteSheetService {
+  static blob = async (req, res, options) => {
+    /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
+    /** @type {import('../file/file.model.js').FileModel} */
+    const File = DataBaseProviderService.getModel('File', options);
+
+    const itemKey = req.params.itemKey;
+    const atlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': itemKey }).lean();
+    if (!atlasDoc) throw new Error(`Atlas not found for itemKey: ${itemKey}`);
+
+    const fileDoc = await File.findById(atlasDoc.fileId);
+    if (!fileDoc || !fileDoc.data) throw new Error(`File not found for atlas itemKey: ${itemKey}`);
+
+    return { buffer: Buffer.from(fileDoc.data), mimetype: fileDoc.mimetype || 'image/png', name: fileDoc.name };
+  };
+  static generate = async (req, res, options, generateOptions = {}) => {
+    /** @type {import('../object-layer/object-layer.model.js').ObjectLayerModel} */
+    const ObjectLayer = DataBaseProviderService.getModel('ObjectLayer', options);
+    /** @type {import('../file/file.model.js').FileModel} */
+    const File = DataBaseProviderService.getModel('File', options);
+    /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
+
+    let objectLayer = req.objectLayer;
+
+    if (!objectLayer) {
+      objectLayer = await ObjectLayer.findById(req.params.id).populate('objectLayerRenderFramesId');
+    }
+
+    if (!objectLayer) {
+      throw new Error('ObjectLayer not found');
+    }
+
+    if (!objectLayer.objectLayerRenderFramesId) {
+      throw new Error('ObjectLayer has no render frames');
+    }
+
+    const itemKey = objectLayer.data.item.id;
+    const { buffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
+      objectLayer.objectLayerRenderFramesId,
+      itemKey,
+    );
+
+    const fileDoc = await new File(FileFactory.create(buffer, `${itemKey}.png`)).save();
+
+    // Add atlas PNG to IPFS and obtain its CID
+    let atlasCid = '';
+    let atlasMetadataCid = '';
+    const userId = req.auth && req.auth.user ? req.auth.user._id : undefined;
+    try {
+      const ipfsResult = await IpfsClient.addBufferToIpfs(
+        buffer,
+        `${itemKey}_atlas_sprite_sheet.png`,
+        `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
+      );
+      if (ipfsResult) {
+        atlasCid = ipfsResult.cid;
+        logger.info(`Atlas sprite sheet pinned to IPFS – CID: ${atlasCid}`);
+      }
+    } catch (ipfsError) {
+      logger.warn('Failed to add atlas sprite sheet to IPFS:', ipfsError.message);
+    }
+
+    // Pin atlas metadata JSON to IPFS (fast-json-stable-stringify) and obtain its CID
+    try {
+      const metadataIpfsResult = await IpfsClient.addJsonToIpfs(
+        metadata,
+        `${itemKey}_atlas_sprite_sheet_metadata.json`,
+        `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
+      );
+      if (metadataIpfsResult) {
+        atlasMetadataCid = metadataIpfsResult.cid;
+        logger.info(`Atlas metadata pinned to IPFS – CID: ${atlasMetadataCid}`);
+      }
+    } catch (ipfsError) {
+      logger.warn('Failed to add atlas metadata to IPFS:', ipfsError.message);
+    }
+
+    let atlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': itemKey });
+
+    if (atlasDoc) {
+      // Clean up old file if it exists
+      if (atlasDoc.fileId) {
+        await File.findByIdAndDelete(atlasDoc.fileId);
+      }
+      atlasDoc.fileId = fileDoc._id;
+      atlasDoc.cid = atlasCid;
+      atlasDoc.metadata = metadata;
+      await atlasDoc.save();
+    } else {
+      atlasDoc = await new AtlasSpriteSheet({
+        fileId: fileDoc._id,
+        cid: atlasCid,
+        metadata,
+      }).save();
+    }
+
+    // Register CIDs in the IPFS registry now that atlasDoc._id is known.
+    if (atlasCid) {
+      try {
+        await createPinRecord({
+          cid: atlasCid,
+          resourceType: 'atlas-sprite-sheet',
+          mfsPath: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
+          options,
+        });
+      } catch (e) {
+        logger.warn('IPFS registry update failed (atlas PNG):', e.message);
+      }
+    }
+    if (atlasMetadataCid) {
+      try {
+        await createPinRecord({
+          cid: atlasMetadataCid,
+          resourceType: 'atlas-metadata',
+          mfsPath: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
+          options,
+        });
+      } catch (e) {
+        logger.warn('IPFS registry update failed (atlas metadata):', e.message);
+      }
+    }
+
+    // When skipObjectLayerSave is set, return CIDs without mutating the OL document.
+    // This enables cut-over consistency: callers stage CIDs in memory and write the
+    // ObjectLayer atomically only after all CIDs are computed.
+    if (generateOptions.skipObjectLayerSave) {
+      return { atlasDoc, atlasCid, atlasMetadataCid };
+    }
+
+    objectLayer.atlasSpriteSheetId = atlasDoc._id;
+    if (!objectLayer.data.render) objectLayer.data.render = {};
+    objectLayer.data.render.cid = atlasCid;
+    objectLayer.data.render.metadataCid = atlasMetadataCid;
+    objectLayer.markModified('data.render');
+    await objectLayer.save();
+
+    return atlasDoc;
+  };
+  static deleteByObjectLayerId = async (req, res, options) => {
+    /** @type {import('../object-layer/object-layer.model.js').ObjectLayerModel} */
+    const ObjectLayer = DataBaseProviderService.getModel('ObjectLayer', options);
+    /** @type {import('../file/file.model.js').FileModel} */
+    const File = DataBaseProviderService.getModel('File', options);
+    /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
+
+    const objectLayer = await ObjectLayer.findById(req.params.id);
+    if (!objectLayer) {
+      throw new Error('ObjectLayer not found');
+    }
+
+    if (objectLayer.atlasSpriteSheetId) {
+      const atlasDoc = await AtlasSpriteSheet.findById(objectLayer.atlasSpriteSheetId);
+      if (atlasDoc) {
+        // Remove pin records and unpin atlas CID from IPFS
+        const atlasCid = atlasDoc.cid || objectLayer.data.render?.cid;
+        const atlasMetadataCid = objectLayer.data.render?.metadataCid;
+        if (atlasCid) {
+          try {
+            await removePinRecordsAndUnpin(atlasCid, options);
+            // Remove the MFS entry for the atlas sprite sheet PNG
+            const itemId = objectLayer.data.item.id;
+            await IpfsClient.removeMfsPath(`/object-layer/${itemId}/${itemId}_atlas_sprite_sheet.png`);
+            logger.info(`Cleaned up IPFS atlas CID ${atlasCid} for ObjectLayer ${objectLayer._id}`);
+          } catch (ipfsErr) {
+            logger.warn(`Failed to clean up IPFS atlas CID ${atlasCid}: ${ipfsErr.message}`);
+          }
+        }
+        if (atlasMetadataCid) {
+          try {
+            await removePinRecordsAndUnpin(atlasMetadataCid, options);
+            const itemId = objectLayer.data.item.id;
+            await IpfsClient.removeMfsPath(`/object-layer/${itemId}/${itemId}_atlas_sprite_sheet_metadata.json`);
+            logger.info(`Cleaned up IPFS atlas metadata CID ${atlasMetadataCid} for ObjectLayer ${objectLayer._id}`);
+          } catch (ipfsErr) {
+            logger.warn(`Failed to clean up IPFS atlas metadata CID ${atlasMetadataCid}: ${ipfsErr.message}`);
+          }
+        }
+
+        // Delete the atlas File document from MongoDB
+        if (atlasDoc.fileId) {
+          await File.findByIdAndDelete(atlasDoc.fileId);
+        }
+        // Delete the AtlasSpriteSheet document itself
+        await AtlasSpriteSheet.findByIdAndDelete(atlasDoc._id);
+      }
+      objectLayer.atlasSpriteSheetId = undefined;
+      if (!objectLayer.data.render) objectLayer.data.render = {};
+      objectLayer.data.render.cid = '';
+      objectLayer.data.render.metadataCid = '';
+      objectLayer.markModified('data.render');
+      await objectLayer.save();
+    }
+
+    return { success: true };
+  };
+  static post = async (req, res, options) => {
+    /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
+    return await new AtlasSpriteSheet(req.body).save();
+  };
+  static get = async (req, res, options) => {
+    /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
+    if (req.params.id)
+      return await AtlasSpriteSheet.findById(req.params.id)
+        .select(AtlasSpriteSheetDto.select.get())
+        .populate('fileId', '-data');
+
+    // Parse query parameters using DataQuery helper
+    const { query, sort, skip, limit, page } = DataQuery.parse(req.query);
+
+    const [data, total] = await Promise.all([
+      AtlasSpriteSheet.find(query)
+        .select(AtlasSpriteSheetDto.select.get())
+        .sort(sort)
+        .limit(limit)
+        .skip(skip)
+        .populate('fileId', '-data'),
+      AtlasSpriteSheet.countDocuments(query),
+    ]);
+
+    const totalPages = Math.ceil(total / limit);
+    return { data, total, page, totalPages };
+  };
+  // Returns atlas metadata (layout + frames) for the client.
+  // Client fetches this once per itemKey, caches it, then fetches the PNG blob.
+  static getMetadata = async (req, res, options) => {
+    /** @type {import('../object-layer/object-layer.model.js').ObjectLayerModel} */
+    const ObjectLayer = DataBaseProviderService.getModel('ObjectLayer', options);
+    /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
+
+    if (req.params.itemKey) {
+      const doc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': req.params.itemKey })
+        .select(AtlasSpriteSheetDto.select.getMetadataOnly())
+        .lean();
+      if (!doc) throw new Error(`Atlas not found for itemKey: ${req.params.itemKey}`);
+      return await withResolvedAtlasFrameDuration(doc, ObjectLayer);
+    }
+
+    const { query, sort, skip, limit, page } = DataQuery.parse(req.query);
+
+    const [data, total] = await Promise.all([
+      AtlasSpriteSheet.find(query)
+        .select(AtlasSpriteSheetDto.select.getMetadataOnly())
+        .sort(sort)
+        .limit(limit)
+        .skip(skip)
+        .lean(),
+      AtlasSpriteSheet.countDocuments(query),
+    ]);
+
+    const totalPages = Math.ceil(total / limit);
+    return {
+      data: data.map((doc) => ({
+        ...doc,
+        metadata: {
+          ...doc.metadata,
+          frame_duration: parseAtlasFrameDuration(doc?.metadata?.frame_duration) || DEFAULT_ATLAS_FRAME_DURATION,
+        },
+      })),
+      total,
+      page,
+      totalPages,
+    };
+  };
+  static put = async (req, res, options) => {
+    /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
+    return await AtlasSpriteSheet.findByIdAndUpdate(req.params.id, req.body);
+  };
+  static delete = async (req, res, options) => {
+    /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
+    /** @type {import('../file/file.model.js').FileModel} */
+    const File = DataBaseProviderService.getModel('File', options);
+
+    if (req.params.id) {
+      const atlasDoc = await AtlasSpriteSheet.findById(req.params.id);
+      if (!atlasDoc) return null;
+
+      // Remove pin records and unpin atlas CID from IPFS
+      if (atlasDoc.cid) {
+        try {
+          await removePinRecordsAndUnpin(atlasDoc.cid, options);
+          if (atlasDoc.metadata?.itemKey) {
+            const itemKey = atlasDoc.metadata.itemKey;
+            await IpfsClient.removeMfsPath(`/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`);
+          }
+          logger.info(`Cleaned up IPFS atlas CID ${atlasDoc.cid} for AtlasSpriteSheet ${atlasDoc._id}`);
+        } catch (ipfsErr) {
+          logger.warn(`Failed to clean up IPFS atlas CID ${atlasDoc.cid}: ${ipfsErr.message}`);
+        }
+      }
+
+      // Delete the referenced File document (the atlas PNG blob)
+      if (atlasDoc.fileId) {
+        await File.findByIdAndDelete(atlasDoc.fileId);
+      }
+
+      return await AtlasSpriteSheet.findByIdAndDelete(req.params.id);
+    } else {
+      // Bulk delete: iterate each atlas to clean up File, IPFS pins, and pin records
+      const allAtlases = await AtlasSpriteSheet.find({});
+      for (const atlasDoc of allAtlases) {
+        try {
+          if (atlasDoc.cid) {
+            await removePinRecordsAndUnpin(atlasDoc.cid, options);
+            if (atlasDoc.metadata?.itemKey) {
+              const itemKey = atlasDoc.metadata.itemKey;
+              await IpfsClient.removeMfsPath(`/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`);
+            }
+          }
+          if (atlasDoc.fileId) {
+            await File.findByIdAndDelete(atlasDoc.fileId);
+          }
+        } catch (err) {
+          logger.error(`Failed to clean up AtlasSpriteSheet ${atlasDoc._id} during bulk delete: ${err.message}`);
+        }
+      }
+      return await AtlasSpriteSheet.deleteMany();
+    }
+  };
+}
+
+export { AtlasSpriteSheetService };

package/src/api/core/core.controller.js

@@ -0,0 +1,8 @@
+import { buildCrudController, serviceHandler } from '../../server/middlewares.js';
+import { CoreService } from './core.service.js';
+
+const CoreController = buildCrudController(CoreService, {
+  get: serviceHandler(CoreService.get),
+});
+
+export { CoreController };

package/src/api/core/core.model.js

@@ -0,0 +1,11 @@
+import { Schema, model, Types } from 'mongoose';
+
+// https://mongoosejs.com/docs/2.7.x/docs/schematypes.html
+
+const CoreSchema = new Schema({});
+
+const CoreModel = model('Core', CoreSchema);
+
+const ProviderSchema = CoreSchema;
+
+export { CoreSchema, CoreModel, ProviderSchema };

package/src/api/core/core.router.js

@@ -0,0 +1,23 @@
+import express from 'express';
+import { registerCrudRoutes } from '../../server/middlewares.js';
+import { adminGuard } from '../../server/auth.js';
+import { CoreController } from './core.controller.js';
+
+class CoreRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const adminOnly = [options.authMiddleware, adminGuard];
+    return registerCrudRoutes(express.Router(), CoreController, options, {
+      readGuards: adminOnly,
+      writeGuards: adminOnly,
+      deleteAllGuards: adminOnly,
+    });
+  }
+}
+
+const ApiRouter = (options) => CoreRouter.router(options);
+
+export { ApiRouter, CoreRouter };

package/src/api/core/core.service.js

@@ -0,0 +1,30 @@
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
+import { loggerFactory } from '../../server/logger.js';
+import { shellExec } from '../../server/process.js';
+
+const logger = loggerFactory(import.meta);
+
+class CoreService {
+  static post = async (req, res, options) => {
+    /** @type {import('./core.model.js').CoreModel} */
+    const Core = DataBaseProviderService.getModel("Core", options);
+    return await new Core(req.body).save();
+  };
+  static get = async (req, res, options) => {
+    /** @type {import('./core.model.js').CoreModel} */
+    const Core = DataBaseProviderService.getModel("Core", options);
+    return await Core.findById(req.params.id);
+  };
+  static put = async (req, res, options) => {
+    /** @type {import('./core.model.js').CoreModel} */
+    const Core = DataBaseProviderService.getModel("Core", options);
+    return await Core.findByIdAndUpdate(req.params.id, req.body);
+  };
+  static delete = async (req, res, options) => {
+    /** @type {import('./core.model.js').CoreModel} */
+    const Core = DataBaseProviderService.getModel("Core", options);
+    return await Core.findByIdAndDelete(req.params.id);
+  };
+}
+
+export { CoreService };

package/src/api/crypto/crypto.controller.js

@@ -0,0 +1,10 @@
+import { serviceHandler } from '../../server/middlewares.js';
+import { CryptoService } from './crypto.service.js';
+
+class CryptoController {
+  static post = serviceHandler(CryptoService.post);
+  static get = serviceHandler(CryptoService.get);
+  static delete = serviceHandler(CryptoService.delete);
+}
+
+export { CryptoController };

package/src/api/crypto/crypto.model.js

@@ -0,0 +1,23 @@
+import { Schema, model, Types } from 'mongoose';
+
+// https://mongoosejs.com/docs/2.7.x/docs/schematypes.html
+
+// Example:
+// JWKS: Array of JWK
+// https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets
+
+const CryptoSchema = new Schema({
+  format: { type: String, required: 'format is required' },
+  data: { type: String, required: 'data is required', unique: true },
+  algorithm: {
+    name: { type: String, required: 'name is required' },
+    namedCurve: { type: String, required: 'namedCurve is required' },
+    hash: { type: String, required: 'hash is required' },
+  },
+});
+
+const CryptoModel = model('Crypto', CryptoSchema);
+
+const ProviderSchema = CryptoSchema;
+
+export { CryptoSchema, CryptoModel, ProviderSchema };

package/src/api/crypto/crypto.router.js

@@ -0,0 +1,23 @@
+import express from 'express';
+import { CryptoController } from './crypto.controller.js';
+
+class CryptoRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const router = express.Router();
+    router.post(`/:id`, async (req, res) => await CryptoController.post(req, res, options));
+    router.post(`/`, options.authMiddleware, async (req, res) => await CryptoController.post(req, res, options));
+    router.get(`/:id`, async (req, res) => await CryptoController.get(req, res, options));
+    router.get(`/`, async (req, res) => await CryptoController.get(req, res, options));
+    router.delete(`/:id`, async (req, res) => await CryptoController.delete(req, res, options));
+    router.delete(`/`, async (req, res) => await CryptoController.delete(req, res, options));
+    return router;
+  }
+}
+
+const ApiRouter = (options) => CryptoRouter.router(options);
+
+export { ApiRouter, CryptoRouter };

package/src/api/crypto/crypto.service.js

@@ -0,0 +1,64 @@
+import { loggerFactory } from '../../server/logger.js';
+import crypto from 'crypto';
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
+const logger = loggerFactory(import.meta);
+
+class CryptoService {
+  static post = async (req, res, options) => {
+    /** @type {import('./crypto.model.js').CryptoModel} */
+    const Crypto = DataBaseProviderService.getModel("Crypto", options);
+    /** @type {import('../user/user.model.js').UserModel} */
+    const User = DataBaseProviderService.getModel("User", options);
+
+    switch (req.params.id) {
+      case 'verify': {
+        const signature = Buffer.from(req.body.signature, 'base64');
+
+        const publicKey = await crypto.subtle.importKey(
+          'jwk',
+          req.body.publicKey,
+          {
+            name: 'ECDSA',
+            namedCurve: 'P-384',
+            hash: 'SHA-256',
+          },
+          true,
+          ['verify'],
+        );
+
+        const isValid = await crypto.subtle.verify(
+          {
+            name: 'ECDSA',
+            hash: 'SHA-256',
+          },
+          publicKey,
+          signature,
+          new TextEncoder().encode(JSON.stringify(req.body.payload)),
+        );
+
+        return { isValid };
+      }
+      default: {
+        const publicKey = await new Crypto(req.body).save();
+        const user = await User.findById(req.auth.user._id);
+        user.publicKey.push(publicKey._id);
+        await User.findByIdAndUpdate(req.auth.user._id, user, {
+          runValidators: true,
+        });
+        return publicKey;
+      }
+    }
+  };
+  static get = async (req, res, options) => {
+    switch (req.params.id) {
+      default:
+    }
+  };
+  static delete = async (req, res, options) => {
+    switch (req.params.id) {
+      default:
+    }
+  };
+}
+
+export { CryptoService };

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

@@ -0,0 +1,8 @@
+import { buildCrudController, serviceHandler } from '../../server/middlewares.js';
+import { CyberiaActionService } from './cyberia-action.service.js';
+
+const CyberiaActionController = buildCrudController(CyberiaActionService, {
+  getByCode: serviceHandler(CyberiaActionService.getByCode, { crossOrigin: true, errorStatus: 404 }),
+});
+
+export { CyberiaActionController };

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

@@ -0,0 +1,79 @@
+import { Schema, model } from 'mongoose';
+
+// https://mongoosejs.com/docs/2.7.x/docs/schematypes.html
+
+const CyberiaActionSchema = new Schema(
+  {
+    // Spatial origin: the cell whose matching bot entity provides this action.
+    // An action has NO type — its capabilities are whatever payloads are
+    // populated (questDialogueCodes / shopItems / craftRecipes / storageSlots),
+    // resolved per player. The quest-provider capability is active when there
+    // are CyberiaQuests bound to this same (sourceMapCode, sourceCellX,
+    // sourceCellY).
+    sourceMapCode: { type: String, trim: true },
+    sourceCellX: { type: Number },
+    sourceCellY: { type: Number },
+
+    // ── Identity ──────────────────────────────────────────────────────────
+    // `code` is a generic, location-scoped slug (it associates the action with
+    // its cell, not a single behavior). `label` is the name shown on the bot's
+    // overhead nameplate (the client fetches it by code via REST).
+    code: { type: String, required: true, trim: true },
+    label: { type: String, trim: true, default: '' },
+
+    // ── Dialogue ──────────────────────────────────────────────────────────
+    // General greeting shown when the interaction modal opens. Empty = client
+    // falls back to /code/default-<skin> from the entity's active skin.
+    dialogCode: { type: String, trim: true, default: '' },
+
+    // Per-quest dialogue map: the CyberiaDialogue code to display for each quest
+    // this NPC handles. The server validates a `talk` objective only when the
+    // viewed dialogCode matches the entry for that quest.
+    questDialogueCodes: [
+      {
+        questCode: { type: String, required: true, trim: true },
+        dialogCode: { type: String, required: true, trim: true },
+      },
+    ],
+
+    // ── Shop payload ──────────────────────────────────────────────────────
+    shopItems: [
+      {
+        itemId: { type: String, required: true, trim: true },
+        priceItemId: { type: String, default: 'coin', trim: true },
+        priceQty: { type: Number, default: 1, min: 0 },
+      },
+    ],
+
+    // ── Craft payload (type="craft") ───────────────────────────────────────
+    craftRecipes: [
+      {
+        outputItems: [
+          {
+            itemId: { type: String, required: true, trim: true },
+            qty: { type: Number, default: 1, min: 1 },
+          },
+        ],
+        ingredients: [
+          {
+            itemId: { type: String, required: true, trim: true },
+            qty: { type: Number, default: 1, min: 1 },
+          },
+        ],
+      },
+    ],
+
+    // ── Storage payload (type="storage") ──────────────────────────────────
+    storageSlots: { type: Number, default: 0, min: 0 },
+  },
+  { timestamps: true },
+);
+
+CyberiaActionSchema.index({ code: 1 }, { unique: true });
+CyberiaActionSchema.index({ sourceMapCode: 1, sourceCellX: 1, sourceCellY: 1 });
+
+const CyberiaActionModel = model('CyberiaAction', CyberiaActionSchema);
+
+const ProviderSchema = CyberiaActionSchema;
+
+export { CyberiaActionSchema, CyberiaActionModel, ProviderSchema };