@heavybit/pendoadmin-shared-lib 1.0.0

package/src/express/permission.guard.ts

@@ -0,0 +1,72 @@
+import type { Request, Response, NextFunction } from 'express';
+
+/**
+ * Require a specific permission. Superadmins bypass all checks.
+ */
+export function requirePermission(...permissions: string[]) {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    if (!req.user) {
+      res.status(401).json({ success: false, message: 'Authentication required' });
+      return;
+    }
+
+    if (req.user.isSuperAdmin) return next();
+
+    const hasPermission = permissions.some(p => req.user!.permissions.includes(p));
+    if (!hasPermission) {
+      res.status(403).json({
+        success: false,
+        message: 'Insufficient permissions',
+        errors: { required: permissions },
+      });
+      return;
+    }
+    next();
+  };
+}
+
+/**
+ * Require ALL of the listed permissions.
+ */
+export function requireAllPermissions(...permissions: string[]) {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    if (!req.user) {
+      res.status(401).json({ success: false, message: 'Authentication required' });
+      return;
+    }
+
+    if (req.user.isSuperAdmin) return next();
+
+    const hasAll = permissions.every(p => req.user!.permissions.includes(p));
+    if (!hasAll) {
+      res.status(403).json({
+        success: false,
+        message: 'Insufficient permissions',
+        errors: { required: permissions },
+      });
+      return;
+    }
+    next();
+  };
+}
+
+/**
+ * Require a specific role.
+ */
+export function requireRole(...roles: string[]) {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    if (!req.user) {
+      res.status(401).json({ success: false, message: 'Authentication required' });
+      return;
+    }
+
+    if (req.user.isSuperAdmin) return next();
+
+    const hasRole = roles.some(r => req.user!.roles.includes(r));
+    if (!hasRole) {
+      res.status(403).json({ success: false, message: 'Insufficient role' });
+      return;
+    }
+    next();
+  };
+}

package/src/express/validation.middleware.ts

@@ -0,0 +1,76 @@
+import type { Request, Response, NextFunction } from 'express';
+import type { ZodSchema, ZodObject, ZodRawShape } from 'zod';
+
+/**
+ * Zod validation middleware for Express routes.
+ * @param schema Zod schema to validate against
+ * @param property Which part of the request to validate ('body' | 'query' | 'params')
+ */
+export function validate(schema: ZodSchema, property: 'body' | 'query' | 'params' = 'body') {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    const result = schema.safeParse(req[property]);
+    if (!result.success) {
+      const errors: Record<string, string[]> = {};
+      for (const issue of result.error.issues) {
+        const key = issue.path.join('.');
+        if (!errors[key]) errors[key] = [];
+        errors[key].push(issue.message);
+      }
+      res.status(422).json({ success: false, message: 'Validation failed', errors });
+      return;
+    }
+    req[property] = result.data;
+    next();
+  };
+}
+
+/**
+ * Zod validation middleware – accepts a compound schema with body/query/params
+ * keys, or a simple schema validated against body.
+ */
+export function validateRequest(schema: ZodSchema) {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    // Check if this is a compound schema with body/query/params keys
+    const shape = (schema as ZodObject<ZodRawShape>)?.shape;
+    const isCompound = shape && ('body' in shape || 'query' in shape || 'params' in shape);
+
+    if (isCompound) {
+      const data: Record<string, unknown> = {};
+      if (shape.body) data.body = req.body;
+      if (shape.query) data.query = req.query;
+      if (shape.params) data.params = req.params;
+
+      const result = schema.safeParse(data);
+      if (!result.success) {
+        const errors: Record<string, string[]> = {};
+        for (const issue of result.error.issues) {
+          const key = issue.path.join('.');
+          if (!errors[key]) errors[key] = [];
+          errors[key].push(issue.message);
+        }
+        res.status(422).json({ success: false, message: 'Validation failed', errors });
+        return;
+      }
+      const parsed = result.data as Record<string, unknown>;
+      if (parsed.body) req.body = parsed.body;
+      if (parsed.query) (req as any).query = parsed.query;
+      if (parsed.params) (req as any).params = parsed.params;
+    } else {
+      // Simple schema – validate body
+      const result = schema.safeParse(req.body);
+      if (!result.success) {
+        const errors: Record<string, string[]> = {};
+        for (const issue of result.error.issues) {
+          const key = issue.path.join('.');
+          if (!errors[key]) errors[key] = [];
+          errors[key].push(issue.message);
+        }
+        res.status(422).json({ success: false, message: 'Validation failed', errors });
+        return;
+      }
+      req.body = result.data;
+    }
+
+    next();
+  };
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+// Types
+export * from './types/index.js';
+
+// Common utilities
+export * from './common/index.js';
+
+// Validation
+export * from './validation/index.js';
+
+// Logging
+export * from './logging/index.js';
+
+// Config
+export * from './config/index.js';
+
+// Messaging
+export * from './messaging/index.js';
+
+// Database
+export * from './database/index.js';
+
+// Express middleware (for Express-based services)
+export * from './express/index.js';

