@heavybit/pendoadmin-shared-lib 1.0.0

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,oBAAoB;AACpB,iDAAiD;AA+NjD,iDAAiD;AACjD,uBAAuB;AACvB,iDAAiD;AAEjD,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,OAAO,EAAE,WAAW;IACpB,UAAU,EAAE,cAAc;IAC1B,UAAU,EAAE,cAAc;IAC1B,UAAU,EAAE,cAAc;IAC1B,gBAAgB,EAAE,oBAAoB;IACtC,aAAa,EAAE,iBAAiB;IAChC,cAAc,EAAE,kBAAkB;IAClC,YAAY,EAAE,gBAAgB;CACtB,CAAC"}

package/dist/validation/index.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+export declare const paginationSchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    search: z.ZodOptional<z.ZodString>;
+    sortBy: z.ZodOptional<z.ZodString>;
+    sortOrder: z.ZodDefault<z.ZodEnum<["asc", "desc"]>>;
+}, "strip", z.ZodTypeAny, {
+    page: number;
+    limit: number;
+    sortOrder: "asc" | "desc";
+    search?: string | undefined;
+    sortBy?: string | undefined;
+}, {
+    page?: number | undefined;
+    limit?: number | undefined;
+    search?: string | undefined;
+    sortBy?: string | undefined;
+    sortOrder?: "asc" | "desc" | undefined;
+}>;
+export declare const emailSchema: z.ZodString;
+export declare const phoneSchema: z.ZodString;
+export declare const uuidSchema: z.ZodString;
+export declare const passwordSchema: z.ZodString;
+export declare const idParamSchema: z.ZodObject<{
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+}, {
+    id: string;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/validation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;EAM3B,CAAC;AAEH,eAAO,MAAM,WAAW,aAAiE,CAAC;AAE1F,eAAO,MAAM,WAAW,aAAyE,CAAC;AAElG,eAAO,MAAM,UAAU,aAAkC,CAAC;AAE1D,eAAO,MAAM,cAAc,aAK8E,CAAC;AAE1G,eAAO,MAAM,aAAa;;;;;;EAExB,CAAC"}

package/dist/validation/index.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+export const paginationSchema = z.object({
+    page: z.coerce.number().int().min(1).default(1),
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+    search: z.string().optional(),
+    sortBy: z.string().optional(),
+    sortOrder: z.enum(['asc', 'desc']).default('desc'),
+});
+export const emailSchema = z.string().email('Invalid email address').toLowerCase().trim();
+export const phoneSchema = z.string().min(9).max(15).regex(/^\+?[0-9]+$/, 'Invalid phone number');
+export const uuidSchema = z.string().uuid('Invalid UUID');
+export const passwordSchema = z.string()
+    .min(8, 'Password must be at least 8 characters')
+    .regex(/[A-Z]/, 'Password must contain at least one uppercase letter')
+    .regex(/[a-z]/, 'Password must contain at least one lowercase letter')
+    .regex(/[0-9]/, 'Password must contain at least one digit')
+    .regex(/[!@#$%^&*()_+\-=\[\]{};':"\\|,.<>\/?]/, 'Password must contain at least one special character');
+export const idParamSchema = z.object({
+    id: z.string().min(1),
+});
+//# sourceMappingURL=index.js.map

package/dist/validation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/C,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAC1D,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;CACnD,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;AAE1F,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,EAAE,sBAAsB,CAAC,CAAC;AAElG,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;AAE1D,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,EAAE;KACrC,GAAG,CAAC,CAAC,EAAE,wCAAwC,CAAC;KAChD,KAAK,CAAC,OAAO,EAAE,qDAAqD,CAAC;KACrE,KAAK,CAAC,OAAO,EAAE,qDAAqD,CAAC;KACrE,KAAK,CAAC,OAAO,EAAE,0CAA0C,CAAC;KAC1D,KAAK,CAAC,uCAAuC,EAAE,sDAAsD,CAAC,CAAC;AAE1G,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACtB,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@heavybit/pendoadmin-shared-lib",
+  "version": "1.0.0",
+  "description": "Shared library for PendoAdmin microservices",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "api",
+    "response",
+    "error-handling",
+    "validation",
+    "utilities",
+    "typescript",
+    "express",
+    "middleware",
+    "nestjs",
+    "logging",
+    "configuration",
+    "database",
+    "messaging",
+    "common"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./express": "./dist/express/index.js",
+    "./nestjs": "./dist/nestjs/index.js",
+    "./common": "./dist/common/index.js",
+    "./messaging": "./dist/messaging/index.js",
+    "./database": "./dist/database/index.js",
+    "./validation": "./dist/validation/index.js",
+    "./logging": "./dist/logging/index.js",
+    "./config": "./dist/config/index.js",
+    "./types": "./dist/types/index.js"
+  },
+  "typesVersions": {
+    "*": {
+      "nestjs": ["dist/nestjs/index.d.ts"],
+      "express": ["dist/express/index.d.ts"],
+      "common": ["dist/common/index.d.ts"],
+      "messaging": ["dist/messaging/index.d.ts"],
+      "database": ["dist/database/index.d.ts"],
+      "validation": ["dist/validation/index.d.ts"],
+      "logging": ["dist/logging/index.d.ts"],
+      "config": ["dist/config/index.d.ts"],
+      "types": ["dist/types/index.d.ts"]
+    }
+  },
+  "dependencies": {
+    "amqplib": "^0.10.4",
+    "bcrypt": "^5.1.1",
+    "google-libphonenumber": "^3.2.38",
+    "jsonwebtoken": "^9.0.2",
+    "knex": "^3.1.0",
+    "mysql2": "^3.11.0",
+    "uuid": "^10.0.0",
+    "winston": "^3.14.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.1.14",
+    "@nestjs/core": "^11.1.14",
+    "@types/amqplib": "^0.10.5",
+    "@types/bcrypt": "^5.0.2",
+    "@types/express": "^5.0.6",
+    "@types/google-libphonenumber": "^7.4.30",
+    "@types/jsonwebtoken": "^9.0.7",
+    "@types/node": "^20.14.0",
+    "@types/uuid": "^10.0.0",
+    "express": "^5.2.1",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
+    "typescript": "^5.5.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": ">=10.0.0",
+    "@nestjs/core": ">=10.0.0",
+    "express": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    },
+    "@nestjs/core": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    }
+  }
+}

