@quiqflow-org/quiqflow-multi-tenants-utils 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,114 @@
+---
+noteId: "4752778074a811f081017bbaf3f56380"
+tags: []
+
+---
+
+# Contributing to Quiqflow common orm
+
+We are thrilled that you'd like to contribute to this project! This document provides guidelines for contributing effectively and collaboratively.
+
+---
+
+## How to Contribute
+
+### 1. Report Issues
+
+If you encounter a bug, have a feature request, or need clarification, please [open an issue](https://github.com/[REPO]/issues).
+
+**When creating an issue:**
+
+- Use the provided issue template.
+- Provide a clear, descriptive title.
+- Include steps to reproduce, if applicable.
+- Add screenshots or logs if necessary.
+
+---
+
+### 2. Create Pull Requests (PRs)
+
+#### Steps for Submitting a PR
+
+1. **Fork the repository** and create a new branch:
+
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** while following the project's coding standards.
+3. **Test your changes** thoroughly.
+4. **Commit your changes**:
+
+   ```bash
+   git commit -m "feat: Add description of the feature"
+   ```
+
+   Follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format.
+5. **Push your branch** to your fork:
+
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+6. **Open a Pull Request**:
+   - Provide a descriptive title and summary.
+   - Link any related issues (e.g., `Fixes #123`).
+   - Follow the PR template.
+
+#### Code Review
+
+- PRs will be reviewed by maintainers.
+- Address requested changes promptly.
+- Once approved, your changes will be merged.
+
+---
+
+## Code Guidelines
+
+- Follow the coding standards defined in the [STYLE_GUIDE.md](./STYLE_GUIDE.md).
+- Use meaningful variable and function names.
+- Write comments where necessary to explain complex logic.
+- Ensure that your code is tested and linted:
+
+  ```bash
+  yarn lint
+  yarn test
+  ```
+
+---
+
+## Branching Strategy
+
+- `main`: Stable production-ready code.
+- `develop`: Latest development code.
+- `feature/*`: Features or enhancements.
+- `bugfix/*`: Bug fixes.
+
+---
+
+## Commit Message Format
+
+Use the following structure for commit messages:
+
+```
+<type>: <short description>
+
+[Optional body explaining what and why.]
+```
+
+**Types:**
+
+- `feat`: New features
+- `fix`: Bug fixes
+- `docs`: Documentation updates
+- `style`: Code style improvements
+- `refactor`: Code changes without changing functionality
+- `test`: Adding or updating tests
+
+---
+
+## Questions
+
+If you have any questions, feel free to reach out by [creating an issue](https://github.com/quiqflow/quiqflow-multi-tenants-utils/issues) or contacting [mohammad@quiqflow.com].
+
+Thank you for contributing to [Quiqflow]!

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Quiqflow-2.0
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/SchemaResolutionService.d.ts

@@ -0,0 +1,12 @@
+import { TenantCache } from "./cache";
+import { AdminConnectionLike } from "./types";
+export declare class SchemaResolutionService {
+    private admin;
+    private cache;
+    private static readonly MAX_RETRIES;
+    constructor(adminConnection: AdminConnectionLike, cache?: TenantCache);
+    preloadAllTenants(): Promise<void>;
+    private isActive;
+    resolveSchemaForTenant(tenantId: number): Promise<string>;
+}
+//# sourceMappingURL=SchemaResolutionService.d.ts.map

package/dist/SchemaResolutionService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchemaResolutionService.d.ts","sourceRoot":"","sources":["../src/SchemaResolutionService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAE,mBAAmB,EAAgB,MAAM,SAAS,CAAC;AAE5D,qBAAa,uBAAuB;IAClC,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAK;gBAGtC,eAAe,EAAE,mBAAmB,EACpC,KAAK,GAAE,WAAkC;IAMrC,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAMxC,OAAO,CAAC,QAAQ;IAMV,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAsBhE"}

package/dist/SchemaResolutionService.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaResolutionService = void 0;
+const cache_1 = require("./cache");
+class SchemaResolutionService {
+    constructor(adminConnection, cache = cache_1.TenantCache.instance) {
+        this.admin = adminConnection;
+        this.cache = cache;
+    }
+    async preloadAllTenants() {
+        const tenants = await this.admin.listAllTenants();
+        for (const t of tenants)
+            if (t.schemaName)
+                this.cache.set(String(t.tenantId), t.schemaName);
+    }
+    isActive(tenant) {
+        if (!tenant)
+            return false;
+        if (!tenant.status)
+            return true;
+        return tenant.status.toLowerCase() === "active";
+    }
+    async resolveSchemaForTenant(tenantId) {
+        const cacheKey = String(tenantId);
+        const cached = this.cache.get(cacheKey);
+        if (cached)
+            return cached;
+        let attempt = 0;
+        let lastError;
+        while (attempt <= SchemaResolutionService.MAX_RETRIES) {
+            try {
+                const record = await this.admin.getTenantById(tenantId);
+                if (!record || !record.schemaName)
+                    throw new Error("Tenant not found");
+                if (!this.isActive(record))
+                    throw new Error("Tenant inactive");
+                this.cache.set(cacheKey, record.schemaName);
+                return record.schemaName;
+            }
+            catch (e) {
+                lastError = e;
+                attempt++;
+                if (attempt > SchemaResolutionService.MAX_RETRIES)
+                    break;
+                await new Promise((r) => setTimeout(r, 50 * attempt));
+            }
+        }
+        throw lastError || new Error("Failed resolving tenant schema");
+    }
+}
+exports.SchemaResolutionService = SchemaResolutionService;
+SchemaResolutionService.MAX_RETRIES = 2;

package/dist/TenantConnectionManager.d.ts

@@ -0,0 +1,18 @@
+import { TenantConnectionManagerOptions } from "./types";
+export declare class TenantConnectionManager {
+    private static _instance;
+    private connections;
+    private factory;
+    private authenticate?;
+    private constructor();
+    static init(opts: TenantConnectionManagerOptions): TenantConnectionManager;
+    static getInstance(): TenantConnectionManager;
+    getConnection(schemaName: string): Promise<any>;
+    /**
+     * Efficiently ensure schema isolation for reused connections
+     * Fixes Sequelize model schema caching issues in multi-tenant environment
+     */
+    private ensureSchemaIsolation;
+    closeAll(): Promise<void>;
+}
+//# sourceMappingURL=TenantConnectionManager.d.ts.map

package/dist/TenantConnectionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TenantConnectionManager.d.ts","sourceRoot":"","sources":["../src/TenantConnectionManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,8BAA8B,EAAE,MAAM,SAAS,CAAC;AAEzD,qBAAa,uBAAuB;IAClC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAwC;IAChE,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,OAAO,CAA4C;IAC3D,OAAO,CAAC,YAAY,CAAC,CAAiD;IAEtE,OAAO;IAKP,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,8BAA8B,GAAG,uBAAuB;IAK1E,MAAM,CAAC,WAAW,IAAI,uBAAuB;IAMvC,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAgBrD;;;OAGG;YACW,qBAAqB;IAgB7B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAUhC"}

package/dist/TenantConnectionManager.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TenantConnectionManager = void 0;
+class TenantConnectionManager {
+    constructor(opts) {
+        this.connections = new Map();
+        this.factory = opts.factory;
+        this.authenticate = opts.authenticate;
+    }
+    static init(opts) {
+        if (!this._instance)
+            this._instance = new TenantConnectionManager(opts);
+        return this._instance;
+    }
+    static getInstance() {
+        if (!this._instance)
+            throw new Error("TenantConnectionManager not initialized");
+        return this._instance;
+    }
+    async getConnection(schemaName) {
+        if (!this.connections.has(schemaName)) {
+            const orm = await this.factory({ schemaName });
+            if (this.authenticate)
+                await this.authenticate(orm);
+            this.connections.set(schemaName, orm);
+        }
+        const orm = this.connections.get(schemaName);
+        // CRITICAL: Ensure schema isolation when reusing connections
+        // This fixes Sequelize model schema caching issues in multi-tenant environment
+        await this.ensureSchemaIsolation(orm, schemaName);
+        return orm;
+    }
+    /**
+     * Efficiently ensure schema isolation for reused connections
+     * Fixes Sequelize model schema caching issues in multi-tenant environment
+     */
+    async ensureSchemaIsolation(orm, expectedSchema) {
+        // Set search_path for this connection (lightweight operation)
+        await orm.sequelize.query(`SET search_path TO "${expectedSchema}", public`);
+        // Force all models to use the correct schema
+        // Sequelize caches schema names in model definitions, so we need to update them
+        Object.values(orm.sequelize.models).forEach((model) => {
+            if (model._schema !== expectedSchema) {
+                model._schema = expectedSchema;
+            }
+        });
+    }
+    async closeAll() {
+        for (const [, orm] of this.connections) {
+            if (orm && typeof orm.close === "function") {
+                try {
+                    await orm.close();
+                }
+                catch { }
+            }
+        }
+        this.connections.clear();
+    }
+}
+exports.TenantConnectionManager = TenantConnectionManager;
+TenantConnectionManager._instance = null;

package/dist/authHelpers.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Authentication and authorization middleware helpers
+ * @author QuiqFlow Team
+ */
+import { Response } from "express";
+import { TenantContextAugmentedRequest } from "./types";
+/**
+ * Ensure user has admin role or send error response
+ * @param req Express request with tenant context
+ * @param res Express response
+ * @returns boolean indicating if validation passed
+ */
+export declare const ensureAdmin: (req: TenantContextAugmentedRequest, res: Response) => boolean;
+/**
+ * Ensure user has specific role or send error response
+ * @param req Express request with tenant context
+ * @param res Express response
+ * @param requiredRole Required role string
+ * @returns boolean indicating if validation passed
+ */
+export declare const ensureRole: (req: TenantContextAugmentedRequest, res: Response, requiredRole: string) => boolean;
+/**
+ * Ensure user has any of the specified roles
+ * @param req Express request with tenant context
+ * @param res Express response
+ * @param allowedRoles Array of allowed role strings
+ * @returns boolean indicating if validation passed
+ */
+export declare const ensureAnyRole: (req: TenantContextAugmentedRequest, res: Response, allowedRoles: string[]) => boolean;
+/**
+ * Ensure user is authenticated (has user object)
+ * @param req Express request with tenant context
+ * @param res Express response
+ * @returns boolean indicating if validation passed
+ */
+export declare const ensureAuthenticated: (req: TenantContextAugmentedRequest, res: Response) => boolean;
+/**
+ * Ensure tenant context is properly set
+ * @param req Express request with tenant context
+ * @param res Express response
+ * @returns boolean indicating if validation passed
+ */
+export declare const ensureTenantContext: (req: TenantContextAugmentedRequest, res: Response) => boolean;
+//# sourceMappingURL=authHelpers.d.ts.map

package/dist/authHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authHelpers.d.ts","sourceRoot":"","sources":["../src/authHelpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,6BAA6B,EAAE,MAAM,SAAS,CAAC;AAGxD;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GACtB,KAAK,6BAA6B,EAClC,KAAK,QAAQ,KACZ,OAaF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GACrB,KAAK,6BAA6B,EAClC,KAAK,QAAQ,EACb,cAAc,MAAM,KACnB,OAeF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GACxB,KAAK,6BAA6B,EAClC,KAAK,QAAQ,EACb,cAAc,MAAM,EAAE,KACrB,OAgBF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAC9B,KAAK,6BAA6B,EAClC,KAAK,QAAQ,KACZ,OAOF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAC9B,KAAK,6BAA6B,EAClC,KAAK,QAAQ,KACZ,OAcF,CAAC"}

package/dist/authHelpers.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * @fileoverview Authentication and authorization middleware helpers
+ * @author QuiqFlow Team
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureTenantContext = exports.ensureAuthenticated = exports.ensureAnyRole = exports.ensureRole = exports.ensureAdmin = void 0;
+const tenantHelpers_1 = require("./tenantHelpers");
+/**
+ * Ensure user has admin role or send error response
+ * @param req Express request with tenant context
+ * @param res Express response
+ * @returns boolean indicating if validation passed
+ */
+const ensureAdmin = (req, res) => {
+    if (!req.user) {
+        res.status(401).json({ message: "Authentication required" });
+        return false;
+    }
+    if (!(0, tenantHelpers_1.isAdmin)(req)) {
+        res.status(403).json({ message: "Admin access required" });
+        return false;
+    }
+    console.log("User is admin:", req.user.role);
+    return true;
+};
+exports.ensureAdmin = ensureAdmin;
+/**
+ * Ensure user has specific role or send error response
+ * @param req Express request with tenant context
+ * @param res Express response
+ * @param requiredRole Required role string
+ * @returns boolean indicating if validation passed
+ */
+const ensureRole = (req, res, requiredRole) => {
+    if (!req.user) {
+        res.status(401).json({ message: "Authentication required" });
+        return false;
+    }
+    if (!(0, tenantHelpers_1.hasRole)(req, requiredRole)) {
+        res.status(403).json({
+            message: `${requiredRole} access required`,
+            userRole: req.user.role,
+        });
+        return false;
+    }
+    return true;
+};
+exports.ensureRole = ensureRole;
+/**
+ * Ensure user has any of the specified roles
+ * @param req Express request with tenant context
+ * @param res Express response
+ * @param allowedRoles Array of allowed role strings
+ * @returns boolean indicating if validation passed
+ */
+const ensureAnyRole = (req, res, allowedRoles) => {
+    if (!req.user) {
+        res.status(401).json({ message: "Authentication required" });
+        return false;
+    }
+    if (!(0, tenantHelpers_1.hasAnyRole)(req, allowedRoles)) {
+        res.status(403).json({
+            message: `Access denied. Required roles: ${allowedRoles.join(", ")}`,
+            userRole: req.user.role,
+            allowedRoles,
+        });
+        return false;
+    }
+    return true;
+};
+exports.ensureAnyRole = ensureAnyRole;
+/**
+ * Ensure user is authenticated (has user object)
+ * @param req Express request with tenant context
+ * @param res Express response
+ * @returns boolean indicating if validation passed
+ */
+const ensureAuthenticated = (req, res) => {
+    if (!req.user || !req.user.id) {
+        res.status(401).json({ message: "Authentication required" });
+        return false;
+    }
+    return true;
+};
+exports.ensureAuthenticated = ensureAuthenticated;
+/**
+ * Ensure tenant context is properly set
+ * @param req Express request with tenant context
+ * @param res Express response
+ * @returns boolean indicating if validation passed
+ */
+const ensureTenantContext = (req, res) => {
+    if (!req.schemaName) {
+        res.status(400).json({ message: "Tenant context missing" });
+        return false;
+    }
+    if (!req.tenantDb) {
+        res
+            .status(500)
+            .json({ message: "Tenant database connection not available" });
+        return false;
+    }
+    return true;
+};
+exports.ensureTenantContext = ensureTenantContext;

package/dist/cache.d.ts

@@ -0,0 +1,10 @@
+export declare class TenantCache {
+    private static _instance;
+    private cache;
+    private constructor();
+    static get instance(): TenantCache;
+    get(key: string): string | undefined;
+    set(key: string, value: string): void;
+    keys(): string[];
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAEA,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAC,SAAS,CAA4B;IACpD,OAAO,CAAC,KAAK,CAAY;IAEzB,OAAO;IAIP,MAAM,KAAK,QAAQ,IAAI,WAAW,CAGjC;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIpC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAIrC,IAAI,IAAI,MAAM,EAAE;CAGjB"}

package/dist/cache.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TenantCache = void 0;
+const node_cache_1 = __importDefault(require("node-cache"));
+class TenantCache {
+    constructor() {
+        this.cache = new node_cache_1.default({ stdTTL: 0, useClones: false, checkperiod: 0 });
+    }
+    static get instance() {
+        if (!this._instance)
+            this._instance = new TenantCache();
+        return this._instance;
+    }
+    get(key) {
+        return this.cache.get(key);
+    }
+    set(key, value) {
+        this.cache.set(key, value);
+    }
+    keys() {
+        return this.cache.keys();
+    }
+}
+exports.TenantCache = TenantCache;
+TenantCache._instance = null;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./types";
+export * from "./cache";
+export * from "./TenantConnectionManager";
+export * from "./SchemaResolutionService";
+export * from "./middleware";
+export * from "./tenantHelpers";
+export * from "./authHelpers";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./cache"), exports);
+__exportStar(require("./TenantConnectionManager"), exports);
+__exportStar(require("./SchemaResolutionService"), exports);
+__exportStar(require("./middleware"), exports);
+__exportStar(require("./tenantHelpers"), exports);
+__exportStar(require("./authHelpers"), exports);

package/dist/middleware.d.ts

@@ -0,0 +1,4 @@
+import { NextFunction, Response } from "express";
+import { CreateTenantMiddlewareOptions, TenantContextAugmentedRequest } from "./types";
+export declare const createTenantMiddleware: (options: CreateTenantMiddlewareOptions) => (req: TenantContextAugmentedRequest, res: Response, next: NextFunction) => Promise<void>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEjD,OAAO,EACL,6BAA6B,EAC7B,6BAA6B,EAC9B,MAAM,SAAS,CAAC;AAIjB,eAAO,MAAM,sBAAsB,GACjC,SAAS,6BAA6B,MAWpC,KAAK,6BAA6B,EAClC,KAAK,QAAQ,EACb,MAAM,YAAY,KACjB,OAAO,CAAC,IAAI,CA2BhB,CAAC"}

package/dist/middleware.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTenantMiddleware = void 0;
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+const defaultDecode = (token) => jsonwebtoken_1.default.decode(token);
+const createTenantMiddleware = (options) => {
+    const { schemaResolutionService, connectionManager, decodeJwt = defaultDecode, headerTenantKey = "x-tenant-id", allowOptional = false, } = options;
+    return async (req, res, next) => {
+        try {
+            const tenantData = extractTenant(req, decodeJwt, headerTenantKey);
+            if (!(tenantData === null || tenantData === void 0 ? void 0 : tenantData.tenantId)) {
+                if (allowOptional)
+                    return next();
+                res.status(400).json({ error: "Tenant ID is required." });
+                return;
+            }
+            const numericTenantId = parseInt(tenantData.tenantId, 10);
+            if (isNaN(numericTenantId) || numericTenantId <= 0) {
+                res.status(400).json({ error: "Invalid tenant ID format." });
+                return;
+            }
+            const schemaName = await schemaResolutionService.resolveSchemaForTenant(numericTenantId);
+            const tenantDb = await connectionManager.getConnection(schemaName);
+            req.tenantId = tenantData.tenantId;
+            req.schemaName = schemaName;
+            if (tenantData.user)
+                req.user = tenantData.user;
+            req.tenantDb = tenantDb;
+            next();
+        }
+        catch (e) {
+            console.error("[createTenantMiddleware] error", e);
+            res.status(400).json({ error: "Failed to resolve tenant schema." });
+        }
+    };
+};
+exports.createTenantMiddleware = createTenantMiddleware;
+const extractTenant = (req, decodeJwt, headerTenantKey) => {
+    var _a, _b, _c, _d;
+    const authHeader = (_a = req.headers) === null || _a === void 0 ? void 0 : _a.authorization;
+    if (authHeader === null || authHeader === void 0 ? void 0 : authHeader.startsWith("Bearer ")) {
+        const token = authHeader.substring(7);
+        const decoded = decodeJwt(token);
+        if (decoded === null || decoded === void 0 ? void 0 : decoded.tenantId) {
+            return {
+                tenantId: String(decoded.tenantId),
+                user: {
+                    tenantId: decoded.tenantId,
+                    userId: decoded.userId || decoded.id,
+                    ...decoded,
+                },
+            };
+        }
+    }
+    const headerTenant = (_b = req.headers) === null || _b === void 0 ? void 0 : _b[headerTenantKey];
+    if (headerTenant)
+        return { tenantId: String(headerTenant) };
+    if ((_c = req.query) === null || _c === void 0 ? void 0 : _c.tenantId)
+        return { tenantId: String(req.query.tenantId) };
+    if ((_d = req.body) === null || _d === void 0 ? void 0 : _d.tenantId)
+        return { tenantId: String(req.body.tenantId) };
+    return null;
+};

package/dist/tenantHelpers.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Tenant context helper functions for multi-tenant applications
+ * @author QuiqFlow Team
+ */
+import { TenantContextAugmentedRequest } from "./types";
+/**
+ * Returns resolved schema name from tenant middleware context.
+ */
+export declare const getSchemaName: (req: TenantContextAugmentedRequest) => string;
+/**
+ * Extract authenticated user id from request (supports id, sub, userId fields).
+ */
+export declare const getTenantUserId: (req: TenantContextAugmentedRequest) => number;
+/**
+ * Get tenant ID from request context
+ */
+export declare const getTenantId: (req: TenantContextAugmentedRequest) => string | number;
+/**
+ * Simple no-op validator kept for compatibility with previous validateUserSchema guard.
+ * Always returns true now that schema resolution is mandatory via middleware.
+ * For response-aware validation, use ensureTenantContext from authHelpers.
+ */
+export declare const validateTenantContext: (_req: TenantContextAugmentedRequest) => boolean;
+/**
+ * Simple boolean tenant context check (for compatibility)
+ * @param req Express request with tenant context
+ * @returns boolean indicating if context is valid
+ */
+export declare const ensureTenantContextBoolean: (req: TenantContextAugmentedRequest) => boolean;
+/**
+ * Check if the user has admin role
+ */
+export declare const isAdmin: (req: TenantContextAugmentedRequest) => boolean;
+/**
+ * Check if user has specific role
+ */
+export declare const hasRole: (req: TenantContextAugmentedRequest, role: string) => boolean;
+/**
+ * Get user roles as array (supports both single role string and roles array)
+ */
+export declare const getUserRoles: (req: TenantContextAugmentedRequest) => string[];
+/**
+ * Check if user has any of the specified roles
+ */
+export declare const hasAnyRole: (req: TenantContextAugmentedRequest, roles: string[]) => boolean;
+//# sourceMappingURL=tenantHelpers.d.ts.map

package/dist/tenantHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenantHelpers.d.ts","sourceRoot":"","sources":["../src/tenantHelpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,6BAA6B,EAAE,MAAM,SAAS,CAAC;AAExD;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,6BAA6B,KAAG,MAKlE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,6BAA6B,KAAG,MAUpE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GACtB,KAAK,6BAA6B,KACjC,MAAM,GAAG,MAIX,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAChC,MAAM,6BAA6B,KAClC,OAAe,CAAC;AAEnB;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,GACrC,KAAK,6BAA6B,KACjC,OAEF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,OAAO,GAAI,KAAK,6BAA6B,KAAG,OAClB,CAAC;AAE5C;;GAEG;AACH,eAAO,MAAM,OAAO,GAClB,KAAK,6BAA6B,EAClC,MAAM,MAAM,KACX,OAAiD,CAAC;AAErD;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,6BAA6B,KAAG,MAAM,EAOvE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,UAAU,GACrB,KAAK,6BAA6B,EAClC,OAAO,MAAM,EAAE,KACd,OAGF,CAAC"}

package/dist/tenantHelpers.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * @fileoverview Tenant context helper functions for multi-tenant applications
+ * @author QuiqFlow Team
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasAnyRole = exports.getUserRoles = exports.hasRole = exports.isAdmin = exports.ensureTenantContextBoolean = exports.validateTenantContext = exports.getTenantId = exports.getTenantUserId = exports.getSchemaName = void 0;
+/**
+ * Returns resolved schema name from tenant middleware context.
+ */
+const getSchemaName = (req) => {
+    if (!req.schemaName)
+        throw new Error("Schema name missing from request context");
+    return req.schemaName;
+};
+exports.getSchemaName = getSchemaName;
+/**
+ * Extract authenticated user id from request (supports id, sub, userId fields).
+ */
+const getTenantUserId = (req) => {
+    var _a, _b, _c;
+    const raw = ((_a = req.user) === null || _a === void 0 ? void 0 : _a.id) ||
+        ((_b = req.user) === null || _b === void 0 ? void 0 : _b.userId) ||
+        ((_c = req.user) === null || _c === void 0 ? void 0 : _c.sub);
+    if (!raw)
+        throw new Error("User id missing in request user payload");
+    const n = typeof raw === "string" ? parseInt(raw, 10) : raw;
+    if (isNaN(n))
+        throw new Error("User id is not numeric");
+    return n;
+};
+exports.getTenantUserId = getTenantUserId;
+/**
+ * Get tenant ID from request context
+ */
+const getTenantId = (req) => {
+    var _a;
+    if (req.tenantId)
+        return req.tenantId;
+    if ((_a = req.user) === null || _a === void 0 ? void 0 : _a.tenantId)
+        return req.user.tenantId;
+    throw new Error("Tenant ID missing from request context");
+};
+exports.getTenantId = getTenantId;
+/**
+ * Simple no-op validator kept for compatibility with previous validateUserSchema guard.
+ * Always returns true now that schema resolution is mandatory via middleware.
+ * For response-aware validation, use ensureTenantContext from authHelpers.
+ */
+const validateTenantContext = (_req) => true;
+exports.validateTenantContext = validateTenantContext;
+/**
+ * Simple boolean tenant context check (for compatibility)
+ * @param req Express request with tenant context
+ * @returns boolean indicating if context is valid
+ */
+const ensureTenantContextBoolean = (req) => {
+    return !!(req.schemaName && req.tenantDb);
+};
+exports.ensureTenantContextBoolean = ensureTenantContextBoolean;
+/**
+ * Check if the user has admin role
+ */
+const isAdmin = (req) => !!(req.user && req.user.role === "admin");
+exports.isAdmin = isAdmin;
+/**
+ * Check if user has specific role
+ */
+const hasRole = (req, role) => !!(req.user && req.user.role === role);
+exports.hasRole = hasRole;
+/**
+ * Get user roles as array (supports both single role string and roles array)
+ */
+const getUserRoles = (req) => {
+    if (!req.user)
+        return [];
+    if (Array.isArray(req.user.roles))
+        return req.user.roles;
+    if (req.user.role)
+        return [req.user.role];
+    return [];
+};
+exports.getUserRoles = getUserRoles;
+/**
+ * Check if user has any of the specified roles
+ */
+const hasAnyRole = (req, roles) => {
+    const userRoles = (0, exports.getUserRoles)(req);
+    return roles.some((role) => userRoles.includes(role));
+};
+exports.hasAnyRole = hasAnyRole;

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+import { Request } from "express";
+import { NextFunction, Response } from "express";
+export interface TenantAwareUser {
+    id?: number | string;
+    userId?: number | string;
+    tenantId?: number | string;
+    role?: string;
+    [key: string]: any;
+}
+export interface TenantContextAugmentedRequest extends Request {
+    tenantId?: string | number;
+    schemaName?: string;
+    user?: TenantAwareUser;
+    tenantDb?: any;
+}
+export interface SchemaRecord {
+    tenantId: number;
+    schemaName: string;
+    status?: string;
+    [key: string]: any;
+}
+export interface SchemaResolutionAdapter {
+    listAllTenants(): Promise<SchemaRecord[]>;
+    getTenantById(tenantId: number): Promise<SchemaRecord | null>;
+}
+export interface AdminConnectionLike {
+    getTenantById(tenantId: number): Promise<SchemaRecord | null>;
+    listAllTenants(): Promise<SchemaRecord[]>;
+}
+export interface TenantConnectionFactoryArgs {
+    schemaName: string;
+}
+export type TenantOrmFactory = (args: TenantConnectionFactoryArgs) => Promise<any>;
+export interface TenantConnectionManagerOptions {
+    factory: TenantOrmFactory;
+    authenticate?(orm: any): Promise<void>;
+}
+export interface CreateTenantMiddlewareOptions {
+    schemaResolutionService: SchemaResolutionServiceLike;
+    connectionManager: TenantConnectionManagerLike;
+    decodeJwt?(token: string): any;
+    headerTenantKey?: string;
+    allowOptional?: boolean;
+}
+export type TenantMiddleware = (req: TenantContextAugmentedRequest, res: Response, next: NextFunction) => Promise<void>;
+export interface TenantConnectionManagerLike {
+    getConnection(schemaName: string): Promise<any>;
+}
+export interface SchemaResolutionServiceLike {
+    resolveSchemaForTenant(tenantId: number): Promise<string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,6BAA8B,SAAQ,OAAO;IAC5D,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,cAAc,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAC1C,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC9D,cAAc,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,2BAA2B;IAC1C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,gBAAgB,GAAG,CAC7B,IAAI,EAAE,2BAA2B,KAC9B,OAAO,CAAC,GAAG,CAAC,CAAC;AAElB,MAAM,WAAW,8BAA8B;IAC7C,OAAO,EAAE,gBAAgB,CAAC;IAC1B,YAAY,CAAC,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,6BAA6B;IAC5C,uBAAuB,EAAE,2BAA2B,CAAC;IACrD,iBAAiB,EAAE,2BAA2B,CAAC;IAC/C,SAAS,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC;IAC/B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,MAAM,gBAAgB,GAAG,CAC7B,GAAG,EAAE,6BAA6B,EAClC,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,KACf,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,MAAM,WAAW,2BAA2B;IAC1C,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,2BAA2B;IAC1C,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3D"}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@quiqflow-org/quiqflow-multi-tenants-utils",
+  "version": "1.0.0",
+  "description": "Shared multi-tenant helpers (schema resolution, connection management, middleware) for Quiqflow services.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint 'src/**/*.{ts,js}' || true",
+    "prepare": "npm run build",
+    "semantic-release": "semantic-release",
+    "test": "echo 'No tests yet'"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/Quiqflow-2-0/quiqflow-multi-tenants-utils.git"
+  },
+  "keywords": [
+    "multi-tenant",
+    "schema",
+    "middleware",
+    "quiqflow"
+  ],
+  "dependencies": {
+    "jsonwebtoken": "^9.0.2",
+    "@semantic-release/github": "^11.0.1",
+    "node-cache": "^5.1.2"
+  },
+  "peerDependencies": {
+    "express": ">=4",
+    "typescript": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/jsonwebtoken": "^9.0.7",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/exec": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/npm": "^11.0.2",
+    "semantic-release": "^22.0.12",
+    "@types/node": "^22.10.1",
+    "express": "^4.21.2",
+    "typescript": "^5.3.3"
+  }
+}