@airoom/nextmin-node 0.1.0

package/dist/api/apiRouter.js

@@ -0,0 +1,1548 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APIRouter = void 0;
+const express_1 = __importDefault(require("express"));
+const BaseModel_1 = require("../models/BaseModel");
+const Logger_1 = __importDefault(require("../utils/Logger"));
+const bcrypt_1 = __importDefault(require("bcrypt"));
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+const SchemaLoader_1 = require("../utils/SchemaLoader");
+const InMemoryAdapter_1 = require("../database/InMemoryAdapter");
+const DefaultDataInitializer_1 = require("../utils/DefaultDataInitializer");
+const SchemaService_1 = require("../services/SchemaService");
+const multer_1 = __importDefault(require("multer"));
+const filename_1 = require("../files/filename");
+const authorize_1 = require("../policy/authorize");
+const fieldCodecs_1 = require("../utils/fieldCodecs");
+class APIRouter {
+    constructor(options) {
+        this.models = {};
+        this.findRoutesMounted = false;
+        this.authRoutesInitialized = false;
+        this.schemasRouteRegistered = false;
+        this.registeredModels = new Set();
+        this.liveSchemas = {};
+        // ---------------- Live lookups ----------------
+        this.getSchema = (name) => {
+            const s = this.liveSchemas[name];
+            if (!s) {
+                const err = new Error(`Model '${name}' removed`);
+                err.code = 'MODEL_REMOVED';
+                throw err;
+            }
+            return s;
+        };
+        this.getModel = (name) => {
+            this.getSchema(name);
+            const m = this.models[name];
+            if (!m) {
+                const err = new Error(`Model '${name}' unavailable`);
+                err.code = 'MODEL_UNAVAILABLE';
+                throw err;
+            }
+            return m;
+        };
+        this.fileAuthMiddleware = (req, res, next) => this.authenticateMiddleware(req, res, next);
+        // ---------------- Auth (login/me/change-password) ----------------
+        this.optionalAuthMiddleware = (req, res, next) => {
+            this.apiKeyMiddleware(req, res, () => {
+                const authHeader = req.headers.authorization;
+                if (!authHeader)
+                    return next();
+                const token = authHeader.split(' ')[1];
+                if (!token)
+                    return next();
+                try {
+                    const decoded = jsonwebtoken_1.default.verify(token, this.jwtSecret);
+                    // @ts-ignore
+                    req.user = decoded;
+                }
+                catch { }
+                next();
+            });
+        };
+        this.normalizeRoleName = async (value) => {
+            const rolesModel = this.getModel('roles'); // already available in your router
+            const isHex24 = (s) => /^[0-9a-fA-F]{24}$/.test(s);
+            const fromString = async (s) => {
+                if (!s)
+                    return null;
+                if (isHex24(s) && rolesModel) {
+                    const docs = await rolesModel.read({ id: s }, 1, 0, true);
+                    const n = docs?.[0]?.name;
+                    return typeof n === 'string' ? n : null;
+                }
+                return s; // assume literal role name like "admin"
+            };
+            if (typeof value === 'string')
+                return (await fromString(value))?.toLowerCase() ?? null;
+            if (Array.isArray(value)) {
+                for (const v of value) {
+                    const n = typeof v === 'string'
+                        ? await fromString(v)
+                        : v && typeof v === 'object' && typeof v.name === 'string'
+                            ? v.name
+                            : null;
+                    if (n)
+                        return n.toLowerCase();
+                }
+                return null;
+            }
+            if (value && typeof value === 'object') {
+                const o = value;
+                if (typeof o.name === 'string')
+                    return o.name.toLowerCase();
+                if (typeof o.id === 'string') {
+                    const n = await fromString(o.id);
+                    return n ? n.toLowerCase() : null;
+                }
+            }
+            return null;
+        };
+        this.apiKeyMiddleware = (req, res, next) => {
+            const apiKey = req.headers['x-api-key'];
+            if (typeof apiKey !== 'string' || apiKey !== this.trustedApiKey) {
+                return res.status(401).json({ error: 'Invalid or missing API key' });
+            }
+            next();
+        };
+        this.authenticateMiddleware = (req, res, next) => {
+            this.apiKeyMiddleware(req, res, () => {
+                const authHeader = req.headers.authorization;
+                if (!authHeader)
+                    return res.status(401).json({ error: 'Authorization header missing' });
+                const token = authHeader.split(' ')[1];
+                if (!token)
+                    return res.status(401).json({ error: 'API Token missing.' });
+                try {
+                    const decoded = jsonwebtoken_1.default.verify(token, this.jwtSecret);
+                    // @ts-ignore
+                    req.user = decoded;
+                    next();
+                }
+                catch {
+                    res.status(401).json({ error: 'Invalid or expired token' });
+                }
+            });
+        };
+        this.isDevelopment = process.env.APP_MODE !== 'production';
+        this.router = express_1.default.Router();
+        this.fileStorage = options.fileStorageAdapter;
+        this.setupFileRoutes();
+        this.dbAdapter = options.dbAdapter || new InMemoryAdapter_1.InMemoryAdapter();
+        this.jwtSecret = process.env.JWT_SECRET || 'default_jwt_secret';
+        if (this.isDevelopment && options.server) {
+            (0, SchemaService_1.startSchemaService)(options.server, {
+                getApiKey: () => this.trustedApiKey,
+            });
+            options.server.on('listening', () => {
+                // @ts-ignore
+                const addr = options.server.address();
+                Logger_1.default.info('SchemaService', `[schema-service] started at /__nextmin__/schema ns /schema on ${typeof addr === 'string' ? addr : `${addr?.address}:${addr?.port}`}`);
+            });
+        }
+        this.schemaLoader =
+            SchemaLoader_1.SchemaLoader.getInstance?.() ?? new SchemaLoader_1.SchemaLoader();
+        const initialSchemas = this.schemaLoader.getSchemas();
+        this.setLiveSchemas(initialSchemas);
+        const finishBoot = async () => {
+            if (typeof this.dbAdapter.registerSchemas === 'function') {
+                await this.dbAdapter.registerSchemas(initialSchemas);
+            }
+            this.rebuildModels(Object.values(initialSchemas));
+            this.mountSchemasEndpointOnce();
+            this.mountRoutes(initialSchemas);
+            this.mountFindRoutes();
+            await this.syncAllIndexes(initialSchemas);
+            const initializer = new DefaultDataInitializer_1.DefaultDataInitializer(this.dbAdapter, this.models);
+            try {
+                await initializer.initialize();
+                this.trustedApiKey = initializer.getApiKey() || '';
+                Logger_1.default.info('APIRouter', `Trusted API key set: ${this.trustedApiKey ? '[hidden]' : 'none'}`);
+            }
+            catch (err) {
+                Logger_1.default.error('APIRouter', 'Failed to initialize default data', err);
+            }
+            this.setupNotFoundMiddleware();
+            this.wireSchemaHotReload();
+        };
+        if (typeof this.dbAdapter.registerSchemas === 'function') {
+            const res = this.dbAdapter.registerSchemas(initialSchemas);
+            if (res instanceof Promise) {
+                res.then(finishBoot).catch((err) => {
+                    Logger_1.default.error('APIRouter', 'registerSchemas failed', err);
+                    this.setupNotFoundMiddleware();
+                });
+                return;
+            }
+        }
+        finishBoot().catch((err) => {
+            Logger_1.default.error('APIRouter', 'finishBoot error', err);
+            this.setupNotFoundMiddleware();
+        });
+    }
+    getRouter() {
+        // Avoid noisy logs on each getRouter() call
+        return this.router;
+    }
+    // ---------------- Hot reload ----------------
+    wireSchemaHotReload() {
+        const anyLoader = this.schemaLoader;
+        if (typeof anyLoader.on !== 'function')
+            return;
+        anyLoader.on('schemasChanged', async (newSchemas) => {
+            try {
+                const removed = this.diffRemovedModels(this.liveSchemas, newSchemas);
+                if (removed.length &&
+                    typeof this.dbAdapter.unregisterSchemas === 'function') {
+                    await this.dbAdapter.unregisterSchemas(removed);
+                }
+                else if (removed.length &&
+                    typeof this.dbAdapter.dropModel === 'function') {
+                    for (const name of removed) {
+                        try {
+                            await this.dbAdapter.dropModel(name);
+                        }
+                        catch { }
+                    }
+                }
+                if (typeof this.dbAdapter.registerSchemas === 'function') {
+                    await this.dbAdapter.registerSchemas(newSchemas);
+                }
+                this.setLiveSchemas(newSchemas);
+                this.rebuildModels(Object.values(newSchemas));
+                this.mountRoutes(newSchemas);
+                await this.syncAllIndexes(newSchemas);
+                Logger_1.default.info('APIRouter', `Schemas reloaded (added/updated: ${Object.keys(newSchemas).length}, removed: ${removed.join(', ') || 'none'})`);
+            }
+            catch (err) {
+                Logger_1.default.error('APIRouter', 'Failed to refresh after schemasChanged', err);
+            }
+        });
+    }
+    async syncAllIndexes(schemas) {
+        if (typeof this.dbAdapter.syncIndexes !== 'function')
+            return;
+        const plan = this.schemaLoader.getIndexPlan(); // modelName -> { field: dir }
+        for (const s of Object.values(schemas)) {
+            const modelName = s.modelName;
+            const spec = plan[modelName];
+            if (spec) {
+                try {
+                    await this.dbAdapter.syncIndexes(modelName, spec);
+                }
+                catch (err) {
+                    Logger_1.default.warn('APIRouter', `Index sync failed for ${modelName}: ${err?.message || err}`);
+                }
+            }
+        }
+    }
+    diffRemovedModels(prev, nextMap) {
+        const next = new Set(Object.keys(nextMap).map((k) => k.toLowerCase()));
+        const removed = [];
+        for (const name of Object.keys(prev)) {
+            if (!next.has(name.toLowerCase()))
+                removed.push(name.toLowerCase());
+        }
+        return removed.filter((n) => n !== 'users' && n !== 'roles');
+    }
+    setLiveSchemas(schemas) {
+        const idx = {};
+        for (const s of Object.values(schemas)) {
+            idx[s.modelName.toLowerCase()] = s;
+        }
+        this.liveSchemas = idx;
+    }
+    rebuildModels(schemas) {
+        for (const s of schemas) {
+            const name = s.modelName.toLowerCase();
+            this.models[name] = new BaseModel_1.BaseModel(s, this.dbAdapter);
+        }
+    }
+    // ---------------- Mounting ----------------
+    mountSchemasEndpointOnce() {
+        if (this.schemasRouteRegistered)
+            return;
+        this.schemasRouteRegistered = true;
+        this.router.get('/_schemas', this.apiKeyMiddleware, (_req, res) => {
+            res.json({
+                success: true,
+                data: this.schemaLoader.getPublicSchemaList(),
+            });
+        });
+    }
+    mountRoutes(schemas) {
+        if (!this.authRoutesInitialized && this.liveSchemas['users']) {
+            this.setupAuthRoutes();
+            this.authRoutesInitialized = true;
+        }
+        for (const s of Object.values(schemas)) {
+            const name = s.modelName.toLowerCase();
+            if (this.registeredModels.has(name))
+                continue;
+            this.setupRoutes(name);
+            this.registeredModels.add(name);
+        }
+        this.ensureNotFoundLast();
+    }
+    // ---------------- Generic CRUD (policy-enforced) ----------------
+    setupRoutes(modelNameLC) {
+        const basePath = `/${modelNameLC}`;
+        const mwCreate = this.pickAuthFor('create', modelNameLC);
+        const mwRead = this.pickAuthFor('read', modelNameLC);
+        const mwUpdate = this.pickAuthFor('update', modelNameLC);
+        const mwDelete = this.pickAuthFor('delete', modelNameLC);
+        const ctxFromReq = (req) => {
+            const raw = req.user?.role;
+            let roleStr = null;
+            if (typeof raw === 'string') {
+                roleStr = raw;
+            }
+            else if (Array.isArray(raw)) {
+                const first = raw[0];
+                if (typeof first === 'string')
+                    roleStr = first;
+                else if (first &&
+                    typeof first === 'object' &&
+                    typeof first.name === 'string') {
+                    roleStr = first.name;
+                }
+            }
+            else if (raw &&
+                typeof raw === 'object' &&
+                typeof raw.name === 'string') {
+                roleStr = raw.name;
+            }
+            roleStr = roleStr ? roleStr.toLowerCase() : null;
+            return {
+                isAuthenticated: !!req.user,
+                role: roleStr,
+                userId: req.user?.id ?? req.user?._id ?? null,
+                isSuperadmin: roleStr === 'superadmin',
+                apiKeyOk: true,
+            };
+        };
+        // -------------- CREATE --------------
+        this.router.post(basePath, mwCreate, async (req, res) => {
+            try {
+                const schema = this.getSchema(modelNameLC);
+                if (!schema.allowedMethods.create) {
+                    return res
+                        .status(405)
+                        .json({ error: true, message: 'Method not allowed' });
+                }
+                const model = this.getModel(modelNameLC);
+                const ctx = ctxFromReq(req);
+                const schemaPolicy = {
+                    allowedMethods: schema.allowedMethods,
+                    access: schema.access,
+                };
+                const cdec = (0, authorize_1.authorize)(modelNameLC, 'create', schemaPolicy, ctx);
+                if (!cdec.allow) {
+                    return res.status(403).json({ error: true, message: 'forbidden' });
+                }
+                let payload = (0, authorize_1.mergeCreateDefaults)(req.body, cdec.createDefaults);
+                (0, authorize_1.enforceRestrictions)(payload, cdec.restrictions, ctx);
+                if (!cdec.exposePrivate) {
+                    payload = (0, authorize_1.stripWriteDeny)(payload, cdec.writeDeny);
+                }
+                // ✅ NEW: DB-agnostic coercion (time/date/range → canonical strings)
+                payload = (0, fieldCodecs_1.coerceForStorage)(schema, payload);
+                // CREATE: required fields must be present and non-empty (now in canonical shape)
+                const missing = this.validateRequiredFields(schema, payload, 'create');
+                if (missing.length) {
+                    return res.status(400).json({
+                        error: true,
+                        message: `Missing required fields: ${missing.join(', ')}`,
+                    });
+                }
+                const conflicts = await this.checkUniqueFields(schema, payload);
+                if (conflicts && conflicts.length > 0) {
+                    return res.status(400).json({
+                        error: true,
+                        fields: conflicts.map((field) => ({
+                            field,
+                            error: true,
+                            message: `You cannot use this ${field}. It's already been used.`,
+                        })),
+                    });
+                }
+                // Hash password for Users creates
+                if (modelNameLC === 'users' && payload.password && this.jwtSecret) {
+                    const salt = await bcrypt_1.default.genSalt(10);
+                    payload.password = await bcrypt_1.default.hash(String(payload.password) + this.jwtSecret, salt);
+                }
+                const created = await model.create(payload);
+                let resultDoc = created;
+                if (cdec.exposePrivate && created?.id) {
+                    const refetched = await model.read({ id: created.id }, 1, 0, true);
+                    if (refetched?.[0])
+                        resultDoc = refetched[0];
+                }
+                const masked = cdec.exposePrivate
+                    ? (0, authorize_1.applyReadMaskOne)(resultDoc, cdec.sensitiveMask)
+                    : (0, authorize_1.applyReadMaskOne)(resultDoc, cdec.readMask);
+                return res.status(201).json({
+                    success: true,
+                    message: `${schema.modelName} has been created successfully.`,
+                    data: masked,
+                });
+            }
+            catch (error) {
+                if (error?.code === 'MODEL_REMOVED') {
+                    return res
+                        .status(410)
+                        .json({ error: true, message: error.message });
+                }
+                this.handleWriteError(error, res);
+            }
+        });
+        // -------------- READ (list) --------------
+        this.router.get(basePath, mwRead, async (req, res) => {
+            try {
+                const schema = this.getSchema(modelNameLC);
+                if (!schema.allowedMethods.read) {
+                    return res
+                        .status(405)
+                        .json({ error: true, message: 'Method not allowed' });
+                }
+                const model = this.getModel(modelNameLC);
+                const page = Number.parseInt(String(req.query.page ?? '0'), 10) || 0;
+                const limit = Number.parseInt(String(req.query.limit ?? '10'), 10) || 10;
+                // ---- search params (extended) ----
+                const q = String(req.query.q ?? '').trim();
+                const searchKey = String(req.query.searchKey ?? '').trim();
+                const searchKeysCSV = String(req.query.searchKeys ?? '').trim();
+                const searchMode = /^(and|or)$/i.test(String(req.query.searchMode ?? ''))
+                    ? String(req.query.searchMode).toLowerCase()
+                    : 'or';
+                const dateFromStr = String(req.query.dateFrom ?? '').trim();
+                const dateToStr = String(req.query.dateTo ?? '').trim();
+                let dateKey = String(req.query.dateKey ?? 'createdAt').trim();
+                // ---- NEW: sort params (supports CSV for multi-field) ----
+                const sortRaw = String(req.query.sort ?? '').trim(); // e.g. "name,createdAt"
+                const sortTypeRaw = String(req.query.sortType ?? '').trim(); // e.g. "asc,desc"
+                const filter = {};
+                const splitCSV = (raw) => raw
+                    .split(',')
+                    .map((s) => s.trim())
+                    .filter(Boolean);
+                // Build sort spec limited to schema fields. Default desc(createdAt) if nothing valid provided.
+                const buildSortSpec = () => {
+                    const keys = splitCSV(sortRaw);
+                    const dirs = splitCSV(sortTypeRaw);
+                    const sort = {};
+                    keys.forEach((k, i) => {
+                        // keep the guard so unknown fields are ignored
+                        if (!schema.attributes?.[k])
+                            return;
+                        const d = dirs[i] ?? dirs[dirs.length - 1] ?? 'desc';
+                        sort[k] = /^(desc|-1)$/i.test(d) ? -1 : 1;
+                    });
+                    if (!Object.keys(sort).length) {
+                        // ✅ always default
+                        sort.createdAt = -1;
+                    }
+                    return sort;
+                };
+                // ---- SEARCH (legacy + multi) ----
+                const ors = [];
+                const ands = [];
+                const buildPredicateForField = (field, attr, raw) => {
+                    const isArray = Array.isArray(attr);
+                    const base = isArray ? attr[0] : attr;
+                    const attrType = this.normalizeAttrType(base);
+                    const tokens = splitCSV(raw);
+                    switch (attrType) {
+                        case 'string':
+                            return isArray
+                                ? { [field]: { $in: tokens.length ? tokens : [raw] } }
+                                : { [field]: { $regex: raw, $options: 'i' } };
+                        case 'number': {
+                            const nums = tokens.map(Number).filter((n) => !Number.isNaN(n));
+                            return isArray
+                                ? nums.length
+                                    ? { [field]: { $in: nums } }
+                                    : null
+                                : nums.length
+                                    ? { [field]: nums[0] }
+                                    : null;
+                        }
+                        case 'boolean': {
+                            const toBool = (t) => /^(true|1|yes)$/i.test(t)
+                                ? true
+                                : /^(false|0|no)$/i.test(t)
+                                    ? false
+                                    : null;
+                            if (isArray) {
+                                const bools = tokens
+                                    .map(toBool)
+                                    .filter((v) => v !== null);
+                                return bools.length ? { [field]: { $in: bools } } : null;
+                            }
+                            const b = toBool(raw);
+                            return b === null ? null : { [field]: b };
+                        }
+                        case 'objectid':
+                            return isArray || tokens.length > 1
+                                ? { [field]: { $in: tokens } }
+                                : raw
+                                    ? { [field]: raw }
+                                    : null;
+                        case 'date': {
+                            const toDate = (t) => {
+                                const d = new Date(t);
+                                return Number.isNaN(+d) ? null : d;
+                            };
+                            if (isArray) {
+                                const ds = tokens.map(toDate).filter((d) => !!d);
+                                return ds.length ? { [field]: { $in: ds } } : null;
+                            }
+                            const d = toDate(raw);
+                            return d ? { [field]: d } : null;
+                        }
+                        default:
+                            return isArray
+                                ? { [field]: { $in: tokens.length ? tokens : [raw] } }
+                                : { [field]: raw };
+                    }
+                };
+                if (q && searchKey && schema.attributes?.[searchKey]) {
+                    const p = buildPredicateForField(searchKey, schema.attributes[searchKey], q);
+                    if (p)
+                        ors.push(p);
+                }
+                if (q && searchKeysCSV) {
+                    const keys = splitCSV(searchKeysCSV);
+                    const preds = keys
+                        .filter((k) => !!schema.attributes?.[k])
+                        .map((k) => buildPredicateForField(k, schema.attributes[k], q))
+                        .filter(Boolean);
+                    if (preds.length) {
+                        if (searchMode === 'and')
+                            ands.push(...preds);
+                        else
+                            ors.push(...preds);
+                    }
+                }
+                if (ands.length && ors.length)
+                    filter.$and = [...ands, { $or: ors }];
+                else if (ands.length)
+                    filter.$and = [...(filter.$and || []), ...ands];
+                else if (ors.length)
+                    filter.$or = [...(filter.$or || []), ...ors];
+                // ---- DATE RANGE (unchanged) ----
+                if (dateFromStr || dateToStr) {
+                    if (!schema.attributes?.[dateKey]) {
+                        if (schema.attributes?.createdAt)
+                            dateKey = 'createdAt';
+                        else if (schema.attributes?.updatedAt)
+                            dateKey = 'updatedAt';
+                    }
+                    if (dateKey && schema.attributes?.[dateKey]) {
+                        const range = {};
+                        if (dateFromStr) {
+                            const d = new Date(dateFromStr);
+                            if (!Number.isNaN(+d))
+                                range.$gte = d;
+                        }
+                        if (dateToStr) {
+                            const d = new Date(dateToStr);
+                            if (!Number.isNaN(+d))
+                                range.$lte = d;
+                        }
+                        if (Object.keys(range).length)
+                            filter[dateKey] = range;
+                    }
+                }
+                const ctx = ctxFromReq(req);
+                const schemaPolicy = {
+                    allowedMethods: schema.allowedMethods,
+                    access: schema.access,
+                };
+                const rdec = (0, authorize_1.authorize)(modelNameLC, 'read', schemaPolicy, ctx);
+                if (!rdec.allow)
+                    return res.status(403).json({ error: true, message: 'forbidden' });
+                const finalFilter = (0, authorize_1.andFilter)(filter, rdec.queryFilter || {});
+                const isUsersModel = modelNameLC === 'user' ||
+                    modelNameLC === 'users' ||
+                    (schema?.modelName ?? '').toLowerCase() === 'users';
+                const currentUserId = req?.user?.id;
+                // ---- NEW: compute sort spec
+                const sort = buildSortSpec();
+                // count
+                const totalRows = await model.count(finalFilter);
+                // try DB-level sort (preferred). Fallback to in-memory if adapter lacks sort support.
+                let rawRows = [];
+                try {
+                    rawRows = await model.read(finalFilter, limit + 1, page * limit, !!rdec.exposePrivate, { sort });
+                }
+                catch {
+                    rawRows = await model.read(finalFilter, limit + 1, page * limit, !!rdec.exposePrivate);
+                    if (sort && Object.keys(sort).length) {
+                        const orderKeys = Object.keys(sort);
+                        rawRows.sort((a, b) => {
+                            for (const k of orderKeys) {
+                                const dir = sort[k];
+                                const av = a?.[k];
+                                const bv = b?.[k];
+                                const ax = av instanceof Date ? +av : (av?.toString?.() ?? av);
+                                const bx = bv instanceof Date ? +bv : (bv?.toString?.() ?? bv);
+                                if (ax == null && bx == null)
+                                    continue;
+                                if (ax == null)
+                                    return 1 * dir;
+                                if (bx == null)
+                                    return -1 * dir;
+                                if (ax > bx)
+                                    return 1 * dir;
+                                if (ax < bx)
+                                    return -1 * dir;
+                            }
+                            return 0;
+                        });
+                    }
+                }
+                let rows = currentUserId && isUsersModel
+                    ? rawRows
+                        .filter((r) => String(r?.id) !== String(currentUserId))
+                        .slice(0, limit)
+                    : rawRows.slice(0, limit);
+                const data = rdec.exposePrivate
+                    ? (0, authorize_1.applyReadMaskMany)(rows, rdec.sensitiveMask)
+                    : (0, authorize_1.applyReadMaskMany)(rows, rdec.readMask);
+                return res.status(200).json({
+                    success: true,
+                    message: `Data fetched for ${schema.modelName}`,
+                    data,
+                    pagination: { totalRows, page, limit },
+                    sort, // optional echo
+                });
+            }
+            catch (error) {
+                if (error?.code === 'MODEL_REMOVED') {
+                    return res.status(410).json({ error: true, message: error.message });
+                }
+                return res.status(400).json({ error: true, message: error.message });
+            }
+        });
+        // -------------- READ (by id) --------------
+        this.router.get(`${basePath}/:id`, mwRead, async (req, res) => {
+            try {
+                const schema = this.getSchema(modelNameLC);
+                if (!schema.allowedMethods.read) {
+                    return res
+                        .status(405)
+                        .json({ error: true, message: 'Method not allowed' });
+                }
+                const model = this.getModel(modelNameLC);
+                const ctx = ctxFromReq(req);
+                const schemaPolicy = {
+                    allowedMethods: schema.allowedMethods,
+                    access: schema.access,
+                };
+                const decForInclude = (0, authorize_1.authorize)(modelNameLC, 'read', schemaPolicy, ctx);
+                const recordArr = await model.read({ id: req.params.id }, 1, 0, !!decForInclude.exposePrivate);
+                const doc = recordArr?.[0];
+                if (!doc) {
+                    return res
+                        .status(404)
+                        .json({ error: true, message: `${schema.modelName} not found` });
+                }
+                const dec = (0, authorize_1.authorize)(modelNameLC, 'read', schemaPolicy, ctx, doc);
+                if (!dec.allow)
+                    return res.status(403).json({ error: true, message: 'forbidden' });
+                const data = dec.exposePrivate
+                    ? (0, authorize_1.applyReadMaskOne)(doc, dec.sensitiveMask)
+                    : (0, authorize_1.applyReadMaskOne)(doc, dec.readMask);
+                return res.status(200).json({
+                    success: true,
+                    message: `${schema.modelName} found`,
+                    data,
+                });
+            }
+            catch (error) {
+                if (error?.code === 'MODEL_REMOVED')
+                    return res
+                        .status(410)
+                        .json({ error: true, message: error.message });
+                Logger_1.default.error('error', error.message);
+                res.status(400).json({ error: true, message: error.message });
+            }
+        });
+        // -------------- UPDATE --------------
+        this.router.put(`${basePath}/:id`, mwUpdate, async (req, res) => {
+            try {
+                const schema = this.getSchema(modelNameLC);
+                if (!schema.allowedMethods.update) {
+                    return res
+                        .status(405)
+                        .json({ error: true, message: 'Method not allowed' });
+                }
+                const model = this.getModel(modelNameLC);
+                const beforeArr = await model.read({ id: req.params.id }, 1, 0, true);
+                const before = beforeArr?.[0];
+                const ctx = ctxFromReq(req);
+                const schemaPolicy = {
+                    allowedMethods: schema.allowedMethods,
+                    access: schema.access,
+                };
+                const udec = (0, authorize_1.authorize)(modelNameLC, 'update', schemaPolicy, ctx, before);
+                if (!udec.allow) {
+                    return res.status(403).json({ error: true, message: 'forbidden' });
+                }
+                let upd = { ...req.body };
+                (0, authorize_1.enforceRestrictions)(upd, udec.restrictions, ctx);
+                if (!udec.exposePrivate) {
+                    upd = (0, authorize_1.stripWriteDeny)(upd, udec.writeDeny);
+                }
+                // ✅ NEW: DB-agnostic coercion (time/date/range → canonical strings)
+                upd = (0, fieldCodecs_1.coerceForStorage)(schema, upd);
+                // Users: handle password if (and only if) provided
+                if (modelNameLC === 'users' &&
+                    Object.prototype.hasOwnProperty.call(upd, 'password')) {
+                    if (!upd.password) {
+                        delete upd.password; // ignore empty → do not overwrite
+                    }
+                    else if (this.jwtSecret) {
+                        const salt = await bcrypt_1.default.genSalt(10);
+                        upd.password = await bcrypt_1.default.hash(String(upd.password) + this.jwtSecret, salt);
+                    }
+                }
+                // UPDATE: validate only fields present in payload (now in canonical shape)
+                const missing = this.validateRequiredFields(schema, upd, 'update');
+                if (missing.length) {
+                    return res.status(400).json({
+                        error: true,
+                        message: `Missing required fields: ${missing.join(', ')}`,
+                    });
+                }
+                const conflicts = await this.checkUniqueFields(schema, upd, req.params.id);
+                if (conflicts && conflicts.length > 0) {
+                    return res.status(400).json({
+                        error: true,
+                        message: 'There are some error while updating record.',
+                        fields: conflicts.map((field) => ({
+                            field,
+                            error: true,
+                            message: `You cannot use this ${field}. It's already been used.`,
+                        })),
+                    });
+                }
+                const updatedRecord = await model.update(req.params.id, upd);
+                let responseDoc = updatedRecord;
+                if (udec.exposePrivate && updatedRecord?.id) {
+                    const refetched = await model.read({ id: updatedRecord.id }, 1, 0, true);
+                    if (refetched?.[0])
+                        responseDoc = refetched[0];
+                }
+                const masked = udec.exposePrivate
+                    ? (0, authorize_1.applyReadMaskOne)(responseDoc, udec.sensitiveMask)
+                    : (0, authorize_1.applyReadMaskOne)(responseDoc, udec.readMask);
+                return res.json(masked);
+            }
+            catch (error) {
+                if (error?.code === 'MODEL_REMOVED') {
+                    return res
+                        .status(410)
+                        .json({ error: true, message: error.message });
+                }
+                this.handleWriteError(error, res);
+            }
+        });
+        // -------------- DELETE --------------
+        this.router.delete(`${basePath}/:id`, mwDelete, async (req, res) => {
+            try {
+                const schema = this.getSchema(modelNameLC);
+                if (!schema.allowedMethods.delete) {
+                    return res
+                        .status(405)
+                        .json({ error: true, message: 'Method not allowed' });
+                }
+                const model = this.getModel(modelNameLC);
+                const docArr = await model.read({ id: req.params.id }, 1, 0, true);
+                const doc = docArr?.[0];
+                const ctx = ctxFromReq(req);
+                const schemaPolicy = {
+                    allowedMethods: schema.allowedMethods,
+                    access: schema.access,
+                };
+                const ddec = (0, authorize_1.authorize)(modelNameLC, 'delete', schemaPolicy, ctx, doc);
+                if (!ddec.allow)
+                    return res.status(403).json({ error: true, message: 'forbidden' });
+                const deletedRecord = await model.delete(req.params.id);
+                if (!deletedRecord) {
+                    return res
+                        .status(404)
+                        .json({ error: true, message: `${schema.modelName} not found` });
+                }
+                const masked = ddec.exposePrivate
+                    ? (0, authorize_1.applyReadMaskOne)(deletedRecord, ddec.sensitiveMask)
+                    : (0, authorize_1.applyReadMaskOne)(deletedRecord, ddec.readMask);
+                return res.json({
+                    success: true,
+                    message: `We have deleted the record successfully.`,
+                    data: masked,
+                });
+            }
+            catch (error) {
+                if (error?.code === 'MODEL_REMOVED')
+                    return res
+                        .status(410)
+                        .json({ error: true, message: error.message });
+                res.status(400).json({ error: true, message: error.message });
+            }
+        });
+    }
+    mountFindRoutes() {
+        if (this.findRoutesMounted)
+            return;
+        this.findRoutesMounted = true;
+        // ---------- helpers ----------
+        const parseSort = (expr) => {
+            if (!expr)
+                return;
+            const out = {};
+            for (const raw of expr
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean)) {
+                if (raw.startsWith('-'))
+                    out[raw.slice(1)] = -1;
+                else if (raw.startsWith('+'))
+                    out[raw.slice(1)] = 1;
+                else
+                    out[raw] = 1;
+            }
+            return Object.keys(out).length ? out : undefined;
+        };
+        const parseQuery = (req) => {
+            const limit = Math.min(parseInt(String(req.query.limit ?? '12'), 10) || 12, 100);
+            const page = Math.max(parseInt(String(req.query.page ?? '1'), 10) || 1, 1);
+            const skip = (page - 1) * limit;
+            const fields = String(req.query.fields ?? '')
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean);
+            const projection = fields.length
+                ? Object.fromEntries(fields.map((f) => [f, 1]))
+                : undefined;
+            const sort = parseSort(String(req.query.sort ?? '-createdAt'));
+            return { limit, page, skip, projection, sort };
+        };
+        // normalize possible values into an array of string ids
+        const extractIds = (val) => {
+            if (val == null)
+                return [];
+            const arr = Array.isArray(val) ? val : [val];
+            const toId = (v) => {
+                if (!v)
+                    return null;
+                if (typeof v === 'string')
+                    return v; // "6523..."
+                if (typeof v === 'number')
+                    return String(v);
+                if (typeof v === 'object') {
+                    if (typeof v.id === 'string')
+                        return v.id; // populated doc.id
+                    if (v._id && typeof v._id === 'string')
+                        return v._id;
+                    if (v._id && typeof v._id.toString === 'function')
+                        return v._id.toString();
+                }
+                return null;
+            };
+            return arr.map(toId).filter((s) => !!s);
+        };
+        // minimal ctx (same logic as setupRoutes)
+        const ctxFromReq = (req) => {
+            const raw = req.user?.role;
+            let roleStr = null;
+            if (typeof raw === 'string')
+                roleStr = raw;
+            else if (Array.isArray(raw)) {
+                const first = raw[0];
+                if (typeof first === 'string')
+                    roleStr = first;
+                else if (first &&
+                    typeof first === 'object' &&
+                    typeof first.name === 'string') {
+                    roleStr = first.name;
+                }
+            }
+            else if (raw &&
+                typeof raw === 'object' &&
+                typeof raw.name === 'string') {
+                roleStr = raw.name;
+            }
+            roleStr = roleStr ? roleStr.toLowerCase() : null;
+            return {
+                isAuthenticated: !!req.user,
+                role: roleStr,
+                userId: req.user?.id ?? req.user?._id ?? null,
+                isSuperadmin: roleStr === 'superadmin',
+                apiKeyOk: true,
+            };
+        };
+        // detect { type: "ObjectId"/"ref" } or array of { type: "ObjectId", ref }
+        const refInfoFromAttr = (attr) => {
+            if (!attr)
+                return null;
+            // array style from your JSON schema
+            if (Array.isArray(attr) && attr[0] && attr[0].ref) {
+                return { ref: String(attr[0].ref), isArray: true };
+            }
+            const a = Array.isArray(attr) ? attr?.[0] : attr;
+            const t = (typeof a?.type === 'string' ? a.type : String(a?.type || '')).toLowerCase();
+            if (a?.ref && (t === 'objectid' || t === 'ref')) {
+                return { ref: String(a.ref), isArray: false };
+            }
+            return null;
+        };
+        // try adapter.findOne with projection to avoid autopopulate; fallback to model.read
+        const safeGetContainerRefIDs = async (containerModelLC, id, refField) => {
+            const containerSchema = this.getSchema(containerModelLC);
+            const adapterAny = this.dbAdapter;
+            if (typeof adapterAny.findOne === 'function') {
+                try {
+                    // adapter should map id → db PK correctly (e.g., _id for Mongo)
+                    const raw = await adapterAny.findOne(containerSchema.modelName, { id }, { projection: { [refField]: 1 } });
+                    return extractIds(raw?.[refField]);
+                }
+                catch {
+                    // fall through
+                }
+            }
+            // fallback: BaseModel.read (may autopopulate, so we still normalize)
+            const containerDoc = (await this.getModel(containerModelLC).read({ id }, 1, 0, true))?.[0];
+            return extractIds(containerDoc?.[refField]);
+        };
+        // ---------- FORWARD ----------
+        // /find/:container/:refField/:id
+        this.router.get('/find/:container/:refField/:id', this.optionalAuthMiddleware, async (req, res) => {
+            try {
+                const containerLC = String(req.params.container || '').toLowerCase();
+                const refField = String(req.params.refField || '');
+                const id = String(req.params.id || '');
+                const schema = this.getSchema(containerLC); // ensure container exists
+                const attr = schema.attributes?.[refField];
+                const rinfo = refInfoFromAttr(attr);
+                if (!rinfo) {
+                    return res.status(400).json({
+                        error: true,
+                        message: 'refField is not a reference field',
+                    });
+                }
+                const { limit, page, skip, projection, sort } = parseQuery(req);
+                // policy on container read
+                const ctx = ctxFromReq(req);
+                const cPolicy = {
+                    allowedMethods: schema.allowedMethods,
+                    access: schema.access,
+                };
+                const cDec = (0, authorize_1.authorize)(containerLC, 'read', cPolicy, ctx);
+                if (!cDec.allow)
+                    return res.status(403).json({ error: true, message: 'forbidden' });
+                // get raw ids safely (no autopopulate dependency)
+                const ids = await safeGetContainerRefIDs(containerLC, id, refField);
+                const targetLC = String(rinfo.ref || '').toLowerCase();
+                const targetSchema = this.getSchema(targetLC);
+                const tPolicy = {
+                    allowedMethods: targetSchema.allowedMethods,
+                    access: targetSchema.access,
+                };
+                const tDec = (0, authorize_1.authorize)(targetLC, 'read', tPolicy, ctx);
+                if (!tDec.allow)
+                    return res.status(403).json({ error: true, message: 'forbidden' });
+                if (ids.length === 0) {
+                    return res.status(200).json({
+                        success: true,
+                        message: `Data fetched for ${targetSchema.modelName}`,
+                        data: [],
+                        pagination: { totalRows: 0, page, limit },
+                    });
+                }
+                const adapterAny = this.dbAdapter;
+                let items = [];
+                if (typeof adapterAny.findMany === 'function') {
+                    items = await adapterAny.findMany(targetSchema.modelName, { id: { $in: ids } }, // DB-agnostic: adapter maps id → PK
+                    { sort, skip, limit, projection });
+                }
+                else {
+                    // fallback (BaseModel.read); note: no projection/sort
+                    items = await this.getModel(targetLC).read({ id: { $in: ids } }, limit, skip, !!tDec.exposePrivate);
+                }
+                const masked = tDec.exposePrivate
+                    ? (0, authorize_1.applyReadMaskMany)(items, tDec.sensitiveMask)
+                    : (0, authorize_1.applyReadMaskMany)(items, tDec.readMask);
+                const totalRows = ids.length;
+                return res.status(200).json({
+                    success: true,
+                    message: `Data fetched for ${targetSchema.modelName}`,
+                    data: masked,
+                    pagination: { totalRows, page, limit },
+                });
+            }
+            catch (err) {
+                if (err?.code === 'MODEL_REMOVED') {
+                    return res.status(410).json({ error: true, message: err.message });
+                }
+                return res
+                    .status(400)
+                    .json({ error: true, message: err?.message || 'Error' });
+            }
+        });
+        // ---------- REVERSE ----------
+        // /find/reverse/:target/:byField/:id
+        this.router.get('/find/reverse/:target/:byField/:id', this.optionalAuthMiddleware, async (req, res) => {
+            try {
+                const targetLC = String(req.params.target || '').toLowerCase();
+                const byField = String(req.params.byField || '');
+                const id = String(req.params.id || '');
+                const targetSchema = this.getSchema(targetLC);
+                const attr = targetSchema.attributes?.[byField];
+                const rinfo = refInfoFromAttr(attr);
+                if (!rinfo) {
+                    return res.status(400).json({
+                        error: true,
+                        message: 'byField is not a reference field',
+                    });
+                }
+                const { limit, page, skip, projection, sort } = parseQuery(req);
+                // policy on target read
+                const ctx = ctxFromReq(req);
+                const tPolicy = {
+                    allowedMethods: targetSchema.allowedMethods,
+                    access: targetSchema.access,
+                };
+                const tDec = (0, authorize_1.authorize)(targetLC, 'read', tPolicy, ctx);
+                if (!tDec.allow)
+                    return res.status(403).json({ error: true, message: 'forbidden' });
+                // reverse filter (DB-agnostic; adapter maps appropriately)
+                const filter = rinfo.isArray
+                    ? { [byField]: { $in: [id] } }
+                    : { [byField]: id };
+                const adapterAny = this.dbAdapter;
+                let items = [];
+                let totalRows = 0;
+                if (typeof adapterAny.findMany === 'function') {
+                    items = await adapterAny.findMany(targetSchema.modelName, filter, {
+                        sort,
+                        skip,
+                        limit,
+                        projection,
+                    });
+                    if (typeof adapterAny.count === 'function') {
+                        totalRows = await adapterAny.count(targetSchema.modelName, filter);
+                    }
+                    else {
+                        // fallback count
+                        const all = await this.getModel(targetLC).read(filter, 0, 0, !!tDec.exposePrivate);
+                        totalRows = all.length;
+                    }
+                }
+                else {
+                    // fallback (BaseModel.read); note: no projection/sort
+                    const all = await this.getModel(targetLC).read(filter, 0, 0, !!tDec.exposePrivate);
+                    totalRows = all.length;
+                    items = all.slice(skip, skip + limit);
+                }
+                const masked = tDec.exposePrivate
+                    ? (0, authorize_1.applyReadMaskMany)(items, tDec.sensitiveMask)
+                    : (0, authorize_1.applyReadMaskMany)(items, tDec.readMask);
+                return res.status(200).json({
+                    success: true,
+                    message: `Data fetched for ${targetSchema.modelName}`,
+                    data: masked,
+                    pagination: { totalRows, page, limit },
+                });
+            }
+            catch (err) {
+                if (err?.code === 'MODEL_REMOVED') {
+                    return res.status(410).json({ error: true, message: err.message });
+                }
+                return res
+                    .status(400)
+                    .json({ error: true, message: err?.message || 'Error' });
+            }
+        });
+        // keep 404 as last if needed
+        this.ensureNotFoundLast();
+    }
+    /** Mount generic file endpoints under this router */
+    setupFileRoutes() {
+        if (!this.fileStorage)
+            return;
+        const upload = (0, multer_1.default)({
+            storage: multer_1.default.memoryStorage(),
+            limits: { fileSize: 50 * 1024 * 1024, files: 20 }, // 50MB
+        });
+        // POST /files
+        this.router.post('/files', this.fileAuthMiddleware, upload.any(), async (req, res) => {
+            try {
+                const files = req.files ?? [];
+                if (!files.length) {
+                    return res
+                        .status(400)
+                        .json({ error: true, message: 'No files uploaded' });
+                }
+                const results = await Promise.all(files.map(async (f) => {
+                    const folder = this.shortFolder(); // uploads/YYYY/MM/DD
+                    const ext = (f.originalname.match(/\.([A-Za-z0-9]{1,8})$/)?.[1] ??
+                        (0, filename_1.extFromMime)(f.mimetype) ??
+                        'bin').toLowerCase();
+                    const key = `${folder}/${this.shortUid()}.${ext}`;
+                    const out = await this.fileStorage.upload({
+                        key,
+                        body: f.buffer,
+                        contentType: f.mimetype,
+                        metadata: { originalName: f.originalname || '' },
+                    });
+                    return {
+                        provider: out.provider,
+                        bucket: out.bucket,
+                        key: out.key,
+                        url: out.url,
+                        etag: out.etag,
+                        contentType: out.contentType,
+                        size: out.size,
+                        metadata: out.metadata,
+                        originalName: f.originalname,
+                    };
+                }));
+                return res.json({
+                    success: true,
+                    message: 'Files uploaded successfully',
+                    data: results,
+                });
+            }
+            catch (err) {
+                return res
+                    .status(400)
+                    .json({ error: true, message: err?.message ?? 'Upload failed' });
+            }
+        });
+        // DELETE /files/:key(*)
+        this.router.delete('/files/:key(*)', this.fileAuthMiddleware, async (req, res) => {
+            try {
+                const key = String(req.params.key || '');
+                if (!key) {
+                    return res
+                        .status(400)
+                        .json({ error: true, message: 'Key is required' });
+                }
+                const { deleted } = await this.fileStorage.delete(key);
+                return res.json({
+                    success: true,
+                    message: deleted ? 'File deleted' : 'Delete attempted',
+                    key,
+                    deleted,
+                });
+            }
+            catch (err) {
+                return res
+                    .status(400)
+                    .json({ error: true, message: err?.message ?? 'Delete failed' });
+            }
+        });
+    }
+    /** uploads/YYYY/MM/DD */
+    shortFolder() {
+        const d = new Date();
+        const y = d.getFullYear();
+        const m = String(d.getMonth() + 1).padStart(2, '0');
+        const day = String(d.getDate()).padStart(2, '0');
+        return `uploads/${y}/${m}/${day}`;
+    }
+    /** small, URL-safe uid */
+    shortUid() {
+        return (Date.now().toString(36) + Math.random().toString(36).slice(2, 6)).toLowerCase();
+    }
+    normalizeAttrType(attr) {
+        const a = Array.isArray(attr) ? attr?.[0] : attr;
+        let t = a?.type ?? a;
+        if (typeof t === 'function' && t.name)
+            t = t.name;
+        if (t && typeof t === 'object' && 'name' in t)
+            t = t.name;
+        if (typeof t === 'string')
+            t = t.toLowerCase();
+        if (t === 'bool')
+            t = 'boolean';
+        if (t === 'objectid' || t === 'oid' || t === 'ref')
+            t = 'objectid';
+        return String(t || '');
+    }
+    pickAuthFor(action, modelNameLC) {
+        try {
+            const schema = this.getSchema(modelNameLC);
+            const access = schema.access || {};
+            const publicRule = access?.public?.[action];
+            if (publicRule === true)
+                return this.optionalAuthMiddleware;
+            if (publicRule === false)
+                return this.authenticateMiddleware;
+            return action === 'read'
+                ? this.optionalAuthMiddleware
+                : this.authenticateMiddleware;
+        }
+        catch {
+            return action === 'read'
+                ? this.optionalAuthMiddleware
+                : this.authenticateMiddleware;
+        }
+    }
+    getUserRoleFromReq(req) {
+        const r = req.user?.role;
+        return typeof r === 'string'
+            ? r
+            : typeof r?.name === 'string'
+                ? r.name
+                : null;
+    }
+    setupAuthRoutes() {
+        const basePath = '/auth/users';
+        // ---- REGISTER ----
+        this.router.post(`${basePath}/register`, this.apiKeyMiddleware, async (req, res) => {
+            try {
+                let { email, username, password, ...rest } = req.body;
+                // Basic password policy (keep minimal, align with change-password)
+                if (String(password).length < 8) {
+                    return res.status(400).json({
+                        error: true,
+                        message: 'Password must be at least 8 characters long',
+                    });
+                }
+                const userModel = this.getModel('users');
+                const usersSchema = this.getSchema('users');
+                // Normalize unique identifiers
+                if (email)
+                    email = String(email).trim().toLowerCase();
+                if (username)
+                    username = String(username).trim();
+                // Prevent client from sending password in plain; we will hash below
+                const data = { ...rest };
+                if (email)
+                    data.email = email;
+                if (username)
+                    data.username = username;
+                // Provide a sensible default status so login works immediately
+                if (data.status == null)
+                    data.status = 'active';
+                // Validate required fields against schema (create mode)
+                if (usersSchema) {
+                    const missing = this.validateRequiredFields(usersSchema, {
+                        ...data,
+                        password,
+                    });
+                    if (missing.length > 0) {
+                        return res.status(400).json({
+                            error: true,
+                            message: `Missing required field(s): ${missing.join(', ')}`,
+                        });
+                    }
+                    // Check unique constraints before writing
+                    const conflicts = await this.checkUniqueFields(usersSchema, data);
+                    if (conflicts && conflicts.length) {
+                        return res.status(400).json({
+                            error: true,
+                            message: `Duplicate value for field(s): ${conflicts.join(', ')}`,
+                        });
+                    }
+                }
+                // Hash password
+                const salt = await bcrypt_1.default.genSalt(10);
+                const hashed = await bcrypt_1.default.hash(String(password) + this.jwtSecret, salt);
+                data.password = hashed;
+                // Create user
+                const created = await userModel.create(data);
+                // Prepare response: generate token and strip password
+                const roleName = (await this.normalizeRoleName(created.role)) ?? '';
+                const token = jsonwebtoken_1.default.sign({ id: created.id, role: roleName }, this.jwtSecret, {
+                    expiresIn: '7days',
+                });
+                delete created.password;
+                return res.json({
+                    success: true,
+                    message: 'Registration successful.',
+                    data: { token, user: created },
+                });
+            }
+            catch (error) {
+                this.handleWriteError(error, res);
+            }
+        });
+        // ---- LOGIN ----
+        this.router.post(`${basePath}/login`, this.apiKeyMiddleware, async (req, res) => {
+            let { email, username, password } = req.body;
+            if ((!email && !username) || !password) {
+                return res.status(400).json({
+                    error: true,
+                    message: 'Email/username and password are required',
+                });
+            }
+            try {
+                const userModel = this.getModel('users');
+                const findBy = email
+                    ? { email: String(email).trim().toLowerCase() }
+                    : { username: String(username).trim() };
+                const users = await userModel.read(findBy, 1, 0, true);
+                const user = users?.[0];
+                if (!user)
+                    return res
+                        .status(400)
+                        .json({ error: true, message: 'Invalid credentials' });
+                const hashedPassword = user.password;
+                if (!hashedPassword)
+                    return res
+                        .status(400)
+                        .json({ error: true, message: 'User password not set' });
+                const isMatch = await bcrypt_1.default.compare(String(password) + this.jwtSecret, hashedPassword);
+                if (!isMatch)
+                    return res
+                        .status(400)
+                        .json({ error: true, message: 'Invalid credentials' });
+                const status = user.status;
+                if (status && status !== 'active') {
+                    const msg = status === 'pending'
+                        ? 'Your account is awaiting approval.'
+                        : 'Your account is suspended.';
+                    return res.status(403).json({ error: true, message: msg });
+                }
+                const roleName = (await this.normalizeRoleName(user.role)) ?? '';
+                const token = jsonwebtoken_1.default.sign({ id: user.id, role: roleName }, // normalize here
+                this.jwtSecret, { expiresIn: '7days' });
+                delete user.password;
+                res.json({
+                    success: true,
+                    message: 'You are successfully logged in.',
+                    data: { token, user },
+                });
+            }
+            catch (error) {
+                if (error?.code === 'MODEL_REMOVED')
+                    return res
+                        .status(410)
+                        .json({ error: true, message: error.message });
+                res.status(500).json({ error: true, message: error.message });
+            }
+        });
+        // ---- ME ----
+        this.router.get(`${basePath}/me`, this.apiKeyMiddleware, this.authenticateMiddleware.bind(this), async (req, res) => {
+            try {
+                const userId = req.user?.id ?? req.user?._id ?? null;
+                if (!userId) {
+                    return res
+                        .status(401)
+                        .json({ error: true, message: 'Not authenticated' });
+                }
+                const userModel = this.getModel('users');
+                const arr = await userModel.read({ id: userId }, 1, 0, true);
+                const user = arr?.[0];
+                if (!user) {
+                    return res
+                        .status(404)
+                        .json({ error: true, message: 'User not found' });
+                }
+                delete user.password;
+                return res.json({ success: true, data: user });
+            }
+            catch (error) {
+                return res
+                    .status(400)
+                    .json({ error: true, message: error?.message || 'Error' });
+            }
+        });
+        // ---- CHANGE PASSWORD ----
+        this.router.post(`${basePath}/change-password`, this.apiKeyMiddleware, this.authenticateMiddleware.bind(this), async (req, res) => {
+            try {
+                const { oldPassword, newPassword } = req.body;
+                if (!oldPassword || !newPassword) {
+                    return res.status(400).json({
+                        error: true,
+                        message: 'oldPassword and newPassword are required',
+                    });
+                }
+                // basic policy (customize as desired)
+                if (String(newPassword).length < 8) {
+                    return res.status(400).json({
+                        error: true,
+                        message: 'New password must be at least 8 characters long',
+                    });
+                }
+                if (String(newPassword) === String(oldPassword)) {
+                    return res.status(400).json({
+                        error: true,
+                        message: 'New password must be different from old password',
+                    });
+                }
+                const userId = req.user?.id ?? req.user?._id ?? null;
+                if (!userId) {
+                    return res
+                        .status(401)
+                        .json({ error: true, message: 'Not authenticated' });
+                }
+                const userModel = this.getModel('users');
+                const arr = await userModel.read({ id: userId }, 1, 0, true);
+                const user = arr?.[0];
+                if (!user) {
+                    return res
+                        .status(404)
+                        .json({ error: true, message: 'User not found' });
+                }
+                const storedHash = user.password;
+                if (!storedHash) {
+                    return res
+                        .status(400)
+                        .json({ error: true, message: 'User password not set' });
+                }
+                const match = await bcrypt_1.default.compare(String(oldPassword) + this.jwtSecret, storedHash);
+                if (!match) {
+                    return res
+                        .status(400)
+                        .json({ error: true, message: 'Old password is incorrect' });
+                }
+                const salt = await bcrypt_1.default.genSalt(10);
+                const newHash = await bcrypt_1.default.hash(String(newPassword) + this.jwtSecret, salt);
+                await userModel.update(user.id, { password: newHash });
+                return res.json({
+                    success: true,
+                    message: 'Password changed successfully.',
+                });
+            }
+            catch (error) {
+                res
+                    .status(400)
+                    .json({ error: true, message: error?.message || 'Error' });
+            }
+        });
+        // ---- FORGOT PASSWORD ----
+        const forgotPasswordHandler = async (req, res) => {
+            try {
+                const { email } = (req.body || {});
+                if (!email || !String(email).trim()) {
+                    return res
+                        .status(400)
+                        .json({ error: true, message: 'Email is required' });
+                }
+                // Normalize and (optionally) look up the user. We do NOT reveal whether the user exists.
+                const normalizedEmail = String(email).trim().toLowerCase();
+                try {
+                    const userModel = this.getModel('users');
+                    // Best-effort read; ignore result to avoid leaking existence
+                    await userModel.read({ email: normalizedEmail }, 1, 0, true);
+                }
+                catch {
+                    // Ignore lookup errors deliberately
+                }
+                // In a real implementation, generate a reset token, store it with expiry, and send an email.
+                // Here we return a generic success message so the React app flow can proceed.
+                return res.json({
+                    success: true,
+                    message: 'If an account exists, reset instructions have been sent.',
+                });
+            }
+            catch (error) {
+                return res
+                    .status(400)
+                    .json({ error: true, message: error?.message || 'Error' });
+            }
+        };
+        // Primary (plural) route under /auth/users
+        this.router.post(`${basePath}/forgot-password`, this.apiKeyMiddleware, forgotPasswordHandler);
+        // NOTE: All Users/Roles CRUD routes are handled by generic routes.
+    }
+    // ---------------- Common helpers ----------------
+    /**
+     * Validate required fields.
+     * - create: field must exist and be non-empty (not null/undefined/'').
+     * - update: only validate fields that are explicitly present in the payload;
+     *           absence means "unchanged".
+     */
+    validateRequiredFields(schema, payload, mode = 'create') {
+        const missing = [];
+        const isEmpty = (v) => v === undefined ||
+            v === null ||
+            (typeof v === 'string' && v.trim() === '');
+        for (const [key, attribute] of Object.entries(schema.attributes)) {
+            const req = attribute && !Array.isArray(attribute) && attribute.required;
+            if (!req)
+                continue;
+            if (mode === 'create') {
+                if (isEmpty(payload[key]))
+                    missing.push(key);
+            }
+            else {
+                // update → only if field is being sent AND is empty
+                if (Object.prototype.hasOwnProperty.call(payload, key) &&
+                    isEmpty(payload[key])) {
+                    missing.push(key);
+                }
+            }
+        }
+        return missing;
+    }
+    handleWriteError(error, res) {
+        if (error?.code === 'MODEL_REMOVED') {
+            res.status(410).json({ error: true, message: error.message });
+            return;
+        }
+        if (error?.code === 11000) {
+            const field = Object.keys(error.keyPattern || {})[0];
+            res
+                .status(400)
+                .json({ error: true, message: `Duplicate value for field: ${field}` });
+        }
+        else {
+            res.status(400).json({ error: true, message: error?.message || 'Error' });
+        }
+    }
+    setupNotFoundMiddleware() {
+        if (!this.notFoundHandler) {
+            this.notFoundHandler = (req, res) => {
+                Logger_1.default.warn('apiRouter', `API route not found: ${req.originalUrl}`);
+                res.status(404).json({
+                    error: 'API route not found',
+                    path: req.originalUrl,
+                    method: req.method,
+                });
+            };
+        }
+        this.ensureNotFoundLast();
+    }
+    ensureNotFoundLast() {
+        if (!this.notFoundHandler)
+            return;
+        // @ts-ignore
+        this.router.stack = this.router.stack.filter((layer) => layer?.handle !== this.notFoundHandler);
+        this.router.use('*', this.notFoundHandler);
+    }
+    async validateRoleValue(roleValue) {
+        const roleModel = this.models['role'];
+        if (!roleModel)
+            return false;
+        const roles = await roleModel.read({ name: roleValue }, 1, 0);
+        return roles.length > 0;
+    }
+    async checkUniqueFields(schema, data, excludeId) {
+        const uniqueFields = Object.entries(schema.attributes)
+            .filter(([_, attr]) => attr.unique)
+            .map(([key]) => key);
+        const conflictingFields = [];
+        for (const field of uniqueFields) {
+            if (data[field] !== undefined) {
+                const query = { [field]: data[field] };
+                if (excludeId)
+                    query.id = { $ne: excludeId };
+                const existingRecords = await this.getModel(schema.modelName.toLowerCase()).read(query);
+                if (existingRecords.length > 0)
+                    conflictingFields.push(field);
+            }
+        }
+        return conflictingFields.length > 0 ? conflictingFields : null;
+    }
+}
+exports.APIRouter = APIRouter;