package/src/common/index.ts

@@ -0,0 +1,5 @@
+export * from './jwt.utils.js';
+export * from './phone.utils.js';
+export * from './password.utils.js';
+export * from './uuid.utils.js';
+export * from './response.utils.js';

package/src/common/jwt.utils.ts

@@ -0,0 +1,43 @@
+import jwt from 'jsonwebtoken';
+import type { IJwtPayload } from '../types/index.js';
+
+const JWT_ISSUER = 'pendoadmin-auth';
+
+export function signAccessToken(
+  payload: Omit<IJwtPayload, 'iat' | 'exp' | 'iss'>,
+  secret: string,
+  expiresIn: string = '1h'
+): string {
+  return jwt.sign(payload, secret, {
+    expiresIn: expiresIn as unknown as jwt.SignOptions['expiresIn'],
+    issuer: JWT_ISSUER,
+  });
+}
+
+export function signRefreshToken(
+  userId: string,
+  secret: string,
+  expiresIn: string = '7d'
+): string {
+  return jwt.sign({ sub: userId, type: 'refresh' }, secret, {
+    expiresIn: expiresIn as unknown as jwt.SignOptions['expiresIn'],
+    issuer: JWT_ISSUER,
+  });
+}
+
+export function verifyToken(token: string, secret: string): IJwtPayload {
+  return jwt.verify(token, secret, { issuer: JWT_ISSUER }) as IJwtPayload;
+}
+
+export function decodeToken(token: string): IJwtPayload | null {
+  try {
+    return jwt.decode(token) as IJwtPayload;
+  } catch {
+    return null;
+  }
+}
+
+export function extractBearerToken(authHeader?: string): string | null {
+  if (!authHeader?.startsWith('Bearer ')) return null;
+  return authHeader.slice(7);
+}

package/src/common/password.utils.ts

