ts-packages 1.0.0 → 2.0.0

package/packages/server-utils/dist/esm/core/server.js

@@ -0,0 +1,396 @@
+import crypto from 'crypto';
+import { CacheFactory, SessionStore, } from '@naman_deep_singh/cache';
+import express, { json, raw } from 'express';
+import { PeriodicHealthMonitor } from './periodic-health';
+import { createGracefulShutdown } from './shutdown';
+import { useSession } from '../middleware';
+export class ExpressServer {
+    constructor(name = 'Express Server', version = '1.0.0', config = {}) {
+        this.status = 'stopped';
+        this.grpcServices = [];
+        this.rpcMethods = {};
+        this.app = express();
+        this.config = {
+            name,
+            version,
+            startTime: new Date(),
+            port: config.port || 3000,
+            cors: config.cors ?? true,
+            helmet: config.helmet ?? true,
+            json: config.json ?? true,
+            cookieParser: config.cookieParser ?? false,
+            customMiddleware: config.customMiddleware || [],
+            healthCheck: config.healthCheck ?? true,
+            gracefulShutdown: config.gracefulShutdown ?? true,
+            socketIO: config.socketIO,
+            periodicHealthCheck: config.periodicHealthCheck || { enabled: false },
+            cache: config.cache || { enabled: false },
+            session: config.session || { enabled: false },
+        };
+        // Initialize locals for cache/session
+        this.app.locals.cache = undefined;
+        this.app.locals.sessionStore = undefined;
+        this.app.locals.cacheDefaultTTL = config.cache?.defaultTTL;
+        // Apply middleware based on configuration
+        this.setupMiddleware();
+        // Setup periodic health monitoring
+        this.setupPeriodicHealthMonitoring();
+    }
+    setupMiddleware() {
+        // Apply CORS if enabled
+        if (this.config.cors) {
+            try {
+                const cors = require('cors');
+                const corsOptions = typeof this.config.cors === 'object' ? this.config.cors : undefined;
+                this.app.use(cors(corsOptions));
+            }
+            catch (_error) {
+                console.warn(`${this.config.name}: CORS middleware not available. Install cors package.`);
+            }
+        }
+        // Apply Helmet if enabled
+        if (this.config.helmet) {
+            try {
+                const helmet = require('helmet');
+                this.app.use(helmet());
+            }
+            catch (_error) {
+                console.warn(`${this.config.name}: Helmet middleware not available. Install helmet package.`);
+            }
+        }
+        // Apply JSON parser if enabled
+        if (this.config.json) {
+            this.app.use(json());
+        }
+        // Apply cookie parser if enabled
+        if (this.config.cookieParser) {
+            try {
+                const cookieParser = require('cookie-parser');
+                this.app.use(cookieParser());
+            }
+            catch (_error) {
+                console.warn(`${this.config.name}: Cookie parser middleware not available. Install cookie-parser package.`);
+            }
+        }
+        // Apply custom middleware
+        if (this.config.customMiddleware &&
+            this.config.customMiddleware.length > 0) {
+            this.config.customMiddleware.forEach((middleware) => {
+                this.app.use(middleware);
+            });
+        }
+        // Add health check if enabled
+        if (this.config.healthCheck) {
+            const healthPath = typeof this.config.healthCheck === 'string'
+                ? this.config.healthCheck
+                : '/health';
+            this.app.get(healthPath, async (req, res) => {
+                const base = {
+                    status: 'healthy',
+                    service: this.config.name,
+                    version: this.config.version,
+                    uptime: Date.now() - this.config.startTime.getTime(),
+                    timestamp: new Date().toISOString(),
+                };
+                // If cache is enabled, include its health
+                const cache = req.app.locals.cache;
+                if (cache && typeof cache.isAlive === 'function') {
+                    try {
+                        base.cache = await cache.isAlive();
+                    }
+                    catch (e) {
+                        base.cache = {
+                            isAlive: false,
+                            adapter: 'unknown',
+                            timestamp: new Date(),
+                            error: e.message,
+                        };
+                    }
+                }
+                res.status(200).json(base);
+            });
+        }
+    }
+    async setupCacheAndSession(config, serverName) {
+        try {
+            // Initialize cache if enabled
+            if (config.cache && config.cache.enabled) {
+                try {
+                    const provided = config.cache?.options;
+                    let cacheConfig = provided && typeof provided === 'object' ? provided : undefined;
+                    if (!cacheConfig) {
+                        cacheConfig = { adapter: config.cache.adapter || 'memory' };
+                    }
+                    console.log(`🔄 [${serverName}] Initializing cache adapter: ${config.cache.adapter || 'memory'}...`);
+                    // Use createWithFallback to prefer primary and fall back to memory when configured
+                    const cfg = {
+                        ...(cacheConfig || {}),
+                        ttl: cacheConfig?.ttl ??
+                            config.cache?.defaultTTL,
+                    };
+                    const cache = await CacheFactory.createWithFallback(cfg);
+                    this.app.locals.cache = cache;
+                    this.cache = cache;
+                    this.app.locals.cacheDefaultTTL = config.cache?.defaultTTL;
+                    // attach per-request helper middleware
+                    this.app.use((req, _res, next) => {
+                        req.cache = cache;
+                        next();
+                    });
+                    console.log(`✅ [${serverName}] Cache initialized successfully (adapter: ${cacheConfig.adapter || 'memory'})`);
+                }
+                catch (err) {
+                    console.error(`❌ [${serverName}] Failed to initialize cache (fallback to memory if enabled):`, err instanceof Error ? err.message : err);
+                    // Cache initialization error is critical but we continue to allow graceful fallback
+                }
+            }
+            // Initialize session if enabled
+            if (config.session && config.session.enabled) {
+                const cookieName = config.session.cookieName ||
+                    `${serverName.replace(/\s+/g, '_').toLowerCase()}.sid`;
+                const ttl = config.session.ttl ?? 3600;
+                let cache = this.app.locals.cache;
+                if (!cache) {
+                    // fallback to in-memory cache for session store
+                    try {
+                        cache = CacheFactory.create({ adapter: 'memory' });
+                        this.app.locals.cache = cache;
+                        this.cache = cache;
+                        console.log(`📝 [${serverName}] Session store using in-memory cache`);
+                    }
+                    catch (e) {
+                        console.error(`❌ [${serverName}] Failed to create in-memory cache for sessions:`, e instanceof Error ? e.message : e);
+                    }
+                }
+                else {
+                    console.log(`📝 [${serverName}] Session store initialized with configured cache adapter`);
+                }
+                if (!cache) {
+                    console.error(`❌ [${serverName}] CRITICAL: Session enabled but no cache available to store sessions. Session functionality will be unavailable.`);
+                }
+                else {
+                    const store = new SessionStore(cache, { ttl });
+                    this.app.locals.sessionStore = store;
+                    this.app.locals.sessionCookieName = cookieName;
+                    this.sessionStore = store;
+                    // attach session middleware globally so req.sessionStore is available
+                    try {
+                        this.app.use(useSession(cookieName));
+                        console.log(`✅ [${serverName}] Session middleware enabled (cookie: ${cookieName}, TTL: ${ttl}s)`);
+                    }
+                    catch (err) {
+                        console.error(`❌ [${serverName}] Session middleware not available:`, err instanceof Error ? err.message : err);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            console.error(`❌ [${serverName}] Error during cache/session setup:`, err instanceof Error ? err.message : err);
+        }
+    }
+    setupPeriodicHealthMonitoring() {
+        if (this.config.periodicHealthCheck?.enabled) {
+            this.healthMonitor = new PeriodicHealthMonitor(this.config.periodicHealthCheck, this.config.name);
+        }
+    }
+    async start() {
+        this.status = 'starting';
+        // Initialize cache and session before starting the server
+        await this.setupCacheAndSession(this.config, this.config.name);
+        return new Promise((resolve, reject) => {
+            try {
+                this.server = this.app.listen(this.config.port, () => {
+                    this.status = 'running';
+                    console.log(`🚀 ${this.config.name} v${this.config.version} running on http://localhost:${this.config.port}`);
+                    if (this.config.gracefulShutdown) {
+                        createGracefulShutdown(this.server, {
+                            onShutdown: async () => {
+                                this.status = 'stopping';
+                                // Stop health monitoring during shutdown
+                                if (this.healthMonitor) {
+                                    this.healthMonitor.stop();
+                                }
+                                // Close cache and session store if present
+                                try {
+                                    const cache = this.app.locals.cache;
+                                    if (cache && typeof cache.close === 'function') {
+                                        await cache.close();
+                                    }
+                                }
+                                catch (e) {
+                                    console.warn(`${this.config.name}: Error closing cache`, e);
+                                }
+                                try {
+                                    const store = this.app.locals.sessionStore;
+                                    if (store && typeof store.close === 'function') {
+                                        await store.close();
+                                    }
+                                }
+                                catch (_e) {
+                                    // SessionStore may not have close; ignore
+                                }
+                            },
+                        });
+                    }
+                    // Start periodic health monitoring after server is running
+                    if (this.healthMonitor) {
+                        this.healthMonitor.start();
+                    }
+                    resolve(this);
+                });
+                this.server.on('error', reject);
+            }
+            catch (error) {
+                this.status = 'stopped';
+                reject(error);
+            }
+        });
+    }
+    async stop() {
+        this.status = 'stopping';
+        // Stop gRPC server if running
+        if (this.grpcServer) {
+            this.grpcServer.forceShutdown();
+        }
+        // Stop periodic health monitoring
+        if (this.healthMonitor) {
+            this.healthMonitor.stop();
+        }
+        // Stop Socket.IO server if running
+        if (this.socketIO) {
+            this.socketIO.close();
+        }
+        if (!this.server) {
+            this.status = 'stopped';
+            return;
+        }
+        return new Promise((resolve) => {
+            this.server.close(() => {
+                this.status = 'stopped';
+                console.log(`👋 ${this.config.name} stopped`);
+                resolve();
+            });
+        });
+    }
+    getInfo() {
+        return {
+            name: this.config.name,
+            version: this.config.version,
+            port: this.config.port,
+            uptime: Date.now() - this.config.startTime.getTime(),
+            status: this.status,
+            startTime: this.config.startTime,
+        };
+    }
+    addGrpcService(service, implementation, port = 50051) {
+        this.grpcServices.push({ service, implementation });
+        // Lazy load gRPC to avoid dependency issues
+        if (!this.grpcServer) {
+            try {
+                const grpc = require('@grpc/grpc-js');
+                this.grpcServer = new grpc.Server();
+                // Add all services
+                this.grpcServices.forEach(({ service, implementation }) => {
+                    this.grpcServer.addService(service, implementation);
+                });
+                this.grpcServer.bindAsync(`0.0.0.0:${port}`, grpc.ServerCredentials.createInsecure(), () => {
+                    this.grpcServer.start();
+                    console.log(`🔗 ${this.config.name} gRPC server running on port ${port}`);
+                });
+            }
+            catch (_error) {
+                console.warn(`${this.config.name}: gRPC not available. Install @grpc/grpc-js to use gRPC features.`);
+            }
+        }
+    }
+    addRpcMethods(methods, path = '/rpc') {
+        Object.assign(this.rpcMethods, methods);
+        try {
+            const jayson = require('jayson');
+            const rpcServer = jayson.server(this.rpcMethods);
+            this.app.use(path, rpcServer.middleware());
+            console.log(`📡 ${this.config.name} JSON-RPC server mounted on ${path}`);
+        }
+        catch (_error) {
+            console.warn(`${this.config.name}: JSON-RPC not available. Install jayson to use RPC features.`);
+        }
+    }
+    addWebhook(config) {
+        this.app.post(config.path, raw({ type: 'application/json' }), async (req, res) => {
+            try {
+                // Verify signature if secret provided
+                if (config.secret) {
+                    const signature = req.headers['x-hub-signature-256'] ||
+                        req.headers['x-signature-256'];
+                    if (signature) {
+                        const expectedSignature = crypto
+                            .createHmac('sha256', config.secret)
+                            .update(req.body)
+                            .digest('hex');
+                        const providedSignature = Array.isArray(signature)
+                            ? signature[0]
+                            : signature;
+                        if (!providedSignature.includes(expectedSignature)) {
+                            return res.status(401).json({ error: 'Invalid signature' });
+                        }
+                    }
+                }
+                // Parse JSON payload
+                const payload = JSON.parse(req.body.toString());
+                // Call handler
+                await config.handler(payload, req.headers);
+                res.status(200).json({ success: true });
+            }
+            catch (error) {
+                console.error('Webhook error:', error);
+                res.status(500).json({ error: 'Webhook processing failed' });
+            }
+        });
+        console.log(`🪝 ${this.config.name} webhook registered at ${config.path}${config.secret ? ' (with signature verification)' : ''}`);
+    }
+    addSocketIO(config = {}) {
+        if (!this.server) {
+            throw new Error(`${this.config.name}: Server must be started before adding Socket.IO`);
+        }
+        try {
+            const { Server } = require('socket.io');
+            // Configure CORS
+            const corsConfig = config.cors === true
+                ? { origin: '*', methods: ['GET', 'POST'] }
+                : config.cors || undefined;
+            // Create Socket.IO server
+            const io = new Server(this.server, {
+                cors: config.cors ? corsConfig : undefined,
+                path: config.path || '/socket.io',
+            });
+            // Store reference for cleanup
+            this.socketIO = io;
+            // Handle connections
+            io.on('connection', (socket) => {
+                const typedSocket = socket;
+                console.log(`🔌 ${this.config.name}: Socket connected [${typedSocket.id}]`);
+                // Call user-defined connection handler
+                if (config.onConnection) {
+                    config.onConnection(socket);
+                }
+                // Handle disconnection
+                typedSocket.on('disconnect', (reason) => {
+                    console.log(`🔌 ${this.config.name}: Socket disconnected [${typedSocket.id}] - ${reason}`);
+                    // Call user-defined disconnection handler
+                    if (config.onDisconnection) {
+                        config.onDisconnection(socket, reason);
+                    }
+                });
+            });
+            console.log(`🔌 ${this.config.name} Socket.IO server attached${config.path ? ` at ${config.path}` : ''}${config.cors ? ' (CORS enabled)' : ''}`);
+            return io;
+        }
+        catch (_error) {
+            console.warn(`${this.config.name}: Socket.IO not available. Install socket.io to use WebSocket features.`);
+            return null;
+        }
+    }
+}
+export function createServer(name, version, config) {
+    return new ExpressServer(name, version, config);
+}

package/packages/server-utils/dist/esm/core/shutdown.d.ts

@@ -0,0 +1,5 @@
+import type { Server } from 'http';
+import type { GracefulShutdownConfig, ServerPlugin } from '../types';
+export declare function createGracefulShutdown(server: Server, config?: GracefulShutdownConfig): void;
+export declare function withGracefulShutdown(config?: GracefulShutdownConfig): ServerPlugin;
+export declare function startServerWithShutdown(app: import('express').Application, port: number, shutdownConfig?: GracefulShutdownConfig, serverName?: string, serverVersion?: string): Server;

package/packages/server-utils/dist/esm/core/shutdown.js

@@ -0,0 +1,53 @@
+export function createGracefulShutdown(server, config = {}) {
+    const { timeout = 10000, onShutdown, serverName, serverVersion } = config;
+    const nameVersion = serverName && serverVersion ? `${serverName} v${serverVersion}` : 'Server';
+    const shutdown = async (signal) => {
+        console.log(`🛑 ${nameVersion} received ${signal}, shutting down gracefully...`);
+        const shutdownTimer = setTimeout(() => {
+            console.log(`⏰ ${nameVersion} shutdown timeout reached, forcing exit`);
+            process.exit(1);
+        }, timeout);
+        try {
+            // Run custom shutdown logic
+            if (onShutdown) {
+                await onShutdown();
+            }
+            // Close server
+            server.close(() => {
+                clearTimeout(shutdownTimer);
+                console.log(`👋 ${nameVersion} closed. Exiting now.`);
+                process.exit(0);
+            });
+        }
+        catch (error) {
+            clearTimeout(shutdownTimer);
+            console.error(`❌ ${nameVersion} error during shutdown:`, error);
+            process.exit(1);
+        }
+    };
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+}
+export function withGracefulShutdown(config = {}) {
+    return (app, _serverConfig) => {
+        // This plugin needs to be applied after server.listen()
+        // Store config for later use
+        ;
+        app.__gracefulShutdownConfig = config;
+    };
+}
+export function startServerWithShutdown(app, port, shutdownConfig = {}, serverName, serverVersion) {
+    const server = app.listen(port, () => {
+        const nameVersion = serverName && serverVersion ? `${serverName} v${serverVersion}` : 'Server';
+        console.log(`🚀 ${nameVersion} running on http://localhost:${port}`);
+    });
+    // Apply graceful shutdown from stored config or provided config
+    const config = app.__gracefulShutdownConfig || shutdownConfig;
+    const enhancedConfig = {
+        ...config,
+        serverName,
+        serverVersion,
+    };
+    createGracefulShutdown(server, enhancedConfig);
+    return server;
+}

package/packages/server-utils/dist/esm/index.d.ts

@@ -0,0 +1,46 @@
+export { ExpressServer, createServer } from './core/server';
+export type { ServerInstance, ServerInfo, GrpcService, RpcMethod, WebhookConfig, } from './core/server';
+export { Request, Response, NextFunction, Router, Application } from 'express';
+export type { RequestHandler, ErrorRequestHandler } from 'express';
+export { createHealthCheck, withHealthCheck, addHealthCheck, } from './core/health';
+export { createGracefulShutdown, withGracefulShutdown, startServerWithShutdown, } from './core/shutdown';
+export { createLoggingMiddleware, createErrorHandler, createRequestIdMiddleware, createValidationMiddleware, createRateLimitMiddleware, createAuthMiddleware, withLogging, withErrorHandler, withRequestId, withValidation, withRateLimit, withAuth, validateFields, rateLimit, requireAuth, cacheResponse, useSession, type ValidationRule, type RateLimitConfig, type AuthConfig, } from './middleware';
+export { getEnv, getEnvNumber, getEnvBoolean, } from './utils/utils';
+export { PeriodicHealthMonitor } from './core/periodic-health';
+export type { ServerConfig, HealthCheckConfig, HealthCheck, GracefulShutdownConfig, ServerPlugin, SocketIOConfig, SocketInstance, PeriodicHealthCheckConfig, HealthCheckService, } from './types';
+import { addHealthCheck, createHealthCheck, withHealthCheck } from './core/health';
+import { PeriodicHealthMonitor } from './core/periodic-health';
+import { ExpressServer, createServer } from './core/server';
+import { createGracefulShutdown, startServerWithShutdown, withGracefulShutdown } from './core/shutdown';
+import { createAuthMiddleware, createErrorHandler, createLoggingMiddleware, createRateLimitMiddleware, createRequestIdMiddleware, createValidationMiddleware, rateLimit, requireAuth, validateFields, withAuth, withErrorHandler, withLogging, withRateLimit, withRequestId, withValidation } from './middleware';
+import { getEnv, getEnvBoolean, getEnvNumber } from './utils/utils';
+declare const ServerUtils: {
+    createServer: typeof createServer;
+    ExpressServer: typeof ExpressServer;
+    createHealthCheck: typeof createHealthCheck;
+    withHealthCheck: typeof withHealthCheck;
+    addHealthCheck: typeof addHealthCheck;
+    createGracefulShutdown: typeof createGracefulShutdown;
+    withGracefulShutdown: typeof withGracefulShutdown;
+    startServerWithShutdown: typeof startServerWithShutdown;
+    createLoggingMiddleware: typeof createLoggingMiddleware;
+    createErrorHandler: typeof createErrorHandler;
+    createRequestIdMiddleware: typeof createRequestIdMiddleware;
+    createValidationMiddleware: typeof createValidationMiddleware;
+    createRateLimitMiddleware: typeof createRateLimitMiddleware;
+    createAuthMiddleware: typeof createAuthMiddleware;
+    withLogging: typeof withLogging;
+    withErrorHandler: typeof withErrorHandler;
+    withRequestId: typeof withRequestId;
+    withValidation: typeof withValidation;
+    withRateLimit: typeof withRateLimit;
+    withAuth: typeof withAuth;
+    validateFields: typeof validateFields;
+    rateLimit: typeof rateLimit;
+    requireAuth: typeof requireAuth;
+    getEnv: typeof getEnv;
+    getEnvNumber: typeof getEnvNumber;
+    getEnvBoolean: typeof getEnvBoolean;
+    PeriodicHealthMonitor: typeof PeriodicHealthMonitor;
+};
+export default ServerUtils;

package/packages/server-utils/dist/esm/index.js

@@ -0,0 +1,58 @@
+// Core server utilities
+export { ExpressServer, createServer } from './core/server';
+// Express re-exports (to avoid direct Express dependency in services)
+export { Router } from 'express';
+// Health check utilities
+export { createHealthCheck, withHealthCheck, addHealthCheck, } from './core/health';
+// Graceful shutdown utilities
+export { createGracefulShutdown, withGracefulShutdown, startServerWithShutdown, } from './core/shutdown';
+// Middleware utilities
+export { createLoggingMiddleware, createErrorHandler, createRequestIdMiddleware, createValidationMiddleware, createRateLimitMiddleware, createAuthMiddleware, withLogging, withErrorHandler, withRequestId, withValidation, withRateLimit, withAuth, validateFields, rateLimit, requireAuth, cacheResponse, useSession, } from './middleware';
+// Utility functions
+export { getEnv, getEnvNumber, getEnvBoolean, } from './utils/utils';
+// Periodic health monitoring
+export { PeriodicHealthMonitor } from './core/periodic-health';
+import { addHealthCheck, createHealthCheck, withHealthCheck, } from './core/health';
+import { PeriodicHealthMonitor } from './core/periodic-health';
+// Import all exports for default export
+import { ExpressServer, createServer } from './core/server';
+import { createGracefulShutdown, startServerWithShutdown, withGracefulShutdown, } from './core/shutdown';
+import { createAuthMiddleware, createErrorHandler, createLoggingMiddleware, createRateLimitMiddleware, createRequestIdMiddleware, createValidationMiddleware, rateLimit, requireAuth, validateFields, withAuth, withErrorHandler, withLogging, withRateLimit, withRequestId, withValidation, } from './middleware';
+import { getEnv, getEnvBoolean, getEnvNumber } from './utils/utils';
+// Default export for namespace usage
+const ServerUtils = {
+    // Server creation
+    createServer,
+    ExpressServer,
+    // Health checks
+    createHealthCheck,
+    withHealthCheck,
+    addHealthCheck,
+    // Graceful shutdown
+    createGracefulShutdown,
+    withGracefulShutdown,
+    startServerWithShutdown,
+    // Middleware
+    createLoggingMiddleware,
+    createErrorHandler,
+    createRequestIdMiddleware,
+    createValidationMiddleware,
+    createRateLimitMiddleware,
+    createAuthMiddleware,
+    withLogging,
+    withErrorHandler,
+    withRequestId,
+    withValidation,
+    withRateLimit,
+    withAuth,
+    validateFields,
+    rateLimit,
+    requireAuth,
+    // Utils
+    getEnv,
+    getEnvNumber,
+    getEnvBoolean,
+    // Periodic Health Monitoring
+    PeriodicHealthMonitor,
+};
+export default ServerUtils;

package/packages/server-utils/dist/esm/middleware/auth.middleware.d.ts

@@ -0,0 +1,7 @@
+import type { Request, RequestHandler } from 'node_modules/@types/express';
+export interface AuthConfig {
+    secret: string;
+    unauthorizedMessage?: string;
+    tokenExtractor?: (req: Request) => string | null;
+}
+export declare function createAuthMiddleware(config: AuthConfig): RequestHandler;

package/packages/server-utils/dist/esm/middleware/auth.middleware.js

@@ -0,0 +1,38 @@
+import { UnauthorizedError } from '@naman_deep_singh/errors-utils';
+import { extractToken, safeVerifyToken } from '@naman_deep_singh/security';
+export function createAuthMiddleware(config) {
+    const { secret, unauthorizedMessage = 'Unauthorized access', tokenExtractor = (req) => extractToken({
+        header: req.headers.authorization || undefined,
+        cookies: req.cookies,
+        query: req.query,
+        body: req.body,
+    }), } = config;
+    return async (req, _res, next) => {
+        try {
+            // Extract token from request
+            const token = tokenExtractor(req);
+            if (!token) {
+                const error = new UnauthorizedError(unauthorizedMessage, {
+                    reason: 'No token provided',
+                });
+                return next(error);
+            }
+            // Use safe verify token from security package
+            const result = safeVerifyToken(token, secret);
+            if (!result.valid) {
+                const error = new UnauthorizedError(unauthorizedMessage, {
+                    reason: 'Invalid or expired token',
+                    originalError: result.error?.message,
+                });
+                return next(error);
+            }
+            // Attach the verified payload as user
+            req.user = result.payload;
+            next();
+        }
+        catch (error) {
+            const unauthorizedError = new UnauthorizedError(unauthorizedMessage, error instanceof Error ? { originalError: error.message } : error);
+            return next(unauthorizedError);
+        }
+    };
+}

package/packages/server-utils/dist/esm/middleware/cache.middleware.d.ts

@@ -0,0 +1,2 @@
+import type { RequestHandler } from 'node_modules/@types/express';
+export declare function cacheResponse(ttl?: number): RequestHandler;

package/packages/server-utils/dist/esm/middleware/cache.middleware.js

@@ -0,0 +1,55 @@
+// Cache response middleware (per-route opt-in)
+export function cacheResponse(ttl) {
+    return async (req, res, next) => {
+        try {
+            if (req.method !== 'GET')
+                return next();
+            const cache = (req.cache ?? req.app.locals.cache);
+            const defaultTTL = req.app.locals.cacheDefaultTTL;
+            if (!cache || typeof cache.get !== 'function')
+                return next();
+            const key = `${req.originalUrl}`;
+            try {
+                const cached = await cache.get(key);
+                if (cached !== null && cached !== undefined) {
+                    res.setHeader('X-Cache', 'HIT');
+                    return res.json(cached);
+                }
+            }
+            catch (cacheErr) {
+                console.error(`[Cache] Failed to retrieve key "${key}":`, cacheErr);
+                // Continue without cache hit
+            }
+            const originalJson = res.json.bind(res);
+            res.json = (body) => {
+                try {
+                    const expiry = ttl ?? defaultTTL;
+                    if (expiry && cache && typeof cache.set === 'function') {
+                        ;
+                        cache.set(key, body, expiry).catch((err) => {
+                            console.error(`[Cache] Failed to set key "${key}" with TTL ${expiry}:`, err);
+                        });
+                    }
+                    else if (cache) {
+                        if (typeof cache.set === 'function') {
+                            ;
+                            cache.set(key, body).catch((err) => {
+                                console.error(`[Cache] Failed to set key "${key}":`, err);
+                            });
+                        }
+                    }
+                }
+                catch (e) {
+                    console.error(`[Cache] Error during cache.set operation:`, e);
+                }
+                res.setHeader('X-Cache', 'MISS');
+                return originalJson(body);
+            };
+            next();
+        }
+        catch (err) {
+            console.error('[Cache] Unexpected error in cacheResponse middleware:', err);
+            next();
+        }
+    };
+}

package/packages/server-utils/dist/esm/middleware/errorHandler.middleware.d.ts

@@ -0,0 +1,2 @@
+import type { ErrorRequestHandler } from 'node_modules/@types/express';
+export declare function createErrorHandler(): ErrorRequestHandler;