package/src/logging/index.ts

@@ -0,0 +1,31 @@
+import winston from 'winston';
+
+const { combine, timestamp, json, errors, colorize, simple } = winston.format;
+
+export function createLogger(service: string, level?: string): winston.Logger {
+  const isProduction = process.env.NODE_ENV === 'production';
+
+  return winston.createLogger({
+    level: level || process.env.LOG_LEVEL || (isProduction ? 'info' : 'debug'),
+    defaultMeta: { service },
+    format: combine(
+      errors({ stack: true }),
+      timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
+      isProduction ? json() : combine(colorize(), simple())
+    ),
+    transports: [
+      new winston.transports.Console(),
+    ],
+  });
+}
+
+export function createAuditLogger(service: string): winston.Logger {
+  return winston.createLogger({
+    level: 'info',
+    defaultMeta: { service, type: 'audit' },
+    format: combine(timestamp(), json()),
+    transports: [
+      new winston.transports.Console(),
+    ],
+  });
+}

package/src/messaging/index.ts

@@ -0,0 +1,161 @@
+import amqplib from 'amqplib';
+import type { Channel, ChannelModel, ConsumeMessage } from 'amqplib';
+import { createLogger } from '../logging/index.js';
+
+const logger = createLogger('rabbitmq');
+
+// ── Event Type Constants ──────────────────────────────
+
+export const EVENTS = {
+  // Auth events
+  AUTH_USER_CREATED: 'auth.user.created',
+  AUTH_USER_UPDATED: 'auth.user.updated',
+  AUTH_USER_DELETED: 'auth.user.deleted',
+  AUTH_USER_REGISTERED: 'auth.user.registered',
+  AUTH_LOGIN_SUCCESS: 'auth.login.success',
+  AUTH_LOGIN_FAILED: 'auth.login.failed',
+  AUTH_ROLE_UPDATED: 'auth.role.updated',
+  AUTH_COMPANY_CREATED: 'auth.company.created',
+  AUTH_COMPANY_UPDATED: 'auth.company.updated',
+  AUTH_COMPANY_CONFIG_UPDATED: 'auth.company.config_updated',
+  AUTH_PASSWORD_RESET_REQUESTED: 'auth.password.reset_requested',
+  AUTH_OTP_REQUESTED: 'auth.otp.requested',
+
+  // SMS events
+  SMS_MESSAGE_SENT: 'sms.message.sent',
+  SMS_MESSAGE_DELIVERED: 'sms.message.delivered',
+  SMS_MESSAGE_FAILED: 'sms.message.failed',
+  SMS_DELIVERY_FAILED: 'sms.delivery.failed',
+  SMS_SCHEDULE_TRIGGERED: 'sms.schedule.triggered',
+  SMS_PROCESS_SCHEDULED: 'sms.process_scheduled',
+  SMS_BULK_QUEUED: 'sms.bulk.queued',
+  SMS_BULK_COMPLETED: 'sms.bulk.completed',
+
+  // M-Pesa events
+  MPESA_PAYMENT_RECEIVED: 'mpesa.payment.received',
+  MPESA_STK_PUSH_SUCCESS: 'mpesa.stk_push.success',
+  MPESA_STK_PUSH_FAILED: 'mpesa.stk_push.failed',
+  MPESA_STK_PUSH_COMPLETED: 'mpesa.stk_push.completed',
+  MPESA_B2C_COMPLETED: 'mpesa.b2c.completed',
+
+  // USSD events
+  USSD_SESSION_STARTED: 'ussd.session.started',
+  USSD_SESSION_ENDED: 'ussd.session.ended',
+  USSD_SUBSCRIBER_REGISTERED: 'ussd.subscriber.registered',
+  USSD_STK_PUSH_REQUEST: 'ussd.stk_push.request',
+
+  // WhatsApp events
+  WHATSAPP_MESSAGE_SENT: 'whatsapp.message.sent',
+  WHATSAPP_MESSAGE_RECEIVED: 'whatsapp.message.received',
+  WHATSAPP_MESSAGE_DELIVERED: 'whatsapp.message.delivered',
+  WHATSAPP_MESSAGE_READ: 'whatsapp.message.read',
+
+  // Notification events
+  NOTIFICATION_SEND_SMS: 'notification.send_sms',
+  NOTIFICATION_SEND_WHATSAPP: 'notification.send_whatsapp',
+  NOTIFICATION_SEND_EMAIL: 'notification.send_email',
+
+  // AI events
+  AI_COMPLETION_SUCCESS: 'ai.completion.success',
+  AI_COMPLETION_FAILED: 'ai.completion.failed',
+  AI_ANOMALY_DETECTED: 'ai.anomaly.detected',
+
+  // Gateway events
+  GATEWAY_REQUEST_COMPLETED: 'gateway.request.completed',
+  GATEWAY_REQUEST_ERROR: 'gateway.request.error',
+} as const;
+
+export const EXCHANGES = {
+  EVENTS: 'pendoadmin.events',
+  COMMANDS: 'pendoadmin.commands',
+} as const;
+
+// ── RabbitMQ Client ───────────────────────────────────
+
+export class RabbitMQClient {
+  private connection: ChannelModel | null = null;
+  private channel: Channel | null = null;
+  private url: string;
+
+  constructor(url: string) {
+    this.url = url;
+  }
+
+  async connect(): Promise<void> {
+    try {
+      this.connection = await amqplib.connect(this.url);
+      this.channel = await this.connection.createChannel();
+
+      // Set up exchanges
+      await this.channel.assertExchange(EXCHANGES.EVENTS, 'topic', { durable: true });
+      await this.channel.assertExchange(EXCHANGES.COMMANDS, 'direct', { durable: true });
+
+      this.connection.on('error', (err) => {
+        logger.error('RabbitMQ connection error', { error: err.message });
+      });
+
+      this.connection.on('close', () => {
+        logger.warn('RabbitMQ connection closed, reconnecting...');
+        setTimeout(() => this.connect(), 5000);
+      });
+
+      logger.info('Connected to RabbitMQ');
+    } catch (error) {
+      logger.error('Failed to connect to RabbitMQ', { error: (error as Error).message });
+      setTimeout(() => this.connect(), 5000);
+    }
+  }
+
+  async publish(routingKey: string, data: Record<string, unknown>, exchange: string = EXCHANGES.EVENTS): Promise<void> {
+    if (!this.channel) {
+      logger.warn('RabbitMQ channel not ready, message dropped', { routingKey });
+      return;
+    }
+
+    const message = Buffer.from(JSON.stringify({
+      routingKey,
+      data,
+      timestamp: new Date().toISOString(),
+    }));
+
+    this.channel.publish(exchange, routingKey, message, {
+      persistent: true,
+      contentType: 'application/json',
+    });
+  }
+
+  async subscribe(
+    queueName: string,
+    routingKeys: string | string[],
+    handler: (data: Record<string, unknown>, routingKey: string) => Promise<void>,
+    exchange: string = EXCHANGES.EVENTS
+  ): Promise<void> {
+    if (!this.channel) throw new Error('RabbitMQ channel not ready');
+
+    const keys = Array.isArray(routingKeys) ? routingKeys : [routingKeys];
+    await this.channel.assertQueue(queueName, { durable: true });
+
+    for (const key of keys) {
+      await this.channel.bindQueue(queueName, exchange, key);
+    }
+
+    await this.channel.consume(queueName, async (msg: ConsumeMessage | null) => {
+      if (!msg) return;
+      try {
+        const parsed = JSON.parse(msg.content.toString());
+        await handler(parsed.data || parsed, msg.fields.routingKey);
+        this.channel!.ack(msg);
+      } catch (error) {
+        logger.error('Error processing message', { queue: queueName, error: (error as Error).message });
+        this.channel!.nack(msg, false, false); // Dead letter
+      }
+    });
+
+    logger.info(`Subscribed to queue: ${queueName}`, { routingKeys });
+  }
+
+  async close(): Promise<void> {
+    await this.channel?.close();
+    await this.connection?.close();
+  }
+}