@@ -0,0 +1,20 @@
+import bcrypt from 'bcrypt';
+
+const SALT_ROUNDS = 12;
+
+export async function hashPassword(password: string): Promise<string> {
+  return bcrypt.hash(password, SALT_ROUNDS);
+}
+
+export async function verifyPassword(password: string, hash: string): Promise<boolean> {
+  return bcrypt.compare(password, hash);
+}
+
+export function generateRandomPassword(length: number = 16): string {
+  const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@#$%^&*';
+  let password = '';
+  for (let i = 0; i < length; i++) {
+    password += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return password;
+}

package/src/common/phone.utils.ts

@@ -0,0 +1,36 @@
+import pkg from 'google-libphonenumber';
+const { PhoneNumberUtil, PhoneNumberFormat } = pkg;
+
+const phoneUtil = PhoneNumberUtil.getInstance();
+
+export function normalizePhoneNumber(phone: string, defaultCountry: string = 'KE'): string {
+  try {
+    const parsed = phoneUtil.parse(phone, defaultCountry);
+    return phoneUtil.format(parsed, PhoneNumberFormat.E164);
+  } catch {
+    return phone;
+  }
+}
+
+export function isValidPhoneNumber(phone: string, defaultCountry: string = 'KE'): boolean {
+  try {
+    const parsed = phoneUtil.parse(phone, defaultCountry);
+    return phoneUtil.isValidNumber(parsed);
+  } catch {
+    return false;
+  }
+}
+
+export function formatPhoneNumber(phone: string, format: 'e164' | 'international' | 'national' = 'e164', defaultCountry: string = 'KE'): string {
+  try {
+    const parsed = phoneUtil.parse(phone, defaultCountry);
+    const formatMap = {
+      e164: PhoneNumberFormat.E164,
+      international: PhoneNumberFormat.INTERNATIONAL,
+      national: PhoneNumberFormat.NATIONAL,
+    };
+    return phoneUtil.format(parsed, formatMap[format]);
+  } catch {
+    return phone;
+  }
+}

package/src/common/response.utils.ts

@@ -0,0 +1,48 @@
+import type { IApiResponse, IPaginationMeta, IPaginatedResult } from '../types/index.js';
+
+export function successResponse<T>(data: T, message: string = 'Success'): IApiResponse<T> {
+  return { success: true, message, data };
+}
+
+export function errorResponse(message: string, errors?: Record<string, string[]>): IApiResponse {
+  return { success: false, message, errors };
+}
+
+export function paginatedResponse<T>(
+  data: T[],
+  total: number,
+  page: number,
+  limit: number,
+  message: string = 'Success'
+): IApiResponse<T[]> {
+  const totalPages = Math.ceil(total / limit);
+  const meta: IPaginationMeta = {
+    page,
+    limit,
+    total,
+    totalPages,
+    hasNext: page < totalPages,
+    hasPrev: page > 1,
+  };
+  return { success: true, message, data, meta };
+}
+
+export function buildPaginatedResult<T>(
+  data: T[],
+  total: number,
+  page: number,
+  limit: number
+): IPaginatedResult<T> {
+  const totalPages = Math.ceil(total / limit);
+  return {
+    data,
+    meta: {
+      page,
+      limit,
+      total,
+      totalPages,
+      hasNext: page < totalPages,
+      hasPrev: page > 1,
+    },
+  };
+}

package/src/common/uuid.utils.ts

@@ -0,0 +1,11 @@
+import { v7 as uuidv7, v4 as uuidv4 } from 'uuid';
+
+/** Generate a UUID v7 (time-ordered, recommended for primary keys) */
+export function generateId(): string {
+  return uuidv7();
+}
+
+/** Generate a UUID v4 (random, for tokens/secrets) */
+export function generateRandomId(): string {
+  return uuidv4();
+}

package/src/config/index.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+
+/**
+ * Base environment schema shared across all services.
+ */
+export const baseEnvSchema = z.object({
+  NODE_ENV: z.enum(['development', 'staging', 'production']).default('development'),
+  PORT: z.coerce.number().int().positive().default(3000),
+  DB_HOST: z.string().default('localhost'),
+  DB_PORT: z.coerce.number().int().positive().default(3306),
+  DB_USER: z.string().default('root'),
+  DB_PASSWORD: z.string().default(''),
+  DB_NAME: z.string(),
+  JWT_SECRET: z.string().min(16),
+  JWT_ACCESS_EXPIRY: z.string().default('15m'),
+  JWT_REFRESH_EXPIRY: z.string().default('7d'),
+  RABBITMQ_URL: z.string().url().default('amqp://localhost:5672'),
+  REDIS_URL: z.string().default('redis://localhost:6379'),
+  LOG_LEVEL: z.enum(['error', 'warn', 'info', 'debug']).default('info'),
+  CORS_ORIGINS: z.string().default('*'),
+});
+
+export type BaseEnv = z.infer<typeof baseEnvSchema>;
+
+/**
+ * Load and validate environment variables using a Zod schema.
+ * Reads .env file from cwd if present (manual parse, no dotenv dependency needed).
+ */
+export function loadEnv<T extends z.ZodObject<any>>(schema: T): z.infer<T> {
+  // Parse .env file from cwd if it exists
+  try {
+    const envPath = resolve(process.cwd(), '.env');
+    if (existsSync(envPath)) {
+      const content = readFileSync(envPath, 'utf-8');
+      for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) continue;
+        const eqIdx = trimmed.indexOf('=');
+        if (eqIdx === -1) continue;
+        const key = trimmed.slice(0, eqIdx).trim();
+        const val = trimmed.slice(eqIdx + 1).trim();
+        if (!process.env[key]) process.env[key] = val;
+      }
+    }
+  } catch { /* ignore */ }
+  const result = schema.safeParse(process.env);
+  if (!result.success) {
+    const formatted = result.error.issues
+      .map((i) => `  ${i.path.join('.')}: ${i.message}`)
+      .join('\n');
+    console.error(`❌ Environment validation failed:\n${formatted}`);
+    process.exit(1);
+  }
+  return result.data;
+}
+
+/**
+ * Service registry: central list of service names and default ports.
+ */
+export const SERVICE_REGISTRY = {
+  'auth-admin': { port: 3000, prefix: '/api/v1/auth' },
+  sms: { port: 3001, prefix: '/api/v1/sms' },
+  mpesa: { port: 3002, prefix: '/api/v1/mpesa' },
+  ussd: { port: 3003, prefix: '/api/v1/ussd' },
+  whatsapp: { port: 3004, prefix: '/api/v1/whatsapp' },
+  notification: { port: 3005, prefix: '/api/v1/notifications' },
+  analytics: { port: 3006, prefix: '/api/v1/analytics' },
+  ai: { port: 3007, prefix: '/api/v1/ai' },
+} as const;
+
+export type ServiceName = keyof typeof SERVICE_REGISTRY;

