@valentine-efagene/qshelter-common 2.0.22 → 2.0.25

package/dist/src/middleware/index.js

@@ -0,0 +1,3 @@
+export * from './error-handler';
+export * from './request-logger';
+export * from './tenant';

package/dist/src/middleware/request-logger.d.ts

@@ -0,0 +1,6 @@
+import { Request, Response, NextFunction } from 'express';
+/**
+ * Request logging middleware that logs method, path, status code, and duration.
+ * Logs in JSON format for easy parsing by log aggregation tools.
+ */
+export declare function requestLogger(req: Request, res: Response, next: NextFunction): void;

package/dist/src/middleware/request-logger.js

@@ -0,0 +1,17 @@
+/**
+ * Request logging middleware that logs method, path, status code, and duration.
+ * Logs in JSON format for easy parsing by log aggregation tools.
+ */
+export function requestLogger(req, res, next) {
+    const start = Date.now();
+    res.on('finish', () => {
+        const duration = Date.now() - start;
+        console.log(JSON.stringify({
+            method: req.method,
+            path: req.path,
+            statusCode: res.statusCode,
+            duration,
+        }));
+    });
+    next();
+}

package/dist/src/middleware/tenant.d.ts

@@ -0,0 +1,76 @@
+import { Request, Response, NextFunction } from 'express';
+import { PrismaClient } from '../../generated/client/client';
+import { TenantContext, TenantPrismaClient } from '../prisma/tenant';
+/**
+ * Extend Express Request to include tenant context and scoped Prisma client
+ */
+declare global {
+    namespace Express {
+        interface Request {
+            tenantContext?: TenantContext;
+            tenantPrisma?: TenantPrismaClient | PrismaClient;
+            /**
+             * API Gateway context added by serverless-express
+             */
+            apiGateway?: {
+                event: {
+                    requestContext: {
+                        authorizer?: {
+                            userId?: string;
+                            email?: string;
+                            roles?: string;
+                            tenantId?: string;
+                        };
+                    };
+                };
+            };
+        }
+    }
+}
+/**
+ * Options for tenant middleware
+ */
+export interface TenantMiddlewareOptions {
+    /**
+     * The base Prisma client to use for creating tenant-scoped clients
+     */
+    prisma: PrismaClient;
+    /**
+     * Whether to create a tenant-scoped Prisma client automatically
+     * If false, only tenantContext is attached to the request
+     * @default true
+     */
+    createScopedClient?: boolean;
+}
+/**
+ * Creates a tenant middleware that extracts tenant context from the request
+ * and optionally creates a tenant-scoped Prisma client.
+ *
+ * The API Gateway authorizer is expected to set:
+ * - x-tenant-id: The tenant ID from the JWT
+ * - x-user-id: The user ID from the JWT
+ *
+ * @example
+ * ```ts
+ * import { createTenantMiddleware } from '@valentine-efagene/qshelter-common';
+ * import { prisma } from './lib/prisma';
+ *
+ * app.use(createTenantMiddleware({ prisma }));
+ * ```
+ */
+export declare function createTenantMiddleware(options: TenantMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Middleware that requires tenant context.
+ * Use this for routes that must have tenant scoping.
+ */
+export declare function requireTenant(req: Request, res: Response, next: NextFunction): void;
+/**
+ * Helper to get tenant-scoped Prisma client from request.
+ * Throws if not available.
+ */
+export declare function getTenantPrisma(req: Request): TenantPrismaClient | PrismaClient;
+/**
+ * Helper to get tenant context from request.
+ * Throws if not available.
+ */
+export declare function getTenantContext(req: Request): TenantContext;

package/dist/src/middleware/tenant.js

@@ -0,0 +1,88 @@
+import { AppError } from '../utils/errors';
+import { createTenantPrisma, } from '../prisma/tenant';
+/**
+ * Creates a tenant middleware that extracts tenant context from the request
+ * and optionally creates a tenant-scoped Prisma client.
+ *
+ * The API Gateway authorizer is expected to set:
+ * - x-tenant-id: The tenant ID from the JWT
+ * - x-user-id: The user ID from the JWT
+ *
+ * @example
+ * ```ts
+ * import { createTenantMiddleware } from '@valentine-efagene/qshelter-common';
+ * import { prisma } from './lib/prisma';
+ *
+ * app.use(createTenantMiddleware({ prisma }));
+ * ```
+ */
+export function createTenantMiddleware(options) {
+    const { prisma, createScopedClient = true } = options;
+    return function tenantMiddleware(req, res, next) {
+        try {
+            // 1. Try Lambda authorizer context first (production)
+            const authorizerContext = req.apiGateway?.event?.requestContext?.authorizer;
+            // 2. Fall back to headers (local dev or alternative setups)
+            const headers = req.headers;
+            const tenantId = authorizerContext?.tenantId || headers['x-tenant-id'];
+            const userId = authorizerContext?.userId || headers['x-user-id'];
+            if (!tenantId) {
+                // For now, allow requests without tenant context for development
+                // In production, you might want to reject these
+                console.warn('Request without tenant context:', req.path);
+                return next();
+            }
+            const tenantContext = {
+                tenantId,
+                userId,
+            };
+            // Attach tenant context to request
+            req.tenantContext = tenantContext;
+            // Create tenant-scoped Prisma client if enabled
+            if (createScopedClient) {
+                req.tenantPrisma = createTenantPrisma(prisma, tenantContext);
+            }
+            else {
+                req.tenantPrisma = prisma;
+            }
+            next();
+        }
+        catch (error) {
+            console.error('Tenant middleware error:', error);
+            next(error);
+        }
+    };
+}
+/**
+ * Middleware that requires tenant context.
+ * Use this for routes that must have tenant scoping.
+ */
+export function requireTenant(req, res, next) {
+    if (!req.tenantContext?.tenantId) {
+        return next(new AppError(400, 'Tenant context required'));
+    }
+    if (!req.tenantPrisma) {
+        return next(new AppError(500, 'Tenant Prisma client not initialized'));
+    }
+    next();
+}
+/**
+ * Helper to get tenant-scoped Prisma client from request.
+ * Throws if not available.
+ */
+export function getTenantPrisma(req) {
+    if (!req.tenantPrisma) {
+        throw new AppError(500, 'Tenant context not available');
+    }
+    return req.tenantPrisma;
+}
+/**
+ * Helper to get tenant context from request.
+ * Throws if not available.
+ */
+export function getTenantContext(req) {
+    if (!req.tenantContext) {
+        throw new AppError(500, 'Tenant context not available');
+    }
+    return req.tenantContext;
+}

package/dist/src/prisma/tenant.d.ts

@@ -0,0 +1,51 @@
+import { PrismaClient, Prisma } from "../../generated/client/client";
+/**
+ * Tenant context for request-scoped operations
+ */
+export interface TenantContext {
+    tenantId: string;
+    userId?: string;
+}
+/**
+ * Creates a tenant-scoped Prisma client that automatically:
+ * 1. Filters all queries on tenant-scoped models by tenantId
+ * 2. Injects tenantId into all create operations on tenant-scoped models
+ *
+ * Usage:
+ * ```ts
+ * const tenantPrisma = createTenantPrisma(prisma, { tenantId: 'tenant-123' });
+ * const properties = await tenantPrisma.property.findMany(); // Auto-filtered by tenant
+ * ```
+ */
+export declare function createTenantPrisma(prisma: PrismaClient, context: TenantContext): import("@prisma/client/runtime/client").DynamicClientExtensionThis<Prisma.TypeMap<import("@prisma/client/runtime/client").InternalArgs & {
+    result: {};
+    model: {};
+    query: {};
+    client: {};
+}, Prisma.GlobalOmitConfig | undefined>, Prisma.TypeMapCb<Prisma.GlobalOmitConfig | undefined>, {
+    result: {};
+    model: {};
+    query: {};
+    client: {};
+}>;
+/**
+ * Type helper for the tenant-scoped Prisma client
+ */
+export type TenantPrismaClient = ReturnType<typeof createTenantPrisma>;
+/**
+ * Helper to verify a record belongs to the current tenant
+ * Use this for operations that can't be filtered at query time
+ */
+export declare function assertTenantOwnership<T extends {
+    tenantId?: string | null;
+}>(record: T | null, tenantId: string, options?: {
+    allowGlobal?: boolean;
+}): asserts record is T;
+/**
+ * Utility to check if a record is accessible by a tenant
+ */
+export declare function canAccessRecord(record: {
+    tenantId?: string | null;
+} | null, tenantId: string, options?: {
+    allowGlobal?: boolean;
+}): boolean;

package/dist/src/prisma/tenant.js

@@ -0,0 +1,211 @@
+/**
+ * Models that require tenant scoping
+ */
+const TENANT_SCOPED_MODELS = [
+    "property",
+    "paymentPlan",
+    "propertyPaymentMethod",
+    "contract",
+];
+/**
+ * Models that can optionally have tenant scoping (nullable tenantId)
+ * PaymentPlan has nullable tenantId for global templates
+ */
+const OPTIONAL_TENANT_MODELS = ["paymentPlan"];
+function isTenantScopedModel(model) {
+    return TENANT_SCOPED_MODELS.includes(model);
+}
+function isOptionalTenantModel(model) {
+    return OPTIONAL_TENANT_MODELS.includes(model);
+}
+/**
+ * Creates a tenant-scoped Prisma client that automatically:
+ * 1. Filters all queries on tenant-scoped models by tenantId
+ * 2. Injects tenantId into all create operations on tenant-scoped models
+ *
+ * Usage:
+ * ```ts
+ * const tenantPrisma = createTenantPrisma(prisma, { tenantId: 'tenant-123' });
+ * const properties = await tenantPrisma.property.findMany(); // Auto-filtered by tenant
+ * ```
+ */
+export function createTenantPrisma(prisma, context) {
+    const { tenantId } = context;
+    return prisma.$extends({
+        name: "tenant-scoping",
+        query: {
+            $allModels: {
+                async findMany({ model, args, query }) {
+                    if (isTenantScopedModel(model)) {
+                        const tenantFilter = isOptionalTenantModel(model)
+                            ? { OR: [{ tenantId }, { tenantId: null }] }
+                            : { tenantId };
+                        args.where = {
+                            ...args.where,
+                            ...tenantFilter,
+                        };
+                    }
+                    return query(args);
+                },
+                async findFirst({ model, args, query }) {
+                    if (isTenantScopedModel(model)) {
+                        const tenantFilter = isOptionalTenantModel(model)
+                            ? { OR: [{ tenantId }, { tenantId: null }] }
+                            : { tenantId };
+                        args.where = {
+                            ...args.where,
+                            ...tenantFilter,
+                        };
+                    }
+                    return query(args);
+                },
+                async findUnique({ model, args, query }) {
+                    // findUnique can only filter by unique fields, so we verify after fetch
+                    const result = await query(args);
+                    if (result && isTenantScopedModel(model)) {
+                        const record = result;
+                        if (isOptionalTenantModel(model)) {
+                            // Allow null tenantId (global) or matching tenantId
+                            if (record.tenantId !== null && record.tenantId !== tenantId) {
+                                return null;
+                            }
+                        }
+                        else {
+                            if (record.tenantId !== tenantId) {
+                                return null;
+                            }
+                        }
+                    }
+                    return result;
+                },
+                async create({ model, args, query }) {
+                    if (isTenantScopedModel(model) && !isOptionalTenantModel(model)) {
+                        // Inject tenantId for required tenant models
+                        args.data.tenantId = tenantId;
+                    }
+                    else if (isOptionalTenantModel(model)) {
+                        // For optional models, inject if not explicitly set to null
+                        if (args.data.tenantId === undefined) {
+                            args.data.tenantId = tenantId;
+                        }
+                    }
+                    return query(args);
+                },
+                async createMany({ model, args, query }) {
+                    if (isTenantScopedModel(model)) {
+                        const data = Array.isArray(args.data) ? args.data : [args.data];
+                        args.data = data.map((item) => {
+                            if (!isOptionalTenantModel(model)) {
+                                return { ...item, tenantId };
+                            }
+                            // For optional models, inject if not explicitly set
+                            if (item.tenantId === undefined) {
+                                return { ...item, tenantId };
+                            }
+                            return item;
+                        });
+                    }
+                    return query(args);
+                },
+                async update({ model, args, query }) {
+                    if (isTenantScopedModel(model)) {
+                        // Verify tenant ownership before update
+                        const tenantFilter = isOptionalTenantModel(model)
+                            ? { OR: [{ tenantId }, { tenantId: null }] }
+                            : { tenantId };
+                        args.where = {
+                            ...args.where,
+                            ...tenantFilter,
+                        };
+                    }
+                    return query(args);
+                },
+                async updateMany({ model, args, query }) {
+                    if (isTenantScopedModel(model)) {
+                        const tenantFilter = isOptionalTenantModel(model)
+                            ? { OR: [{ tenantId }, { tenantId: null }] }
+                            : { tenantId };
+                        args.where = {
+                            ...args.where,
+                            ...tenantFilter,
+                        };
+                    }
+                    return query(args);
+                },
+                async delete({ model, args, query }) {
+                    if (isTenantScopedModel(model)) {
+                        const tenantFilter = isOptionalTenantModel(model)
+                            ? { OR: [{ tenantId }, { tenantId: null }] }
+                            : { tenantId };
+                        args.where = {
+                            ...args.where,
+                            ...tenantFilter,
+                        };
+                    }
+                    return query(args);
+                },
+                async deleteMany({ model, args, query }) {
+                    if (isTenantScopedModel(model)) {
+                        const tenantFilter = isOptionalTenantModel(model)
+                            ? { OR: [{ tenantId }, { tenantId: null }] }
+                            : { tenantId };
+                        args.where = {
+                            ...args.where,
+                            ...tenantFilter,
+                        };
+                    }
+                    return query(args);
+                },
+                async count({ model, args, query }) {
+                    if (isTenantScopedModel(model)) {
+                        const tenantFilter = isOptionalTenantModel(model)
+                            ? { OR: [{ tenantId }, { tenantId: null }] }
+                            : { tenantId };
+                        args.where = {
+                            ...args.where,
+                            ...tenantFilter,
+                        };
+                    }
+                    return query(args);
+                },
+                async aggregate({ model, args, query }) {
+                    if (isTenantScopedModel(model)) {
+                        const tenantFilter = isOptionalTenantModel(model)
+                            ? { OR: [{ tenantId }, { tenantId: null }] }
+                            : { tenantId };
+                        args.where = {
+                            ...args.where,
+                            ...tenantFilter,
+                        };
+                    }
+                    return query(args);
+                },
+            },
+        },
+    });
+}
+/**
+ * Helper to verify a record belongs to the current tenant
+ * Use this for operations that can't be filtered at query time
+ */
+export function assertTenantOwnership(record, tenantId, options) {
+    if (!record) {
+        throw new Error("Record not found");
+    }
+    if (options?.allowGlobal && record.tenantId === null) {
+        return; // Global records are accessible to all tenants
+    }
+    if (record.tenantId !== tenantId) {
+        throw new Error("Access denied: resource belongs to another tenant");
+    }
+}
+/**
+ * Utility to check if a record is accessible by a tenant
+ */
+export function canAccessRecord(record, tenantId, options) {
+    if (!record)
+        return false;
+    if (options?.allowGlobal && record.tenantId === null)
+        return true;
+    return record.tenantId === tenantId;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentine-efagene/qshelter-common",
-  "version": "2.0.22",
+  "version": "2.0.25",
   "description": "Shared database schemas and utilities for QShelter services",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -34,8 +34,22 @@
     "dotenv": "^17.2.3",
     "prisma": "^7.0.0"
   },
+  "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0",
+    "zod": "^3.0.0 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@types/express": "^5.0.0",
     "@types/node": "^25.0.3",
-    "typescript": "^5.7.3"
+    "typescript": "^5.7.3",
+    "zod": "^4.0.0"
   }
 }