package/src/nestjs/auth.guard.ts

@@ -0,0 +1,69 @@
+import {
+  Injectable,
+  CanActivate,
+  ExecutionContext,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { verifyToken } from '../common/jwt.utils.js';
+import { GATEWAY_HEADERS, type IAuthUser } from '../types/index.js';
+
+export const IS_PUBLIC_KEY = 'isPublic';
+
+/**
+ * NestJS Guard: validates JWT or trusts gateway-injected headers.
+ */
+@Injectable()
+export class AuthGuard implements CanActivate {
+  constructor(private reflector: Reflector) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+    if (isPublic) return true;
+
+    const request = context.switchToHttp().getRequest();
+
+    // Trust gateway-injected headers first
+    const gatewayUserId = request.headers[GATEWAY_HEADERS.USER_ID];
+    if (gatewayUserId) {
+      const permissions = request.headers[GATEWAY_HEADERS.USER_PERMISSIONS];
+      request.user = {
+        id: gatewayUserId,
+        companyId: request.headers[GATEWAY_HEADERS.COMPANY_ID] || undefined,
+        email: request.headers[GATEWAY_HEADERS.USER_EMAIL] || undefined,
+        roles: request.headers[GATEWAY_HEADERS.USER_ROLES]
+          ? (request.headers[GATEWAY_HEADERS.USER_ROLES] as string).split(',')
+          : [],
+        permissions: permissions ? (permissions as string).split(',') : [],
+        isSuperAdmin:
+          request.headers[GATEWAY_HEADERS.IS_SUPERADMIN] === 'true',
+      } as IAuthUser;
+      return true;
+    }
+
+    // Fallback to direct JWT validation
+    const authHeader = request.headers.authorization;
+    if (!authHeader?.startsWith('Bearer ')) {
+      throw new UnauthorizedException('Missing authentication token');
+    }
+
+    try {
+      const token = authHeader.slice(7);
+      const payload = verifyToken(token, process.env.JWT_SECRET!);
+      request.user = {
+        id: payload.sub,
+        companyId: payload.companyId,
+        email: payload.email,
+        roles: payload.roles || [],
+        permissions: payload.permissions || [],
+        isSuperAdmin: payload.isSuperAdmin || false,
+      } as IAuthUser;
+      return true;
+    } catch {
+      throw new UnauthorizedException('Invalid or expired token');
+    }
+  }
+}