package/src/database/index.ts

@@ -0,0 +1,77 @@
+import knex, { Knex } from 'knex';
+
+export interface DatabaseConfig {
+  host: string;
+  port: number;
+  user: string;
+  password: string;
+  database: string;
+}
+
+/**
+ * Create a Knex instance for MySQL 8.0.
+ * Used for migrations, seeds, and as a fallback query builder.
+ */
+export function createKnexInstance(config: DatabaseConfig): Knex {
+  return knex({
+    client: 'mysql2',
+    connection: {
+      host: config.host,
+      port: config.port,
+      user: config.user,
+      password: config.password,
+      database: config.database,
+      charset: 'utf8mb4',
+      timezone: '+00:00',
+    },
+    pool: {
+      min: 2,
+      max: 10,
+      acquireTimeoutMillis: 30000,
+    },
+    migrations: {
+      tableName: 'knex_migrations',
+    },
+  });
+}
+
+/**
+ * Standard Knex config for migrations/seeds.
+ */
+export function createKnexConfig(config: DatabaseConfig): Knex.Config {
+  return {
+    client: 'mysql2',
+    connection: {
+      host: config.host,
+      port: config.port,
+      user: config.user,
+      password: config.password,
+      database: config.database,
+      charset: 'utf8mb4',
+    },
+    migrations: {
+      directory: './migrations',
+      extension: 'cjs',
+    },
+    seeds: {
+      directory: './seeds',
+      extension: 'cjs',
+    },
+  };
+}
+
+/**
+ * Helper: build paginated query with Knex.
+ */
+export async function paginateQuery<T>(
+  query: Knex.QueryBuilder,
+  countQuery: Knex.QueryBuilder,
+  page: number,
+  limit: number
+): Promise<{ data: T[]; total: number }> {
+  const offset = (page - 1) * limit;
+  const [countResult] = await countQuery.count('* as total');
+  const total = (countResult as any).total as number;
+  const data = await query.limit(limit).offset(offset) as T[];
+  return { data, total };
+}

package/src/express/auth.middleware.ts

