@node-tenant/tenant-express 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# @node-tenant/tenant-express
+
+> **Express.js middleware** for the `@node-tenant` ecosystem — effortlessly resolves tenant context from HTTP requests.
+
+[![npm version](https://img.shields.io/npm/v/@node-tenant/tenant-express)](https://www.npmjs.com/package/@node-tenant/tenant-express)
+[![license](https://img.shields.io/npm/l/@node-tenant/tenant-express)](./LICENSE)
+
+---
+
+## Overview
+
+`@node-tenant/tenant-express` provides middleware and resolvers to automatically identify which tenant is making an HTTP request in your Express application. It integrates perfectly with `@node-tenant/tenant-core` to establish the tenant context using Node.js `AsyncLocalStorage`.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Resolvers](#resolvers)
+  - [Header Resolver](#header-resolver)
+  - [Subdomain Resolver](#subdomain-resolver)
+  - [Custom Resolver](#custom-resolver)
+- [API Reference](#api-reference)
+- [License](#license)
+
+---
+
+## Installation
+
+```bash
+npm install @node-tenant/tenant-core @node-tenant/tenant-express
+```
+
+> **Peer dependency**: `express >= 4.0.0` must be installed in your project.
+
+---
+
+## Quick Start
+
+```ts
+import express from 'express';
+import { TenantManager, TenantContextManager } from '@node-tenant/tenant-core';
+import { tenantMiddleware, headerResolver } from '@node-tenant/tenant-express';
+
+const manager = new TenantManager({ /* storage, etc */ });
+const app = express();
+
+// Use the middleware globally (or on specific routes)
+// This will look for a tenant slug in the 'x-tenant-id' header
+app.use(tenantMiddleware({
+  manager,
+  resolver: headerResolver('x-tenant-id')
+}));
+
+app.get('/api/me', (req, res) => {
+  // Access the resolved tenant context safely!
+  const tenant = TenantContextManager.currentOrThrow();
+  
+  res.json({
+    message: `Hello from tenant: ${tenant.name}`,
+    tenantId: tenant.id
+  });
+});
+
+app.listen(3000);
+```
+
+---
+
+## Resolvers
+
+Resolvers are strategies for extracting the tenant identifier (slug or ID) from an incoming Express request.
+
+### Header Resolver
+
+Extracts the tenant identifier from an HTTP header. Common in API-first applications.
+
+```ts
+import { headerResolver } from '@node-tenant/tenant-express';
+
+// Looks for 'x-tenant-id' in headers
+const resolver = headerResolver('x-tenant-id');
+```
+
+### Subdomain Resolver
+
+Extracts the tenant identifier from the subdomain (e.g., `acme` in `acme.myapp.com`). You **must** provide the `storage` adapter so the resolver can lookup the tenant by its slug.
+
+```ts
+import { subdomainResolver } from '@node-tenant/tenant-express';
+
+// Extracts subdomain and looks up tenant via storage.getTenantBySlug(subdomain)
+const resolver = subdomainResolver(manager.storage);
+```
+
+### Custom Resolver
+
+You can easily write your own resolver by implementing the `TenantResolver` signature: `(req: Request) => Promise<string | undefined>`
+
+```ts
+const jwtResolver = async (req) => {
+  // Extract tenant ID from a decoded JWT token
+  return req.user?.tenantId;
+};
+
+app.use(tenantMiddleware({ manager, resolver: jwtResolver }));
+```
+
+---
+
+## API Reference
+
+### `tenantMiddleware(options)`
+
+Creates the Express middleware.
+
+```ts
+const middleware = tenantMiddleware({
+  manager: managerInstance,
+  resolver: myResolver,
+  requireTenant: true // default: false
+});
+```
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `manager` | `TenantManager` | ✅ | Instance of `TenantManager` |
+| `resolver` | `TenantResolver` | ✅ | Function to extract tenant ID/slug from request |
+| `requireTenant` | `boolean` | ❌ | If true, returns 401 if no tenant is found. Default: `false`. |
+
+---
+
+## License
+
+MIT © AdPulseFlow

package/dist/index.cjs

@@ -0,0 +1,91 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  chainResolvers: () => import_tenant_core2.chainResolvers,
+  domainResolver: () => import_tenant_core2.domainResolver,
+  getCurrentTenant: () => getCurrentTenant,
+  headerResolver: () => import_tenant_core2.headerResolver,
+  pathResolver: () => import_tenant_core2.pathResolver,
+  subdomainResolver: () => import_tenant_core2.subdomainResolver,
+  tenantMiddleware: () => tenantMiddleware
+});
+module.exports = __toCommonJS(index_exports);
+var import_tenant_core = require("@node-tenant/tenant-core");
+var import_tenant_core2 = require("@node-tenant/tenant-core");
+function tenantMiddleware(options) {
+  const { manager, resolver, required = true } = options;
+  return async (req, res, next) => {
+    try {
+      const result = await resolver(req);
+      if (!result) {
+        if (required) {
+          if (options.onNotFound) {
+            return options.onNotFound(req, res, next);
+          }
+          res.status(401).json({ error: "Tenant not found" });
+          return;
+        }
+        return next();
+      }
+      const tenant = await manager.getTenant(result.tenantId);
+      if (!tenant) {
+        if (required) {
+          res.status(401).json({ error: "Tenant not found" });
+          return;
+        }
+        return next();
+      }
+      if (tenant.status !== "active") {
+        res.status(403).json({ error: `Tenant is ${tenant.status}` });
+        return;
+      }
+      const ctx = {
+        id: tenant.id,
+        slug: tenant.slug,
+        strategy: tenant.strategy,
+        organizationId: tenant.organizationId,
+        config: tenant.config
+      };
+      for (const plugin of manager.plugins) {
+        await plugin.onTenantResolved?.(ctx);
+      }
+      manager.emit("tenant.resolved", ctx);
+      import_tenant_core.TenantContextManager.run(ctx, () => next());
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+function getCurrentTenant() {
+  return import_tenant_core.TenantContextManager.currentOrThrow();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  chainResolvers,
+  domainResolver,
+  getCurrentTenant,
+  headerResolver,
+  pathResolver,
+  subdomainResolver,
+  tenantMiddleware
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { Request, Response, NextFunction, RequestHandler } from 'express';\nimport {\n  TenantContextManager,\n  TenantManager,\n  type TenantResolverFn,\n  type TenantPlugin,\n} from '@node-tenant/tenant-core';\n\nexport interface TenantMiddlewareOptions {\n  manager: TenantManager;\n  resolver: TenantResolverFn<Request>;\n  /** If true, 401 is returned when tenant cannot be resolved. Default: true */\n  required?: boolean;\n  /** Called when tenant resolution fails */\n  onNotFound?: (req: Request, res: Response, next: NextFunction) => void;\n}\n\n/**\n * Express middleware that resolves the tenant for each request and\n * runs the rest of the middleware chain inside that tenant's context.\n *\n * Usage:\n *   app.use(tenantMiddleware({ manager, resolver: subdomainResolver(manager.storage) }))\n */\nexport function tenantMiddleware(options: TenantMiddlewareOptions): RequestHandler {\n  const { manager, resolver, required = true } = options;\n\n  return async (req, res, next) => {\n    try {\n      const result = await resolver(req);\n\n      if (!result) {\n        if (required) {\n          if (options.onNotFound) {\n            return options.onNotFound(req, res, next);\n          }\n          res.status(401).json({ error: 'Tenant not found' });\n          return;\n        }\n        return next();\n      }\n\n      const tenant = await manager.getTenant(result.tenantId);\n      if (!tenant) {\n        if (required) {\n          res.status(401).json({ error: 'Tenant not found' });\n          return;\n        }\n        return next();\n      }\n\n      if (tenant.status !== 'active') {\n        res.status(403).json({ error: `Tenant is ${tenant.status}` });\n        return;\n      }\n\n      const ctx = {\n        id: tenant.id,\n        slug: tenant.slug,\n        strategy: tenant.strategy,\n        organizationId: tenant.organizationId,\n        config: tenant.config,\n      };\n\n      for (const plugin of (manager as any).plugins as TenantPlugin[]) {\n        await plugin.onTenantResolved?.(ctx);\n      }\n\n      manager.emit('tenant.resolved', ctx);\n\n      TenantContextManager.run(ctx, () => next());\n    } catch (err) {\n      next(err);\n    }\n  };\n}\n\n/**\n * Get the current tenant context inside an Express handler.\n * Must be used after tenantMiddleware().\n */\nexport function getCurrentTenant() {\n  return TenantContextManager.currentOrThrow();\n}\n\nexport { subdomainResolver, domainResolver, pathResolver, headerResolver, chainResolvers } from '@node-tenant/tenant-core';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AACA,yBAKO;AA+EP,IAAAA,sBAAgG;AA7DzF,SAAS,iBAAiB,SAAkD;AACjF,QAAM,EAAE,SAAS,UAAU,WAAW,KAAK,IAAI;AAE/C,SAAO,OAAO,KAAK,KAAK,SAAS;AAC/B,QAAI;AACF,YAAM,SAAS,MAAM,SAAS,GAAG;AAEjC,UAAI,CAAC,QAAQ;AACX,YAAI,UAAU;AACZ,cAAI,QAAQ,YAAY;AACtB,mBAAO,QAAQ,WAAW,KAAK,KAAK,IAAI;AAAA,UAC1C;AACA,cAAI,OAAO,GAAG,EAAE,KAAK,EAAE,OAAO,mBAAmB,CAAC;AAClD;AAAA,QACF;AACA,eAAO,KAAK;AAAA,MACd;AAEA,YAAM,SAAS,MAAM,QAAQ,UAAU,OAAO,QAAQ;AACtD,UAAI,CAAC,QAAQ;AACX,YAAI,UAAU;AACZ,cAAI,OAAO,GAAG,EAAE,KAAK,EAAE,OAAO,mBAAmB,CAAC;AAClD;AAAA,QACF;AACA,eAAO,KAAK;AAAA,MACd;AAEA,UAAI,OAAO,WAAW,UAAU;AAC9B,YAAI,OAAO,GAAG,EAAE,KAAK,EAAE,OAAO,aAAa,OAAO,MAAM,GAAG,CAAC;AAC5D;AAAA,MACF;AAEA,YAAM,MAAM;AAAA,QACV,IAAI,OAAO;AAAA,QACX,MAAM,OAAO;AAAA,QACb,UAAU,OAAO;AAAA,QACjB,gBAAgB,OAAO;AAAA,QACvB,QAAQ,OAAO;AAAA,MACjB;AAEA,iBAAW,UAAW,QAAgB,SAA2B;AAC/D,cAAM,OAAO,mBAAmB,GAAG;AAAA,MACrC;AAEA,cAAQ,KAAK,mBAAmB,GAAG;AAEnC,8CAAqB,IAAI,KAAK,MAAM,KAAK,CAAC;AAAA,IAC5C,SAAS,KAAK;AACZ,WAAK,GAAG;AAAA,IACV;AAAA,EACF;AACF;AAMO,SAAS,mBAAmB;AACjC,SAAO,wCAAqB,eAAe;AAC7C;","names":["import_tenant_core"]}

package/dist/index.d.cts

@@ -0,0 +1,28 @@
+import * as _node_tenant_tenant_core from '@node-tenant/tenant-core';
+import { TenantManager, TenantResolverFn } from '@node-tenant/tenant-core';
+export { chainResolvers, domainResolver, headerResolver, pathResolver, subdomainResolver } from '@node-tenant/tenant-core';
+import { Request, Response, NextFunction, RequestHandler } from 'express';
+
+interface TenantMiddlewareOptions {
+    manager: TenantManager;
+    resolver: TenantResolverFn<Request>;
+    /** If true, 401 is returned when tenant cannot be resolved. Default: true */
+    required?: boolean;
+    /** Called when tenant resolution fails */
+    onNotFound?: (req: Request, res: Response, next: NextFunction) => void;
+}
+/**
+ * Express middleware that resolves the tenant for each request and
+ * runs the rest of the middleware chain inside that tenant's context.
+ *
+ * Usage:
+ *   app.use(tenantMiddleware({ manager, resolver: subdomainResolver(manager.storage) }))
+ */
+declare function tenantMiddleware(options: TenantMiddlewareOptions): RequestHandler;
+/**
+ * Get the current tenant context inside an Express handler.
+ * Must be used after tenantMiddleware().
+ */
+declare function getCurrentTenant(): _node_tenant_tenant_core.TenantContext;
+
+export { type TenantMiddlewareOptions, getCurrentTenant, tenantMiddleware };

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import * as _node_tenant_tenant_core from '@node-tenant/tenant-core';
+import { TenantManager, TenantResolverFn } from '@node-tenant/tenant-core';
+export { chainResolvers, domainResolver, headerResolver, pathResolver, subdomainResolver } from '@node-tenant/tenant-core';
+import { Request, Response, NextFunction, RequestHandler } from 'express';
+
+interface TenantMiddlewareOptions {
+    manager: TenantManager;
+    resolver: TenantResolverFn<Request>;
+    /** If true, 401 is returned when tenant cannot be resolved. Default: true */
+    required?: boolean;
+    /** Called when tenant resolution fails */
+    onNotFound?: (req: Request, res: Response, next: NextFunction) => void;
+}
+/**
+ * Express middleware that resolves the tenant for each request and
+ * runs the rest of the middleware chain inside that tenant's context.
+ *
+ * Usage:
+ *   app.use(tenantMiddleware({ manager, resolver: subdomainResolver(manager.storage) }))
+ */
+declare function tenantMiddleware(options: TenantMiddlewareOptions): RequestHandler;
+/**
+ * Get the current tenant context inside an Express handler.
+ * Must be used after tenantMiddleware().
+ */
+declare function getCurrentTenant(): _node_tenant_tenant_core.TenantContext;
+
+export { type TenantMiddlewareOptions, getCurrentTenant, tenantMiddleware };

package/dist/index.js

@@ -0,0 +1,62 @@
+// src/index.ts
+import {
+  TenantContextManager
+} from "@node-tenant/tenant-core";
+import { subdomainResolver, domainResolver, pathResolver, headerResolver, chainResolvers } from "@node-tenant/tenant-core";
+function tenantMiddleware(options) {
+  const { manager, resolver, required = true } = options;
+  return async (req, res, next) => {
+    try {
+      const result = await resolver(req);
+      if (!result) {
+        if (required) {
+          if (options.onNotFound) {
+            return options.onNotFound(req, res, next);
+          }
+          res.status(401).json({ error: "Tenant not found" });
+          return;
+        }
+        return next();
+      }
+      const tenant = await manager.getTenant(result.tenantId);
+      if (!tenant) {
+        if (required) {
+          res.status(401).json({ error: "Tenant not found" });
+          return;
+        }
+        return next();
+      }
+      if (tenant.status !== "active") {
+        res.status(403).json({ error: `Tenant is ${tenant.status}` });
+        return;
+      }
+      const ctx = {
+        id: tenant.id,
+        slug: tenant.slug,
+        strategy: tenant.strategy,
+        organizationId: tenant.organizationId,
+        config: tenant.config
+      };
+      for (const plugin of manager.plugins) {
+        await plugin.onTenantResolved?.(ctx);
+      }
+      manager.emit("tenant.resolved", ctx);
+      TenantContextManager.run(ctx, () => next());
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+function getCurrentTenant() {
+  return TenantContextManager.currentOrThrow();
+}
+export {
+  chainResolvers,
+  domainResolver,
+  getCurrentTenant,
+  headerResolver,
+  pathResolver,
+  subdomainResolver,
+  tenantMiddleware
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { Request, Response, NextFunction, RequestHandler } from 'express';\nimport {\n  TenantContextManager,\n  TenantManager,\n  type TenantResolverFn,\n  type TenantPlugin,\n} from '@node-tenant/tenant-core';\n\nexport interface TenantMiddlewareOptions {\n  manager: TenantManager;\n  resolver: TenantResolverFn<Request>;\n  /** If true, 401 is returned when tenant cannot be resolved. Default: true */\n  required?: boolean;\n  /** Called when tenant resolution fails */\n  onNotFound?: (req: Request, res: Response, next: NextFunction) => void;\n}\n\n/**\n * Express middleware that resolves the tenant for each request and\n * runs the rest of the middleware chain inside that tenant's context.\n *\n * Usage:\n *   app.use(tenantMiddleware({ manager, resolver: subdomainResolver(manager.storage) }))\n */\nexport function tenantMiddleware(options: TenantMiddlewareOptions): RequestHandler {\n  const { manager, resolver, required = true } = options;\n\n  return async (req, res, next) => {\n    try {\n      const result = await resolver(req);\n\n      if (!result) {\n        if (required) {\n          if (options.onNotFound) {\n            return options.onNotFound(req, res, next);\n          }\n          res.status(401).json({ error: 'Tenant not found' });\n          return;\n        }\n        return next();\n      }\n\n      const tenant = await manager.getTenant(result.tenantId);\n      if (!tenant) {\n        if (required) {\n          res.status(401).json({ error: 'Tenant not found' });\n          return;\n        }\n        return next();\n      }\n\n      if (tenant.status !== 'active') {\n        res.status(403).json({ error: `Tenant is ${tenant.status}` });\n        return;\n      }\n\n      const ctx = {\n        id: tenant.id,\n        slug: tenant.slug,\n        strategy: tenant.strategy,\n        organizationId: tenant.organizationId,\n        config: tenant.config,\n      };\n\n      for (const plugin of (manager as any).plugins as TenantPlugin[]) {\n        await plugin.onTenantResolved?.(ctx);\n      }\n\n      manager.emit('tenant.resolved', ctx);\n\n      TenantContextManager.run(ctx, () => next());\n    } catch (err) {\n      next(err);\n    }\n  };\n}\n\n/**\n * Get the current tenant context inside an Express handler.\n * Must be used after tenantMiddleware().\n */\nexport function getCurrentTenant() {\n  return TenantContextManager.currentOrThrow();\n}\n\nexport { subdomainResolver, domainResolver, pathResolver, headerResolver, chainResolvers } from '@node-tenant/tenant-core';\n"],"mappings":";AACA;AAAA,EACE;AAAA,OAIK;AA+EP,SAAS,mBAAmB,gBAAgB,cAAc,gBAAgB,sBAAsB;AA7DzF,SAAS,iBAAiB,SAAkD;AACjF,QAAM,EAAE,SAAS,UAAU,WAAW,KAAK,IAAI;AAE/C,SAAO,OAAO,KAAK,KAAK,SAAS;AAC/B,QAAI;AACF,YAAM,SAAS,MAAM,SAAS,GAAG;AAEjC,UAAI,CAAC,QAAQ;AACX,YAAI,UAAU;AACZ,cAAI,QAAQ,YAAY;AACtB,mBAAO,QAAQ,WAAW,KAAK,KAAK,IAAI;AAAA,UAC1C;AACA,cAAI,OAAO,GAAG,EAAE,KAAK,EAAE,OAAO,mBAAmB,CAAC;AAClD;AAAA,QACF;AACA,eAAO,KAAK;AAAA,MACd;AAEA,YAAM,SAAS,MAAM,QAAQ,UAAU,OAAO,QAAQ;AACtD,UAAI,CAAC,QAAQ;AACX,YAAI,UAAU;AACZ,cAAI,OAAO,GAAG,EAAE,KAAK,EAAE,OAAO,mBAAmB,CAAC;AAClD;AAAA,QACF;AACA,eAAO,KAAK;AAAA,MACd;AAEA,UAAI,OAAO,WAAW,UAAU;AAC9B,YAAI,OAAO,GAAG,EAAE,KAAK,EAAE,OAAO,aAAa,OAAO,MAAM,GAAG,CAAC;AAC5D;AAAA,MACF;AAEA,YAAM,MAAM;AAAA,QACV,IAAI,OAAO;AAAA,QACX,MAAM,OAAO;AAAA,QACb,UAAU,OAAO;AAAA,QACjB,gBAAgB,OAAO;AAAA,QACvB,QAAQ,OAAO;AAAA,MACjB;AAEA,iBAAW,UAAW,QAAgB,SAA2B;AAC/D,cAAM,OAAO,mBAAmB,GAAG;AAAA,MACrC;AAEA,cAAQ,KAAK,mBAAmB,GAAG;AAEnC,2BAAqB,IAAI,KAAK,MAAM,KAAK,CAAC;AAAA,IAC5C,SAAS,KAAK;AACZ,WAAK,GAAG;AAAA,IACV;AAAA,EACF;AACF;AAMO,SAAS,mBAAmB;AACjC,SAAO,qBAAqB,eAAe;AAC7C;","names":[]}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@node-tenant/tenant-express",
+  "version": "0.1.0",
+  "description": "Express.js middleware for @node-tenant/tenant",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".":{
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  },
+  "dependencies": {
+    "@node-tenant/tenant-core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "express": "^4.18.3",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.4.0"
+  }
+}
+