package/src/nestjs/correlation.interceptor.ts

@@ -0,0 +1,30 @@
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+} from '@nestjs/common';
+import { Observable, tap } from 'rxjs';
+import { v4 as uuidv4 } from 'uuid';
+
+/**
+ * NestJS Interceptor: propagates or generates x-correlation-id header.
+ */
+@Injectable()
+export class CorrelationInterceptor implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    const request = context.switchToHttp().getRequest();
+    const response = context.switchToHttp().getResponse();
+
+    const correlationId =
+      request.headers['x-correlation-id'] || uuidv4();
+    request.correlationId = correlationId;
+    response.setHeader('x-correlation-id', correlationId);
+
+    return next.handle().pipe(
+      tap(() => {
+        // correlation id already set on response
+      })
+    );
+  }
+}

package/src/nestjs/exception.filter.ts

@@ -0,0 +1,53 @@
+import {
+  ExceptionFilter,
+  Catch,
+  ArgumentsHost,
+  HttpException,
+  HttpStatus,
+} from '@nestjs/common';
+import { createLogger } from '../logging/index.js';
+
+const logger = createLogger('exception-filter');
+
+/**
+ * NestJS Exception Filter: standardises error responses.
+ */
+@Catch()
+export class GlobalExceptionFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse();
+    const request = ctx.getRequest();
+
+    let status = HttpStatus.INTERNAL_SERVER_ERROR;
+    let message = 'Internal server error';
+    let errors: any = undefined;
+
+    if (exception instanceof HttpException) {
+      status = exception.getStatus();
+      const exResponse = exception.getResponse();
+      if (typeof exResponse === 'string') {
+        message = exResponse;
+      } else if (typeof exResponse === 'object') {
+        message = (exResponse as any).message || message;
+        errors = (exResponse as any).errors;
+      }
+    } else if (exception instanceof Error) {
+      message = exception.message;
+      logger.error('Unhandled exception', {
+        error: exception.message,
+        stack: exception.stack,
+        path: request.url,
+      });
+    }
+
+    response.status(status).json({
+      success: false,
+      message,
+      ...(errors ? { errors } : {}),
+      statusCode: status,
+      timestamp: new Date().toISOString(),
+      path: request.url,
+    });
+  }
+}

package/src/nestjs/index.ts

@@ -0,0 +1,11 @@
+export { AuthGuard } from './auth.guard.js';
+export {
+  RequirePermission,
+  RequireAllPermissions,
+  RequireRole,
+  Public,
+} from './permission.decorator.js';
+export { PermissionGuard } from './permission.guard.js';
+export { CurrentUser } from './user.decorator.js';
+export { CorrelationInterceptor } from './correlation.interceptor.js';
+export { GlobalExceptionFilter } from './exception.filter.js';