@@ -0,0 +1,93 @@
+import type { Request, Response, NextFunction } from 'express';
+import { verifyToken, extractBearerToken } from '../common/jwt.utils.js';
+import { GATEWAY_HEADERS, type IAuthUser } from '../types/index.js';
+
+// Extend Express Request
+declare global {
+  namespace Express {
+    interface Request {
+      user?: IAuthUser;
+    }
+  }
+}
+
+/**
+ * Auth middleware for downstream services (behind API gateway).
+ * Reads user context from gateway-injected headers.
+ * Falls back to JWT validation if headers are missing (direct access).
+ */
+export function authenticateFromGateway(jwtSecret?: string) {
+  return (req: Request, _res: Response, next: NextFunction): void => {
+    // Method 1: Read gateway-injected headers
+    const userId = req.headers[GATEWAY_HEADERS.USER_ID] as string;
+    if (userId) {
+      req.user = {
+        id: userId,
+        email: req.headers[GATEWAY_HEADERS.USER_EMAIL] as string || '',
+        companyId: req.headers[GATEWAY_HEADERS.COMPANY_ID] as string || '',
+        roles: ((req.headers[GATEWAY_HEADERS.USER_ROLES] as string) || '').split(',').filter(Boolean),
+        permissions: ((req.headers[GATEWAY_HEADERS.USER_PERMISSIONS] as string) || '').split(',').filter(Boolean),
+        isSuperAdmin: req.headers[GATEWAY_HEADERS.IS_SUPERADMIN] === 'true',
+      };
+      return next();
+    }
+
+    // Method 2: Direct JWT validation (for development / direct access)
+    if (jwtSecret) {
+      const token = extractBearerToken(req.headers.authorization);
+      if (token) {
+        try {
+          const payload = verifyToken(token, jwtSecret);
+          req.user = {
+            id: payload.sub,
+            email: payload.email,
+            companyId: payload.companyId,
+            roles: payload.roles || [],
+            permissions: payload.permissions || [],
+            isSuperAdmin: payload.isSuperAdmin || false,
+          };
+          return next();
+        } catch {
+          // Fall through to 401
+        }
+      }
+    }
+
+    _res.status(401).json({ success: false, message: 'Authentication required' });
+  };
+}
+
+/**
+ * Optional auth — attaches user if present, continues if not.
+ */
+export function optionalAuthFromGateway(jwtSecret?: string) {
+  return (req: Request, _res: Response, next: NextFunction): void => {
+    const userId = req.headers[GATEWAY_HEADERS.USER_ID] as string;
+    if (userId) {
+      req.user = {
+        id: userId,
+        email: req.headers[GATEWAY_HEADERS.USER_EMAIL] as string || '',
+        companyId: req.headers[GATEWAY_HEADERS.COMPANY_ID] as string || '',
+        roles: ((req.headers[GATEWAY_HEADERS.USER_ROLES] as string) || '').split(',').filter(Boolean),
+        permissions: ((req.headers[GATEWAY_HEADERS.USER_PERMISSIONS] as string) || '').split(',').filter(Boolean),
+        isSuperAdmin: req.headers[GATEWAY_HEADERS.IS_SUPERADMIN] === 'true',
+      };
+    } else if (jwtSecret) {
+      const token = extractBearerToken(req.headers.authorization);
+      if (token) {
+        try {
+          const payload = verifyToken(token, jwtSecret);
+          req.user = {
+            id: payload.sub,
+            email: payload.email,
+            companyId: payload.companyId,
+            roles: payload.roles || [],
+            permissions: payload.permissions || [],
+            isSuperAdmin: payload.isSuperAdmin || false,
+          };
+        } catch { /* ignore */ }
+      }
+    }
+    next();
+  };
+}

package/src/express/correlation.middleware.ts

@@ -0,0 +1,16 @@
+import type { Request, Response, NextFunction } from 'express';
+import { v4 as uuidv4 } from 'uuid';
+import { GATEWAY_HEADERS } from '../types/index.js';
+
+/**
+ * Ensures every request has a correlation ID for distributed tracing.
+ */
+export function correlationMiddleware(serviceName: string) {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    const correlationId = (req.headers[GATEWAY_HEADERS.CORRELATION_ID] as string) || uuidv4();
+    req.headers[GATEWAY_HEADERS.CORRELATION_ID] = correlationId;
+    req.headers[GATEWAY_HEADERS.SERVICE_NAME] = serviceName;
+    res.setHeader(GATEWAY_HEADERS.CORRELATION_ID, correlationId);
+    next();
+  };
+}

package/src/express/error-handler.ts

@@ -0,0 +1,28 @@
+import type { Request, Response, NextFunction } from 'express';
+import { createLogger } from '../logging/index.js';
+
+const logger = createLogger('error-handler');
+
+export interface AppError extends Error {
+  statusCode?: number;
+  errors?: Record<string, string[]>;
+}
+
+export function globalErrorHandler(err: AppError, _req: Request, res: Response, _next: NextFunction): void {
+  const statusCode = err.statusCode || 500;
+  const message = statusCode === 500 ? 'Internal server error' : err.message;
+
+  if (statusCode === 500) {
+    logger.error('Unhandled error', { error: err.message, stack: err.stack });
+  }
+
+  res.status(statusCode).json({
+    success: false,
+    message,
+    errors: err.errors,
+  });
+}
+
+export function notFoundHandler(_req: Request, res: Response): void {
+  res.status(404).json({ success: false, message: 'Resource not found' });
+}

package/src/express/index.ts

@@ -0,0 +1,5 @@
+export * from './auth.middleware.js';
+export * from './permission.guard.js';
+export * from './error-handler.js';
+export * from './correlation.middleware.js';
+export * from './validation.middleware.js';