package/src/nestjs/permission.decorator.ts

@@ -0,0 +1,36 @@
+import { SetMetadata } from '@nestjs/common';
+import { IS_PUBLIC_KEY } from './auth.guard.js';
+
+export const PERMISSIONS_KEY = 'permissions';
+export const REQUIRE_ALL_KEY = 'requireAll';
+export const ROLES_KEY = 'roles';
+
+/**
+ * Decorator: require at least one of the listed permissions.
+ * @example @RequirePermission('sms.messages:read', 'sms.messages:list')
+ */
+export const RequirePermission = (...permissions: string[]) =>
+  SetMetadata(PERMISSIONS_KEY, permissions);
+
+/**
+ * Decorator: require ALL of the listed permissions.
+ */
+export const RequireAllPermissions = (...permissions: string[]) => {
+  return (target: any, key?: string | symbol, descriptor?: any) => {
+    SetMetadata(PERMISSIONS_KEY, permissions)(target, key!, descriptor);
+    SetMetadata(REQUIRE_ALL_KEY, true)(target, key!, descriptor);
+    return descriptor;
+  };
+};
+
+/**
+ * Decorator: require at least one of the listed roles.
+ * @example @RequireRole('admin', 'manager')
+ */
+export const RequireRole = (...roles: string[]) =>
+  SetMetadata(ROLES_KEY, roles);
+
+/**
+ * Decorator: mark route as public (skip auth guard).
+ */
+export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

package/src/nestjs/permission.guard.ts

@@ -0,0 +1,76 @@
+import {
+  Injectable,
+  CanActivate,
+  ExecutionContext,
+  ForbiddenException,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import {
+  PERMISSIONS_KEY,
+  REQUIRE_ALL_KEY,
+  ROLES_KEY,
+} from './permission.decorator.js';
+import { IS_PUBLIC_KEY } from './auth.guard.js';
+import type { IAuthUser } from '../types/index.js';
+
+/**
+ * NestJS Guard: checks permissions/roles from decorators.
+ * Must be used after AuthGuard so that request.user is populated.
+ */
+@Injectable()
+export class PermissionGuard implements CanActivate {
+  constructor(private reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    // Skip permission check for public routes
+    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+    if (isPublic) return true;
+
+    const request = context.switchToHttp().getRequest();
+    const user: IAuthUser | undefined = request.user;
+
+    if (!user) {
+      throw new ForbiddenException('User context not found');
+    }
+
+    // Super admins bypass all permission checks
+    if (user.isSuperAdmin) return true;
+
+    // Check roles
+    const requiredRoles = this.reflector.getAllAndOverride<string[]>(
+      ROLES_KEY,
+      [context.getHandler(), context.getClass()]
+    );
+    if (requiredRoles?.length) {
+      const hasRole = requiredRoles.some((role: string) => user.roles.includes(role));
+      if (!hasRole) {
+        throw new ForbiddenException('Insufficient role');
+      }
+    }
+
+    // Check permissions
+    const requiredPermissions = this.reflector.getAllAndOverride<string[]>(
+      PERMISSIONS_KEY,
+      [context.getHandler(), context.getClass()]
+    );
+    if (!requiredPermissions?.length) return true;
+
+    const requireAll = this.reflector.getAllAndOverride<boolean>(
+      REQUIRE_ALL_KEY,
+      [context.getHandler(), context.getClass()]
+    );
+
+    const hasPermission = requireAll
+      ? requiredPermissions.every((p: string) => user.permissions.includes(p))
+      : requiredPermissions.some((p: string) => user.permissions.includes(p));
+
+    if (!hasPermission) {
+      throw new ForbiddenException('Insufficient permissions');
+    }
+
+    return true;
+  }
+}

package/src/nestjs/user.decorator.ts

@@ -0,0 +1,19 @@
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+import type { IAuthUser } from '../types/index.js';
+
+/**
+ * Decorator: extract the authenticated user from the request.
+ * @example
+ *   @Get('profile')
+ *   getProfile(@CurrentUser() user: IAuthUser) { ... }
+ *
+ *   @Get('id')
+ *   getId(@CurrentUser('id') userId: string) { ... }
+ */
+export const CurrentUser = createParamDecorator(
+  (data: keyof IAuthUser | undefined, ctx: ExecutionContext) => {
+    const request = ctx.switchToHttp().getRequest();
+    const user: IAuthUser = request.user;
+    return data ? user?.[data] : user;
+  }
+);